thebuyside-x402-agent

thebuyside-x402-agent

The MCP gateway that lets any AI agent discover and pay metered APIs on Base or Solana — without the user wiring payments themselves.

thebuyside-x402-agent is the canonical buyer-side reference implementation for two open agent-payment protocols:

• x402 — the HTTP 402 payment standard stewarded by the Linux Foundation. EVM (Base) and SVM (Solana) via the exact scheme.
• MPP — Machine Payments Protocol, the new RFC-7235-style protocol behind pay.sh (Solana Foundation × Google Cloud, launched May 2026). Solana mainnet USDC.

Drop it into Claude Code, Claude Desktop, Cursor, or any MCP client, and your agent gains three tools:

• pay.discover — search the curated registry plus three federated indexes (CDP Bazaar, agentic.market, x402watch) for paid APIs
• 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)
• pay.wallet_status — show the gateway's wallet(s), today's spend, and caps

The agent never sees the 402, never sees a wallet, never holds a private key.

Status

v0.5.0 — first cross-implementation MPP-Solana settlement, 2026-05-11. End-to-end live runs across all three supported protocol/chain combinations:

Base mainnet · x402 v2 · $0.005 USDC · tx 0xd0917b35…

Solana mainnet · x402 v2 · $0.005 USDC · tx 4DYWUMEx…

Solana mainnet · MPP solana/charge · $0.001 USDC · tx 3UzJ7Uz…

That third settlement is, as far as we know, the first cross-implementation Machine Payments Protocol 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 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).

• 154 unit tests + MCP smoke test, all green
• 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.
• 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.
• Federated discovery: pay.discover queries the curated seed.json + CDP Bazaar + agentic.market + x402watch in parallel and dedupes by canonical endpoint URL
• Spend caps, host allowlist, receipts log, self-transfer guard — protocol-agnostic
• Confirm-before-pay via MCP elicitation, with graceful fallback for clients lacking task-creation support (Claude Code)
• Apache 2.0, DCO not CLA

Quickstart

Two steps. You need Node 20+ and a wallet funded with USDC on whichever chain you want to pay on.

1. Set at least one wallet key in your environment

For Base / EVM:

export X402_PAYER_PRIVATE_KEY=0x...

0x-prefixed 64-hex-char private key. Fund the wallet with at least $0.01 USDC on Base mainnet.

For Solana:

export X402_PAYER_SOLANA_KEY=<base58 secret key>

Accepts 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.

You 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.

Use a fresh wallet, not your main one. (You can also pass these via your MCP client's env block — see below.)

2. Register the gateway with your MCP client

Claude Code (CLI):

claude mcp add x402-pay -- npx -y thebuyside-x402-agent

Open a session, type /mcp to verify, then ask: "Use pay.wallet_status to show my wallet."

Claude Desktop:

See docs/install-claude-desktop.md.

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.

Try it

Once connected, ask the model:

"Use pay.discover to find APIs about news."

"Use pay.fetch to get https://news-ep.com/api/v1/stories?market=houston&limit=5"

The 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.

After a successful call, ask pay.wallet_status and you'll see today's spend reflected (and which chains have signers configured).

Configuration

Spend controls have safe defaults. Override via env if needed.

Wallet keys (configure at least one to pay):

Var	Default	What it does
X402_PAYER_PRIVATE_KEY	(unset)	Base / EVM private key (0x-prefixed, 64 hex chars)
X402_PAYER_SOLANA_KEY	(unset)	Solana secret key — base58 (Phantom export) or JSON-array (solana-keygen) format
X402_SOLANA_RPC	api.mainnet-beta.solana.com	Solana RPC for fetching a recent blockhash at sign time

Spend caps and confirm-before-pay:

Var	Default	What it does
X402_DAILY_LIMIT	1.00	Max USDC spent per rolling 24h window
X402_PER_CALL_LIMIT	0.05	Max USDC per single call
X402_ALLOWLIST	hosts in seed.json	Comma-separated allowed hostnames (replaces default)
X402_ALLOW_UNVERIFIED	(off)	1 allows any host — dev only
X402_REQUIRE_CONFIRM	always	always, never, or a USDC threshold (e.g. 0.01). Asks the user to approve via MCP elicitation before signing
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
X402_RECEIPTS_PATH	.local/receipts.jsonl	Where the receipts log is written

Federated discovery (pay.discover queries these in parallel and merges with the local seed.json):

Var	Default	What it does
X402_FEDERATION	on	off disables all external indexes; discover returns local-only results
X402_FEDERATION_TIMEOUT_MS	1500	Per-source timeout. A slow source produces zero entries (and a warning), never blocks discover
X402_BAZAAR_URL	api.cdp.coinbase.com/platform/v2/x402/discovery/search	CDP Bazaar endpoint override
X402_AGENTIC_URL	api.agentic.market/v1/services/search	agentic.market endpoint override
X402_X402WATCH_URL	GitHub raw snapshot URL	x402watch daily snapshot URL (the {date} placeholder is filled at request time)
X402_DISABLE_BAZAAR	(off)	1 skips CDP Bazaar
X402_DISABLE_AGENTIC	(off)	1 skips agentic.market
X402_DISABLE_X402WATCH	(off)	1 skips x402watch

Dev / test:

Var	Default	What it does
X402_TEST_URL	news-ep stories	Override target for pnpm pay-newsep and pnpm pay-solana

Limit values accept either decimal USDC (0.05) or atomic units (50000). See docs/configuring-spend-limits.md for the full spend-controls guide.

How it works

   Claude Code / Claude Desktop / Cursor
                  │
                  │  MCP over stdio
                  │
            ┌─────▼─────┐
            │  Gateway  │   ← src/server.ts (this repo)
            └─────┬─────┘
                  │
                  │  HTTPS GET → 402 challenge → pick chain by signer →
                  │             EVM: EIP-3009 typed-data sign  ─┐
                  │             SVM: partial-sign Solana tx    ─┤
                  │             → retry with PAYMENT-SIGNATURE  │
                  │             → 200 + body                    │
            ┌─────▼──────┐         ┌──────────────────┐         │
            │ x402 server│ ──────→ │ Facilitator      │ ─→ chain settle
            │ (e.g.      │         │ (verify + submit │     (Base USDC
            │  news-ep)  │ ←────── │  tx)             │      or Solana USDC)
            └────────────┘         └──────────────────┘

The 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.

Run from source

For contributors and anyone who wants to hack on the gateway:

git clone https://github.com/jaysperspective/thebuyside-x402-agent.git
cd thebuyside-x402-agent
pnpm install
cp .env.example .env   # then paste your key into X402_PAYER_PRIVATE_KEY

Useful scripts:

• pnpm pay-newsep — standalone script that pays news-ep $0.005 on Base end-to-end without MCP. Verifies your EVM wallet + protocol setup.
• 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.
• pnpm smoke — spawns the MCP server in a subprocess and round-trips a few tool calls. CI-safe; no real payments.
• pnpm verify-seed — hits each registry entry's example URL and asserts a valid 402 with the advertised price. Run nightly in CI.
• pnpm test — the full vitest unit-test suite (154 tests as of v0.5.0).
• pnpm build — compiles to dist/. Used by npm publish.

To point your MCP client at the local source instead of the published npm package:

claude mcp add x402-pay -- "$(pwd)/node_modules/.bin/tsx" "$(pwd)/src/index.ts"

Adding an API to the registry

The discover tool reads src/registry/seed.json. Adding a new x402-priced endpoint is a single PR — see docs/adding-an-api.md. CI verifies the entry returns a clean 402 with your advertised price before merge.

What this is not

• An agent framework. Bring your own.
• An LLM router. Bring your own.
• A marketplace. The registry is curated open-source data, not a vendor list.
• 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.

Contributing

Apache 2.0. Sign your commits with DCO (git commit -s). No CLA. PRs welcome — small, focused, with tests.

License

Apache License 2.0.