@cryptoapis-io/mcp-x402-pay
This is the BUYER side of x402 — the tool an agent uses to spend (pay for a resource). Merchants who want to charge for an API use the middleware SDK (
@cryptoapis-io/x402-merchant-sdk), not an MCP tool.
An MCP server that lets an AI agent find and pay x402-gated HTTP endpoints.
x402_pay— fetches a URL and, if the server returns402 Payment Required, authorizes the payment via the CryptoAPIs buyer service, signs locally, retries, and returns the paid response.x402_discover— browses the facilitator's catalogue of x402 resources and their prices, so an agent can find a paid API instead of only calling one it was handed.
Non-custodial: the private key is passed per request and never leaves the process (no HTTP server — stdio only).
Supported today: EVM (eip712, e.g. Base USDC) and Solana. Tron, Bitcoin/UTXO, XRP and Kaspa are
upcoming — wired but not yet enabled; paying on them returns a clear family_not_yet_supported
("coming soon") result.
Run
node dist/cli.js # stdio MCP server (no --api-key at startup; keys are per-tool-call)
Prerequisite — an agent walletId
x402_pay pays from a CryptoAPIs agent wallet (walletId). Create one ONCE per blockchain+network
before paying — a single POST to the buyer API returns the id (non-custodial: you register only your
PUBLIC address):
curl -X POST https://ai.cryptoapis.io/x402/buyer/wallets \
-H "x-api-key: $CRYPTOAPIS_API_KEY" -H "content-type: application/json" \
-d '{"blockchain":"base","network":"eip155:8453","address":"0xYourAddress"}'
# → { "walletId": "…" }
network MUST be the CAIP-2 id (eip155:8453, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, …), not a
bare name — and exactly one of address (any chain; required for Solana/Kaspa) or xpub
(xpub-capable chains). A malformed body returns a clear 400 malformed_request. Set the returned id as
X402_WALLET_ID (or pass walletId).
Tool: x402_pay
| Input | Required | Description |
|---|---|---|
url | ✓ | the (possibly paywalled) resource |
apiKey | ✓ | your CryptoAPIs key (X402_BUYER feature) — only used to call the buyer /authorize |
walletId | ✓ | the wallet record id from POST /wallets (a registry _id) — NOT the on-chain address (an address gets wallet_not_found) |
privateKey | ✓ | the wallet's EVM key — signs locally, never sent anywhere |
method/body/headers | the request to make | |
allowedNetworks | restrict which CAIP-2 networks to pay on | |
maxAmount | safety cap — refuse if the required atomic-unit amount exceeds it | |
allowedHosts | restrict WHICH SITES may be paid, e.g. ["api.acme.com"] (leading dot = subdomains). A url outside the list is refused before any network call. Falls back to X402_ALLOWED_HOSTS (comma-separated) — pin it there to keep the allowlist outside the model's reach |
Returns { status, paid, body, settlement? }. On a 402 with no acceptable option (or over maxAmount),
paid:false with a reason — nothing is signed or paid.
Tool: x402_discover
Browse the x402 "Bazaar" — the registered x402 resources and what each charges (spec §8).
| Input | Required | Description |
|---|---|---|
type | filter by resource type, e.g. "http" | |
limit | page size, 1–100 (default 20) | |
offset | rows to skip, for paging (default 0) | |
facilitatorBaseUrl | override the facilitator (QA/local) |
Returns { resources: [{ resource, type, x402Version, accepts, lastUpdated, metadata? }], pagination }.
Public — no API key, no wallet, spends nothing, so it is always safe to call. Note accepts[].amount
is in atomic units (USDC 6-decimals: "10000" = $0.01) — convert before quoting a price to a user.
Pass a chosen resource to x402_pay to actually buy it.
Flow
fetch(url). Not 402 → return it.- 402 → pick an
acceptsentry (allowlist-aware), authorize via buyer/authorize→ the signing artifact. - Sign locally (
@cryptoapis-io/mcp-signerevm_signtyped-data) → build the x402PaymentPayload(wire scheme is alwaysexact; the family is innetwork). - Retry with the base64
X-PAYMENTheader; return the paid response + theX-PAYMENT-RESPONSEsettlement.
Security
The private key is a tool parameter and may be logged by MCP clients or stored in conversation
history — use only in trusted local environments. This mirrors @cryptoapis-io/mcp-signer.