Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@thebuyside-x402-agent search for weather APIs under $0.01 per call"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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· tx0xd0917b35…Solana mainnet · x402 v2 ·
$0.005 USDC· tx4DYWUMEx…Solana mainnet · MPP
solana/charge·$0.001 USDC· tx3UzJ7Uz…
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
Related MCP server: AgentPay
Two steps. You need Node 20+ and a wallet funded with USDC on whichever chain you want to pay on.
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.)
Claude Code (CLI):
claude mcp add x402-pay -- npx -y thebuyside-x402-agentOpen 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.
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).
Spend controls have safe defaults. Override via env if needed.
Wallet keys (configure at least one to pay):
Var | Default | What it does |
| (unset) | Base / EVM private key (0x-prefixed, 64 hex chars) |
| (unset) | Solana secret key — base58 (Phantom export) or JSON-array ( |
|
| Solana RPC for fetching a recent blockhash at sign time |
Spend caps and confirm-before-pay:
Var | Default | What it does |
|
| Max USDC spent per rolling 24h window |
|
| Max USDC per single call |
| hosts in | Comma-separated allowed hostnames (replaces default) |
| (off) |
|
|
|
|
| (off) |
|
|
| 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 |
|
|
|
|
| Per-source timeout. A slow source produces zero entries (and a warning), never blocks discover |
|
| CDP Bazaar endpoint override |
|
| agentic.market endpoint override |
| GitHub raw snapshot URL | x402watch daily snapshot URL (the |
| (off) |
|
| (off) |
|
| (off) |
|
Dev / test:
Var | Default | What it does |
| news-ep stories | Override target for |
Limit values accept either decimal USDC (0.05) or atomic units (50000). See docs/configuring-spend-limits.md for the full spend-controls guide.
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.
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_KEYUseful 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"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.
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.
Apache 2.0. Sign your commits with DCO (git commit -s). No CLA. PRs welcome — small, focused, with tests.
Search the registry of paid APIs by free-text query. Queries the local curated registry plus external indexes (CDP Bazaar, agentic.market, x402watch) when federation is enabled. Each match carries a source field — verified means the entry is in our curated seed; other values are external indexes that have not been independently verified. The protocol field indicates whether the seller speaks x402 or mpp (Solana, paymentauth.org draft).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text search (e.g. "houston news", "weather", "stock prices"). Empty string returns the full list. | |
| limit | No | Max number of matches to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it queries a local curated registry and external indexes when federation is enabled, explains the 'source' field (verified vs. unverified), and the 'protocol' field (x402 or mpp). No destructive actions are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each serving a distinct purpose: core function, external indexes, source field, and protocol field. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description covers the tool's purpose, federation behavior, and key response fields. It is slightly lacking details on error handling or pagination, but overall provides sufficient context for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters adequately. The description adds no significant new meaning beyond what is in the schema (e.g., 'free-text' repeats the schema description for query, and limit defaults are restated). Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches a registry of paid APIs by free-text query, using the verb 'Search' and specifying the resource. It distinguishes itself from siblings 'pay.fetch' and 'pay.wallet_status' by focusing on discovery versus retrieval or status checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., pay.fetch). The description does not include when-not-to-use scenarios or suggest alternative tools, leaving the agent without clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make an HTTP request to a URL that may require payment. If the server returns 402, the gateway speaks either x402 (Coinbase's spec, Base and Solana) or MPP (paymentauth.org draft-solana-charge, Solana only) and signs the required USDC payment from its configured wallet — subject to spend caps and the host allowlist — then returns the response body. The LLM client never sees the wallet or the 402.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full URL of the paid endpoint | |
| method | No | HTTP method (default GET) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the payment process (signs USDC payment, subject to spend caps and allowlist) and what the LLM sees. However, it does not disclose error handling for payment failures or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: main purpose, 402 handling, restrictions, and LLM visibility. No filler, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description explains the return value ('response body') and hides wallet details. Missing error scenarios and redirect/timeout handling, but comprehensive for a payment tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds no new meaning beyond the schema. The description's parameter descriptions ('Full URL of the paid endpoint', 'HTTP method (default GET)') are redundant with schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it makes HTTP requests to URLs that may require payment, handles 402 responses with x402 or MPP protocols, and returns the response body. This distinguishes it from siblings like pay.discover (for discovering paid endpoints) and pay.wallet_status (for wallet state).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for URLs requiring payment but does not explicitly state when to use this tool versus siblings. It lacks guidance on when not to use it or alternatives like pay.discover for listing endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the gateway wallet address, today's spend total in USDC, and the configured per-call and per-day spend limits. Use this to surface payment context to the user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It is implied to be a read-only operation. With no annotations, the description is adequate but lacks details on authentication, error cases, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with return data, succinct usage advice. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists the three key return items. It is fairly complete for a simple status read, but could specify format details (e.g., address format).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. Baseline 4 per instructions. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns specific payment context data (wallet address, spend total, limits) and uses the verb 'Return'. However, it does not differentiate from sibling tools pay.discover and pay.fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool says 'Use this to surface payment context to the user', which gives a usage context. But it does not specify when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.1pay.discoverpay.fetchpay.wallet_statusEach tool targets a distinct function: discovery of paid APIs, execution of paid requests, and wallet status inspection. There is no functional overlap.
All tools use a consistent 'pay.<action>' pattern with underscores for multi-word verbs (pay.wallet_status). Perfectly predictable and uniform.
With 3 tools, the set is at the lower bound of well-scoped. It covers core operations but feels slightly thin for a payment gateway agent.
Missing tools for managing the registry (add/update/delete APIs) and wallet configuration (set spend limits, allowlists). These are notable gaps for a full lifecycle.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Discover and pay for APIs with USDC credits. No wallet, no gas, MCP-native marketplace.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Production-grade MCP gateway delivering 8 real-time AI tools with instant x402 micropayments settled in USDC on Base Mainnet or SPL-USDC on Solana. Features Basescan contract auditing, wallet analytics, headless browser scraping, and pre-scraped oracle data feeds.
Production-grade MCP gateway delivering 8 real-time AI tools with instant x402 micropayments settled in USDC on Base Mainnet or SPL-USDC on Solana. Features Basescan contract auditing, wallet analytics, headless browser scraping, and pre-scraped oracle data feeds.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jaysperspective/thebuyside-x402-agent'
If you have feedback or need assistance with the MCP directory API, please join our Discord server