Choose how your agent acts
- Approval mode: Your agent prepares an action for your main wallet. You review and sign through an approval link.
- Eligible agent-wallet mode: A dedicated wallet and expiring signing grant let your agent perform supported actions within saved spending controls. This does not give unrestricted control of your main wallet.
Approval-mode demo
This demo illustrates individual approvals. Eligible autonomous sessions follow the mode-aware tool behavior instead.Connect your agent
Connect Wallet MCP to your assistant, then load the skill for wallet workflows. Existing client keys such asbase-mcp remain valid; you do not need to rename them.
1
Connect the MCP
- Claude
- ChatGPT
- Perplexity
- Claude Code
- Codex
- Cursor
- Hermes
- Open Customize → Connectors → Add custom connector
- The Add custom connector modal opens
- Fill in:
- Name:
Wallet MCP - Remote MCP server URL:
https://wallet-mcp.coinbase.com
- Name:
- Click Add
- Next hit Connect, then approve the connection in Coinbase Wallet. Click Allow once to authorize:
2
Load the skill
Use the hosted skill prompt for current guidance in chat clients. Disable an older persistent copy before loading it. The legacy
base-mcp-v0.2.0 archive does not contain the execution-mode guidance documented here and is not an equivalent installation.- Claude
- ChatGPT
- Perplexity
- Claude Code
- Codex
- Cursor
- Hermes
Paste this prompt into a new conversation:
Disclaimer
AI agents can make errors, misinterpret instructions, or produce inaccurate output. Coinbase does not guarantee the accuracy of any action taken by an AI agent using this product. You are solely responsible for reviewing your agent’s actions, including trades, transfers, or account changes made through agentic workflows, and securing the environment it runs in. Your use of this software is subject to the Coinbase Wallet Account and Coinbase Wallet Terms of Service.Manage and fund an agent wallet
An agent wallet has its own address, balance, activity, and spending policy. Eligible sessions can use it for supported actions without requesting a new signature from you each time. Enrollment does not guarantee every autonomous tool is enabled. A refused autonomous action does not automatically become an approval request.Identify your wallet and manage access
Ask your assistant to list your wallets.get_wallets reports spending policy and session authorization. Headless sessions expose only the bound agent wallet, not your main wallet or other agent wallets. Connection state and authorization in the current session are distinct.
Reconnecting from the same client can reuse its bound wallet. Multiple clients can share one wallet without disconnecting one another; they share its budget and spending history, not separate allowances. This does not imply a wallet-picker UI in every client.
Disconnecting an agent wallet stops its associated MCP sessions across clients. Signing authorization is checked again at execution. Refreshing an MCP session does not extend the original signing deadline indefinitely.
You retain direct access to your funds through the wallet. Agent spending controls constrain MCP-initiated actions, not transactions you personally make. CDP performs delegated signing; Wallet MCP does not store your onchain private keys.
Use the wallet controls available in your signed-in session to manage limits and disconnect access. Client interfaces can differ; ask your assistant to report the current policy before starting an autonomous action.
Spending limits
Save a spending limit before your agent spends autonomously. There is no implicit starter allowance. The USD budget uses a rolling 24-hour window, not a calendar-day reset. Usage is shared across tools, clients, and supported chains for the same wallet. Pending operations reserve the shared budget before signing. Wallet MCP reports saved limits, remaining budget, and pending activity. Spending display supports tenths of a cent. Your token balance, remaining budget, and native gas balance are different values.What counts
- Native-asset sends and supported token transfers.
- Supported token approvals and spending authorizations.
- The input amount of an autonomous swap.
- x402 payments, including prepaid-channel deposits. Later voucher-only requests do not create another token outflow.
Temporary limits and pending activity
A saved policy can include a persistent limit or a next-transaction-only temporary limit. The temporary limit is consumed by the first value-moving reservation, not a zero-outflow action. If an operation cannot be recognized, priced, or bounded, it is refused. A proven-unsent attempt can release its reservation. An uncertain outcome retains its hold; a revert or refund does not guarantee automatic budget restoration. These are agent spending controls, not a universal wallet-level lock or a general policy engine for arbitrary contracts.Keep native gas available
Unsponsored EVM execution requires the executing wallet’s native token. USDC and main-wallet funds do not automatically cover agent-wallet gas. Native gas is bounded separately from the USD spending budget.Fund your wallet
Usefund to request receive instructions and get_request_status to check progress. Depending on the rail, instructions can include a receive URI, PNG QR image, public QR-page link, or text fallback.
Top up from your main wallet
Where enabled for a headless session,top_up_from_main_wallet requests USDC or native ETH on Base from your main wallet to the bound agent wallet. You review and sign the transfer through an approval link; it never silently pulls funds.
Check balances and activity
Autonomous wallet-scoped reads are limited to the session’s bound agent wallet; they are not a general view of your main wallet or other agent wallets.Check balance and portfolio
Balance prompts
Wallets
Balance
Portfolio
Token Holdings
Wallet and portfolio tools
get_wallets — in approval mode, lists your main wallet and visible agent wallets. Headless responses omit baseAccount and expose only the bound agent wallet, with session authorization and supported-chain information.
get_portfolio — returns portfolio value and per-asset breakdown for your Coinbase Wallet or an in-session agent wallet.
search_tokens — resolve a token symbol or name to its contract address and decimals. Useful before sending less common tokens.
View transaction history
Activity prompts
Recent Transactions
Filter by Asset
Next Page
Another Chain
Transaction-history parameters
get_transaction_history returns transactions in reverse chronological order (newest first) for your Coinbase Wallet or an in-session agent wallet. Third-party wallet addresses are rejected.
Date range filtering is not supported — paginate through results to find transactions from a specific period.
Pagination
WhenhasMore is true in the response, more transactions exist. Ask your assistant to load more:
Load More
nextCursor for the next page; limit does not resize those pages.
Check newly funded balances
Entries markedverifiedOnChain were read from the chain. Other entries may come from an indexer that lags; a missing token does not establish a zero balance.
When live verification is enabled, eligible EVM native-token and canonical USDC balances can be corrected from chain reads, with totals recomputed. Failed verification falls back to indexed data. This does not verify every token or page.
Send and swap tokens
Send or swap assets using individual approvals or an eligible agent-wallet session. The examples below express user intent; asset and network eligibility depend on the execution mode. For autonomoussend and swap, supply an idempotencyKey per intended operation. Keep it and the parameters unchanged on retry. Swap inputs consume spending budget. Ordinary autonomous EVM source chains are Base, plus Base Sepolia only when enabled for your connection. Swaps remain mainnet-only.
Send tokens
Transfer prompts
Send USDC
Transfer ETH
Pay an ENS Name
Send an ERC-20
Send behavior and parameters
Approval mode:send prepares a main-wallet transfer and returns an approval link. Review and sign, then check the request status.
Eligible agent-wallet mode: send executes a supported bounded transfer from the bound agent wallet without a new approval screen. A saved budget, valid signing grant, eligible chain and asset, and native gas when unsponsored are required. Keep the returned requestId; accepted is not confirmed. A refused action does not automatically fall back to approval.
The EVM parameter table applies to both modes; network and asset restrictions still differ.
Swap tokens
Swap prompts
Swap
Buy
Trade
Convert
Swap behavior and parameters
Approval mode:swap prepares a main-wallet swap for your review and signature.
Eligible agent-wallet mode: swap executes only supported routes from the bound wallet. Its input consumes the shared spending budget; unbounded routes are refused. Use the returned request handle to check submission and delivery instead of treating acceptance as confirmation.
Swaps are mainnet-only in both modes. The EVM parameter table applies to both modes.
Testnet swaps are not supported. Use
send on base-sepolia for testing only if that chain is enabled for your connection.Move assets across networks
For an enabled Base-to-Arbitrum USDC route, usechain: "base" and toChain: "arbitrum". The input is spent on Base and delivery is on Arbitrum.
Where cross-chain routing is enabled, swap accepts toChain to swap between supported EVM mainnets or bridge the same asset, such as USDC. The destination is the executing wallet’s own address, not an arbitrary third-party recipient.
Quotes can include estimated fill time. Status can distinguish source confirmation from destination delivery, including partial delivery, refunds, failures, or unknown outcomes. A source transaction’s success does not prove destination delivery; aggregator fill reports are not independent finality proof.
Autonomous source-chain and policy restrictions still apply. Some existing-allowance ERC-20 routes are refused when their input cannot be bounded. Cross-chain routing must be enabled for your session and route.
Sign messages and authorizations
Usesign to sign a message or supported authorization with the wallet connected to your session.
Choose the signing mode
- Approval mode: Review the message in the returned approval link, sign, and retrieve the signature through the request-status flow below.
- Eligible agent-wallet mode: Sign plain messages and supported spending authorizations without a separate approval link. Arbitrary typed data is not supported. The signature represents your agent wallet, not your main wallet; protocol login compatibility must be verified separately.
For agent-wallet spending authority and lifetime limits, see spending controls. Signing is not retry-deduplicated: after an uncertain response, follow the retry guidance instead of blindly repeating it.
Approval-mode flow
1
Your Assistant Calls Sign()
Passes the message type and payload to Wallet MCP.
2
You Receive an Approval Link
Open the approval link to review what you’re signing in Coinbase Wallet — the message content is shown in full.
3
You Approve
Confirm the signature in the approval UI.
4
Signature Returned
Your assistant polls
get_request_status to retrieve the completed signature, then passes it to the requesting service.Execute contract calls
Usesend_calls to group supported contract interactions into one batch.
Approval-mode contract calls
In approval mode,send_calls submits a batch of raw contract calls for a single Coinbase Wallet approval. Use it for DeFi interactions, multi-step operations, and NFT mints that go beyond simple send or swap.
The most common use case: protocol plugins like Moonwell prepare a calls array (including token approvals and deposits), and you pass it directly to send_calls — everything executes atomically in one approval. Moonwell works entirely via web_request, with no additional MCP server required.
Protocol prompts
With the Moonwell plugin:Supply
Borrow
Repay
Approval-mode flow
1
A Plugin Prepares the Calls
Protocol plugins like Moonwell return a
calls array, often with a chain ID from their prepare endpoints. The calls include any required token approvals and the protocol interaction itself.2
Your Assistant Calls send_calls()
Passes the
calls array and Wallet MCP chain name to Wallet MCP.3
You Review and Approve
Open the approval link to review all calls in Coinbase Wallet before signing.
4
Calls Execute Onchain
All calls in the batch execute atomically — if one fails, none go through.
Eligible agent-wallet flow
Submit only policy-supported bounded calls from the bound wallet. The signing grant, saved budget, asset and chain restrictions are checked before execution. No separate approval screen is required for an eligible batch. Preserve its request ID and inspect status; accepted is not confirmed. Unsupported calls are refused, not converted to approval requests.EVM parameters for both modes
Pay for APIs with x402
Find a paid service, inspect its offer, and pay with USDC through an approval flow or an eligible agent wallet. Network and scheme support are separate from rollout eligibility; check the compatibility matrix.Discover and inspect
Usesearch_x402_services to filter Bazaar listings by query, network, scheme, maximum USD price, curated-only listings, or up to five tags. Search one network per call. Base is the default; result counts range from 1–20, with a default of five. Discovery is USDC-scoped.
A listing is not an endorsement or proof of payment eligibility. Filtering discovery by scheme does not select the scheme for a later payment request.
Use probe_x402_response to inspect an endpoint’s HTTP status, x402 version, and supported offers without signing or attaching payment. A probe still sends an HTTP request: a POST to an uncharged endpoint can have application-side effects.
Choose a payment model
Set
scheme explicitly when you need a particular model. It is honored or rejected, never silently substituted. Without an explicit choice, preference is exact, auth-capture, upto, then batch-settlement, among valid supported offers.
Authorization and capture
auth-capture is Base mainnet only. Accepted merchant terms bound capture deadlines to seven days and refund deadlines to thirty days. These are maximum accepted terms, not promises that capture or refunds occur automatically at those times. A general self-service reclaim tool is not exposed.
Prepaid channels
Newbatch-settlement payments require separately eligible headless sessions. The full new deposit must fit within maxPayment and consumes the agent’s spending budget. Later requests sign new cumulative vouchers against prepaid funds; voucher-only requests have no incremental token outflow.
Existing legacy approval-based batch requests can still be recovered, but new approval-mode batch payments are not the current path. Cooperative refunds depend on the supported merchant flow. There is no generally available unilateral escrow-withdrawal tool.
Pay in your session mode
- Approval mode:
initiate_x402_requestprepares the payment and returns an approval link andrequestId. After you approve, callcomplete_x402_requestwith that ID to complete the paid request. - Eligible agent-wallet mode: Initiation pays inline from the bound wallet and returns content plus payment metadata.
complete_x402_requestis not available in this mode. Spending controls and enabled schemes still apply.
maxPayment USDC ceiling. Read the current tool schema for exact inputs. A maximum authorization is not an unlimited bill or a promise that the full ceiling will be charged.
Recover a payment
Approval-based completion
Retry completion with the originalrequestId. Once a result is persisted, same-request retries return it instead of paying again. Cached results last thirty minutes from persistence; pending context lasts ten minutes from initiation.
Observe approveBy, the returned first-submission deadline. A deadline passing or a lost response does not prove an earlier payment never settled. While recovery data remains available, recover the original request. If the outcome is uncertain after recovery data expires, inspect status and transaction evidence rather than authorizing another purchase.
Explicit pending settlement uses the original signed payment for bounded confirmation handling, not a new authorization.
Uncertain autonomous payments
Headless initiation does not share the transaction idempotency contract used bysend and swap. Paid content and signatures are not stored for generic result replay. After a timeout, inspect the original request and transaction evidence instead of initiating another payment.
Long-running resources
Paid responses can include safe, size-limited seller headers such asLocation, Retry-After, Link, job/status links, and receipt headers. Follow the merchant’s asynchronous workflow to retrieve the result. Payment acceptance does not guarantee delivery.
Prepaid-channel recovery
Unresolved channel state blocks new signing. Supported cooperative refund and reconciliation flows preserve the original proof. Where available,reconcile_x402_refund reconciles an already-submitted refund. It never creates, signs, or submits a new refund or payment. “Not needed” means no pending proof exists to reconcile—not that escrow is empty. Refunds do not reset spending budget.
Track actions and retry safely
Keep therequestId returned by an operation. Accepted means a backend accepted it, not that it is confirmed onchain. Signed alone does not prove a transfer succeeded. Check get_request_status and transaction evidence before reporting completion.
Choose the right recovery path
A timeout does not prove failure. Preserve the original request, check status and chain evidence, and do not blindly submit a replacement. Reconciliation observes an existing operation; it does not resend it. An expired deduplication record is not permission to assume the previous operation failed.
Interpret pending and failed outcomes
Status checks can reconcile accepted or uncertain user operations to transaction hashes or reverted states. Approval-based EVM sends require a successful receipt and a successful matching user-operation event. Missing evidence leaves the request pending or signed with guidance to check again. Activity can include pending holds, signing/activity timestamps, and user-operation or transaction hashes. Reverts and refunds do not guarantee automatic budget restoration.Networks and availability
Available networks depend on your connection and the action you choose.EVM network names
EVM network names are Base (base), Ethereum (ethereum), Arbitrum (arbitrum), Optimism (optimism), Polygon (polygon), BNB Chain (bsc), Avalanche (avalanche), and Robinhood Chain (robinhood-chain). Base Sepolia (base-sepolia) is available only when enabled; swaps require mainnet.
Wallet operations
Polygon and Arbitrum autonomous x402 support and its setup do not authorize arbitrary autonomous sends, swaps, or contract calls on those networks.
x402 payment schemes
Permit2 setup must also be enabled for your connection. Setup may require an onchain USDC approval and native gas: POL on Polygon or ETH on Arbitrum when unsponsored.
Solana support
Solana support is coming soon. Use the EVM networks listed above for the workflows in this guide.Use protocol plugins
Load the Wallet MCP skill, then describe what you want to do. The assistant reads the relevant plugin instructions when needed. Protocol sign-in, wallet-specific preparation, and write/payment workflows are documented for approval mode; autonomous sessions must stop before unverified workflows and must not substitute a different wallet identity. Explicitly documented public, read-only discovery can run in either mode when it needs no protocol identity, authentication, signature, transaction preparation, payment, or other side effect. Read access does not establish autonomous trading compatibility. Aerodrome, Balancer, and GMGN require shell access. Other plugins have their own client, authentication, chain, and API requirements. Read the native-plugin reference before starting a protocol workflow.- Aerodrome: Swaps and liquidity.
- Avantis: Perpetual markets and positions.
- Balancer: Swaps and liquidity.
- Bankr: Token-launch discovery.
- Bitrefill: Gift cards, top-ups, and eSIMs.
- Brickken: Agent identity and reputation.
- Clawnch: Token discovery and launches.
- Flaunch: Token launches and swaps.
- GMGN: Quotes and market intelligence.
- Hydrex: Swaps and liquidity positions.
- KyberSwap: Aggregated swap routes.
- Moonwell: Lending and borrowing.
- Morpho: Vaults and lending markets.
- o1.exchange: Token swaps.
- OpenSea: NFTs, swaps, and minting.
- Printr: Token launches.
- Uniswap: Swaps and liquidity.
- Venice: Paid inference.
- Virtuals: Agent services and authentication.
- YO: Yield vaults.
Build a custom plugin
A plugin teaches your assistant to use an API, CLI, SDK, or another MCP server to prepare wallet actions. It does not establish autonomous compatibility. For calldata-based workflows, prepare unsigned calls, validate the wallet and chain, then submit throughsend_calls using the applicable execution mode.
The custom-plugin guide includes response shapes, a template, HTTP allowlist restrictions, and client routing patterns.
What to read next
- Explore native plugins for protocol-specific requirements.
- Build a custom plugin to connect your own API.