English Français العربية

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

السجل الرسمي أخرى

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

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

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 (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "mcp-x402-pay": {
            "command": "npx",
            "args": [
                "-y",
                "@cryptoapis-io/mcp-x402-pay@0.5.3"
            ]
        }
    }
}

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  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.

الأسئلة الشائعة

ما هو io.github.CryptoAPIs-io/mcp-x402-pay؟

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

كيف أثبّت io.github.CryptoAPIs-io/mcp-x402-pay؟

يعمل على جهازك. في Claude Code: claude mcp add mcp-x402-pay -- npx -y @cryptoapis-io/mcp-x402-pay@0.5.3. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.CryptoAPIs-io/mcp-x402-pay إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل io.github.CryptoAPIs-io/mcp-x402-pay مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.CryptoAPIs-io/mcp-x402-pay؟

ينشره CryptoAPIs-io. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.