Pague por requisição (x402)

Um agente com uma carteira de criptomoedas pode usar o UberLLM sem conta e sem API key. Ele paga por cada requisição em USDC na Base, usando o padrão de pagamento aberto x402 (versão 2).

Isso funciona para chat: POST /v1/chat/completions e POST /v1/messages. Imagens, vídeo, música e fala ainda precisam de uma key.

Para verificar se o pagamento por requisição está ativado, abra api.uberllm.dev/x402. Ele mostra a rede, o contrato USDC e a carteira que recebe o pagamento. Se a resposta for "404 not found", o pagamento por requisição está desativado. Use uma key em vez disso (Quickstart).

Como funciona

1. Envie a requisição sem chave. A resposta é HTTP 402 Payment Required. O cabeçalho PAYMENT-REQUIRED (JSON base64, também no corpo) informa o custo máximo da requisição e quais formas de pagamento são aceitas.
2. Sua carteira assina uma dessas opções. Envie a mesma requisição novamente com a assinatura no cabeçalho PAYMENT-SIGNATURE.
3. UberLLM verifica o pagamento, responde e então coleta o pagamento. Uma resposta normal (não-streaming) vem com o recibo no cabeçalho PAYMENT-RESPONSE, que inclui a transação on-chain.

Cada assinatura paga por uma requisição. Para fazer outra requisição, assine novamente.

O que você paga

O 402 orça o valor máximo que a requisição pode custar. Isso é o seu prompt mais max_tokens de saída, pela rota mais cara que a requisição pode seguir. Defina max_tokens para manter o orçamento baixo.

Existem duas formas de pagar:

• upto (oferecido primeiro). Você assina o orçamento como um teto. Após a resposta, apenas o custo real é cobrado, arredondado para o próximo milionésimo de dólar. O primeiro pagamento precisa de uma aprovação única de USDC. Onde o serviço de pagamento suporta, essa aprovação não precisa de gas.
• exact. O valor total orçado é cobrado, mesmo que a requisição tenha usado menos. Nada é reembolsado. Escolha exact apenas se sua carteira não puder fazer upto.

Você nunca é cobrado mais do que o valor que assinou. Se nada for servido (nenhum modelo disponível, um erro antes do início da resposta), nada é cobrado.

Experimente com 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á em unidades base USDC: 1,000,000 é $1. Assine uma entrada de accepts com sua carteira. Em seguida, envie a mesma requisição novamente com -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Do código

Uma biblioteca cliente x402 faz a assinatura 402, e a retentativa para você. Em 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());

Para pagar apenas o custo real, registre também UptoEvmScheme de @x402/evm/upto/client. Bibliotecas para Go e Python estão listadas em x402.org.

Bom saber

• Streaming funciona. Com "stream": true, a resposta é transmitida (streamed) normalmente. O pagamento é coletado quando o streaming termina. Não há header PAYMENT-RESPONSE, porque os headers já foram enviados. Sua carteira mostra a transferência.
• Uma carteira, no máximo 4 requisições pagas por vez.
• Se um pagamento não puder ser coletado após a resposta (por exemplo, a carteira foi esvaziada nesse meio tempo), uma resposta normal é retida e você recebe 402 payment_failed. Essa carteira então não poderá pagar por 24 horas.
• A versão 1 x402 (header X-PAYMENT) não é aceita. Use um cliente de versão 2.
• Muitas requisições? Uma conta com crédito pré-pago é mais simples e não tem etapa on-chain: cadastre-se.

Erros