Cos'è x402.
x402 è un protocollo aperto per i pagamenti nativi HTTP, pubblicato da Coinbase alla fine del 2024. Definisce come un server restituisce 402 Payment Required con un corpo JSON strutturato - un elenco di requisiti di pagamento accettabili (schema, rete, id della catena, indirizzo del destinatario, importo in unità di base USDC e un id di richiesta di pagamento) - in modo che un client macchina possa analizzare la risposta, pagare on-chain e ripetere la chiamata originale con un'intestazione X-Payment, tutto programmaticamente.
HTTP 402 è rimasto inutilizzato per trenta anni. x402 lo ha fatto funzionare.
The 402 Payment Required status code was reserved in the original HTTP spec for "future use" and never received a standardized implementation. For three decades, every actual payment flow on the web was built on top of 200 / 401 / 403: a server returns 401 when authentication is missing, the client signs up via a separate UI flow, gets credentials, and re-authenticates. The signup happens out of band. None of this works for AI agents, which cannot complete signup forms.
x402 fixes this by giving 402 a usable specification. A server can return 402 with structured machine-readable payment instructions; a client can parse those instructions, pay, and retry, all without ever touching a signup form. The protocol is the missing piece between "AI agents can call APIs" and "AI agents can pay for the APIs they call". Before x402, the only practical agent payment paths were pre-paid balance accounts (with manual top-up) or proprietary integrations per API. Both broke at scale.
L'importanza strategica di x402 è che stabilisce uno standard su cui il resto dell'ecosistema può costruire. I portafogli implementano un gestore x402 una volta, e ogni API conforme a x402 funziona con quel portafoglio. I framework server implementano un middleware x402 una volta, e ogni client consapevole di x402 può pagarli. I facilitatori (servizi che regolano i pagamenti sottostanti) competono sulla qualità del servizio piuttosto che sul lock-in.
Una risposta, un tentativo, un pagamento.
Il ciclo di vita ha tre stati: chiamata non pagata, pagamento, chiamata riprovata. Di seguito è riportato come appare effettivamente la risposta della chiamata non pagata attraverso la rete.
HTTP/1.1 402 Payment Required Content-Type: application/json { "resource": "POST /api/research-query", "accepts": [ { "scheme": "exact-usdc", "network": "mainnet", "chainId": "eip155:8453", "payToAddress": "0xAgent...", "amountWeiUsdc": "50000", "paymentRequestId": "pr_01J9...", "maxAgeSeconds": 60 } ] }
- Status code 402. Distinct from 401 (auth missing) and 403 (auth refused). The presence of 402 signals "payment is the missing input."
- resource + accepts[]. Il corpo nomina la risorsa protetta e elenca uno o più requisiti di pagamento accettabili. Una migrazione può citare due requisiti (ad es. mainnet e testnet) e lasciare che il cliente scelga.
- scheme / network / chainId. Lo schema di pagamento (exact-usdc), la catena (mainnet è Base) e il suo id CAIP-2. Il cliente si abbina a questi prima di pagare.
- payToAddress / amountWeiUsdc. Il wallet del destinatario e l'importo esatto in unità base USDC (50000 = 0.05 USDC, 6 decimali). Il cliente verifica entrambi prima di pagare.
- paymentRequestId + maxAgeSeconds. L'id lega il pagamento a questa quotazione; maxAgeSeconds è quanto deve essere fresco il pagamento. Un pagamento che fa riferimento a un id diverso, o è più vecchio della finestra, viene rifiutato.
- Il ripristino porta un'intestazione X-Payment. Il cliente paga on-chain, poi ripete la richiesta originale con un'intestazione X-Payment che prova il pagamento. Il server lo verifica e restituisce il risultato reale. Nessuna intestazione di risposta o pagina ospitata fa parte del wire x402 stesso.
x402 in natura.
Tre implementazioni concrete, ordinate in base a quanto è matura l'adozione in ciascun layer.
Server MCP che restituisce una sfida 402 a una chiamata di strumento non pagata
Uno strumento MCP a pagamento riceve un'invocazione da Claude Desktop e il chiamante non è ancora contrassegnato come pagato. Il server costruisce una sfida requirePayment - un 402 il cui corpo porta il prezzo e un hostedUrl - e lo restituisce come errore dello strumento. Claude Desktop rende il link nella chat; l'utente paga $0.05 USDC; la chiamata successiva allo stesso strumento ha successo.
Fatturazione per chiamata con gating degli endpoint API
Un'API di ricerca addebita $0.50 per chiamata dietro l'adattatore del server x402. Un agente AI chiama l'endpoint, ottiene un 402 che elenca l'importo e il destinatario, paga su Base dal suo wallet e ripete la richiesta con un'intestazione X-Payment. L'adattatore verifica l'intestazione e restituisce la risposta pagata. L'intero ciclo si completa in meno di 60 secondi.
Agente che paga in modo programmatico tramite portafoglio compatibile con x402
Il runtime di un agente è consapevole di x402 (implementa la specifica). Quando incontra un 402, legge il payToAddress e l'importo da accepts[], firma un trasferimento dal suo portafoglio pre-autorizzato (all'interno del suo permesso di spesa), trasmette su Base e ripete la chiamata originale con un'intestazione X-Payment. Nessun coinvolgimento umano; il ciclo si completa in 5-10 secondi.
Cosa circonda x402 nello stack.
x402 è il protocollo. Questi tre termini coprono i concetti su cui si basa e i casi d'uso che abilita.