ERPC

Invia la tua prima richiesta a pagamento con x402

Questa guida segue una richiesta Solana attraverso x402: leggere il prezzo, pagarlo e ricevere la risposta con una ricevuta di regolamento. Le altre 15 chain funzionano allo stesso modo, ciascuna sul proprio percorso.
Ti servono un wallet con USDC su Solana, oppure con USDC o EURC su Base, e un client x402: il software che legge la risposta 402, firma un pagamento dal tuo wallet e invia di nuovo la richiesta con quel pagamento. Per i client x402, consulta la documentazione di x402 su x402.org.

1. Invia la richiesta

Invia la richiesta RPC senza pagamento:
bash
curl -i https://x402.erpc.global/v1/solana-mainnet \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getSlot"}'
La risposta è 402 Payment Required. I suoi header indicano il metodo e il prezzo:
http
HTTP/2 402
x-payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…
x-rpc-methods: getSlot
x-rpc-weight: 1000
x-rpc-price-usd: 0.001
Il body elenca le opzioni di pagamento in accepts, una per ogni stablecoin con cui si può pagare la richiesta. amount è espresso nell'unità più piccola della stablecoin, quindi 1000 corrisponde a 0.001 USDC, oppure a 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. Paga con un client x402

Passa la risposta 402 al tuo client x402. Il client sceglie un'opzione che il tuo wallet può pagare, firma un pagamento per quell'importo e lo codifica per l'header X-Payment. Il pagamento non richiede SOL né ETH per le commissioni di rete.

3. Invia di nuovo la richiesta con il pagamento

Invia di nuovo lo stesso body, con il pagamento nell'header 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"}'
Non modificare il body. Il prezzo viene calcolato in base al body: se un body modificato ha un prezzo diverso, il pagamento non corrisponde più e la risposta è price_mismatch.
Quando il pagamento è verificato e regolato, la risposta RPC torna con la ricevuta di regolamento nell'header X-Payment-Response:
http
HTTP/2 200
x-payment-response: <RECEIPT>
json
{ "jsonrpc": "2.0", "id": 1, "result": … }
Ogni pagamento copre una sola richiesta. Se invii di nuovo lo stesso pagamento, viene rifiutato con 402 payment_invalid o 409 duplicate_payment, e la richiesta non viene inoltrata un'altra volta.

Risposte

Una richiesta a cui x402.erpc.global risponde con un errore prima di chiedere il pagamento non costa nulla.
Statoerror.codeCosa è successo
402payment_requiredNon è stato inviato alcun pagamento. Il body indica il prezzo e le opzioni di pagamento.
402payment_invalidIl pagamento non ha superato la verifica. Firma un nuovo pagamento e invia di nuovo la richiesta.
402price_mismatchIl pagamento non corrisponde a nessuna opzione offerta dalla risposta 402 di questa richiesta, per esempio nel prezzo.
402payment_amount_too_lowL'importo è inferiore al pagamento minimo regolato da x402.erpc.global.
402settlement_failedIl regolamento è stato segnalato come non riuscito. La risposta offre di nuovo le opzioni di pagamento.
409duplicate_paymentIl pagamento è già stato usato.
400method_not_supported, invalid_requestIl percorso non vende il metodo o non accetta il body. Non viene addebitato nulla.
413batch_too_largeIl batch contiene più di 100 chiamate. Non viene addebitato nulla.
500configuration_errorIl percorso al momento non può servire richieste. Non viene addebitato nulla.
503payment_unavailableAl momento non è possibile offrire alcuna opzione di pagamento. Non viene addebitato nulla. Riprova dopo il numero di secondi indicato in Retry-After.
503service_busyTroppe richieste contemporaneamente. Non viene addebitato nulla. Riprova dopo il numero di secondi indicato in Retry-After.
502settlement_failedL'esito del regolamento è sconosciuto: il pagamento potrebbe essere andato a buon fine, e non è allegata alcuna ricevuta. Prima di firmarne uno nuovo, verifica su Solana o su Base se il pagamento che hai firmato è andato a buon fine.
502, 504upstream_error, upstream_timeoutIl pagamento è stato regolato, ma la chain non ha risposto, o non ha risposto in tempo. La ricevuta è comunque allegata. Per inviare di nuovo la richiesta serve un nuovo pagamento.
Su Solana, una chiamata che leggerebbe troppi dati, come un getProgramAccounts senza filtri su un programma di grandi dimensioni, riceve HTTP 200 e un errore JSON-RPC prima che venga chiesto un pagamento, quindi non costa nulla.

Prossimi passi

PrecedentePanoramicaSuccessivoPrezzi