Pago por solicitud (x402)

Un agente con una billetera de criptomonedas puede usar UberLLM sin cuenta y sin API key. Paga por cada solicitud en USDC en Base, usando el estándar de pago abierto x402 (versión 2).

Esto funciona para chat: POST /v1/chat/completions y POST /v1/messages. Imágenes, video, música y voz aún necesitan una key.

Para comprobar que el pago por solicitud está activado, abre api.uberllm.dev/x402. Muestra la network, el contrato de USDC y la billetera a la que se le paga. Si responde "404 not found", el pago por solicitud está desactivado. Usa una key en su lugar (Quickstart).

Cómo funciona

1. Envía la solicitud sin clave. La respuesta es HTTP 402 Payment Required. El encabezado PAYMENT-REQUIRED (JSON base64, también en el cuerpo) indica cuánto puede costar la solicitud como máximo y qué formas de pago se aceptan.
2. Tu cartera firma una de esas opciones. Envía la misma solicitud de nuevo con la firma en el encabezado PAYMENT-SIGNATURE.
3. UberLLM verifica el pago, responde y luego cobra el pago. Una respuesta normal (no streaming) viene con el recibo en el encabezado PAYMENT-RESPONSE, que incluye la transacción en cadena.

Cada firma paga por una solicitud. Para hacer otra solicitud, firma de nuevo.

Lo que pagas

El 402 te cotiza el máximo que la solicitud puede costar. Esto es tu prompt más max_tokens de salida, por la ruta más cara que la solicitud pueda tomar. Configura max_tokens para mantener la cotización baja.

Hay dos formas de pagar:

• upto (ofrecido primero). Firmas la cotización como un tope. Después de la respuesta, solo se cobra el costo real, redondeado al siguiente millonésimo de dólar. El primer pago requiere una aprobación única de USDC. Si el servicio de pago lo soporta, esa aprobación no requiere gas.
• exact. Se cobra el monto total cotizado, incluso si la solicitud utilizó menos. No se reembolsa nada. Elige exact solo si tu billetera no puede hacer upto.

Nunca se te cobra más de la cantidad que firmaste. Si no se entrega nada (ningún modelo disponible, un error antes de que la respuesta comience), no se cobra nada.

Pruébalo 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 está en unidades base de USDC: 1,000,000 es $1. Firma una entrada de accepts con tu billetera. Luego envía la misma solicitud de nuevo con -H 'PAYMENT-SIGNATURE: <base64 payment>'.

Desde código

Una biblioteca cliente x402 se encarga de la firma 402, y el reintento por ti. 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());

Para pagar solo el costo real, registra también UptoEvmScheme de @x402/evm/upto/client. Las bibliotecas para Go y Python se encuentran en x402.org.

A tener en cuenta

• El streaming funciona. Con "stream": true, la respuesta hace streaming como de costumbre. El pago se cobra cuando el stream termina. No hay un header PAYMENT-RESPONSE, porque los headers ya fueron enviados. Tu wallet muestra la transferencia.
• Una wallet, un máximo de 4 solicitudes pagadas a la vez.
• Si un pago no puede ser cobrado después de la respuesta (por ejemplo, la wallet se vació mientras tanto), una respuesta normal es retenida y recibes 402 payment_failed. Esa wallet entonces no podrá pagar durante 24 horas.
• La versión 1 x402 (header X-PAYMENT) no es aceptada. Usa un cliente de la versión 2.
• ¿Muchas solicitudes? Una cuenta con crédito prepagado es más sencilla y no tiene un paso on-chain: regístrate.

Errores