API AI x402: paghi a chiamata, senza account

x402 è un protocollo di pagamento aperto che trasforma il codice di stato HTTP 402, rimasto a lungo inutilizzato, in un paywall funzionante: il server risponde a una richiesta con 402 Payment Required più le condizioni di pagamento in formato leggibile dalle macchine, il client firma un’autorizzazione in stablecoin, ripete la stessa richiesta e ottiene la risposta. Niente account, niente chiave API, niente piano mensile. Coinbase ha affidato il protocollo alla Linux Foundation ad aprile 2026 e, quando la x402 Foundation è diventata operativa, contava già 40 organizzazioni aderenti, tra cui AWS, Google, Stripe, Visa e Mastercard. Insomma, non è più un passatempo per appassionati di crypto.

In breve: l’endpoint x402 di BananaBanana è https://bananabanana.pro/api/x402. Fai un POST con { "tool": "...", "arguments": {...} }, ricevi un 402 con il prezzo esatto per quegli argomenti, lo paghi in USDC su Base e ripeti la richiesta. Le immagini partono da $0.03, i video da $0.20, la voce da $0.01 ogni 200 caratteri. Immagini e voce si pagano solo se il file esiste davvero.

Quest’ultima frase è la parte che quasi tutti gli articoli su x402 saltano, quindi ci dedicherò la maggior parte del post. Far pagare è facile. Non far pagare le chiamate andate storte: è lì che il design diventa interessante.

Come avviene davvero il pagamento

Quattro passaggi, e tre li fa il tuo client HTTP.

1. Il tuo agente invia un normale POST in JSON. Nessun header di pagamento.
2. Il server risponde 402 con un array accepts. Ogni requisito di pagamento contiene l’importo in unità atomiche, l’indirizzo del destinatario, il contratto USDC, la chain e una finestra di scadenza.
3. Il tuo client firma un’autorizzazione di trasferimento EIP-3009 per quell’importo esatto e la codifica in base64 nell’header X-PAYMENT.
4. La stessa richiesta riparte, stavolta con l’header. Il server passa la firma a un facilitator per la verifica, esegue il lavoro, poi chiede al facilitator di regolare il pagamento on-chain.

La firma non è una transazione. È un’autorizzazione off-chain che diventa un trasferimento solo quando qualcuno la invia, ed è questo che rende possibile il design in due fasi: prima verifichi, poi lavori, per ultimo incassi.

Un dettaglio pratico. La specifica v2 rinomina gli header in PAYMENT-SIGNATURE e PAYMENT-RESPONSE, ma la maggior parte dei client in circolazione manda ancora X-PAYMENT, quindi oggi accettiamo quello. Se scrivi usando l’SDK TypeScript ufficiale, non te ne accorgerai in nessun caso.

Quanto costa una chiamata

I prezzi sono per generazione e ti vengono comunicati prima che tu firmi qualsiasi cosa. Il numero esatto dipende dagli argomenti (un’immagine 4K non è un’immagine 1K), quindi la risposta 402 prezza la tua richiesta, non una categoria.

Una clip Omni di tre secondi con audio costa $0.30 a 720p, oppure $0.09 come bozza a 360p, e Wan 3.0 ti dà quattro secondi a 480p con audio per $0.20. Sono i video veri più economici della lista e, sinceramente, quelli che uso di più. Veo ha una resa migliore, ma a 8 secondi e 1080p con audio paghi un ordine di grandezza in più per una bozza che magari butterai; Wan a 30 secondi e 1080p è l’altro estremo della scala, a $6.00.

Se preferisci non fidarti di un post di blog, leggi i numeri aggiornati direttamente dalla macchina: GET https://bananabanana.pro/api/x402 restituisce il catalogo completo gratis, senza alcun pagamento.

Due richieste, dall’inizio alla fine

Ecco tutto il flusso con curl, tranne la firma (quella la fa la tua libreria client x402).

# 1. Ask. No payment header: this is the quote.
curl -s -X POST https://bananabanana.pro/api/x402 \
  -H 'Content-Type: application/json' \
  -d '{"tool":"generate_image","arguments":{"prompt":"a paper boat on still water at dawn","model":"nano-banana-pro","resolution":"2048"}}'

{
  "x402Version": 1,
  "error": "Payment required: $0.11 for generate_image.",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "110000",
    "resource": "https://bananabanana.pro/api/x402",
    "payTo": "0x7c0e9abd1c48380e27ab5bfced1be54f23ce773f",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Firma, rimanda la richiesta con l’header, e la seconda risposta contiene l’immagine finita:

{
  "paid_usd": 0.11,
  "result": {
    "status": "completed",
    "images": [{ "url": "https://bananabanana.pro/api/files/..." }]
  }
}

Due dettagli da rubare se stai costruendo il tuo server x402. maxAmountRequired è in unità atomiche. USDC ha sei decimali, quindi $0.11 è 110000, e sbagliare qui è in assoluto il bug di integrazione più comune. E extra.name deve corrispondere a ciò che restituisce la funzione name() del contratto USDC stesso, perché entra nel domain separator EIP-712. Su Base mainnet quella stringa è USD Coin; su Base Sepolia è USDC. Sono diverse, se tiri a indovinare la firma non viene verificata, e l’errore che ricevi non ti dice quasi nulla di utile. Chiedimi come lo so.

Il video è diverso: paghi prima, e se fallisce ricevi un token

Immagini e voce finiscono dentro la richiesta. Quindi l’ordine è verifica → generazione → incasso, e l’incasso avviene solo se dall’altra parte è uscito un file. Un rifiuto del filtro contenuti, un errore a monte, un timeout: nessuno di questi costa nulla a chi paga. La firma semplicemente non viene mai inviata.

Il video non può funzionare così. Un render Veo o Omni richiede da uno a dieci minuti, nessuno tiene aperta una connessione HTTP così a lungo, e una generazione già in corso da Google non si può annullare (il loro interactions.cancel restituisce 501 UNIMPLEMENTED, e l’ho verificato, perché volevo il design più elegante). Quindi il video si paga in anticipo, restituisce un job_id e tu interroghi un endpoint dei risultati gratuito.

Resta la domanda onesta: e se una clip già pagata torna rifiutata?

Ricevi un token di rimborso. Importo pieno, bb_rf_…, valido 90 giorni, utilizzabile su qualsiasi chiamata successiva passandolo come refund_token. Paghi $1.30 per una clip che il classificatore di sicurezza blocca, e la tua prossima chiamata costa $1.30 in meno. Se spendi meno del credito, il resto ti torna come nuovo token.

Non è un rimborso in USDC, e preferisco dirlo chiaramente invece di infiocchettarlo. Questo server non custodisce alcuna chiave privata. Non può far uscire denaro, può solo rifiutarsi di prenderlo, quindi un rimborso on-chain qui è impossibile per architettura. Visto quanti servizi x402 le chiavi invece le custodiscono, lo considero un pregio.

Quella clip è costata $0.30 tramite lo stesso endpoint. Gemini Omni Flash, tre secondi, il prompt era un’unica ripresa continua di inchiostro che si diffonde nell’acqua di una vasca di vetro, luce laterale morbida, con l’audio descritto come un leggero rumore d’ambiente. L’audio lo genera il modello stesso; non esiste una modalità senza audio.

Come un agente trova l’endpoint

Un agente che conosce già l’URL non ha bisogno di scoprirlo. Tutti gli altri sì, per questo il servizio pubblica un manifest su /.well-known/x402 (e su /.well-known/x402.json, perché i crawler provano entrambe le grafie più o meno nella stessa misura, e li abbiamo visti farlo).

Il manifest elenca ogni tool come risorsa a sé, con un blocco completo di requisiti di pagamento, la rete in formato CAIP-2, l’indirizzo di incasso e il facilitator. Lì dentro c’è una scelta voluta: il blocco accepts riporta il prezzo minimo del tool, non il massimo. Da un manifest non puoi comunque firmare un pagamento alla cieca, perché il prezzo dipende dai tuoi argomenti. Ma se pubblicassi il tetto, un agente ben educato pagherebbe volentieri troppo per un’immagine da $0.03. Minimo più una fascia dichiarata: questa è la forma onesta.

I cataloghi, poi, sondano gli endpoint con un POST spazzatura e controllano il codice di stato. Il nostro a quelle richieste risponde 402, con un suggerimento su come indicare il tool. Prima rispondeva 400, che veniva letto come «non abilitato ai pagamenti» e per una settimana ci ha tenuti silenziosamente fuori da due directory.

x402 o un account?

Entrambi gli ingressi portano agli stessi generatori. Scegli in base a quello che ha il tuo agente.

La colonna dei bonus è il vero bivio. Deposita $100 in crypto con un codice promo attivo e sul saldo ti arrivano $120: è uno sconto del 17% che x402 per struttura non può eguagliare, perché non c’è un saldo da ricaricare. D’altra parte, un agente con un wallet e senza email può iniziare a generare in un solo giro di andata e ritorno, ed è proprio questo il punto.

Se preferisci la strada dell’account, il server MCP copre Claude Code, Cursor, VS Code e qualunque altro client che parli Streamable HTTP, e il generatore funziona nel browser. Stessi modelli, stessi prezzi, porta diversa.

FAQ

Mi serve un account Coinbase per pagare?

No. Va bene qualsiasi wallet EVM con USDC su Base. Il trasferimento lo regola il facilitator; nemmeno con lui devi creare un account.

Cosa succede se la mia generazione viene bloccata dal filtro contenuti?

Per immagini e voce non paghi nulla: l’incasso avviene solo dopo che il file esiste. Per il video ricevi un token di rimborso pari all’intero importo, utilizzabile su una chiamata successiva.

Quali chain e token sono supportati?

USDC su Base mainnet, schema exact. Il manifest su /.well-known/x402 riporta il chain id CAIP-2 e l’indirizzo del token, così un client può verificarli prima di firmare.

Posso modificare un video generato tramite x402?

Non tramite x402. La modifica lavora su clip che appartengono a un account, quindi edit_video e la rifinitura conversazionale restano sul lato MCP. Una nuova generazione è sempre disponibile.

Per quanto tempo è valido un prezzo comunicato?

La finestra della firma è di 300 secondi di default, indicata in maxTimeoutSeconds. I prezzi arrivano dalla stessa tabella usata dal sito e non cambiano a metà sessione.

Parti da un’immagine da $0.03 sull’endpoint live. Se il tuo client sa firmare un’autorizzazione EIP-3009, sei a circa quattro righe di codice da un’immagine finita.