x402: come un'IA paga un'API senza avere un account

Ogni API su internet si vende attraverso un modulo.

Arrivi su una pagina prezzi, scrivi un’email, la confermi dalla casella, incolli una carta, copi una chiave e la metti in una variabile d’ambiente. Sono quattro minuti e funziona benissimo — perché sei un essere umano, e gli esseri umani hanno una casella di posta, una carta e pazienza.

Ora immagina un agente IA a metà di un ciclo di ricerca. Gli serve una pagina web convertita in Markdown, adesso, per finire il compito che gli è stato affidato. Non può ricevere un’email di conferma. Non ha una carta. Non può aspettare che un umano si svegli e gli incolli una chiave.

Così fa l’unica cosa che gli resta: rinuncia e usa qualcos’altro.

È esattamente il vuoto che colma x402 — e da oggi l’API Minibase ci risponde in produzione.

HTTP ci aveva pensato nel 1997

Il codice di stato 402 Payment Required è nella specifica HTTP fin dall’inizio, con la dicitura «riservato per uso futuro». Per quasi trent’anni è rimasto la barzelletta della RFC: il codice che nessuno poteva implementare, perché il web non aveva modo di muovere piccole somme dentro una richiesta.

x402 è il protocollo che finalmente lo usa. La forma sta in tre passaggi:

1. Un client chiama il tuo endpoint senza alcuna credenziale.
2. Invece di un 401 Unauthorized, il server risponde 402 Payment Required e allega condizioni di pagamento leggibili da una macchina: quanto, in quale asset, su quale rete, verso quale indirizzo.
3. Il client paga e ripete la richiesta con la prova di pagamento allegata. Il server verifica, regola e serve la risposta.

Nessun account. Nessuna chiave. Nessuna dashboard. Tutta la negoziazione avviene in due giri HTTP, in un formato che un altro programma sa leggere.

Che aspetto ha su un endpoint reale

Chiama il nostro endpoint di conversione senza niente:

curl -i -X POST https://api.minibase.md/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

Ottieni un 402, e le condizioni tornano codificate in base64 in un header payment-required:

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xfb8157a583e3050440301f418f5e890190222a5c",
    "maxTimeoutSeconds": 300
  }]
}

C’è tutto quello che serve a un client autonomo. network è un identificatore CAIP-2 — eip155:8453 è Base mainnet. asset è il contratto USDC. amount è in unità atomiche: USDC ha sei decimali, quindi 10000 è un centesimo. payTo è dove finiscono i soldi.

Il client firma un trasferimento USDC, ripete la richiesta con il pagamento allegato e riceve il suo Markdown. Coinvolgimento umano: zero.

La parte che nessuno menziona: non devi detenere cripto

L’obiezione ovvia a qualsiasi discorso su «accetta stablecoin» è che ora gestisci un portafoglio. Chiavi private. Custodia. Un saldo denominato in qualcosa che il tuo commercialista non ha mai visto, valorizzato a un cambio che si è mosso mentre dormivi.

Noi non facciamo niente di tutto ciò, e nemmeno tu devi. L’indirizzo di deposito nel payload qui sopra è stato emesso da Stripe. I pagamenti vengono regolati on-chain verso quell’indirizzo, Stripe registra ciascuno come un normale PaymentIntent e liquida in euro secondo il calendario abituale.

La conseguenza pratica è che il denaro compare nella stessa dashboard di qualsiasi pagamento con carta, sullo stesso bonifico, negli stessi libri. Nessun portafoglio da proteggere, nessuna valutazione valutaria ricevuta per ricevuta, nessun registro parallelo da riconciliare a fine anno. La parte stablecoin è reale, ed è al tempo stesso del tutto invisibile dal lato contabile.

Due cose che ci sono costate tempo

Se lo implementi da solo, ecco le due trappole che abbiamo pagato.

L’handshake con il facilitatore non è opzionale. Un resource server deve chiedere al facilitatore quali coppie schema/rete regola davvero prima di poter quotare qualcosa. Salta quel passaggio e ogni singola chiamata muore con Facilitator does not support exact on eip155:8453 — un messaggio che sembra un errore di configurazione ed è in realtà un giro di rete mancante. Sul mainnet quel facilitatore è quello di Coinbase; quello pubblico di testnet non regola denaro vero.

Un prezzo sotto il centesimo rompe la contabilità in silenzio. Il nostro costo è di circa 0,002 $ a pagina, quindi mettere la porta x402 a 0,002 $ sembrava ovvio. Non lo è: i PaymentIntent sono denominati in centesimi interi, quindi qualsiasi cifra sotto il centesimo viene regolata on-chain e poi non può essere registrata affatto. Il denaro arriva e non entra in nessun libro. Per questo la porta senza chiave costa 0,01 $ a chiamata — cinque volte la nostra tariffa a volume, che un pagamento a chiamata senza account né impegno sostiene senza problemi.

Vale la pena aggiungerlo?

Siamo onesti sulle proporzioni: x402 non sostituirà i tuoi abbonamenti questo trimestre. I pagamenti avviati da agenti sono agli inizi, gli strumenti lato client sono giovani, e la maggior parte dei tuoi clienti resta umana e con una carta.

Ma l’asimmetria è insolita. Costruire la porta ci è costato qualche centinaio di righe e scatta solo per chi non presenta alcuna credenziale — ogni possessore di chiave cade dritto nel percorso che aveva già, stessa quota, stesso piano. Niente di ciò che vendi già viene messo a rischio.

E il modo di fallire del non averlo è invisibile. Un chiamante senza chiave che incontra un 401 non lascia traccia: nessuna registrazione, nessun ticket, nemmeno una riga nelle statistiche. Non scopri mai che è passato. Ora lo misuriamo apposta — ogni chiamata senza credenziali viene registrata, insieme all’informazione se il chiamante parla già il protocollo — perché «c’è qualcuno che bussa?» è l’unica domanda che decide se tutto questo valeva la pena.

Se gli agenti devono comprare cose sul web aperto, serve loro un modo di pagare che non passi da un modulo di registrazione. Quel modo esiste già, dorme nella specifica HTTP dal 1997, e si collega in un pomeriggio.

---

Provalo: chiama POST https://api.minibase.md/v1/convert senza credenziali e leggi l’header payment-required. Preferisci una chiave? Il piano gratuito dà 1.000 pagine al mese, senza carta. Specifica completa per gli agenti: minibase.md/api.md.