x402dispatcher

AI 에이전트를 위한 로컬 x402 Bazaar 애그리게이터: Coinbase x402 Bazaar에서 유료 API를 발견하고, 이를 Model Context Protocol(MCP) 도구로 래핑하며, CDP 트레저리 지갑에서 마이크로페이먼트를 정산하고, 업스트림 데이터를 에이전트에 반환합니다.

이 저장소는 현재 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를 검색하고, 총 가격(업스트림 + 마크업)으로 후보를 순위화하며, 결제 없이 계획을 반환

2. route_and_call — 동일한 순위화로 가장 저렴한 API에 결제 및 호출; 실패 시 다음으로 저렴한 API 시도 (max_attempts까지)

모든 지출은 MAX_PRICE_USD로 제한됩니다.

V2 기능

시작 시 MCP 서버는:

1. .env에서 자격 증명 로드

2. CDP Treasury 지불자 지갑 해석

3. Base Sepolia (eip155:84532) HTTP 리소스 중 MAX_PRICE_USD 이하 가격의 Coinbase Bazaar 검색/목록화

4. 각 매칭을 MCP 도구로 등록

5. 헬퍼 도구도 등록: search_bazaar, list_discovered_apis, call_x402_api

6. V1 데모 도구 get_mbta_predictions 유지

에이전트가 발견된 도구(또는 call_x402_api)를 호출하면:

1. 업스트림 가격 + 마크업에 MAX_PRICE_USD 적용

2. CdpX402Client + @x402/fetch의 wrapFetchWithPayment로 실제 x402 엔드포인트에 결제

3. 마크업 스프레드 수집 (가능한 경우 Treasury → Merchant USDC 전송)

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 (CDP Portal → Non-custodial Wallet → Security의 Wallet Secret — MetaMask 개인 키가 아님)

• Treasury 주소의 Base Sepolia USDC (+ 가스용 소량 ETH)

설정

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

출력된 evmAddress로 Base Sepolia USDC(및 소량 ETH)를 보내세요.

실행

MCP 서버 (stdio)

npm start

Cursor MCP 설정

프로젝트 파일: .cursor/mcp.json (이미 포함됨). Cursor는 다음을 실행해야 합니다:

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

클론/설치 후 Cursor에서 MCP를 다시 로드하세요. Cursor 빌드에서 ${workspaceFolder}가 확장되지 않으면 cwd를 이 저장소의 절대 경로로 설정하고 선택적으로 command를 Node 22 바이너리로 지정하세요.

MCP 도구

핵심

동적 도구

시작 시 x402dispatcher는 발견된 각 Bazaar 리소스당 하나의 MCP 도구도 등록합니다 (x402_<host>_<path>_<n> 형식). 각 도구는 선택적 query / body를 받고 업스트림 URL에 결제합니다.

테스트

V4 엔드투엔드 (권장)

두 번의 economy 날씨 호출을 시드하고, 승자를 Verified로 승격한 후 tier=verified로 견적/라우팅합니다:

npm run test:v4

예상 결과: V4 SMOKE TEST PASSED

이전 버전

npm run test:v3
npm run test:v2

Cursor에서 수동 확인

1. x402dispatcher MCP 서버 다시 로드

2. economy 라우팅으로 날씨를 두어 번 요청 (통계 축적)

3. "List verified APIs" / "Get API stats" 요청

4. "Use the verified tier to get weather for Boston" 요청

5. chosen.verified가 true이고 data/api-stats.json이 증가했는지 확인

가드레일 확인

MAX_PRICE_USD를 목록의 총액보다 낮게 설정하고 견적/라우팅이 거부하거나 후보를 0개 반환하는지 확인.

프로젝트 구조

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 Wallet Secret(긴 base64)이어야 하며 MetaMask 16진수 키가 아닙니다.

스택 참고 자료

• Coinbase CDP 문서

• x402 서비스 발견 (Bazaar)

• x402 구매자 퀵스타트

• Model Context Protocol

라이선스

ISC