​

Coinbase for Agents

​

Setup

​

Remote MCP

​

Harness setup

1. Enable Developer mode: Settings > Security and login > turn on Developer mode.
2. Open ChatGPT Plugins and select the + button.
3. Enter a name (for example, “Coinbase”) and description. Under Connection, enter https://agents.coinbase.com/mcp.
4. Create the connection and sign in with Coinbase when prompted.
5. Start a new conversation and add the Coinbase connection from the tools menu.

1. Click Customize in the left navigation.
2. Under Connectors, search for Coinbase.
3. Click Add Connector.
4. Sign in with your Coinbase account.

1. Click the Customize toolbox icon in the left sidebar.
2. Go to Connectors > click + > Add custom connector.
3. Name it “Coinbase” and enter https://agents.coinbase.com/mcp.
4. Leave all other fields blank, then click Create.
5. Sign in with your Coinbase account when prompted.
6. On the approval screen, select which portfolios to give the agent access to.

1. Run claude mcp add coinbase --transport http https://agents.coinbase.com/mcp.
2. Start Claude Code, run /mcp, and choose coinbase > Authenticate.
3. Complete the Coinbase sign-in and approval flow.

​

First connection checklist

1. Reuse an authenticated connection or complete the matching harness setup above. Let the harness manage MCP initialization, OAuth, and credential storage; do not replace working credential helpers with custom token handling.
2. Let the harness discover supported OAuth scopes from the protected-resource metadata and request all scopes needed for the intended Coinbase capabilities. Do not limit scopes to read-only just because verification uses a portfolio-list call; honor an explicit read-only request. If authentication is needed, have the user sign in on Coinbase and approve the permissions and portfolios. Wait for them to finish. Never ask for passwords, one-time codes, authorization codes, or tokens in chat.
3. Discover available Coinbase tools through the connected harness. Call the exposed coinbase_portfolios_list tool with an empty arguments object, using the exact tool name and schema the connection exposes. Check for tool and authorization errors; an empty portfolio list is a valid result. If no Coinbase tools are available after the matching setup flow, report that verification is blocked rather than claiming success or bypassing the connection with raw HTTP requests.
4. Report that the connection was verified only after the read-only portfolio call succeeds. Granted OAuth permissions enable actions; execute trades, transfers, or paid requests only when the user requests or approves them.

​

Adopt this guide as a skill

---
name: coinbase-for-agents
description: >-
  Connect Coinbase, check a crypto portfolio or balances, trade crypto,
  eligible US stocks or futures, and pay for research with x402.
  Use for Coinbase setup, connection verification, trading, or disconnecting.
metadata:
  author: developer-platform@coinbase.com
  version: "0.2.2"
---

​

Disconnect or remove local instructions

​

Local CLI (Cursor, Windsurf, Codex, and other coding agents)

node --version   # must be >= 22
npm i -g @coinbase/coinbase-cli
coinbase --version   # verify

which secret-tool || sudo apt install -y libsecret-tools

​

Authentication (CLI only)

1. Sign in to https://portal.cdp.coinbase.com/api-keys/secret (a project is auto-created on first sign-in)
2. Click Create API Key
3. Give it a name (e.g., my-trading-agent)
4. Under Advanced Settings > Coinbase App & Advanced Trade:
   • Under Accounts, select the portfolio for the agent to trade from. US Derivatives (Futures) only work in your default portfolio — include it in the key scope if the agent will trade US Derivatives (Futures).
   • Enable Trade and Transfer (View is enabled by default)
   • Check Opt out of IP allowlisting if you haven’t configured specific IP addresses, or set your IP range to allowlist them
5. Click Create & Download and save the JSON key file

coinbase env live --key-file <path-to-key.json>
coinbase env          # verify: "live" appears with key ID
coinbase balance      # verify: returns JSON with account balances

​

x402 Payments

​

x402 Tools

​

How x402 works

1. Discover: Run coinbase x402 resources q==<keyword> or call coinbase_x402_resources. Read the resource URL, advisory price, and input schema; do not invent endpoints or parameters.
2. Authorize: Establish a user-approved research budget before spending. A request to connect Coinbase or research a topic is not unlimited payment or trading authority.
3. Fetch: Supply the catalog resource URL and flat resource parameters inside input (not a hand-built HTTP request). Set max_amount within the remaining budget, generate an idempotency_key UUID, and retain it before the call. Fetch handles a v2 challenge, payment, and the provider request.
4. Report: Inspect paid, payment metadata, and data. Report provider, amount, and any data-delivery failure separately; cite only values returned by the source. Track total spend across calls. A trade requires its own authorization.

• Payments use USDC on Base only, with a 5 USDC per-payment cap. Other account and spending controls may apply.
• For fetch, max_amount is optional and expressed in atomic USDC units (1000000 = 1 USDC). It tightens the catalog ceiling; it cannot raise that ceiling. A prompt budget is not a server-enforced session or daily limit.
• Catalog prices are advisory. The live challenge supplies the exact price, bounded by the request ceiling and server limits. Stop and ask if the authorized budget is insufficient.
• Fetch supports curated catalog URLs and x402 v2 only. Prefer it over manually constructing a payment.
• For low-level pay, copy the actual challenge fields and use coinbase x402 pay --template or the MCP schema. Send the returned header as X-PAYMENT for v1 or PAYMENT-SIGNATURE for v2. Pay authorizes funds but does not retrieve the resource.
• A timeout or unknown payment outcome is not proof of failure. Reuse the original idempotency_key for the same logical payment; omitting or changing it can create another hold. For terminal rejection, follow the error’s instructions before starting a new authorized attempt.
• Do not claim native Sign-In-With-X (SIWX) support. If an endpoint requires a separate signing or asynchronous retrieval flow, verify that it is supported before paying; don’t repeatedly pay to work around missing authentication.
• Settled payments are irreversible.

​

Available providers

• Nansen: smart money flows and wallet intelligence
• Arkham (Arkham x402): entity intelligence and wallet data
• Glassnode: onchain metrics
• Dripstack (Drip): market analysis
• Exa: web search and content retrieval
• You.com: web search
• Massive: stock market data

​

x402 Workflows

Use coinbase_x402_resources to search for "smart money"
Use coinbase_x402_fetch to get Nansen smart money flows for ETH
Summarize which wallets are accumulating and what the net flow looks like

Use coinbase_x402_fetch to pull Glassnode's MVRV and funding rate for BTC
Use coinbase_x402_fetch to search recent crypto news via You.com
Summarize: is the market overheated or calm based on these indicators?

Use coinbase_x402_fetch to get exchange net flow data for BTC from Glassnode
Summarize whether institutions appear to be accumulating or distributing

​

Core Commands

​

Market Data

​

Product-type support and limitations

​

Equity sessions and order lifecycle

• NORMAL is regular market hours and the only session supporting market orders. The core MCP defaults resolved equity orders to NORMAL when no session is supplied.
• PRE_MARKET, AFTER_HOURS, and OVERNIGHT target their named sessions; MULTI_SESSION spans multiple eligible sessions. These sessions accept whole-share limit orders, not market orders, fractional base_size, or quote_size. Verify the applicable session, trading calendar, and product eligibility rather than assuming weekdays or a fixed UTC window.
• equity_order_date is the trade date (YYYY-MM-DD), not the order’s expiry or an agent scheduling instruction. end_time is an RFC 3339 timestamp with timezone for a GTD order.
• For extended-session planning, specify the intended session, trade date, whole-share base_size, limit price, time_in_force=GTD, and end_time. The ChatGPT trading flow validates this set. Check the selected surface’s schema before submission: the core MCP’s current orders_preview does not expose time_in_force or end_time, and equity session/date fields can be disabled for an account. Do not assume a preview validated an expiry it could not accept.
• Market or quote-sized equity orders can be rejected outside normal hours. Do not assume they queue for the next open. Report the rejection; ask before changing the session, order type, sizing, or execution time.
• An equity preview may fail with API order preview is not available for equities products. Report the missing estimate rather than retrying it or calling orders_create as a test. If the user required a preview before execution, stop. An explicitly authorized order without a preview still needs the applicable equity checks.
• A returned order ID is not a fill. Read orders_get/orders_list and fills to distinguish accepted/open, filled, canceled, or rejected states. Inspect per-order cancellation results; don’t treat an HTTP success as proof of cancellation.

​

Orders

​

Portfolios & Balances

​

Conversions

​

Info & Session

​

Agent-Critical Flags

​

Field syntax

​

Workflows

​

1. Check price and preview a trade

# Get current BTC price
coinbase products get BTC-USD --jq '.price'

# Preview a $100 market buy (shows fees + estimated fill price)
coinbase orders preview product_id=BTC-USD side=BUY type=market quote_size=100

# If preview looks good, execute
coinbase orders create product_id=BTC-USD side=BUY type=market quote_size=100 client_order_id=$(uuidgen)

# Check order status
coinbase orders get <order_id>

​

2. Sell an asset

# Check how much you hold
coinbase balance --jq '.accounts[] | select(.currency=="DOGE")'

# Preview the sell
coinbase orders preview product_id=DOGE-USD side=SELL type=market base_size=10

# Execute
coinbase orders create product_id=DOGE-USD side=SELL type=market base_size=10 client_order_id=$(uuidgen)

​

3. Transfer funds between portfolios

# List portfolios to get UUIDs
coinbase portfolios list --jq '.portfolios[] | {name, uuid}'

# Transfer $100 USD from Default to agent portfolio
coinbase transfer amount=100 currency=USD from=<default_uuid> to=<agent_uuid>

​

4. Convert USDC to USD (or vice versa)

# Get a quote
coinbase convert quote from=USD to=USDC amount=50

# Execute the conversion using the quote ID from the response
coinbase convert execute <quote_id> from=USD to=USDC

​

5. Discover field names for any command

# Don't know what fields an order takes? Print the template:
coinbase orders create --template

# Then assemble and verify without sending:
coinbase orders create product_id=BTC-USD side=BUY type=market quote_size=10 --dry-run

​

6. Filter large result sets

# Find all USD trading pairs
coinbase products list symbol==USD

# Top 10 USD products by 24h volume
coinbase products list symbol==USD --jq '[.products | sort_by(.volume_24h | tonumber) | reverse | .[:10] | .[].product_id]'

​

Local MCP Server Setup

claude mcp add --scope user --transport stdio coinbase -- coinbase mcp

{ "command": "coinbase", "args": ["mcp"], "transport": "stdio" }

​

Install agent skills

coinbase skills add

coinbase skills add --dir <skills-directory>

​

Gotchas

• Products list returns hundreds of items. Use symbol==USD to filter by currency, or --jq for custom filters.
• client_order_id prevents duplicate orders. If your connection drops mid-request, retrying with the same client_order_id returns the existing order instead of creating a new one. Always generate one per order attempt.
• Futures orders need base_size, not quote_size. CFM dated-futures market orders reject quote_size — use base_size (number of contracts). They’re available only in your default portfolio, so configure the API key to include that portfolio; a key scoped only to an isolated agent portfolio cannot place futures orders. Preview the order first and read back predicted_liquidation_price.
• Equities use TICKER-QUOTE product IDs, such as AAPL-USD or AAPL-USDC. Discover eligible tickers rather than assuming a fixed index list. Read product-type limitations and equity session rules before planning an equity order.
• nvm/fnm users: Upgrading Node versions requires reinstalling global packages. After upgrading, open a new terminal and run npm i -g @coinbase/coinbase-cli again.
• USDC pairs: When buying crypto with a USDC balance, use USDC pairs (e.g., BTC-USDC not BTC-USD). The agent may default to USD pairs otherwise.
• x402 routing: Explicitly tell the agent “use x402 fetch to…” or “you have authorization to pay for this data” so it routes to the correct tool.

​

Troubleshooting

​

Remote MCP integration reference

​

OAuth endpoints and discovery

​

Register and authorize

1. Reuse the approved client registration. If the harness needs DCR, POST its real client metadata as JSON to the registration endpoint. Include its client_name, exact redirect_uris, response_types: ["code"], grant_types: ["authorization_code", "refresh_token"], and token_endpoint_auth_method: "none" for a public client. Use only a callback the harness controls. Save the returned client_id securely rather than registering again each run. Do not put resource in the DCR JSON; it belongs on authorization and token requests.
2. Request consent. Generate a fresh cryptographically random state and PKCE verifier; derive the S256 challenge. Open the authorization endpoint in the user’s browser with the fields below. The user signs in on Coinbase and chooses the permissions/portfolios to approve.
3. Exchange the code. At the registered callback, verify state before accepting the code. POST a form-encoded token request using grant_type=authorization_code, client_id, the same redirect_uri, code, code_verifier, and resource=https://agents.coinbase.com/mcp. Public clients registered with none do not send a client secret.
4. Store and refresh securely. Keep tokens in the harness’s credential store, never in model-visible logs, prompts, source files, or chat. Use the returned expires_in; request offline_access if continued access needs a refresh token. Refresh at the token endpoint with grant_type=refresh_token, client_id, refresh_token, and the same resource identifier. Atomically save replacement tokens and serialize refresh attempts; do not keep reusing a rotated refresh token. Reconnect if consent is revoked or refresh fails permanently.

response_type=code
client_id=<registered client ID>
redirect_uri=<exact registered callback>
state=<fresh random state>
code_challenge=<base64url SHA-256 of PKCE verifier>
code_challenge_method=S256
resource=https://agents.coinbase.com/mcp

​

Scope reference

​

Verify the connection

Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "your-harness", "version": "1.0.0" }
  }
}

{ "jsonrpc": "2.0", "method": "notifications/initialized" }

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "coinbase_portfolios_list", "arguments": {} }
}

​

Rate limits and connection failures

• HTTP 429 or a rate-limit tool error: honor Retry-After when present; otherwise use bounded exponential backoff with jitter. Reduce concurrency instead of retrying continuously.
• HTTP 401: let the harness refresh the connection or ask the user to reconnect through its Coinbase OAuth flow. Do not handle tokens or register a new OAuth client yourself.
• Missing scopes: ask the user to reconnect and approve the required permissions. A working tools/list does not prove every tool call is authorized.
• Registration or authorization denied: if the harness is not listed under Setup, follow the CLI-or-unsupported guidance there. For a supported harness, report the error and request help through CDP Discord. Do not switch to manual registration or bypass access restrictions.
• Unsupported product/session or unavailable tool: use the product guidance and current schema; don’t change the product, session, or order type without authorization.
• Unknown write outcome: inspect order/payment state and preserve the original idempotency key before considering a retry. Connection setup never requires a write.