{
  "markdown": "# @cryptoapis-io/mcp-x402-pay\n\n> **This is the BUYER side of x402** — the tool an agent uses to *spend* (pay for a resource). Merchants\n> who want to *charge* for an API use the middleware SDK (`@cryptoapis-io/x402-merchant-sdk`), not an MCP tool.\n\nAn MCP server that lets an AI agent **find and pay** x402-gated HTTP endpoints.\n\n- **`x402_pay`** — fetches a URL and, if the server returns `402 Payment Required`, authorizes the payment\n  via the CryptoAPIs buyer service, **signs locally**, retries, and returns the paid response.\n- **`x402_discover`** — browses the facilitator's catalogue of x402 resources and their prices, so an agent\n  can *find* a paid API instead of only calling one it was handed.\n\n**Non-custodial:** the private key is passed per request and never leaves the process (no HTTP server —\nstdio only).\n\n**Supported today:** EVM (`eip712`, e.g. Base USDC) and Solana. Tron, Bitcoin/UTXO, XRP and Kaspa are\n**upcoming** — wired but not yet enabled; paying on them returns a clear `family_not_yet_supported`\n(\"coming soon\") result.\n\n## Run\n\n```bash\nnode dist/cli.js            # stdio MCP server (no --api-key at startup; keys are per-tool-call)\n```\n\n## Prerequisite — an agent `walletId`\n\n`x402_pay` pays from a CryptoAPIs **agent wallet** (`walletId`). Create one ONCE per blockchain+network\nbefore paying — a single `POST` to the buyer API returns the id (non-custodial: you register only your\nPUBLIC address):\n\n```bash\ncurl -X POST https://ai.cryptoapis.io/x402/buyer/wallets \\\n  -H \"x-api-key: $CRYPTOAPIS_API_KEY\" -H \"content-type: application/json\" \\\n  -d '{\"blockchain\":\"base\",\"network\":\"eip155:8453\",\"address\":\"0xYourAddress\"}'\n# → { \"walletId\": \"…\" }\n```\n\n`network` MUST be the **CAIP-2 id** (`eip155:8453`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, …), not a\nbare name — and exactly one of `address` (any chain; **required for Solana/Kaspa**) or `xpub`\n(xpub-capable chains). A malformed body returns a clear `400 malformed_request`. Set the returned id as\n`X402_WALLET_ID` (or pass `walletId`).\n\n## Tool: `x402_pay`\n\n| Input | Required | Description |\n|---|---|---|\n| `url` | ✓ | the (possibly paywalled) resource |\n| `apiKey` | ✓ | your CryptoAPIs key (X402_BUYER feature) — only used to call the buyer `/authorize` |\n| `walletId` | ✓ | the **wallet record id** from `POST /wallets` (a registry `_id`) — **NOT the on-chain address** (an address gets `wallet_not_found`) |\n| `privateKey` | ✓ | the wallet's EVM key — **signs locally, never sent anywhere** |\n| `method`/`body`/`headers` | | the request to make |\n| `allowedNetworks` | | restrict which CAIP-2 networks to pay on |\n| `maxAmount` | | safety cap — refuse if the required atomic-unit amount exceeds it |\n| `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** |\n\nReturns `{ status, paid, body, settlement? }`. On a 402 with no acceptable option (or over `maxAmount`),\n`paid:false` with a `reason` — nothing is signed or paid.\n\n## Tool: `x402_discover`\n\nBrowse the x402 \"Bazaar\" — the registered x402 resources and what each charges\n([spec §8](https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md)).\n\n| Input | Required | Description |\n|---|---|---|\n| `type` | | filter by resource type, e.g. `\"http\"` |\n| `limit` | | page size, 1–100 (default 20) |\n| `offset` | | rows to skip, for paging (default 0) |\n| `facilitatorBaseUrl` | | override the facilitator (QA/local) |\n\nReturns `{ resources: [{ resource, type, x402Version, accepts, lastUpdated, metadata? }], pagination }`.\n\n**Public — no API key, no wallet, spends nothing**, so it is always safe to call. Note `accepts[].amount`\nis in **atomic units** (USDC 6-decimals: `\"10000\"` = $0.01) — convert before quoting a price to a user.\nPass a chosen `resource` to `x402_pay` to actually buy it.\n\n## Flow\n\n1. `fetch(url)`. Not 402 → return it.\n2. 402 → pick an `accepts` entry (allowlist-aware), authorize via buyer `/authorize` → the signing artifact.\n3. Sign locally (`@cryptoapis-io/mcp-signer` `evm_sign` typed-data) → build the x402 `PaymentPayload`\n   (**wire scheme is always `exact`**; the family is in `network`).\n4. Retry with the base64 `X-PAYMENT` header; return the paid response + the `X-PAYMENT-RESPONSE` settlement.\n\n## Security\n\nThe private key is a tool parameter and **may be logged by MCP clients or stored in conversation\nhistory** — use only in trusted local environments. This mirrors `@cryptoapis-io/mcp-signer`.\n",
  "bytes": 4634,
  "sha": "2a1e3a1d4f07314e1e32d03888f4889d605afc019b39fc7a4dea3404ea37f841",
  "repo_slug": "cryptoapis-io/cryptoapis-mcp-x402-pay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cryptoapis_io_mcp_x402_pay_5eb3c794/readme"
}