Skip to main content
Un agente con una clave de API puede gastar lo que sea que la clave pueda gastar. Eso está bien cuando una persona lo está vigilando e incómodo cuando nadie lo hace. Los arreglos habituales viven fuera del agente, en un panel o en una alerta de facturación que te avisa del problema después de que ocurra. Venice admite una segunda vía. En lugar de una clave, el agente lleva una billetera. Se autentica firmando un mensaje, paga cada petición desde un saldo en USDC vinculado a esa dirección de billetera, y cada cargo cae en un libro contable que puede leer. No hay cuenta, no hay panel y no hay clave que filtrar. El tope es el saldo, y tú decides qué poner ahí. Esta guía construye un agente que hace exactamente eso, bajo un presupuesto que se aplica a sí mismo.

Ejecuta este notebook en Google Colab

Cada paso de abajo como un notebook ejecutable. Funciona sin una billetera financiada y se detiene en el muro de pago, así puedes ver todo el flujo antes de gastar nada.

Cómo funciona

Cuatro piezas en movimiento, tres de las cuales son solo HTTP: La inferencia en sí es la llamada corriente a /chat/completions. La única diferencia está en la cabecera que envías.

Cuánto cuesta empezar

Importan dos números y no son el mismo número. El top-up mínimo son cinco dólares. Es la cantidad más pequeña que /x402/top-up liquidará, y viene devuelto en la respuesta de descubrimiento en lugar de estar hardcodeado en algún sitio, así que léelo en lugar de fiarte de esta página. El saldo mínimo para hacer una llamada son diez centavos. Una billetera con menos de eso recibe un 402 desde inferencia aunque tenga dinero. Así que cinco dólares es la billetera más pequeña que merece la pena financiar, y cinco dólares es lo que esta guía le da al agente. Vale la pena saber qué compra eso: una pregunta corta a qwen3-5-9b cuesta unos veintisiete tokens de entrada y veintiséis de salida, lo que a los precios de ese modelo son aproximadamente siete millonésimas de dólar. Cinco dólares están del orden de las tres cuartas partes de un millón de preguntas. El presupuesto aquí no es una restricción ajustada, es un radio de explosión.

Configuración

El SDK de x402 hace la firma del pago. No lo hagas a mano: la autorización de transferencia son datos tipados EIP-712 y un nonce reutilizado falla la verificación de formas que son tediosas de depurar.
El SDK de Python de x402 requiere Python 3.10 o más reciente. Colab está bien. Un Python de sistema que vino con macOS puede que no.
Crea agent.py con la configuración. BUDGET_USD es el tope que el agente se aplica a sí mismo, aquí fijado a toda la billetera. Bájalo y el agente se detendrá antes que el dinero, que es la única perilla que probablemente cambies.

Una billetera que el agente posee

El agente necesita un par de claves. En producción esta es una billetera que financiaste deliberadamente y cuya clave vive en un gestor de secretos. Mientras construyes, generar una desechable es la jugada correcta, porque una billetera sin dinero no puede hacer nada caro por accidente.
Mantén la clave privada fuera del notebook. En Colab, ponla en Secrets y léela con userdata.get("WALLET_KEY").

Iniciar sesión en lugar de autenticarse

No hay clave que enviar, así que cada petición lleva una prueba de que el dueño de la billetera la hizo. La prueba es un mensaje EIP-4361, firmado y luego codificado en base64 en la cabecera SIGN-IN-WITH-X. El formato del mensaje es exacto. Venice reconstruye estos bytes en su lado y verifica tu firma contra ellos, así que una línea en blanco perdida significa una firma rechazada en vez de un error útil.
Tres reglas gobiernan estas cabeceras, y las tres existen para impedir replay. La firma es válida durante cinco minutos desde Issued At. Cada nonce es de un solo uso durante unos cinco minutos y medio. Y el firmante debe coincidir con la billetera en la ruta, así que una billetera no puede inspeccionar otra y recibe un 403 por intentarlo. La consecuencia práctica es que firmas una cabecera nueva por petición en vez de cachear una. Firmar es local y gratis, así que esto no cuesta nada.
En una billetera nueva:
canConsume es el campo sobre el que ramificar. Tiene en cuenta el piso de diez centavos, así que tú no tienes que hacerlo.

Meter dinero

Recargar son dos peticiones. La primera pregunta qué acepta Venice y no está autenticada, porque todavía no hay nada que autenticar. La segunda lleva una autorización de transferencia firmada.
El descubrimiento devuelve una entrada por vía. Base y Solana hoy:
Dos detalles ahí dentro son fáciles de pasar por alto. amount está en unidades base, y USDC tiene seis decimales, así que 5000000 son cinco dólares y no cinco millones de nada. En la vía de Solana, extra.feePayer es una cuenta operada por Venice que cubre la comisión de la transacción, y eso es lo que permite a una billetera pagar sin tener SOL.
El control de gasto por defecto es lo primero que te detendrá. El SDK viene con max_amount_per_payment fijado en un dólar, y el top-up mínimo de Venice son cinco, así que un cliente sin modificar rechaza cada vía ofrecida y lanza NoMatchingRequirementsError antes de contactar con la red. Sube el tope deliberadamente en lugar de desactivar los controles de gasto.
Liquidar desde una billetera sin USDC devuelve un 400 con PAYMENT_VERIFICATION_FAILED. Esa es la forma esperada del fallo: la firma estaba bien y la transferencia no.

Pagar por llamada

Con un saldo en su sitio, la inferencia es una petición normal que resulta llevar una firma. Apagar el system prompt de Venice importa más de lo que parece: vale unos mil setecientos tokens de entrada por llamada, que son dos órdenes de magnitud más que la pregunta en sí.
Tratar 402 como un resultado normal en lugar de una excepción es todo el diseño. Un agente que paga su propio camino se quedará sin dinero eventualmente, y quedarse sin dinero no es un crash.

Leer lo que gastó

El libro contable es autoritativo. En lugar de estimar desde recuentos de tokens, pregunta qué se cobró realmente.
Cada fila enlaza con la llamada que la causó:
Las filas TOP_UP y REFUND también aparecen aquí, con importes positivos. Filtrar por CHARGE te da el gasto.

La ejecución presupuestada

Ahora el bucle. Antes de cada llamada, el agente comprueba lo que ha gastado, y se niega a empezar un trabajo que no puede pagar.
Ejecútalo con los cinco dólares completos y el presupuesto nunca se activa, que es el resultado honesto a estos precios. Para ver el tope funcionando de verdad, fija uno que una sola llamada supere:

Dónde te deja esto

El agente lleva su propio dinero, prueba su identidad con una firma y no puede superar un límite que tú pones, todo sin que exista una cuenta en ninguna parte. Para un trabajo programado, una función serverless o cualquier cosa a la que preferirías no entregar una clave de larga vida, esa es una postura de seguridad materialmente distinta. Algunas cosas que vale la pena hacer a continuación:

Ponle un tope en el protocolo

Los controles de gasto del SDK son por pago, no por sesión. Combínalos con el bucle de presupuesto de arriba para que un bug en uno no pueda derrotar al otro.

Recarga al vaciarse

Captura el 402, recarga y reintenta. Esto es lo que venice-x402-client hace por ti en el lado de TypeScript.

Paga en Solana

Mismo flujo, distinta vía. Firma Ed25519 y establece el feePayer devuelto para que la billetera no necesite SOL.

Dale trabajo real

Cambia la lista de tareas por un bucle de tool-calling y el libro contable empezará a mostrarte cuánto costó cada decisión.
Para la referencia completa del endpoint, consulta x402 top-up y Usar x402 con la API de Venice.