English Français العربية

io.github.CryptoAPIs-io/mcp-x402-pay

Official registry Other

MCP server that pays x402-gated HTTP endpoints — fetch, and on a 402 authorize, sign, retry

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @cryptoapis-io/mcp-x402-pay
Claude Code 
claude mcp add mcp-x402-pay -- npx -y @cryptoapis-io/mcp-x402-pay@0.5.3
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "mcp-x402-pay": {
            "command": "npx",
            "args": [
                "-y",
                "@cryptoapis-io/mcp-x402-pay@0.5.3"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. @cryptoapis-io/mcp-x402-pay
  2. Run
  3. Prerequisite — an agent walletId
  4. Tool: x402_pay
  5. Tool: x402_discover
  6. Flow
  7. Security

@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

InputRequiredDescription
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/headersthe request to make
allowedNetworksrestrict which CAIP-2 networks to pay on
maxAmountsafety cap — refuse if the required atomic-unit amount exceeds it
allowedHostsrestrict 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).

InputRequiredDescription
typefilter by resource type, e.g. "http"
limitpage size, 1–100 (default 20)
offsetrows to skip, for paging (default 0)
facilitatorBaseUrloverride 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.

Frequently asked questions

What is io.github.CryptoAPIs-io/mcp-x402-pay?

MCP server that pays x402-gated HTTP endpoints — fetch, and on a 402 authorize, sign, retry

How do I install io.github.CryptoAPIs-io/mcp-x402-pay?

It runs on your machine. In Claude Code: claude mcp add mcp-x402-pay -- npx -y @cryptoapis-io/mcp-x402-pay@0.5.3. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.CryptoAPIs-io/mcp-x402-pay need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.CryptoAPIs-io/mcp-x402-pay open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.CryptoAPIs-io/mcp-x402-pay?

It is published by CryptoAPIs-io. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.