Paga per richiesta (x402)

Un agente con un wallet crypto può usare UberLLM senza nessun account e nessuna API key. Paga per ogni richiesta in USDC su Base, usando lo standard di pagamento aperto x402 (versione 2).

Questo funziona per la chat: POST /v1/chat/completions e POST /v1/messages. Immagini, video, musica e parlato hanno ancora bisogno di una chiave.

Per verificare che il pagamento per richiesta sia attivo, apri api.uberllm.dev/x402. Mostra la rete, il contratto USDC e il wallet che riceve il pagamento. Se risponde "404 not found", il pagamento per richiesta è disattivato. Usa una chiave invece (Quickstart).

Come funziona

1. Invia la richiesta senza chiave. La risposta è HTTP 402 Payment Required. L'header PAYMENT-REQUIRED (JSON base64, anche nel corpo) indica il costo massimo della richiesta e quali metodi di pagamento sono accettati.
2. Il tuo wallet firma una di queste opzioni. Invia di nuovo la stessa richiesta con la firma nell'header PAYMENT-SIGNATURE.
3. UberLLM verifica il pagamento, risponde, quindi riscuote il pagamento. Una risposta normale (non-streaming) include la ricevuta nell'header PAYMENT-RESPONSE, che comprende la transazione on-chain.

Ogni firma paga per una richiesta. Per fare un'altra richiesta, firma di nuovo.

Cosa paghi

Il 402 indica il costo massimo che la richiesta può avere. Questo include il tuo prompt più max_tokens di output, calcolato sulla rotta più costosa che la richiesta potrebbe prendere. Imposta max_tokens per mantenere il preventivo basso.

Ci sono due modi per pagare:

• upto (offerto per primo). Firmi il preventivo come tetto massimo. Dopo la risposta, viene prelevato solo il costo reale, arrotondato per eccesso al milionesimo di dollaro successivo. Il primo pagamento richiede un'approvazione USDC una tantum. Laddove il servizio di pagamento lo supporti, tale approvazione non richiede gas.
• exact. Viene prelevato l'intero importo preventivato, anche se la richiesta ha utilizzato meno. Nulla viene rimborsato. Scegli exact solo se il tuo wallet non può fare upto.

Non ti viene mai addebitato più dell'importo che hai firmato. Se non viene servito nulla (nessun modello disponibile, un errore prima che la risposta inizi), nulla viene prelevato.

Provalo con curl

curl -i https://api.uberllm.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"deepseek/deepseek-v4-flash","max_tokens":200,"messages":[{"role":"user","content":"Hello"}]}'
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi…
#
# {"x402Version":2,"error":"PAYMENT-SIGNATURE header is required",
#  "accepts":[{"scheme":"upto","network":"eip155:8453","amount":"…","asset":"0x8335…2913","payTo":"0x…",…},
#             {"scheme":"exact",…}]}

amount è in unità base USDC: 1,000,000 è $1. Firma una voce di accepts con il tuo wallet. Quindi invia di nuovo la stessa richiesta con -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Dal codice

Una libreria client x402 gestisce per te la firma 402, e il retry. In JavaScript:

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://api.uberllm.dev/v1/chat/completions", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    model: "deepseek/deepseek-v4-flash",
    max_tokens: 200,
    messages: [{ role: "user", content: "Hello" }],
  }),
});
console.log(await res.json());

Per pagare solo il costo reale, registra anche UptoEvmScheme da @x402/evm/upto/client. Le librerie per Go e Python sono elencate su x402.org.

Utile da sapere

• Lo streaming funziona. Con "stream": true, la risposta viene trasmessa in streaming come al solito. Il pagamento viene riscosso al termine dello streaming. Non c'è un header PAYMENT-RESPONSE, perché gli header sono già stati inviati. Il tuo wallet mostra il trasferimento.
• Un wallet, al massimo 4 richieste a pagamento alla volta.
• Se un pagamento non può essere riscosso dopo la risposta (ad esempio, il wallet è stato svuotato nel frattempo), una risposta normale viene bloccata e ricevi 402 payment_failed. Quel wallet non potrà quindi pagare per 24 ore.
• La versione 1 x402 (header X-PAYMENT) non è accettata. Usa un client versione 2.
• Hai molte richieste? Un account con credito prepagato è più semplice e non ha passaggi on-chain: registrati.

Errori