{"id":"32c59a3a-9c79-40c7-8013-3211511ed315","slug":"thebuyside-x402-agent","kind":"mcp","name":"thebuyside-x402-agent","summary":"Buyer-side x402 MCP gateway — let any agent pay any x402 API on Base or Solana without seeing a 402 or a wallet","owner":"jaysperspective","repoUrl":"https://github.com/jaysperspective/thebuyside-x402-agent","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-10T10:14:01.000Z","addedAt":"2026-10-21T06:04:54.156Z","logoUrl":"https://avatars.githubusercontent.com/u/83143386?u=d34ba34108aa050a5c8560814fc9bc0035baed84&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics","memory-knowledge"],"tags":["agents","base","crypto-payments","usdc","x402","agent-payments","solana","stablecoin"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T06:05:25.632Z","sample":false,"url":"https://conduits.dev/tools/thebuyside-x402-agent","language":"TypeScript","transports":["stdio"],"install":{"npm":"thebuyside-x402-agent"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# thebuyside-x402-agent\n\nThe MCP gateway that lets any AI agent discover and pay metered APIs on Base or Solana — without the user wiring payments themselves.\n\n`thebuyside-x402-agent` is the canonical buyer-side reference implementation for two open agent-payment protocols:\n\n- **[x402](https://x402.org)** — the HTTP 402 payment standard stewarded by the Linux Foundation. EVM (Base) and SVM (Solana) via the `exact` scheme.\n- **MPP** — [Machine Payments Protocol](https://paymentauth.org/draft-solana-charge-00.html), the new RFC-7235-style protocol behind [pay.sh](https://pay.sh) (Solana Foundation × Google Cloud, launched May 2026). Solana mainnet USDC.\n\nDrop it into Claude Code, Claude Desktop, Cursor, or any MCP client, and your agent gains three tools:\n\n- **`pay.discover`** — search the curated registry plus three federated indexes (CDP Bazaar, agentic.market, x402watch) for paid APIs\n- **`pay.fetch`** — call one (the gateway pays the 402 challenge automatically, on whichever chain you have a key for, speaking whichever protocol the seller uses)\n- **`pay.wallet_status`** — show the gateway's wallet(s), today's spend, and caps\n\nThe agent never sees the 402, never sees a wallet, never holds a private key.\n\n## Status\n\n**v0.5.0 — first cross-implementation MPP-Solana settlement, 2026-05-11.** End-to-end live runs across all three supported protocol/chain combinations:\n\n> Base mainnet · x402 v2 · `$0.005 USDC` · tx [`0xd0917b35…`](https://basescan.org/tx/0xd0917b35d8b778cf8d0249cc1b107a48ff7125b9fcaf7b4b257d823f73cc6aac)\n>\n> Solana mainnet · x402 v2 · `$0.005 USDC` · tx [`4DYWUMEx…`](https://solscan.io/tx/4DYWUMExSrMNxYLjUuH9G8feN4fmYXm4ToCx7gGaAEjJRf2QNrE8LsvoFSGhXwQJrchhgrnGpUFwjxrci9PRLF71)\n>\n> Solana mainnet · MPP `solana`/`charge` · `$0.001 USDC` · tx [`3UzJ7Uz…`](https://solscan.io/tx/3UzJ7UzhyLwAAFf5Jsnf5jcW9pXUV1BzDswnuxyvNvUgJXnorS5Moozb4fdnqCyy3fwPNLk5jYkqiX8USdpDLJmG)\n\nThat third settlement is, as far as we know, the first cross-implementation [Machine Payments Protocol](https://paymentauth.org/draft-solana-charge-00.html) round-trip on Solana — a JS buyer (this gateway, `@solana/web3.js`) paying a Python/FastAPI seller (news-ep.com, `solders`), with no shared code between sides. See [docs/mpp-implementer-notes.md](docs/mpp-implementer-notes.md) for the wire-format reference and the four pitfalls we hit during pair-test (RFC 7235 multi-challenge gating, strict tx instruction whitelist, `solders` v0-prefix byte gotcha, and middleware-onion ordering).\n\n- 154 unit tests + MCP smoke test, all green\n- **Dual-protocol**: speaks x402 v1 + v2 *and* MPP (`solana`/`charge` intent). `pay.fetch` peeks at the 402 and dispatches transparently — agents never know which protocol the seller uses.\n- Multi-chain: configure either Base (EVM/EIP-3009) or Solana (SVM/SPL-TransferChecked) — or both. Sellers offering multiple chains are routed to whichever you have a signer for. On Solana, the seller's facilitator covers SOL gas — buyer wallet only needs USDC.\n- Federated discovery: `pay.discover` queries the curated `seed.json` + CDP Bazaar + agentic.market + x402watch in parallel and dedupes by canonical endpoint URL\n- Spend caps, host allowlist, receipts log, self-transfer guard — protocol-agnostic\n- Confirm-before-pay via MCP elicitation, with graceful fallback for clients lacking task-creation support (Claude Code)\n- Apache 2.0, DCO not CLA\n\n## Quickstart\n\nTwo steps. You need Node 20+ and a wallet funded with USDC on whichever chain you want to pay on.\n\n### 1. Set at least one wallet key in your environment\n\nFor Base / EVM:\n\n```bash\nexport X402_PAYER_PRIVATE_KEY=0x...\n```\n\n0x-prefixed 64-hex-char private key. Fund the wallet with at least `$0.01 USDC` on Base mainnet.\n\nFor Solana:\n\n```bash\nexport X402_PAYER_SOLANA_KEY=<base58 secret key>\n```\n\nAccepts either base58 (Phantom's \"Show Private Key\" export) or the JSON-array format `solana-keygen new` writes. Fund the wallet with at least `$0.01 USDC` (mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) on Solana mainnet. **Buyer wallet does not need SOL** — facilitators cover network fees as the transaction's `feePayer`.\n\nYou can configure either, both, or neither. With neither, the gateway boots and lists tools but can't pay anything. With both, sellers offering multi-chain options are routed by accept order (typically EVM first); to force a specific chain, configure only that key.\n\nUse a fresh wallet, not your main one. (You can also pass these via your MCP client's `env` block — see below.)\n\n### 2. Register the gateway with your MCP client\n\n**Claude Code (CLI):**\n\n```bash\nclaude mcp add x402-pay -- npx -y thebuyside-x402-agent\n```\n\nOpen a session, type `/mcp` to verify, then ask: *\"Use pay.wallet_status to show my wallet.\"*\n\n**Claude Desktop:**\n\nSee [docs/install-claude-desktop.md](docs/install-claude-desktop.md).\n\n> Local stdio MCP servers can only be reached by **local** MCP clients (Claude Code CLI, Claude Desktop). The claude.ai web app's \"Code\" mode runs in Anthropic's cloud and can't reach a server on your laptop.\n\n## Try it\n\nOnce connected, ask the model:\n\n> *\"Use pay.discover to find APIs about news.\"*\n\n> *\"Use pay.fetch to get https://news-ep.com/api/v1/stories?market=houston&limit=5\"*\n\nThe first returns the registry plus federated matches from CDP Bazaar, agentic.market, and x402watch (each result tagged with its `source`). The second pays `$0.005 USDC` and returns Houston news. news-ep advertises both Base and Solana — the gateway picks whichever chain you have a key for.\n\nAfter a successful call, ask `pay.wallet_status` and you'll see today's spend reflected (and which chains have signers configured).\n\n## Configuration\n\nSpend controls have safe defaults. Override via env if needed.\n\n**Wallet keys** (configure at least one to pay):\n\n| Var | Default | What it does |\n| --- | --- | --- |\n| `X402_PAYER_PRIVATE_KEY` | *(unset)* | Base / EVM private key (0x-prefixed, 64 hex chars) |\n| `X402_PAYER_SOLANA_KEY` | *(unset)* | Solana secret key — base58 (Phantom export) or JSON-array (`solana-keygen`) format |\n| `X402_SOLANA_RPC` | `api.mainnet-beta.solana.com` | Solana RPC for fetching a recent blockhash at sign time |\n\n**Spend caps and confirm-before-pay:**\n\n| Var | Default | What it does |\n| --- | --- | --- |\n| `X402_DAILY_LIMIT` | `1.00` | Max USDC spent per rolling 24h window |\n| `X402_PER_CALL_LIMIT` | `0.05` | Max USDC per single call |\n| `X402_ALLOWLIST` | hosts in `seed.json` | Comma-separated allowed hostnames (replaces default) |\n| `X402_ALLOW_UNVERIFIED` | *(off)* | `1` allows any host — dev only |\n| `X402_REQUIRE_CONFIRM` | `always` | `always`, `never`, or a USDC threshold (e.g. `0.01`). Asks the user to approve via MCP elicitation before signing |\n| `X402_CONFIRM_STRICT` | *(off)* | `1` refuses payment when the client lacks elicitation OR advertises elicitation but lacks tasks/create (e.g. Claude Code as of 2026-05). Default: log a one-time warning and proceed |\n| `X402_RECEIPTS_PATH` | `.local/receipts.jsonl` | Where the receipts log is written |\n\n**Federated discovery** (`pay.discover` queries these in parallel and merges with the local `seed.json`):\n\n| Var | Default | What it does |\n| --- | --- | --- |\n| `X402_FEDERATION` | `on` | `off` disables all external indexes; discover returns local-only results |\n| `X402_FEDERATION_TIMEOUT_MS` | `1500` | Per-source timeout. A slow source produces zero entries (and a warning), never blocks discover |\n| `X402_BAZAAR_URL` | `api.cdp.coinbase.com/platform/v2/x402/discovery/search` | CDP Bazaar endpoint override |\n| `X402_AGENTIC_URL` | `api.agentic.market/v1/services/search` | agentic.market endpoint override |\n| `X402_X402WATCH_URL` | GitHub raw snapshot URL | x402watch daily snapshot URL (the `{date}` placeholder is filled at request time) |\n| `X402_DISABLE_BAZAAR` | *(off)* | `1` skips CDP Bazaar |\n| `X402_DISABLE_AGENTIC` | *(off)* | `1` skips agentic.market |\n| `X402_DISABLE_X402WATCH` | *(off)* | `1` skips x402watch |\n\n**Dev / test:**\n\n| Var | Default | What it does |\n| --- | --- | --- |\n| `X402_TEST_URL` | news-ep stories | Override target for `pnpm pay-newsep` and `pnpm pay-solana` |\n\nLimit values accept either decimal USDC (`0.05`) or atomic units (`50000`). See [docs/configuring-spend-limits.md](docs/configuring-spend-limits.md) for the full spend-controls guide.\n\n## How it works\n\n```\n   Claude Code / Claude Desktop / Cursor\n                  │\n                  │  MCP over stdio\n                  │\n            ┌─────▼─────┐\n            │  Gateway  │   ← src/server.ts (this repo)\n            └─────┬─────┘\n                  │\n                  │  HTTPS GET → 402 challenge → pick chain by signer →\n                  │             EVM: EIP-3009 typed-data sign  ─┐\n                  │             SVM: partial-sign Solana tx    ─┤\n                  │             → retry with PAYMENT-SIGNATURE  │\n                  │             → 200 + body                    │\n            ┌─────▼──────┐         ┌──────────────────┐         │\n            │ x402 server│ ──────→ │ Facilitator      │ ─→ chain settle\n            │ (e.g.      │         │ (verify + submit │     (Base USDC\n            │  news-ep)  │ ←────── │  tx)             │      or Solana USDC)\n            └────────────┘         └──────────────────┘\n```\n\nThe gateway holds the wallet(s), drives the 402 → sign → 200 loop, picks the right chain adapter per challenge, enforces spend caps, and writes a receipts log. The agent stays at the MCP layer and never deals with payment plumbing.\n\n## Run from source\n\nFor contributors and anyone who wants to hack on the gateway:\n\n```bash\ngit clone https://github.com/jaysperspective/thebuyside-x402-agent.git\ncd thebuyside-x402-agent\npnpm install\ncp .env.example .env   # then paste your key into X402_PAYER_PRIVATE_KEY\n```\n\nUseful scripts:\n\n- **`pnpm pay-newsep`** — standalone script that pays news-ep `$0.005` on Base end-to-end without MCP. Verifies your EVM wallet + protocol setup.\n- **`pnpm pay-solana`** — same idea on Solana. Registers ONLY the Solana adapter so it routes via SVM even when the seller offers Base too. Defaults to a target that advertises Solana; override with `X402_TEST_URL`.\n- **`pnpm smoke`** — spawns the MCP server in a subprocess and round-trips a few tool calls. CI-safe; no real payments.\n- **`pnpm verify-seed`** — hits each registry entry's example URL and asserts a valid 402 with the advertised price. Run nightly in CI.\n- **`pnpm test`** — the full vitest unit-test suite (154 tests as of v0.5.0).\n- **`pnpm build`** — compiles to `dist/`. Used by `npm publish`.\n\nTo point your MCP client at the local source instead of the published npm package:\n\n```bash\nclaude mcp add x402-pay -- \"$(pwd)/node_modules/.bin/tsx\" \"$(pwd)/src/index.ts\"\n```\n\n## Adding an API to the registry\n\nThe discover tool reads `src/registry/seed.json`. Adding a new x402-priced endpoint is a single PR — see [docs/adding-an-api.md](docs/adding-an-api.md). CI verifies the entry returns a clean 402 with your advertised price before merge.\n\n## What this is *not*\n\n- An agent framework. Bring your own.\n- An LLM router. Bring your own.\n- A marketplace. The registry is curated open-source data, not a vendor list.\n- A custodial wallet service. Keys live in your `.env`. A managed-wallet (KMS) seam exists for a future hosted version, but the OSS gateway will always work BYO-key.\n\n## Contributing\n\nApache 2.0. Sign your commits with DCO (`git commit -s`). No CLA. PRs welcome — small, focused, with tests.\n\n## License\n\n[Apache License 2.0](./LICENSE).\n"}