Paiement par requête (x402)

Un agent avec un portefeuille crypto peut utiliser UberLLM sans compte ni clé API. Il paie pour chaque requête en USDC sur Base, en utilisant le standard de paiement ouvert x402 (version 2).

Cela fonctionne pour le chat : POST /v1/chat/completions et POST /v1/messages. Les images, la vidéo, la musique et la parole nécessitent toujours une clé.

Pour vérifier que le paiement par requête est activé, ouvrez api.uberllm.dev/x402. Il affiche le réseau, le contrat USDC et le portefeuille qui reçoit le paiement. S'il répond "404 not found", le paiement par requête est désactivé. Utilisez plutôt une clé (Démarrage rapide).

Comment ça marche

1. Envoyez la requête sans clé. La réponse est HTTP 402 Payment Required. L'en-tête PAYMENT-REQUIRED (JSON base64, également dans le corps) indique le coût maximal de la requête et les modes de paiement acceptés.
2. Votre portefeuille signe l'une de ces options. Envoyez à nouveau la même requête avec la signature dans l'en-tête PAYMENT-SIGNATURE.
3. UberLLM vérifie le paiement, répond, puis encaisse le paiement. Une réponse normale (non-streaming) est accompagnée du reçu dans l'en-tête PAYMENT-RESPONSE, qui inclut la transaction on-chain.

Chaque signature paie pour une seule requête. Pour faire une autre requête, signez à nouveau.

Ce que vous payez

Le 402 indique le coût maximal possible pour la requête. Cela inclut votre prompt plus max_tokens de sortie, selon l'itinéraire le plus cher que la requête pourrait emprunter. Définissez max_tokens pour maintenir le devis bas.

Il y a deux façons de payer :

• upto (offert en premier). Vous signez le devis comme un plafond. Après la réponse, seul le coût réel est prélevé, arrondi au millionième de dollar supérieur. Le premier paiement nécessite une approbation USDC unique. Lorsque le service de paiement le prend en charge, cette approbation ne nécessite pas de gas.
• exact. Le montant total devisé est prélevé, même si la requête a utilisé moins. Rien n'est remboursé. Choisissez exact uniquement si votre wallet ne peut pas faire upto.

Vous n'êtes jamais facturé plus que le montant que vous avez signé. Si rien n'est servi (aucun modèle disponible, une erreur avant le début de la réponse), rien n'est prélevé.

Essayez-le avec 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 est en unités de base USDC: 1,000,000 est $1. Signez une entrée de accepts avec votre portefeuille. Puis envoyez la même requête à nouveau avec -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Depuis le code

Une bibliothèque cliente x402 gère la signature 402, et la nouvelle tentative pour vous. En 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());

Pour ne payer que le coût réel, enregistrez également UptoEvmScheme depuis @x402/evm/upto/client. Les bibliothèques pour Go et Python sont listées sur x402.org.

Bon à savoir

• Le streaming fonctionne. Avec "stream": true, la réponse est streamée comme d'habitude. Le paiement est collecté lorsque le streaming se termine. Il n'y a pas de header PAYMENT-RESPONSE, car les headers ont déjà été envoyés. Votre portefeuille affiche le transfert.
• Un seul portefeuille, 4 requêtes payantes maximum à la fois.
• Si un paiement ne peut pas être collecté après la réponse (par exemple, si le portefeuille a été vidé entre-temps), une réponse normale est retenue et vous recevez 402 payment_failed. Ce portefeuille ne pourra alors plus payer pendant 24 heures.
• La version 1 x402 (header X-PAYMENT) n'est pas acceptée. Utilisez un client version 2.
• Beaucoup de requêtes ? Un compte avec crédit prépayé est plus simple et n'a pas d'étape on-chain : inscrivez-vous.

Erreurs