X402 Payagent Mcp

io.github.stevemiltonPublished by GitHub account stevemiltonv4.1.0Updated Oct 24, 2026

Pay x402 APIs in USDC on Base, Solana, and BNB Chain with spend mandates, receipts, idempotency.

VerifiedSTDIODesktop onlyWeb Search & ScrapingFinanceDeveloper Tools

Overview

AI-generated overview

Lets an assistant pay x402-paid APIs in USDC on Base, Solana, and BNB Chain, with spend mandates, receipts, and idempotency.

What you can do
Wraps the payagent SDK to call x402-paid APIs: discover searches the paid-API catalog by intent and budget, inspect reads a URL's price and payment requirements without paying, and pay runs the full request-to-402-to-settlement path and returns a structured receipt. balance and history report the active identity, deposit address, on-chain USDC balance, mandate limits, and recent payments. check_payment_signal buys signed probe evidence about an x402 resource. Admin wallet tools load only when PAYAGENT_MCP_PROFILE=admin.
When to use it
Use it when an assistant needs to call APIs that charge per request over the x402 protocol and you want spending limits, receipts, and idempotent retries rather than manual payment handling. It suits agents that must inspect prices before buying or keep a record of what was paid. It is not for free APIs or for fiat funding and platform end-user surfaces, which were removed in v4.
Requirements
Runs locally over stdio via npx or npm (@arispay/payagent-mcp); desktop MCP clients only. No environment variables are required to start. Optional secrets: PAYAGENT_PRIVATE_KEY for local self-custody signing, or ARISPAY_API_KEY (usually self-provisioned by setup). Optional ARISPAY_URL and PAYAGENT_MCP_PROFILE=admin. A funded USDC wallet and network access are needed to pay.
Before you install
Two secret names are involved: ARISPAY_API_KEY and PAYAGENT_PRIVATE_KEY. In local mode the private key signs payments directly and the only guardrail is the wallet balance, so a dedicated low-balance wallet is advised. The pay and check_payment_signal tools spend real money (check_payment_signal costs 1 cent per uncached call); pay requires an idempotencyKey. Credentials persist to a local config file shared with the payagent CLI.

Installation

In SourceWeft

  1. Open X402 Payagent Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@arispay/payagent-mcp

One 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 SDK.

Two ways to hold the wallet:

  • 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.
  • 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.

Tools

Seven core tools (the default surface):

ToolWhat it doesMoney
setupCreate or recover an account + payer wallet in one call (delegated mode)moves none
discoverSearch the paid-API catalog by intent + budgetread-only
inspectRead a URL's price and payment requirements without payingread-only
payThe complete machine path: request → 402 → select variant → validate policy → pay → structured receipt. Requires an idempotencyKey; a repeated key returns the cached receipt without paying againspends real money
balanceActive identity, deposit address, on-chain USDC balance, mandate limitsread-only
historyRecent payments — server feed (delegated) or local receipts (self-custody)read-only
check_payment_signalBuy 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 freespends 1¢ per uncached call

Wallet administration (create_agent, fund_agent, list_agents, rename_agent) loads only when the host config sets PAYAGENT_MCP_PROFILE=admin.

Every tool declares MCP safety annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); pay and check_payment_signal are the only destructive tools — both spend real money.

Support matrix

AssetNetworkLocal key (self-custody)Delegated (managed mandate)
USDCBase (default)✅✅
USDCEthereum, Polygon✅✅
USDCBase Sepolia (testnet)✅✅
USDC (SPL)Solana, Solana devnet❌ (EVM signing only)✅ (live on api.arispay.app since 2026-08-25)
USD1BNB Chain✅✅

Notes:

  • 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.
  • Delegated mandates are integer cents, validated server-side before any signature exists. Local mode has no server-side cap.
  • 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.
  • ArisPay's own facilitator (facilitator.arispay.app) charges no facilitator fee; sellers may use any facilitator, and their fee/finality policy applies.

Setup

Add 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.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "arispay": {      "command": "npx",      "args": ["-y", "@arispay/payagent-mcp"]    }  }}

For the zero-signup mode, add the key to the env block:

json
      "env": { "PAYAGENT_PRIVATE_KEY": "0x..." }

Cursor

Same server block in .cursor/mcp.json. Windsurf: same pattern in ~/.codeium/windsurf/mcp_config.json.

Cold start, from nothing

  • 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.
  • Managed: ask the agent to run setup({ email: "[email protected]" }) — 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.

Environment variables (all optional)

VariableDescription
PAYAGENT_PRIVATE_KEYFunded EOA key for local self-custody signing (zero-signup mode).
ARISPAY_API_KEYDeveloper key — usually unneeded; setup self-provisions one.
ARISPAY_URLArisPay API base URL. Default https://api.arispay.app.
PAYAGENT_MCP_PROFILEadmin additionally loads the four wallet-administration tools. Default: core (seven tools).
ARISPAY_AGENT_KEY / PAYAGENT_WALLETLegacy single-agent pair for v2.0.x hosts.

Migrating from v3

v4 is a breaking release: the surface collapsed to one x402/USDC product.

v3 toolv4
create_usersetup
pay_apipay (now requires idempotencyKey, returns a structured receipt)
discover_paid_apidiscover
inspect_paid_apiinspect
check_wallet, get_balance_agentbalance
—history (new)
create_agent, fund_agent, list_agents, rename_agentunchanged, behind PAYAGENT_MCP_PROFILE=admin
create_wallet, list_wallets, fund_wallet, get_balance, pay_merchant, create_enduser, attach_card_for_user, set_user_limits, get_user_statusremoved — the fiat funding and platform (end-user) surfaces left the public MCP

Receipts and idempotency

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.

How it works

  1. The agent calls pay with a URL and an idempotencyKey; the seller answers HTTP 402 with its price.
  2. 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.
  3. payagent retries with the signed payment header; the seller's facilitator settles USDC on-chain.
  4. The tool returns the paid response plus a structured receipt.

In 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.

Install

bash
npm install @arispay/payagent-mcp

Or 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.

Related

License

MIT

Source: README.md at commit ba86a72

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v4.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts