cryptoapis-mcp-x402-pay: Instructions file for Claude Code

CLAUDE.md — @cryptoapis-io/mcp-x402-pay

MCP server with three tools. x402_pay: fetch an HTTP resource and, on a 402 Payment Required, auto-pay it with x402 (authorize → sign locally → retry) and return the paid response. The agentic buyer surface — an AI agent calls x402_pay(url, apiKey, walletId, privateKey) and paywalled endpoints just work. Sibling of mcp-signer (which it depends on for local signing) and the buyer SDK (cryptoapis-x402-buyer-sdk, whose orchestration this mirrors inside the monorepo).

Non-custodial + local-only

Like mcp-signer: stdio transport only, no HTTP server, no startup api-key. The buyer's private key is a per-call tool parameter, signs LOCALLY, and never leaves the process. apiKey (the X402_BUYER key) is used ONLY to call the buyer /authorize — never to sign.

Three tools, ONE payment core

• x402_pay — pays an HTTP url (402 → X-PAYMENT header → retry).
• x402_pay_tool — pays a TOOL on ANOTHER MCP server (challenge in the tool result → _meta["x402/payment"] → retry). Launches the upstream over stdio for the call.
• x402_discover — browse the facilitator's catalogue (public, no key, no cost).

x402_pay and x402_pay_tool share src/tools/payCore.ts (select → authorize → sign → build PaymentPayload). Only the ENVELOPE differs: HTTP base64-encodes the payload into a header; MCP sends the same object RAW in _meta (it carries structured JSON natively). Put any change to the payment flow in payCore, never in one transport — the split exists precisely so a fix or a newly-enabled family cannot land on only one side. (The buyer SDK made the same split: payFlow.js.)

The flow (payCore.ts, used by both payers)

1. The transport fetches/calls and detects a challenge (HTTP 402, or an isError tool result).
2. Parse accepts, pick one (allowedNetworks-aware), enforce maxAmount cap.
3. POST it to the buyer /authorize (apiKey + walletId) → { authorized, scheme, signingPayload }.
4. Sign by the artifact scheme, calling the matching @cryptoapis-io/mcp-signer function with the per-family key (all six wired): eip712→evmSignTypedData, svm-transaction→svmPartialSign, tron-transaction→tronSignFromDetails, utxo-transaction→utxoSignFromDetails, kaspa-transaction→kaspaSignFromDetails, xrp-transaction→xrpSignFromDetails.
5. Build the PaymentPayload — wire scheme is ALWAYS exact (the facilitator's parseEnvelope rejects anything else; the family comes from network). The /authorize scheme is the artifact type, NOT the wire scheme. Every family's parsePayload reads payload.transaction first, so the wrapper is uniform payload:{transaction: <value>} — but the VALUE differs per family: EVM {signature, authorization}; SVM base64; UTXO/XRP signed hex; Kaspa signed JSON; Tron the structured {txID, raw_data_hex, raw_data, signature[]} object (the facilitator rejects a bare hex — hence mcp-signer's tronSignFromDetails additively returns signedTransaction). Base64 → X-PAYMENT header, retry once, return {status, paid, body, settlement?}.