Cómo pagar una API x402 desde Claude Code (con un límite de gasto)
Claude Code puede pagar APIs x402 por su cuenta: pide una URL, recibe 402 Payment Required y paga unos céntimos de USDC para obtener la respuesta. Esta guía lo configura con un límite firme. Claude Code recibe fetch_paid, la herramienta de Burnbound que paga APIs, y cada pago que hace se comprueba contra un tope diario, un máximo por pago y una lista de hosts que tú eliges, antes de firmar nada.
Necesitas Node.js 20 o posterior, Claude Code, una cuenta de Burnbound (gratuita) y una cartera con un saldo pequeño de USDC en Base. Para probarlo antes sin dinero real, consulta Pruébalo primero en Base Sepolia.
Qué vas a montar
Al final, puedes pedir a Claude Code algo como «busca en la web noticias recientes de x402 con Exa» y hará esto:
- llama a
get_budgetpara ver lo que puede gastar hoy; - llama a
fetch_paidsobrehttps://api.exa.ai/search; - recibe el precio del vendedor (0.007 USDC por búsqueda la última vez que lo verificamos), Burnbound lo comprueba contra tus reglas, tu cartera lo firma y devuelve los resultados de la búsqueda.
Un pago que incumple una regla se deniega antes de firmarse, y el motivo vuelve a Claude Code como un error de la herramienta. Cada decisión queda en el registro de auditoría del panel.
Paso 1: Crea un agente con topes bajos
Entra en burnbound.dev y pulsa Crear cuenta. El onboarding crea tu primer agente. Elige cifras que no te dolerían si el agente las gastara enteras:
| Ajuste | Ejemplo | Qué hace |
|---|---|---|
| Tope diario | 1 USD |
Lo que el agente puede gastar en total por día UTC. |
| Máximo por pago | 0.05 USD |
Cualquier precio por encima se deniega. |
| Hosts permitidos | api.exa.ai |
Los únicos hosts a los que el agente puede pagar, o incluso pedir con la herramienta. |
| Red | Base | Dónde paga en USDC. Base Sepolia es la red de pruebas. |
Los hosts permitidos son hosts exactos (api.exa.ai) o comodines (*.example.com). Añade solo las APIs a las que quieras que este agente compre. Puedes ver los vendedores x402 verificados, con sus hosts y precios, en el catálogo de APIs x402.
Paso 2: Conecta la cartera que firma
Burnbound decide; tu cartera firma. Elige uno de los dos modos en el panel:
- Coinbase CDP: pega tus credenciales de la API de CDP y la dirección de la cartera. La clave se queda en Coinbase y Claude Code nunca tiene nada que pueda firmar.
- Firma en el cliente: crea una cartera en tu máquina y registra solo su dirección.
npx -y @burnbound/mcp@latest wallet init
El comando imprime una dirección. Pégala en el panel y envíale unos pocos dólares de USDC en Base. La cartera no necesita ETH: en x402, el facilitador del vendedor envía la transferencia y paga el gas.
La firma en el cliente es cooperativa: Claude Code puede ejecutar comandos de shell, así que en teoría podría leer la clave local y firmar por fuera de Burnbound. Si eso te importa, usa CDP. Carteras de agente: Coinbase CDP o una clave local explica las ventajas e inconvenientes.
Paso 3: Añade el servidor MCP a Claude Code
El panel muestra un comando de instalación con la clave de tu agente ya dentro. Se parece a esto:
claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp@latest
--scope user hace que el servidor esté disponible en todos los proyectos. Comprueba que está registrado:
claude mcp list
Después, abre Claude Code y pregunta: «¿Cuál es mi presupuesto de Burnbound?». Llama a get_budget y responde con el gasto de hoy, el tope diario, el máximo por pago, los hosts permitidos y la red. Si funciona, la clave y la conexión están bien. La página de la integración con Claude Code cubre el ámbito de proyecto, los permisos y la resolución de problemas.
Paso 4: Haz la primera petición de pago
La búsqueda x402 de Exa recibe un POST con un cuerpo JSON. Pídeselo a Claude Code con tus palabras, o sé explícito:
Use fetch_paid to POST https://api.exa.ai/search with the JSON body
{"query": "x402 payments for AI agents", "numResults": 5}
and the header Content-Type: application/json, with maxAmountUsd "0.02".
maxAmountUsd es un techo por llamada que el servidor MCP comprueba además de tu política. Si el precio es mayor, la llamada falla con amount_exceeds_max y no se paga nada.
Una llamada correcta devuelve status: "paid" con amountUsd, network, intentId, un receipt y el cuerpo de la respuesta. El cuerpo va marcado como contenido no fiable de un tercero, así que su texto no puede hacerse pasar por instrucciones tuyas. El pago aparece en el panel con su transacción en la cadena.
Paso 5: Comprueba que el límite funciona
Pide algo que la política no permite, por ejemplo un host que no está en la lista:
Use fetch_paid to GET https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools?query=weth&network=eth
El servidor MCP lo rechaza antes de enviar nada: host_not_allowed. Si añades el host y el precio supera el máximo por pago, recibes policy_denied con amount_exceeds_per_transaction. Cuando el gasto del día superaría el tope diario, todos los pagos reciben policy_denied con daily_cap_exceeded hasta la medianoche UTC. En todos los casos no se firmó nada.
| Resultado | Qué significa |
|---|---|
paid |
Firmado, enviado y servido. Cuenta para el tope de hoy. |
ok |
La URL no pidió ningún pago. No se pagó nada. |
pending_approval |
Primero decide una persona: el primer pago a una dirección de cobro nueva, o un importe en el umbral de aprobación o por encima. |
host_not_allowed |
El host no está en la lista del agente. No se envió nada. |
policy_denied con daily_cap_exceeded |
Supera el tope de hoy. No se firmó nada. |
policy_denied con amount_exceeds_per_transaction |
Supera el máximo por pago. No se firmó nada. |
Pruébalo primero en Base Sepolia
Para recorrer todo el flujo con USDC de prueba sin valor:
- Pon la red del agente en Base Sepolia en el onboarding, o después en la pestaña Red del agente.
- Recarga la cartera con USDC de prueba del faucet de Circle.
- Añade
demo.burnbound.deva los hosts permitidos. - Pide a Claude Code:
Use fetch_paid to GET https://demo.burnbound.dev/premium with maxAmountUsd "0.05".
Nuestro vendedor de demostración cobra 0.01 USDC por /premium, 0.50 por /report y 2.00 por /dataset. Con los valores por defecto del onboarding (1 USD por pago), /premium se paga al momento y /dataset se deniega con amount_exceeds_per_transaction; /report espera una aprobación si el umbral de aprobación del agente es de 0.50 USD o menos. Solo vende en Base Sepolia. Su primer pago no necesita aprobación porque está en el catálogo de Burnbound con su dirección de cobro fijada; el primer pago a una dirección de cobro nueva de otro vendedor espera una vez la tuya (new_pay_to). Cuando termines, vuelve a poner el agente en Base y recarga la cartera con USDC real en Base.
Deja que Claude Code encuentre APIs por sí mismo
search_paid_apis busca en el catálogo de APIs x402 verificadas de Burnbound y le dice al agente, para cada resultado, si su política dejaría que fetch_paid lo pagara:
Use search_paid_apis to find an API for crypto prices on Base.
Cada resultado trae el host, una petición de ejemplo, el precio y allowedByPolicy con lo que lo bloquea, como host_not_allowed. El catálogo nunca amplía por su cuenta lo que el agente puede pagar: una persona tiene que añadir el host, o activar la regla de hosts del catálogo del agente, y después el primer pago a cada host nuevo espera una aprobación. El mismo catálogo es público en /apis.
Siguientes pasos
- Haz que los pagos por encima de un umbral te esperen: Aprobación humana de los pagos de agentes con Slack.
- Entiende cada límite que puedes fijar: Cómo limitar el gasto de un agente de IA.
- Referencia completa de las herramientas: Herramientas MCP.
- Deja que el mismo agente reembolse cargos de Stripe con los mismos topes: Gateway de acciones: reembolsos de Stripe.
- Empieza desde cero con los Primeros pasos.