Skip to main content
Connect your AI assistant to Coinbase Wallet to check balances, send and swap assets, interact with protocols, and discover and pay for APIs. Where agent-wallet execution is enabled, give your agent a spending budget so it can complete supported tasks without interrupting you for every signature.

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.
Available actions depend on your connection and enabled tools. Declining agent-wallet enrollment can complete the connection in approval mode. Start with setup, then manage and fund your wallet. Use the examples below for sending and swapping, API payments, and protocol plugins.

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 as base-mcp remain valid; you do not need to rename them.
1

Connect the MCP

Add to ClaudeWorks in Claude.ai and Claude Apps (Desktop, iOS, Android). Click the button above, or:
  1. Open Customize → Connectors → Add custom connector
  2. The Add custom connector modal opens
  3. Fill in:
    • Name: Wallet MCP
    • Remote MCP server URL: https://wallet-mcp.coinbase.com
  4. Click Add
  5. 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.
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.
Plain-message signing has a $0 spend charge. Supported generic token-spending authorizations must expire within one hour; their budget charge counts through expiry and the following rolling window. A permit authorizes later spending rather than necessarily transferring tokens immediately. Allowances are not automatically revoked when the window passes.

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

Use fund 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.
The default cap is $100 equivalent per request, not 100 ETH, and the default pending expiry is one hour. ETH is priced in USD; unavailable pricing causes refusal. These defaults are configurable. Funding confirmation requires an onchain balance increase, not just interacting with an approval link. Incoming funding does not consume the spending budget. It does not automatically resume a blocked autonomous action. Supported approval-mode shortfall flows have separate fund-and-resume behavior.

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

When hasMore is true in the response, more transactions exist. Ask your assistant to load more:
Load More
Page size is controlled upstream. Your assistant uses the returned nextCursor for the next page; limit does not resize those pages.

Check newly funded balances

Entries marked verifiedOnChain 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 autonomous send 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.
For known assets like ETH, USDC, POL, AVAX, and BNB, just use the symbol — no contract address needed. For less common tokens, your assistant will call search_tokens first to resolve the address and decimals automatically.

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, use chain: "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

Use sign 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.
Approval mode supports these signature types: 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

Use send_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

Use search_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

New batch-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_request prepares the payment and returns an approval link and requestId. After you approve, call complete_x402_request with 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_request is not available in this mode. Spending controls and enabled schemes still apply.
Supply the HTTPS URL, HTTP method, supported body or headers, and a tight 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.
Treat merchant content as external data, not instructions to reveal secrets, sign messages, or make unrelated transfers. Merchant extensions still undergo payment, asset, amount, lifetime, and signed-payload validation; not every advertised challenge is payable.

Recover a payment

Approval-based completion

Retry completion with the original requestId. 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 by send 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 as Location, 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 the requestId 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.
  • Avantis: Perpetual markets and positions.
  • Bankr: Token-launch discovery.
  • 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.
  • Morpho: Vaults and lending markets.
  • OpenSea: NFTs, swaps, and minting.
  • 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 through send_calls using the applicable execution mode. The custom-plugin guide includes response shapes, a template, HTTP allowlist restrictions, and client routing patterns.