AgentPay MCP is a stdio MCP server for x402 payments and Base wallet operations (currently paused for security maintenance; not for production).
Deploy and inspect AgentAccountV2 wallets (deploy_wallet, get_wallet_info).
Send ETH/ERC20 payments, check spend limits, and manage over-limit approvals (send_payment, check_spend_limit, queue_approval).
Make x402 payments with payment caps and automatic HTTP 402 handling (x402_pay).
Start, fetch through, inspect, and end x402 V2 payment sessions (x402_session_start, x402_session_fetch, x402_session_status, x402_session_end).
Query recent wallet transaction history from on-chain events (get_transaction_history).
Enforce operator-controlled, default-deny spend policies via environment variables, with local signing-key use and optional persistent spend-intent journaling.
Facilitates multi-chain USDC settlement using Circle's CCTP infrastructure for cross-chain payments.
Enables non-custodial payments and native USDC settlement on the Base Layer 2 network.
Supports on-chain payment execution and x402-native settlement on the Polygon network.
Provides tools for automated on-chain payments and native USDC settlement on the Stellar network.
Paused for security maintenance. Do not use in production.
AgentPay MCP is a stdio Model Context Protocol server for x402 payments and wallet operations. It exposes Agent Wallet SDK functions as MCP tools and loads a caller-controlled signing key from the local process environment.
The current npm package is agentpay-mcp v5.0.0.
Check the installed command without loading wallet credentials:
npx -y agentpay-mcp --version
npx -y agentpay-mcp --helpUse the AgentPay Wallet Starter for a no-funds verification of allowed, approval-required, and blocked policy outcomes.
Related MCP server: 402-mcp
Wallet tools read the following environment variables:
Variable | Required for wallet tools | Meaning |
| Yes | Local hot-wallet signing key |
| Yes | Deployed |
| No |
|
| No | Caller-selected Base RPC endpoint |
| For deployment | Wallet factory address |
| For deployment | Token contract bound to a wallet |
| No | Local session lifetime in seconds |
Operator safety variables. They are read from the server environment only and cannot be changed through MCP:
Variable | Default | Meaning |
| unset | Operator 24-hour rolling limit (ETH-equivalent) |
| unset | Operator per-transaction cap (ETH-equivalent) |
| unset | Comma-separated operator recipient allowlist |
| off |
|
| unset | USDC ceiling applied on top of every per-call x402 cap; non-USDC x402 payments are refused while set |
| unset | Directory for the fsync'd spend-intent journal; locks and keyed settlements survive restarts, and the journal is compacted to its live state automatically. One process owns the directory at a time ( |
| unset | Comma-separated hosts whose private address may be reached by outbound requests |
| off | Development only: permit private destinations and plain |
Without at least one AGENTPAY_POLICY_* variable, or
AGENTPAY_ALLOW_UNPOLICED_SPEND=1, every value-moving tool refuses to spend.
Example MCP configuration:
{
"mcpServers": {
"agentpay": {
"command": "npx",
"args": ["-y", "agentpay-mcp"],
"env": {
"AGENT_PRIVATE_KEY": "<secret-reference-or-local-key>",
"AGENT_WALLET_ADDRESS": "0x<deployed-wallet-address>",
"CHAIN_ID": "84532",
"AGENTPAY_POLICY_PER_TX_CAP_ETH": "0.01",
"AGENTPAY_POLICY_DAILY_LIMIT_ETH": "0.1",
"AGENTPAY_X402_MAX_PAYMENT": "1",
"AGENTPAY_STATE_DIR": "<writable-private-directory>"
}
}
}
}Do not commit a real signing key. Use the client or operating system's secret mechanism where one exists. Start on Base Sepolia before using Base mainnet.
The tool registry in src/index.ts exposes these groups:
Group | Examples |
Wallet |
|
Payments |
|
Policy |
|
Tokens | Lookup, custom-token registration, balances, and transfers |
Execution | Swap, USDC bridge, and mutual-stake escrow |
Trust | ERC-8004 identity, reputation, and UAID verification |
History |
|
Tool schemas and handlers live under src/tools/.
These boundaries matter more than the feature list:
The server reads AGENT_PRIVATE_KEY into its local Node.js process and uses
viem for signing. Protect the process, environment, and MCP client config.
Spend policy is default-deny. The operator policy comes from
AGENTPAY_POLICY_* environment variables, is loaded once, and cannot be
changed or cleared through MCP. Without it, value movement is refused unless
the operator sets AGENTPAY_ALLOW_UNPOLICED_SPEND=1.
set_spend_policy can only tighten. Each call adds a layer to its scope; a
request that raises a limit, drops a constraint, or widens an allowlist is
refused, and earlier layers keep their rolling-window accounting. Loosening
requires an operator restart. All policy state is still in-process and is
reset by a restart.
x402_pay and x402_session_start require max_payment_eth and pay_to.
The asset is always bound: it defaults to the chain's USDC unless asset
names another; network can be bound too. A 402 that names another payee,
asset, or network, the zero address, or a debit (principal plus the 0.77%
protocol fee) above the cap is refused before any wallet write.
AGENTPAY_X402_MAX_PAYMENT is a USDC ceiling; with it set, non-USDC
payments are refused. Use x402_quote to read the offered terms first.
If a payment settles but its response is not delivered — the response fails, or the paid request is answered with any non-2xx status — every new x402 payment to that host (any path, port or spelling of the name) and to that payee (behind any host) is locked until an operator reconciles it. The lock is written before the wallet call, so a crash cannot lose it.
Caller-selected outbound requests (x402, quote, sessions, OTel kill
callback) use a safe transport: https only (a kill callback may use http
only for a host in AGENTPAY_KILL_CALLBACK_ALLOWED_HOSTS), private, loopback, link-local and metadata destinations refused,
DNS resolved once with the
socket pinned to the validated address, no automatic redirects, and
response bodies capped at 2 MiB (1 MiB rendered).
send_payment, send_token, swap_tokens, bridge_usdc, create_escrow,
x402_pay, and x402_session_start run inside a spend intent. Identical retries replay;
idempotencyKey distinguishes equal payments; an unclear post-broadcast
outcome locks the intent with no timer. Locks are process-local unless
AGENTPAY_STATE_DIR journals them. Reconcile with
agentpay-mcp spend-intents list and
resolve <id> settled|unsettled, which is a local CLI, never an MCP tool.
<id> is the shell-safe id: handle list prints for each intent.
settled (the value moved) clears the lock and retires a keyed intent's
idempotencyKey for good; a keyless intent has no key to retire, so an
identical new request is a new payment (use idempotencyKey for retry
safety). unsettled (nothing moved) clears the lock so a retry may pay.
Only one process may use a state directory at a time: stop the server
before resolve (list shows a read-only snapshot while it runs), and
give each server its own AGENTPAY_STATE_DIR.
idempotencyKey may not contain control, invisible formatting, or
line-separator characters; keys are printed escaped and shell-inert.
send_payment takes decimals from the token registry or the token
contract; a differing token_decimals is refused before signing.
On-chain limits exist only when the wallet owner configures them directly on
AgentAccountV2. The application policy does not write those contract
limits, and an over-limit transaction is a human gate only when the owner
key is kept separate from the agent key.
get_transaction_history reads on-chain wallet events and, for unscoped
all queries, also lists x402 settlements made by this server process (final URL of
the paid response, which may differ from the 402 issuer under redirects, method, amount, token, payee, tx hash, replay count). Those x402
receipts mean the payment was broadcast (a tx hash was returned), not that a receipt was confirmed. They are kept in memory only, capped at 256, and lost on restart. They are
omitted from block-scoped queries. This is not an MCP request log: it does not
record rejected pre-chain attempts or read-only calls.
Runtime wallet configuration currently supports Base mainnet and Base
Sepolia. Unsupported chain IDs fail closed in
src/utils/client.ts.
Swap, bridge, escrow, and payment tools can move funds and consume gas. Test with bounded values and independent wallet limits.
Read docs/security-posture.md for the detailed
control map and known limitations.
v5.0.0 is a breaking security release. Before upgrading:
Set an operator policy (AGENTPAY_POLICY_*) or explicitly opt out with
AGENTPAY_ALLOW_UNPOLICED_SPEND=1; otherwise every spend is refused.
Pass max_payment_eth and pay_to to every x402_pay and
x402_session_start call. Use x402_quote to read the terms first.
Stop relying on set_spend_policy to raise or clear limits.
Move any http or private-network x402 endpoint to https, or allow it with
AGENTPAY_ALLOWED_PRIVATE_HOSTS (production) or
AGENTPAY_ALLOW_PRIVATE_NETWORK=1 (development only).
Set AGENTPAY_STATE_DIR on long-lived servers.
docs/security-remediation-2026-10.md
maps every finding to its fix and test.
The repository keeps deeper interoperability and buyer-safety evidence in versioned documents:
docs/agentpay-buyer-flow-parity.md
covers typed payment errors and buyer flow behavior.
docs/paid-mcp-gateway-hardening.md
covers default-deny controls and quota envelopes.
docs/agentpay-five-tool-parity-proof.md
records the five-tool parity check.
docs/agentpay-escrow-reputation-boundary.md
defines the escrow and reputation boundary.
docs/paid-mcp-proxy-discovery-readiness.md
records discovery readiness evidence.
docs/x402-chain-neutral-gateway-profile.md
defines the packaged chain-neutral profile.
docs/x402-dynamic-paid-mcp-manifest-drift.md
documents checks for stale paid-tool metadata.
docs/mcp-registry-listing-proof.md
and llms.txt expose directory metadata.
docs/smithery-paid-mcp-installation.md
and
examples/smithery-paid-mcp-installation
document the packaged Smithery path without asserting a live listing.
docs/paid-provider-health-proof.md
defines provider-health evidence.
docs/hosted-x402-proxy-verification.md
defines hosted-proxy preflight checks.
docs/x402-native-vs-stripe-proxy.md
separates local spend control from hosted proxy billing.
docs/dependency-pin-policy.md defines the
release gate for payment-critical packages.
AgentPay pins viem exactly at 2.57.4.
The directory comparison was captured against agentpay-mcp@4.1.9; the
package version at the top of this README is the current release.
npm ci
npm run build
npm run typecheck
npm test
npm run lint
npm run security
npm run smoke:clean-installThe CI workflow is separate from scheduled daily review and repair workflows. A scheduled-review failure is not a product-test result, and a repair success does not replace CI.
Agent Wallet SDK provides the wallet and policy library used by this server.
AgentPay Wallet Starter provides the combined no-funds onboarding path.
NVIDIA NeMo Agent Toolkit Examples PR 17 is an independently merged integration example.
File product bugs through the GitHub issue queue.
Report security issues through SECURITY.md.
Contribution rules live in CONTRIBUTING.md.
MIT. See LICENSE.
Check whether a proposed payment amount is within the wallet's autonomous spend limits. Returns a clear yes/no with remaining budget details. Use this before send_payment to avoid surprise queuing.
Inputs: amount_eth (required), token.
Deploy a new AgentAccountV2 wallet via the factory contract. The wallet is deterministically addressed (CREATE2) and owned by an NFT. Returns the wallet address and deployment transaction hash. Requires FACTORY_ADDRESS and NFT_CONTRACT_ADDRESS env vars (or pass them as arguments).
Inputs: token_id (required), nft_contract_address, factory_address.
Retrieve the wallet's recent on-chain transaction history from event logs. Shows executions, queued transactions, approvals, cancellations, spend policy updates, and operator changes. Filter by event type or block range for targeted queries.
Inputs: limit, from_block, to_block, event_type.
Get comprehensive wallet information including address, on-chain balance, spend limits, remaining period allowance, and queue depth. Use token parameter to check budget for a specific ERC20 (defaults to ETH).
Inputs: token.
Manage over-limit transactions queued for owner review. Use action="list" to see pending transactions, "approve" to approve one by ID, or "cancel" to cancel one by ID. Approve/cancel require the agent key to have owner privileges.
Inputs: action (required), tx_id.
Send ETH or ERC20 tokens from the Agent Wallet. If the amount is within the configured spend limits, it executes immediately and returns the tx hash. If it exceeds limits, the transaction is queued for owner approval (use queue_approval to manage). Always check spend limits first with check_spend_limit to avoid surprises.
Inputs: to (required), amount_eth (required), token, token_decimals, +1 more.
Fetch a URL and automatically handle HTTP 402 Payment Required responses. If an active x402 V2 session covers this URL, the session token is used instead of making a new payment (no on-chain cost). If no session exists, the Agent Wallet pays the required amount and retries. Payment is rejected if it exceeds your wallet's spend limits or the max_payment_eth cap. Powered by the x402 protocol on Base network. Tip: Use x402_session_start to pay once for a session and save on repeated calls.
Inputs: url (required), method, headers, body, +3 more.
Explicitly close an x402 V2 session before it expires naturally. After calling this, x402_session_fetch will return an error for the closed session. Useful for security hygiene or when you know a session is no longer needed.
Inputs: session_id (required).
Make an HTTP request within an established x402 V2 session — NO payment required. The session token (signed by your wallet) is automatically attached to the request. The server recognises your session and grants access without a new on-chain payment. Requires a session_id from x402_session_start. Returns an error if the session has expired (call x402_session_start again to renew).
Inputs: session_id (required), url (required), method, headers, +2 more.
Establish an x402 V2 payment session: make a SINGLE on-chain payment and receive a cryptographically signed session token. All subsequent calls to the same endpoint within the session lifetime use x402_session_fetch — no additional payments required. Agents pay once per session rather than once per API call. Session tokens are signed locally by your wallet key (non-custodial). Returns a session_id you pass to x402_session_fetch for all future calls.
Inputs: endpoint (required), scope, ttl_seconds, label, +5 more.
Check the status of x402 V2 payment sessions. Without arguments, lists all active sessions with TTL remaining. With a session_id, shows full details for that session including call count, payment info, and the signed session token.
Inputs: session_id.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
The tools are mostly distinct with clear purposes, but there is some overlap between check_spend_limit and send_payment, as both involve spend limit checks, which could cause minor confusion. The x402 session tools are well-differentiated, and other tools like deploy_wallet and get_transaction_history have unique functions.
Naming is mostly consistent with a verb_noun pattern, such as check_spend_limit and send_payment, but there are minor deviations like x402_pay (which mixes protocol prefix with verb) and the x402_session_* tools that use a consistent prefix but vary in verb style. Overall, it's readable with only slight inconsistencies.
With 11 tools, the count is well-scoped for managing AgentPay wallets and x402 payments. Each tool serves a specific purpose, such as deployment, transactions, and session management, without feeling excessive or insufficient for the domain.
The tool set provides comprehensive coverage for wallet management and x402 payment handling. It includes deployment, transaction sending, limit checks, history retrieval, approval queuing, and full session lifecycle management, leaving no obvious gaps for the intended use cases.
x402 pay-per-call APIs over MCP, settled in USDC on Base for autonomous agents and developers.
Pay-per-call x402 MCP for AI agents: 35 tools, USDC on Base, from $0.001/call, no API keys.
Policy-gated MCP treasury for AI agents — x402 subscribe, 50+ tools, multi-chain.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.