Betalen per verzoek (x402)

Een agent met een crypto wallet kan UberLLM gebruiken zonder account en zonder API key. Het betaalt voor elk verzoek in USDC op Base, met behulp van de open x402 betaalstandaard (versie 2).

Dit werkt voor chat: POST /v1/chat/completions en POST /v1/messages. Afbeeldingen, video, muziek en spraak hebben nog steeds een key nodig.

Om te controleren of betalen-per-verzoek is ingeschakeld, open api.uberllm.dev/x402. Het toont het netwerk, het USDC contract en de wallet die betaald krijgt. Als het antwoordt "404 not found", is betalen-per-verzoek uitgeschakeld. Gebruik in plaats daarvan een key (Quickstart).

Hoe het werkt

1. Stuur het verzoek zonder key. Het antwoord is HTTP 402 Payment Required. De PAYMENT-REQUIRED header (base64 JSON, ook in de body) zegt hoeveel het verzoek maximaal mag kosten, en welke betaalmethoden worden geaccepteerd.
2. Je wallet ondertekent een van die opties. Stuur hetzelfde verzoek opnieuw met de handtekening in de PAYMENT-SIGNATURE header.
3. UberLLM controleert de betaling, antwoordt, en int vervolgens de betaling. Een normaal (non-streaming) antwoord komt met de bon in de PAYMENT-RESPONSE header, die de on-chain transactie bevat.

Elke handtekening betaalt voor één verzoek. Om een ander verzoek te doen, onderteken opnieuw.

Wat je betaalt

De 402 geeft de maximale kosten van het verzoek weer. Dat is je prompt plus max_tokens aan uitvoer, via de duurste route die het verzoek kan nemen. Stel max_tokens in om de offerte laag te houden.

Er zijn twee manieren om te betalen:

• upto (eerst aangeboden). Je ondertekent de offerte als een maximum. Na het antwoord worden alleen de werkelijke kosten in rekening gebracht, naar boven afgerond op het volgende miljoenste deel van een dollar. De eerste betaling vereist een eenmalige USDC-goedkeuring. Waar de betaaldienst dit ondersteunt, is voor die goedkeuring geen gas nodig.
• exact. Het volledige geoffreerde bedrag wordt in rekening gebracht, zelfs als het verzoek minder heeft gebruikt. Er wordt niets terugbetaald. Kies exact alleen als je wallet upto niet kan doen.

Je wordt nooit meer in rekening gebracht dan het bedrag dat je hebt ondertekend. Als er niets wordt geleverd (geen model beschikbaar, een fout voordat het antwoord begint), wordt er niets in rekening gebracht.

Probeer het met 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 is in USDC basiseenheden: 1,000,000 is $1. Onderteken één item van accepts met je wallet. Verzend vervolgens dezelfde aanvraag opnieuw met -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Vanuit code

Een x402 clientbibliotheek doet de 402, ondertekening en herhaalpoging voor je. 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());

Om alleen de werkelijke kosten te betalen, registreer ook UptoEvmScheme van @x402/evm/upto/client. Bibliotheken voor Go en Python staan vermeld op x402.org.

Goed om te weten

• Streaming werkt. Met "stream": true streamt het antwoord zoals gewoonlijk. De betaling wordt geïnd wanneer de stream eindigt. Er is geen PAYMENT-RESPONSE header, omdat de headers al zijn verzonden. Je wallet toont de overboeking.
• Eén wallet, maximaal 4 betaalde verzoeken tegelijk.
• Als een betaling niet kan worden geïnd na het antwoord (bijvoorbeeld, de wallet is in de tussentijd leeggemaakt), wordt een normaal antwoord tegengehouden en krijg je 402 payment_failed. Die wallet kan dan 24 uur lang niet betalen.
• Versie 1 x402 (X-PAYMENT header) wordt niet geaccepteerd. Gebruik een versie 2 client.
• Veel verzoeken? Een account met prepaid tegoed is eenvoudiger en heeft geen on-chain stap: meld je aan.

Fouten