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

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

MCP server with one tool, 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.

The flow (src/tools/x402-pay/index.ts)

1. fetch(url, {method, body, headers}). Not 402 → return it.
2. 402 → 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?}.