ERPC

Faça sua primeira requisição paga com o x402

Este guia acompanha uma requisição da Solana pelo x402: ler o preço, pagar e receber a resposta com um comprovante de liquidação. As outras 15 chains funcionam do mesmo jeito, cada uma no seu caminho.
Você precisa de uma carteira com USDC na Solana, ou USDC ou EURC na Base, e de um cliente x402: o software que lê a resposta 402, assina um pagamento com a sua carteira e reenvia a requisição com ele. Para escolher um cliente x402, consulte a documentação do x402 em x402.org.

1. Envie a requisição

Envie a requisição RPC sem pagamento:
bash
curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
A resposta é 402 Payment Required. Os cabeçalhos informam o método e o preço:
http
HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001
O corpo lista as opções de pagamento em accepts, uma para cada stablecoin com que a requisição pode ser paga. amount está na menor unidade da stablecoin, então 1000 equivale a 0.001 USDC, ou 0.001 EURC:
json
{
  "error": { "code": "payment_required", "message": "Payment required", "request_id": "…" },
  "x402Version": 2,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "1000", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", … },
    { "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", … },
    { "scheme": "exact", "network": "eip155:8453", "amount": "1000", "asset": "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", … }
  ],
  "pricing": { "methods": ["getSlot"], …, "weight": 1000, "rawWeight": 42, …, "price": "$0.001", … },
  …
}

2. Pague com um cliente x402

Entregue a resposta 402 ao seu cliente x402. Ele escolhe uma opção que a sua carteira consegue pagar, assina um pagamento desse valor e o codifica para o cabeçalho X-Payment. O pagamento não exige SOL nem ETH para taxas de rede.

3. Envie a requisição de novo com o pagamento

Envie o mesmo corpo de novo, com o pagamento no cabeçalho X-Payment:
bash
curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --header 'X-Payment: <PAYMENT_PAYLOAD>' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
Não altere o corpo. O preço é calculado a partir do corpo; se um corpo alterado tiver outro preço, o pagamento deixa de corresponder a ele e a resposta é price_mismatch.
Depois que o pagamento é verificado e liquidado, a resposta RPC volta com o comprovante de liquidação no cabeçalho X-Payment-Response:
http
HTTP/2 200
x-payment-response: <RECEIPT>
json
{ "jsonrpc": "2.0", "id": 1, "result": … }
Cada pagamento vale para uma única requisição. Se você enviar o mesmo pagamento de novo, ele é recusado com 402 payment_invalid ou 409 duplicate_payment, e a requisição não é encaminhada outra vez.

Respostas

Uma requisição à qual o x402.erpc.global responde com erro antes de pedir o pagamento não custa nada.
Statuserror.codeO que aconteceu
402payment_requiredNenhum pagamento foi enviado. O corpo informa o preço e as opções de pagamento.
402payment_invalidO pagamento não passou na verificação. Assine um novo pagamento e envie a requisição de novo.
402price_mismatchO pagamento não corresponde a nenhuma das opções oferecidas pelo 402 desta requisição, por exemplo no preço.
402payment_amount_too_lowO valor está abaixo do menor pagamento que o x402.erpc.global liquida.
402settlement_failedA liquidação foi reportada como malsucedida. A resposta oferece de novo as opções de pagamento.
409duplicate_paymentO pagamento já foi usado.
400method_not_supported, invalid_requestO caminho não vende o método ou não aceita o corpo. Nada é cobrado.
413batch_too_largeO lote tem mais de 100 chamadas. Nada é cobrado.
500configuration_errorO caminho não consegue atender requisições no momento. Nada é cobrado.
503payment_unavailableNenhuma opção de pagamento pode ser oferecida no momento. Nada é cobrado. Tente de novo depois dos segundos indicados em Retry-After.
503service_busyRequisições demais ao mesmo tempo. Nada é cobrado. Tente de novo depois dos segundos indicados em Retry-After.
502settlement_failedO resultado da liquidação é desconhecido: o pagamento pode ter sido concluído, e nenhum comprovante vem anexado. Antes de assinar um novo pagamento, verifique na Solana ou na Base se o pagamento que você assinou foi concluído.
502, 504upstream_error, upstream_timeoutO pagamento foi liquidado, mas a chain não respondeu, ou não respondeu a tempo. Mesmo assim, o comprovante vem anexado. Enviar a requisição de novo exige um novo pagamento.
Na Solana, uma chamada que leria dados demais, como um getProgramAccounts sem filtro em um programa grande, é respondida com HTTP 200 e um erro JSON-RPC antes de qualquer pedido de pagamento, então não custa nada.

Próximos passos

AnteriorVisão geralPróximoPreços