x402dispatcher

Lokaler x402 Bazaar Aggregator für KI-Agenten: Entdecke kostenpflichtige APIs aus dem Coinbase x402 Bazaar, verpacke sie als Model Context Protocol (MCP)-Tools, wickle Mikrozahlungen aus einer CDP-Treasury-Wallet ab und gib die Upstream-Daten an den Agenten zurück.

Dieses Repository befindet sich derzeit bei V4.

Warum es das gibt

KI-Agenten sind gut im Denken und in der Werkzeugnutzung, aber schlecht darin, für APIs zu bezahlen. Das x402-Protokoll verwandelt HTTP 402 Payment Required in eine programmierbare Stablecoin-Mikrozahlungsschiene (typischerweise USDC).

x402dispatcher sitzt dazwischen als ein für Einzelbetreiber freundlicher Aggregator:

Gelder fließen von Wallet zu Händler. Die Plattform verwahrt keine Käufergelder.

Related MCP server: JMT x402 MCP Server

Roadmap

Was V4 tut

Zusätzlich zum V3-Routing zeichnet V4 den Erfolg und die Latenz jedes bezahlten Aufrufs in data/api-stats.json auf und bietet dann zwei Tiers:

Schwellenwerte (env): VERIFIED_MIN_SAMPLES (Standard 2), VERIFIED_MIN_SUCCESS_RATE (Standard 0.8).

Neue Tools: get_api_stats, list_verified_apis. quote_route / route_and_call akzeptieren optional tier.

Was V3 tut

Zusätzlich zu V2-Entdeckung + Zahlung fügt V3 einen Router hinzu:

1. quote_route — Bazaar nach einer natürlichsprachlichen Aufgabe durchsuchen, Kandidaten nach Gesamtpreis (Upstream + Aufschlag) sortieren, den Plan ohne zu bezahlen zurückgeben

2. route_and_call — gleiche Sortierung, günstigste bezahlen und aufrufen; bei Fehler die nächstgünstigere versuchen (bis zu max_attempts)

Alle Ausgaben bleiben durch MAX_PRICE_USD begrenzt.

Was V2 tut

Beim Start tut der MCP-Server Folgendes:

1. Lädt Anmeldedaten aus .env

2. Löst eine CDP-Treasury-Zahler-Wallet auf

3. Durchsucht/listet den Coinbase Bazaar nach Base Sepolia (eip155:84532) HTTP-Ressourcen, die bei oder unter MAX_PRICE_USD liegen

4. Registriert jeden Treffer als MCP-Tool

5. Registriert außerdem Hilfstools: search_bazaar, list_discovered_apis, call_x402_api

6. Behält das V1-Demo-Tool get_mbta_predictions

Wenn ein Agent ein entdecktes Tool (oder call_x402_api) aufruft:

1. MAX_PRICE_USD auf Upstream-Preis + Aufschlag durchsetzen

2. Den echten x402-Endpunkt mit CdpX402Client + wrapFetchWithPayment aus @x402/fetch bezahlen

3. Die Aufschlagsspanne einsammeln (Treasury → Händler-USDC-Übertragung, wenn möglich)

4. { payment, data } an den Agenten zurückgeben

Das V1-get_mbta_predictions beweist weiterhin eine feste $0.01 USDC Base Sepolia-Übertragung und ruft dann kostenlose öffentliche MBTA-Vorhersagedaten ab.

Architektur

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)

Wichtige Pakete

• @coinbase/cdp-sdk — Wallets, Bazaar-Entdeckung, CdpX402Client

• @x402/fetch / @x402/core / @x402/evm — HTTP-402-Zahlungsschleife

• @modelcontextprotocol/sdk — MCP-Server + Tools

• dotenv, zod, viem

Anforderungen

• Node.js 19+ (CDP-SDK-Anforderung; 22 LTS empfohlen)

• Coinbase Developer Platform-Anmeldedaten:

  • CDP_API_KEY_ID

  • CDP_API_KEY_SECRET

  • CDP_WALLET_SECRET (Wallet Secret aus CDP Portal → Non-custodial Wallet → Security — kein MetaMask-Private-Key)

• Base Sepolia USDC (+ etwas ETH für Gas) auf der Treasury-Adresse

Einrichtung

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

Umgebungsvariablen

.env niemals committen. Nur .env.example wird versioniert.

Treasury finanzieren

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());"

Sende Base Sepolia USDC (und etwas ETH) an die ausgegebene evmAddress.

Ausführen

MCP-Server (stdio)

npm start

Cursor-MCP-Konfiguration

Projektdatei: .cursor/mcp.json (bereits enthalten). Cursor sollte starten:

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

MCP in Cursor nach Klonen/Installieren neu laden. Wenn ${workspaceFolder} in deinem Cursor-Build nicht expandiert wird, setze cwd auf den absoluten Pfad dieses Repos und weise command optional auf dein Node-22-Binary.

MCP-Tools

Kern

Dynamische Tools

Beim Start registriert x402dispatcher außerdem ein MCP-Tool pro entdeckter Bazaar-Ressource (Namen wie x402_<host>_<path>_<n>). Jedes akzeptiert optional query / body und bezahlt die Upstream-URL.

Testen

V4-End-to-End (empfohlen)

Sät zwei Economy-Wetteraufrufe, befördert den Gewinner in Verified und quotet/routet dann mit tier=verified:

npm run test:v4

Erwartung: V4 SMOKE TEST PASSED

Frühere Versionen

npm run test:v3
npm run test:v2

Manuelle Prüfungen in Cursor

1. Den x402dispatcher-MCP-Server neu laden

2. Ein paar Mal nach Wetter mit Economy-Routing fragen (baut Statistiken auf)

3. Fragen: „Verified-APIs auflisten“ / „API-Statistiken abrufen“

4. Fragen: „Nutze den Verified-Tier, um Wetter für Boston zu bekommen“

5. Bestätigen, dass chosen.verified true ist und data/api-stats.json gewachsen ist

Schutzprüfung

Setze MAX_PRICE_USD unter den Gesamtpreis eines Listings und bestätige, dass Quote/Route ablehnen oder null Kandidaten zurückgeben.

Projektstruktur

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

Sicherheitshinweise

• Wallet-Anmeldedaten werden nur aus .env geladen — niemals Geheimnisse hartkodieren.

• Jede automatisierte Ausgabe ist vor dem Signieren durch MAX_PRICE_USD begrenzt.

• V2 konfiguriert außerdem CDP-x402-Ausgabenkontrollen (maxAmountPerPayment + Base Sepolia-Netzwerk-Allowlist).

• Behandle den Bazaar als Katalog, nicht als Empfehlung. Bevorzuge zuerst kleine Limits im Testnetz.

• CDP_WALLET_SECRET muss das Portal-Wallet-Secret (langes base64) sein, kein MetaMask-Hex-Schlüssel.

Stack-Referenzen

• Coinbase CDP-Dokumentation

• x402-Dienste entdecken (Bazaar)

• x402-Käufer-Schnellstart

• Model Context Protocol

Lizenz

ISC