x402dispatcher

Локальный агрегатор x402 Bazaar для AI-агентов: обнаружение платных API из Coinbase x402 Bazaar, обёртывание их как инструментов Model Context Protocol (MCP), оплата микроплатежей из казначейского кошелька CDP и возврат данных вышестоящего API агенту.

Этот репозиторий сейчас на V4.

Зачем это существует

AI-агенты хорошо умеют рассуждать и использовать инструменты, но плохо умеют платить за API. Протокол x402 превращает HTTP 402 Payment Required в программируемый канал микроплатежей в стейблкоинах (обычно USDC).

x402dispatcher находится посередине как агрегатор, удобный для одиночных операторов:

Средства перемещаются кошелёк → мерчант. Платформа не хранит средства покупателя.

Related MCP server: JMT x402 MCP Server

Дорожная карта

Что делает V4

Поверх маршрутизации V3, V4 записывает успешность и задержку каждого платного вызова в data/api-stats.json, а затем предлагает два уровня:

Пороги (env): VERIFIED_MIN_SAMPLES (по умолчанию 2), VERIFIED_MIN_SUCCESS_RATE (по умолчанию 0.8).

Новые инструменты: get_api_stats, list_verified_apis. quote_route / route_and_call принимают необязательный tier.

Что делает V3

Поверх обнаружения и оплаты V2, V3 добавляет маршрутизатор:

1. quote_route — поиск в Bazaar по задаче на естественном языке, ранжирование кандидатов по общей цене (вышестоящий API + наценка), возврат плана без оплаты

2. route_and_call — то же ранжирование, оплата и вызов самого дешёвого; при сбое попробовать следующий по цене (до max_attempts)

Все расходы остаются ограниченными MAX_PRICE_USD.

Что делает V2

При запуске MCP-сервер:

1. Загружает учётные данные из .env

2. Определяет казначейский кошелёк плательщика CDP Treasury

3. Ищет / перечисляет HTTP-ресурсы Coinbase Bazaar на Base Sepolia (eip155:84532) с ценой не выше MAX_PRICE_USD

4. Регистрирует каждое совпадение как MCP-инструмент

5. Также регистрирует вспомогательные инструменты: search_bazaar, list_discovered_apis, call_x402_api

6. Сохраняет демо-инструмент V1 get_mbta_predictions

Когда агент вызывает обнаруженный инструмент (или call_x402_api):

1. Применять MAX_PRICE_USD к цене вышестоящего API + наценке

2. Оплатить реальную конечную точку x402 с помощью CdpX402Client + wrapFetchWithPayment из @x402/fetch

3. Собирать спред наценки (перевод USDC Treasury → Merchant, когда это возможно)

4. Вернуть { payment, data } агенту

V1 get_mbta_predictions по-прежнему демонстрирует фиксированный перевод $0.01 USDC на Base Sepolia, а затем получает бесплатные публичные данные прогнозов MBTA.

Архитектура

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)

Ключевые пакеты

• @coinbase/cdp-sdk — кошельки, обнаружение Bazaar, CdpX402Client

• @x402/fetch / @x402/core / @x402/evm — цикл оплаты HTTP 402

• @modelcontextprotocol/sdk — MCP-сервер и инструменты

• dotenv, zod, viem

Требования

• Node.js 19+ (требование CDP SDK; рекомендуется 22 LTS)

• Учётные данные Coinbase Developer Platform:

  • CDP_API_KEY_ID

  • CDP_API_KEY_SECRET

  • CDP_WALLET_SECRET (Wallet Secret из CDP Portal → Non-custodial Wallet → Security — не приватный ключ MetaMask)

• Base Sepolia USDC (+ немного ETH для газа) на адресе Treasury

Настройка

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

Переменные окружения

Никогда не коммитьте .env. Отслеживается только .env.example.

Пополнение казначейства

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

Отправьте Base Sepolia USDC (и немного ETH) на напечатанный evmAddress.

Запуск

MCP-сервер (stdio)

npm start

Конфигурация Cursor MCP

Файл проекта: .cursor/mcp.json (уже включён). Cursor должен запустить:

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

Перезагрузите MCP в Cursor после клонирования/установки. Если ${workspaceFolder} не раскрывается в вашей сборке Cursor, установите cwd на абсолютный путь этого репозитория и при необходимости укажите command на ваш бинарник Node 22.

MCP-инструменты

Основные

Динамические инструменты

При запуске x402dispatcher также регистрирует один MCP-инструмент для каждого обнаруженного ресурса Bazaar (имена вида x402_<host>_<path>_<n>). Каждый принимает необязательные query / body и оплачивает URL вышестоящего API.

Тестирование

V4 end-to-end (рекомендуется)

Заполняет два economy-вызова погоды, продвигает победителя в Verified, затем котирует/маршрутизирует с tier=verified:

npm run test:v4

Ожидайте: V4 SMOKE TEST PASSED

Более ранние версии

npm run test:v3
npm run test:v2

Ручные проверки в Cursor

1. Перезагрузите MCP-сервер x402dispatcher

2. Попросите погоду с economy-маршрутизацией пару раз (накапливает статистику)

3. Спросите: «Перечисли проверенные API» / «Получи статистику API»

4. Спросите: «Используй verified-уровень, чтобы получить погоду для Бостона»

5. Подтвердите, что chosen.verified равно true и data/api-stats.json увеличился

Проверка ограничений

Установите MAX_PRICE_USD ниже общей суммы листинга и убедитесь, что quote/route отказывают или возвращают ноль кандидатов.

Структура проекта

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

Замечания по безопасности

• Учётные данные кошелька загружаются только из .env — никогда не хардкодьте секреты.

• Каждый автоматический расход ограничен MAX_PRICE_USD перед подписанием.

• V2 также настраивает контроль расходов CDP x402 (maxAmountPerPayment + список разрешённых сетей Base Sepolia).

• Относитесь к Bazaar как к каталогу, а не к одобрению. Сначала предпочитайте небольшие суммы в тестнете.

• CDP_WALLET_SECRET должен быть секретом кошелька Portal (длинный base64), а не hex-ключом MetaMask.

Ссылки на стек

• Документация Coinbase CDP

• Обнаружение сервисов x402 (Bazaar)

• Краткое руководство покупателя x402

• Model Context Protocol

Лицензия

ISC