{
  "markdown": "# @arispay/payagent-mcp\n\nOne coherent USDC payment product for AI agents: call x402-paid APIs, with spend mandates, receipts, and idempotency. Works with Claude Desktop, Cursor, Windsurf, or any MCP client. A thin wrapper around the [`payagent`](https://www.npmjs.com/package/payagent) SDK.\n\nTwo ways to hold the wallet:\n\n- **Local key (zero signup).** Set `PAYAGENT_PRIVATE_KEY` to a funded EOA key. `pay` signs EIP-3009 locally — no ArisPay account, no email. The only guardrail is the wallet balance; use a dedicated low-balance wallet.\n- **Delegated custody (managed, recommended).** `setup({ email })` self-provisions an account, a CDP-managed wallet, and a spend mandate in one call. ArisPay enforces per-transaction, daily, and monthly limits server-side **before** signing; no private key ever lives in this process.\n\n## Tools\n\nSeven core tools (the default surface):\n\n| Tool | What it does | Money |\n|------|--------------|-------|\n| `setup` | Create or recover an account + payer wallet in one call (delegated mode) | moves none |\n| `discover` | Search the paid-API catalog by intent + budget | read-only |\n| `inspect` | Read a URL's price and payment requirements without paying | read-only |\n| `pay` | The complete machine path: request → 402 → select variant → validate policy → pay → structured receipt. Requires an `idempotencyKey`; a repeated key returns the cached receipt without paying again | **spends real money** |\n| `balance` | Active identity, deposit address, on-chain USDC balance, mandate limits | read-only |\n| `history` | Recent payments — server feed (delegated) or local receipts (self-custody) | read-only |\n| `check_payment_signal` | Buy ArisPay Signal: recent signed probe evidence about an x402 resource (did a real paid probe settle and deliver?). A still-valid cached artifact returns without spending; an unknown resource is answered free | **spends 1¢ per uncached call** |\n\nWallet administration (`create_agent`, `fund_agent`, `list_agents`, `rename_agent`) loads only when the host config sets `PAYAGENT_MCP_PROFILE=admin`.\n\nEvery tool declares MCP safety annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`); `pay` and `check_payment_signal` are the only destructive tools — both spend real money.\n\n## Support matrix\n\n| Asset | Network | Local key (self-custody) | Delegated (managed mandate) |\n|-------|---------|--------------------------|------------------------------|\n| USDC | Base (default) | ✅ | ✅ |\n| USDC | Ethereum, Polygon | ✅ | ✅ |\n| USDC | Base Sepolia (testnet) | ✅ | ✅ |\n| USDC (SPL) | Solana, Solana devnet | ❌ (EVM signing only) | ✅ (live on `api.arispay.app` since 2026-08-25) |\n| USD1 | BNB Chain | ✅ | ✅ |\n\nNotes:\n\n- All prices are quoted by sellers in the 402 challenge; `pay` prefers an EVM variant and falls back to Solana when the seller offers no EVM option.\n- Delegated mandates are **integer cents**, validated server-side before any signature exists. Local mode has no server-side cap.\n- Settlement is a single on-chain `transferWithAuthorization` (EIP-3009): it succeeds or reverts atomically. When the seller returns `X-PAYMENT-RESPONSE`, the receipt carries the settlement transaction hash.\n- ArisPay's own facilitator (`facilitator.arispay.app`) charges no facilitator fee; sellers may use any facilitator, and their fee/finality policy applies.\n\n## Setup\n\nAdd the server to your MCP client config. No environment variables are required — pick a wallet mode later, from inside the chat, or set one of the env options below.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"arispay\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@arispay/payagent-mcp\"]\n    }\n  }\n}\n```\n\nFor the zero-signup mode, add the key to the env block:\n\n```json\n      \"env\": { \"PAYAGENT_PRIVATE_KEY\": \"0x...\" }\n```\n\n### Cursor\n\nSame server block in `.cursor/mcp.json`. **Windsurf:** same pattern in `~/.codeium/windsurf/mcp_config.json`.\n\n## Cold start, from nothing\n\n- **Zero signup:** generate a key with `npx payagent wallet new`, put it in the host config as `PAYAGENT_PRIVATE_KEY`, send USDC on Base to the printed address. `balance` shows the deposit address; `pay` pays.\n- **Managed:** ask the agent to run `setup({ email: \"you@example.com\" })` — it returns the wallet address and mandate. Fund the wallet with USDC, confirm with `balance`, then `pay`. Credentials persist to `~/.payagent/config.json` and are shared with the `payagent` CLI.\n\n## Environment variables (all optional)\n\n| Variable | Description |\n|----------|-------------|\n| `PAYAGENT_PRIVATE_KEY` | Funded EOA key for local self-custody signing (zero-signup mode). |\n| `ARISPAY_API_KEY` | Developer key — usually unneeded; `setup` self-provisions one. |\n| `ARISPAY_URL` | ArisPay API base URL. Default `https://api.arispay.app`. |\n| `PAYAGENT_MCP_PROFILE` | `admin` additionally loads the four wallet-administration tools. Default: core (seven tools). |\n| `ARISPAY_AGENT_KEY` / `PAYAGENT_WALLET` | Legacy single-agent pair for v2.0.x hosts. |\n\n## Migrating from v3\n\nv4 is a breaking release: the surface collapsed to one x402/USDC product.\n\n| v3 tool | v4 |\n|---------|----|\n| `create_user` | `setup` |\n| `pay_api` | `pay` (now requires `idempotencyKey`, returns a structured receipt) |\n| `discover_paid_api` | `discover` |\n| `inspect_paid_api` | `inspect` |\n| `check_wallet`, `get_balance_agent` | `balance` |\n| — | `history` (new) |\n| `create_agent`, `fund_agent`, `list_agents`, `rename_agent` | unchanged, behind `PAYAGENT_MCP_PROFILE=admin` |\n| `create_wallet`, `list_wallets`, `fund_wallet`, `get_balance`, `pay_merchant`, `create_enduser`, `attach_card_for_user`, `set_user_limits`, `get_user_status` | removed — the fiat funding and platform (end-user) surfaces left the public MCP |\n\n## Receipts and idempotency\n\n`pay` requires a caller-chosen `idempotencyKey` (min 8 chars — use a UUID). Every completed payment writes a machine-readable receipt (amount, asset, network, wallet, settlement tx, remaining mandate) to `~/.payagent/mcp-receipts.json`. Re-calling `pay` with a key that already paid returns the stored receipt and does **not** pay again — including when the paid request failed mid-flight. `history` lists receipts in self-custody mode; delegated mode reads the authoritative server feed.\n\n## How it works\n\n1. The agent calls `pay` with a URL and an `idempotencyKey`; the seller answers HTTP 402 with its price.\n2. With `PAYAGENT_PRIVATE_KEY` set, `payagent` signs the EIP-3009 authorization locally. Otherwise ArisPay validates the request against the agent's mandate and signs via Coinbase CDP.\n3. `payagent` retries with the signed payment header; the seller's facilitator settles USDC on-chain.\n4. The tool returns the paid response plus a structured receipt.\n\nIn delegated mode, no private key lives in this process and payments that breach the mandate are rejected before any on-chain action. In local mode, the key is yours and stays in your process.\n\n## Install\n\n```bash\nnpm install @arispay/payagent-mcp\n```\n\nOr invoke directly via `npx @arispay/payagent-mcp` from an MCP client config — no pre-install required. `npx buyforme-mcp` is the same server under the consumer brand.\n\n## Related\n\n- [payagent](https://www.npmjs.com/package/payagent) — the SDK + CLI for programmatic use\n- [facilitator.arispay.app](https://facilitator.arispay.app) — ArisPay's open x402 facilitator, where paid 402s settle\n- [x402 protocol](https://github.com/coinbase/x402) — HTTP 402 payment standard\n\n## License\n\nMIT\n",
  "bytes": 7557,
  "sha": "2d14dea91890d16514b37f7ab6d465e9d5b052ee87b48f60ae01637a88f919ba",
  "repo_slug": "arispay-inc/payagent-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_stevemilton_payagent_mcp_81fe6f81/readme"
}