x402dispatcher

Local x402 Bazaar Aggregator para agentes de IA: descubre APIs de pago del Coinbase x402 Bazaar, envuélvelas como herramientas del Model Context Protocol (MCP), liquida micropagos desde una cartera de tesorería CDP y devuelve los datos del proveedor al agente.

Este repositorio está actualmente en la V4.

Por qué existe esto

Los agentes de IA son buenos razonando y usando herramientas, pero malos pagando APIs. El protocolo x402 convierte el HTTP 402 Payment Required en un carril de micropagos programable con stablecoins (normalmente USDC).

x402dispatcher se sitúa en medio como un agregador fácil de usar para operadores individuales:

Los fondos van de la cartera al comerciante. La plataforma no custodia los fondos del comprador.

Related MCP server: JMT x402 MCP Server

Hoja de ruta

Qué hace V4

Sobre el enrutamiento de V3, V4 registra el éxito y la latencia de cada llamada de pago en data/api-stats.json y ofrece dos niveles:

Umbrales (env): VERIFIED_MIN_SAMPLES (por defecto 2), VERIFIED_MIN_SUCCESS_RATE (por defecto 0.8).

Nuevas herramientas: get_api_stats, list_verified_apis. quote_route / route_and_call aceptan tier opcional.

Qué hace V3

Sobre el descubrimiento y pago de V2, V3 añade un enrutador:

1. quote_route — busca en el Bazaar una tarea en lenguaje natural, ordena los candidatos por precio total (proveedor + recargo) y devuelve el plan sin pagar

2. route_and_call — misma ordenación, paga y llama al más barato; si falla, prueba con el siguiente más barato (hasta max_attempts)

Todos los gastos siguen limitados por MAX_PRICE_USD.

Qué hace V2

Al iniciarse, el servidor MCP:

1. Carga las credenciales desde .env

2. Resuelve una cartera pagadora de Tesorería CDP

3. Busca / lista los recursos HTTP de Base Sepolia (eip155:84532) de Coinbase Bazaar con un precio igual o inferior a MAX_PRICE_USD

4. Registra cada coincidencia como una herramienta MCP

5. También registra herramientas auxiliares: search_bazaar, list_discovered_apis, call_x402_api

6. Mantiene la herramienta de demostración de V1 get_mbta_predictions

Cuando un agente llama a una herramienta descubierta (o a call_x402_api):

1. Aplicar MAX_PRICE_USD sobre el precio del proveedor + recargo

2. Pagar al endpoint real x402 con CdpX402Client + wrapFetchWithPayment de @x402/fetch

3. Recoger el margen del recargo (transferencia USDC de Tesorería → Comerciante cuando sea posible)

4. Devolver { payment, data } al agente

La herramienta get_mbta_predictions de V1 sigue realizando una transferencia fija de $0.01 USDC en Base Sepolia y luego obtiene los datos públicos gratuitos de predicciones de MBTA.

Arquitectura

Agent / Cursor
    │  MCP (stdio)
    ▼
x402dispatcher MCP server (src/index.ts)
    │
    ├─ Discovery  → listX402DiscoveryResources / searchX402Resources (@coinbase/cdp-sdk)
    ├─ Payment    → CdpX402Client + wrapFetchWithPayment (@coinbase/cdp-sdk/x402, @x402/fetch)
    ├─ Routing    → economy (price) / verified (stats score) with failover
    ├─ Stats      → data/api-stats.json success + latency history
    ├─ Guardrails → MAX_PRICE_USD (+ SDK spend controls)
    └─ Markup     → MARKUP_BPS applied; optional USDC transfer to Merchant account
    │
    ▼
Upstream x402 HTTP API (Bazaar listing)

Paquetes clave

• @coinbase/cdp-sdk — carteras, descubrimiento en el Bazaar, CdpX402Client

• @x402/fetch / @x402/core / @x402/evm — bucle de pago HTTP 402

• @modelcontextprotocol/sdk — servidor MCP + herramientas

• dotenv, zod, viem

Requisitos

• Node.js 19+ (requisito del CDP SDK; se recomienda 22 LTS)

• Credenciales de Coinbase Developer Platform:

  • CDP_API_KEY_ID

  • CDP_API_KEY_SECRET

  • CDP_WALLET_SECRET (Wallet Secret del Portal CDP → Cartera no custodial → Seguridad — no una clave privada de MetaMask)

• USDC en Base Sepolia (+ un poco de ETH para gas) en la dirección de la Tesorería

Configuración

git clone https://github.com/jegamboafuentes/x402dispatcher.git
cd x402dispatcher
npm install
cp .env.example .env
# edit .env with your CDP credentials

Variables de entorno

Nunca hagas commit de .env. Solo se rastrea .env.example.

Financia la tesorería

npx tsx -e "import 'dotenv/config'; import { CdpX402Client } from '@coinbase/cdp-sdk/x402'; const c = new CdpX402Client({ environment: 'development', walletConfig: { type: 'eoa', accountName: 'Treasury' } }); console.log(await c.getAddresses());"

Envía USDC en Base Sepolia (y un poco de ETH) a la evmAddress mostrada.

Ejecución

Servidor MCP (stdio)

npm start

Configuración MCP en Cursor

Archivo del proyecto: .cursor/mcp.json (ya incluido). Cursor debería lanzar:

{
  "mcpServers": {
    "x402dispatcher": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Recarga el MCP en Cursor después de clonar/instalar. Si ${workspaceFolder} no se expande en tu versión de Cursor, configura cwd con la ruta absoluta de este repositorio y, opcionalmente, apunta command a tu binario de Node 22.

Herramientas MCP

Principales

Herramientas dinámicas

Al inicio, x402dispatcher también registra una herramienta MCP por cada recurso del Bazaar descubierto (nombres como x402_<host>_<path>_<n>). Cada una acepta query / body opcionales y paga a la URL del proveedor.

Pruebas

Prueba de extremo a extremo de V4 (recomendada)

Siembra dos llamadas de clima con economy, promueve a la ganadora a Verified y luego cotiza/enruta con tier=verified:

npm run test:v4

Espera: V4 SMOKE TEST PASSED

Versiones anteriores

npm run test:v3
npm run test:v2

Comprobaciones manuales en Cursor

1. Recarga el servidor MCP de x402dispatcher

2. Pide el clima con enrutamiento economy un par de veces (acumula estadísticas)

3. Pregunta: «Lista las APIs verificadas» / «Obtén las estadísticas de API»

4. Pregunta: «Usa el nivel verified para obtener el clima de Boston»

5. Confirma que chosen.verified es true y que data/api-stats.json ha crecido

Comprobación del límite de seguridad

Establece MAX_PRICE_USD por debajo del total de un listado y confirma que quote/route rechazan o devuelven cero candidatos.

Estructura del proyecto

x402dispatcher/
├── src/
│   ├── index.ts       # MCP server, tool registration
│   ├── discovery.ts   # Bazaar list/search → DiscoveredApi
│   ├── payment.ts     # CdpX402Client, markup, MBTA settle
│   ├── routing.ts     # quote + economy/verified route + failover
│   ├── stats.ts       # V4 local success/latency store
│   └── config.ts      # MAX_PRICE_USD, MARKUP_BPS, verified thresholds
├── scripts/
│   ├── v4-smoke-test.ts
│   ├── v3-smoke-test.ts
│   ├── v2-smoke-test.ts
│   ├── mcp-test.ts
│   └── smoke-test.ts
├── data/              # local api-stats.json (gitignored)
├── .cursor/
│   ├── mcp.json
│   └── rules/         # security + x402-stack agent rules
├── AGENTS.md          # product / roadmap context for agents
├── .env.example
└── package.json

Notas de seguridad

• Las credenciales de la cartera se cargan solo desde .env — nunca codifiques secretos.

• Cada gasto automatizado está limitado por MAX_PRICE_USD antes de firmar.

• V2 también configura los controles de gasto de CDP x402 (maxAmountPerPayment + lista blanca de red Base Sepolia).

• Trata el Bazaar como un catálogo, no como un respaldo. Prefiere primero topes pequeños en testnet.

• CDP_WALLET_SECRET debe ser el Wallet Secret del Portal (base64 largo), no una clave hexadecimal de MetaMask.

Referencias del stack

• Documentación de Coinbase CDP

• Descubre los servicios x402 (Bazaar)

• Inicio rápido para compradores de x402

• Model Context Protocol

Licencia

ISC