Coinbase for Agents (CLI/MCP) - Coinbase Developer Documentation

The Coinbase CLI gives you headless access to Coinbase Advanced Trade. Install once, authenticate with a CDP API key, and trade crypto with JSON output, order preview, and a built-in MCP server.

Trade from the terminal

Market and limit orders, portfolio management, and USDC/USD conversions from the command line.

AI-native

JSON output by default, an MCP server for agent tool-calling, and a bundled skill file for agent self-onboarding.

Preview before you execute

Every write operation supports --dry-run and order preview. See fees, slippage, and estimated fill price before committing.

Zero dependencies

A single ESM bundle on Node.js 22+. No runtime dependencies.

Get started

The fastest way to get started is to point your AI agent at the setup instructions. Copy this into Claude Code, Cursor, Codex, or any coding agent:

Follow https://docs.cdp.coinbase.com/coinbase-cli/skill.md to install and configure the Coinbase CLI.

Your agent will install the CLI, walk you through API key creation, and verify the connection.

The skill file is a machine-readable guide that teaches agents how to install, authenticate, and use the CLI. It covers every command and common workflows.

Manual install

If you prefer to set things up yourself:

1. Install the CLI

npm install -g @coinbase/coinbase-cli
coinbase --version

Node.js 22 or later is required.

nvm/fnm users: Each Node version has its own global packages. If you upgrade Node, reinstall the CLI in a new terminal:

npm install -g @coinbase/coinbase-cli

Linux only: install keyring support to keep secrets out of plaintext:

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

2. Create a CDP API key

Go to API Keys in the CDP Portal (a project is auto-created on first sign-in)
Click Create API Key and give it a name (e.g., my-trading-agent)
Under API restrictions, enable Trade and Transfer (View is enabled by default)
Under Advanced settings, change the key type to ECDSA
Click Create & Download and save the JSON key file

The key secret is only shown at creation time. The brokerage API requires ECDSA keys. Ed25519 keys return HTTP 401.

3. Configure and verify

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

4. Check a price and place a trade

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

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

# Execute the trade with an idempotent order ID
coinbase orders create product_id=BTC-USD side=BUY type=market \
  quote_size=10 client_order_id=$(uuidgen)

# Check the order
coinbase orders get <order_id>

client_order_id makes the order idempotent. If your connection drops and you retry with the same ID, the API returns the existing order instead of creating a duplicate. Always include one.

Commands

Market data

Command	Description
`coinbase products get <product_id>`	Price, 24-hour volume/change, and size limits
`coinbase products list`	All tradable products (900+ results, filter with `symbol` or `--jq`)
`coinbase products list symbol==USD`	Products with USD as the base or quote currency
`coinbase products ticker <product_id>`	Recent trades with best bid/ask
`coinbase products book <product_id>`	Full order book (bids + asks)
`coinbase products candles <product_id> granularity==1h`	OHLCV price history
`coinbase products best-bid-ask product_ids=BTC-USD`	Current best bid and ask

Orders

Command	Description
`coinbase orders preview ...`	Dry-run: returns fill estimate, fees, and slippage
`coinbase orders create ...`	Execute an order
`coinbase orders list`	All orders with status, fill percentage, and fees
`coinbase orders get <order_id>`	Single order detail
`coinbase orders fills`	All trade fills with price, size, and commission
`coinbase orders edit <order_id>`	Modify an existing order
`coinbase orders cancel order_ids:='["<id>"]'`	Batch cancel orders
`coinbase orders close-position product_id=<id> size=<n>`	Close an open position

Market order: executes immediately at the best available price.

# Buy $100 of BTC (quote_size = USD amount to spend)
coinbase orders create product_id=BTC-USD side=BUY type=market quote_size=100

# Sell 0.5 ETH (base_size = amount of the asset to sell)
coinbase orders create product_id=ETH-USD side=SELL type=market base_size=0.5

Limit order: executes at the specified price or better.

coinbase orders create product_id=BTC-USD side=BUY type=limit \
  base_size=0.001 limit_price=50000

Market buys use quote_size (the amount to spend in USD). Market sells use base_size (the amount of the asset to sell). When switching between buy and sell, explicitly clear the other field (e.g., add quote_size= to clear a stale value).

Portfolios and balances

Command	Description
`coinbase balance`	All account balances (crypto + fiat)
`coinbase portfolios list`	All portfolios with UUID, name, and type
`coinbase portfolios get <portfolio_id>`	Breakdown: balances, positions, allocation %, unrealized PnL
`coinbase portfolios create name=<name>`	Create a new portfolio
`coinbase portfolios edit <portfolio_id> name=<n>`	Rename a portfolio
`coinbase portfolios delete <portfolio_id>`	Delete a portfolio (must be empty)
`coinbase transfer amount=<n> currency=<c> from=<uuid> to=<uuid>`	Move funds between portfolios

Conversions

Command	Description
`coinbase convert quote from=<c> to=<c> amount=<n>`	Get a conversion quote (rate + fee)
`coinbase convert execute <quote_id> from=<c> to=<c>`	Execute a quoted conversion
`coinbase convert get <quote_id>`	Check conversion status

Info and session

Command	Description
`coinbase fees`	Fee tier (maker/taker rates) and 30-day volume
`coinbase env`	View and manage credential environments
`coinbase mcp`	Start the MCP server (stdio)

Global flags

These flags work on any command:

Flag	What it does	When to use
`--template`	Print the expected request body without sending	Before your first call to any command. Discover field names instead of guessing.
`--dry-run`	Assemble the full request and print it without sending	Before any write operation to verify what will be sent
`--jq <expr>`	Filter the JSON response with a jq expression	Extract specific fields: `--jq '.price'`, `--jq '.accounts[].currency'`
`-e <env>`	Override the active environment	Switch between configured environments

Field syntax

Syntax	Meaning	Example
`key=value`	String body field	`product_id=BTC-USD`
`key:=value`	Raw JSON (arrays, numbers, Boolean values)	`order_ids:='["abc","def"]'`
`key==value`	Query parameter	`product_type==SPOT`
`@file.json`	Load body from a JSON file	`@order.json`

MCP server

The CLI includes an MCP server that exposes every command as a typed tool. When your agent needs to check prices, preview orders, or manage portfolios, it calls the corresponding tool. The CLI handles auth, request formatting, and JSON parsing. Claude Code:

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

Other MCP clients (Cursor, Windsurf, etc.), add to your MCP config:

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

Without a global install, use npx:

{
  "mcpServers": {
    "coinbase": {
      "command": "npx",
      "args": ["-y", "@coinbase/coinbase-cli", "mcp"],
      "transport": "stdio"
    }
  }
}

The MCP server runs on stdio (no network ports opened) and uses the same credentials configured with coinbase env.

Coinbase CLI vs. CDP CLI

	Coinbase CLI	CDP CLI
Command	`coinbase`	`cdp`
Purpose	Trade crypto on Coinbase Advanced Trade	Build apps on CDP APIs (server wallets, onchain data, x402)
Example	`coinbase orders create product_id=BTC-USD ...`	`cdp evm accounts create name=my-wallet`
Package	`@coinbase/coinbase-cli`	`@coinbase/cdp-cli`
Auth	CDP API key (ECDSA, with Trade + Transfer permissions)	CDP API key + wallet secret

Both run as MCP servers. Use the Coinbase CLI when you need exchange trading. Use the CDP CLI when you need onchain infrastructure.

Troubleshooting

Error	Cause	Fix
`HTTP 401`	Ed25519 key or expired credentials	Create a new ECDSA key in the CDP Portal
`HTTP 403 Missing required scopes`	API key missing Trade or Transfer permission	Check key permissions in the Portal
`insufficient fund`	Account balance too low	Run `coinbase balance` to check available funds
`coinbase: command not found`	CLI not on PATH	Run `npm install -g @coinbase/coinbase-cli`; on Windows, add `%APPDATA%\npm` to PATH
`MISSING_FIELDS`	Required fields not provided	Run `coinbase <command> --template` to see expected fields
`INVALID_VALUE`	Unrecognized enum value	Check the error message for accepted values
`INVALID_FORMAT`	Wrong date/time format	Use RFC 3339 with timezone (e.g., `2024-01-01T00:00:00Z`)

Documentation Index

Trade from the terminal

AI-native

Preview before you execute

Zero dependencies

​Get started

​Manual install

​1. Install the CLI

​2. Create a CDP API key

​3. Configure and verify

​4. Check a price and place a trade

​Commands

​Market data

​Orders

​Portfolios and balances

​Conversions

​Info and session

​Global flags

​Field syntax

​MCP server

​Coinbase CLI vs. CDP CLI

​Troubleshooting

Get started

Manual install

1. Install the CLI

2. Create a CDP API key

3. Configure and verify

4. Check a price and place a trade

Commands

Market data

Orders

Portfolios and balances

Conversions

Info and session

Global flags

Field syntax

MCP server

Coinbase CLI vs. CDP CLI

Troubleshooting