ERPC

Make your first paid request with x402

This guide takes one Solana request through x402: read the price, pay it, and get the answer with a settlement receipt. The other 15 chains work the same way at their own routes.
You need a wallet that holds USDC on Solana, or USDC or EURC on Base, and an x402 client: the software that reads the 402 response, signs a payment from your wallet and sends the request again with it. For x402 clients, see the x402 documentation at x402.org.

1. Send the request

Send the RPC request without a payment:
bash
curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
The answer is 402 Payment Required. Its headers give the method and the price:
http
HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001
The body lists the payment options in accepts, one for each stablecoin the request can be paid with. amount is in the stablecoin's smallest unit, so 1000 is 0.001 USDC, or 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. Pay with an x402 client

Give the 402 response to your x402 client. It picks an option your wallet can pay, signs a payment for that amount and encodes it for the X-Payment header. The payment needs no SOL or ETH for network fees.

3. Send the request again with the payment

Send the same body again, with the payment in the X-Payment header:
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"}'
Keep the body unchanged. The price is worked out from the body, so if a changed body has a different price, the payment no longer matches it and is answered with price_mismatch.
Once the payment is verified and settled, the RPC answer comes back with the settlement receipt in the X-Payment-Response header:
http
HTTP/2 200
x-payment-response: <RECEIPT>
json
{ "jsonrpc": "2.0", "id": 1, "result": … }
A payment pays for one request. If you send the same payment again, it is refused with 402 payment_invalid or 409 duplicate_payment, and the request is not forwarded again.

Responses

A request that x402.erpc.global answers with an error before it asks for payment costs nothing.
Statuserror.codeWhat happened
402payment_requiredNo payment was sent. The body gives the price and the payment options.
402payment_invalidThe payment did not pass verification. Sign a new payment and send the request again.
402price_mismatchThe payment does not match an option this request's 402 offered, such as its price.
402payment_amount_too_lowThe amount is below the smallest payment x402.erpc.global settles.
402settlement_failedThe settlement was reported as failed. The response offers the payment options again.
409duplicate_paymentThe payment was already used.
400method_not_supported, invalid_requestThe route does not sell the method, or does not take the body. Nothing is charged.
413batch_too_largeThe batch has more than 100 calls. Nothing is charged.
500configuration_errorThe route cannot serve requests right now. Nothing is charged.
503payment_unavailableNo payment option can be offered right now. Nothing is charged. Try again after the Retry-After seconds.
503service_busyToo many requests at once. Nothing is charged. Try again after the Retry-After seconds.
502settlement_failedThe settlement result is unknown: the payment may have gone through, and no receipt is attached. Check on Solana or Base whether the payment you signed went through before you sign a new one.
502, 504upstream_error, upstream_timeoutThe payment settled, but the chain did not answer, or did not answer in time. The receipt is still attached. Sending the request again takes a new payment.
On Solana, a call that would read too much, such as an unfiltered getProgramAccounts on a large program, is answered with HTTP 200 and a JSON-RPC error before any payment is asked for, so it costs nothing.

Next steps

PreviousOverviewNextPricing