@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 returns 402 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

1. fetch(url). Not 402 → return it.
2. 402 → pick an accepts entry (allowlist-aware), authorize via buyer /authorize → the signing artifact.
3. Sign locally (@cryptoapis-io/mcp-signer evm_sign typed-data) → build the x402 PaymentPayload (wire scheme is always exact; the family is in network).
4. Retry with the base64 X-PAYMENT header; return the paid response + the X-PAYMENT-RESPONSE settlement.

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.