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.
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.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 cabeceraSIGN-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.
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.
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.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.
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í.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.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.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.