> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coinbase for Agents (CLI/MCP)

> Give your AI agent access to Coinbase.

Coinbase for Agents gives your AI apps access to [Coinbase Advanced Trade](https://www.coinbase.com/advanced-trade) to trade crypto, preview orders, and manage portfolios from any AI harness or the terminal.

## Get started

<Tip>
  **Portfolio isolation:** Create a separate [Advanced portfolio](https://www.coinbase.com/advanced-trade), fund it with only what you're willing to risk, and scope your agent's access to that portfolio. This limits the blast radius if the agent makes an unexpected trade.
</Tip>

<Tabs>
  <Tab title="Local MCP / CLI (recommended)">
    The local MCP server runs on your machine with a CDP API key. It's the most reliable setup for executing trades consistently across all models — remote MCP has known issues with high-reasoning models blocking trades on certain platforms.

    ### Quickstart

    Paste this into your coding agent and it will install, configure, and verify automatically:

    ```
    Follow https://docs.cdp.coinbase.com/coinbase-for-agents/skill.md to install and configure Coinbase for Agents.
    ```

    Your agent will ask you to create a CDP API key (below) during setup.

    ### Create a CDP API key

    1. Go to [API Keys](https://portal.cdp.coinbase.com/projects/api-keys) in the CDP Portal (a project is auto-created on first sign-in)
    2. Click **Create API Key** and give it a name (e.g., `my-trading-agent`)
    3. Under **Advanced Settings** > **Coinbase App & Advanced Trade**:
       * Under **Accounts**, select the portfolio you want the agent to trade from (Primary is selected by default)
       * Enable **Trade** and **Transfer**. Transfer allows moves between your portfolios only and does not allow withdrawals to external addresses.
       * Check **Opt out of IP allowlisting** if you haven't configured specific IP addresses.
    4. Click **Create & Download** and save the JSON key file

    <Warning>
      The key secret is only shown at creation time.
    </Warning>

    ### Manual setup

    If you prefer to set things up yourself instead of using the quickstart:

    **1. Install the CLI**

    ```bash theme={null}
    npm install -g @coinbase/coinbase-cli
    coinbase --version
    ```

    <Info>
      Node.js 22 or later is required.
    </Info>

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

    ```bash theme={null}
    which secret-tool || sudo apt install -y libsecret-tools
    ```

    **2. Configure your API key**

    ```bash theme={null}
    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
    ```

    **3. Register the MCP server**

    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --scope user --transport stdio coinbase -- coinbase mcp
        ```
      </Tab>

      <Tab title="Codex">
        ```bash theme={null}
        codex mcp add coinbase -- coinbase mcp
        ```
      </Tab>

      <Tab title="Cursor / Windsurf">
        Add to your MCP config file:

        ```json theme={null}
        {
          "mcpServers": {
            "coinbase": {
              "command": "coinbase",
              "args": ["mcp"]
            }
          }
        }
        ```
      </Tab>

      <Tab title="Other MCP clients">
        Add to your agent's MCP configuration:

        ```json theme={null}
        { "command": "coinbase", "args": ["mcp"] }
        ```

        **Without a global install**, use `npx` (replace `coinbase` with `npx -y @coinbase/coinbase-cli`).
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Remote MCP (ChatGPT & Claude)">
    The remote MCP connects directly to `https://agents.coinbase.com/mcp` via OAuth — no local install required. Currently supported in **ChatGPT** (web, desktop, mobile) and **Claude** (web, desktop, mobile). Note: on hosted chat clients, high-reasoning and extended-thinking modes sometimes draft an order but stop short of executing it. If that happens, reply asking the agent to place the order explicitly, or use the local MCP setup above for the most consistent execution.

    <Tabs>
      <Tab title="ChatGPT (web, desktop, mobile)">
        <Frame>
          <video controls className="w-full aspect-video" src="https://mintcdn.com/coinbase-prod/VEOiRsdcuIXl9Rfc/coinbase-for-agents/videos/connect-chatgpt.mp4?fit=max&auto=format&n=VEOiRsdcuIXl9Rfc&q=85&s=ee36d27c419dfb3981d627e1df5a68d1" data-path="coinbase-for-agents/videos/connect-chatgpt.mp4" />
        </Frame>

        <Warning>
          **Prerequisite:** You must enable **developer mode** in ChatGPT before the "Create App" option appears. Go to **Settings** > **Apps** > **Advanced Settings** and toggle on developer mode.
        </Warning>

        1. Click your **profile icon** in the bottom-left corner
        2. Click **Settings** > **Apps** > **Create App**
        3. Name the app (e.g., "Coinbase") and set the connection URL to `https://agents.coinbase.com/mcp`
        4. Click **Create**
        5. Sign in with your Coinbase account when prompted

        <Info>
          **Desktop & mobile:** Set up the connection on ChatGPT web first. Once connected, the app will automatically be available in ChatGPT desktop and mobile.
        </Info>
      </Tab>

      <Tab title="Claude (web, desktop, mobile)">
        <Frame>
          <video controls className="w-full aspect-video" src="https://mintcdn.com/coinbase-prod/6dQ55Y4ZSkfpLVIM/coinbase-for-agents/videos/connect-claude.mp4?fit=max&auto=format&n=6dQ55Y4ZSkfpLVIM&q=85&s=e78fd2219fd2b3757f3168c284abafd6" data-path="coinbase-for-agents/videos/connect-claude.mp4" />
        </Frame>

        1. Click the **Customize** toolbox icon in the left sidebar
        2. Go to **Connectors**
        3. Click the **+** button, then **Add custom connector**
        4. Name it (e.g., "Coinbase") and enter the server URL: `https://agents.coinbase.com/mcp`
        5. Leave all other fields blank — click **Create**
        6. Sign in with your Coinbase account when prompted
        7. On the approval screen, select which portfolios to give the agent access to

        <Warning>
          **Known limitation:** On hosted chat clients, high-reasoning and extended-thinking modes sometimes draft an order but stop short of placing it. If your agent only previews, ask it explicitly to execute the order — or use the local MCP setup above, which executes most consistently across models.
        </Warning>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

<Info>
  To disconnect Coinbase from an app, go to [Coinbase Account > Security > Connections](https://accounts.coinbase.com/security/connections) and revoke the connection.
</Info>

***

## What's supported today

Coinbase for Agents currently supports:

* **Spot crypto trading**: buy and sell 900+ trading pairs on Coinbase Advanced Trade
* **Isolated agent portfolios**: spot crypto only, scoped to a specific portfolio selected when logging in or creating an API key
* **Portfolio management**: Check balances and positions across your account
* **USDC/USD conversions**: instant zero-fee conversions between USDC and USD

<Info>
  **Coming soon:** x402 payments for agent-consumed services (paywalled research, data APIs, compute), equities, prediction markets, and additional asset classes. If it's on Coinbase, your agent will be able to trade it.
</Info>

***

## Guiding agents to place orders

Based on order-creation testing across Claude and ChatGPT clients and models connected to the Coinbase for Agents remote MCP server:

* Web clients for Claude and ChatGPT reliably create orders from clear, well-specified instructions, across models. The exception is **GPT-5.5 Pro**, which doesn't appear to automatically discover the connected MCP.
* Claude previews and requests confirmation in the chat to create the order, whereas ChatGPT creates the order in one turn.
* Claude Desktop refuses most orders that the web client creates; **Sonnet 4.6** is the exception, creating orders when the request includes an explicit authorization (e.g. `I authorize you to buy…`).
* Lower-tier models may create orders with the wrong product, for example, `ETH-USD` instead of `ETH-USDC`. Prompt for approval to confirm before creating the order.

For reliable order creation, specify the order type, the amount and asset or currency, and the portfolio in one instruction, for example, `Buy 1 USDC of ETH in my agent portfolio`. Vague or partial requests require the model to infer and resolve additional details.

### Best practices

* Scope the agent's access to the portfolio(s) you want it to use — a focused set gives the agent a clear, unambiguous target.
* Higher-reasoning models translate more complex intent and recover from underspecified orders; use one for multi-step or vague requests, e.g. `check my balance, then put 5% of my USDC into BTC`.

***

## Tools

### Market data

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

### Orders

| CLI command                                               | MCP tool                | Description                                        |
| :-------------------------------------------------------- | :---------------------- | :------------------------------------------------- |
| `coinbase orders preview ...`                             | `orders_preview`        | Dry-run: returns fill estimate, fees, and slippage |
| `coinbase orders create ...`                              | `orders_create`         | Execute an order                                   |
| `coinbase orders list`                                    | `orders_list`           | All orders with status, fill percentage, and fees  |
| `coinbase orders get <order_id>`                          | `orders_get`            | Single order detail                                |
| `coinbase orders fills`                                   | `orders_fills`          | All trade fills with price, size, and commission   |
| `coinbase orders edit <order_id>`                         | `orders_edit`           | Modify an existing order                           |
| `coinbase orders cancel order_ids:='["<id>"]'`            | `orders_cancel`         | Batch cancel orders                                |
| `coinbase orders close-position product_id=<id> size=<n>` | `orders_close_position` | Close an open position                             |

**Market order**: executes immediately at the best available price.

```bash theme={null}
# 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.

```bash theme={null}
coinbase orders create product_id=BTC-USD side=BUY type=limit \
  base_size=0.001 limit_price=50000
```

<Info>
  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).
</Info>

### Portfolios and balances

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

### Conversions

| CLI command                                           | MCP tool          | Description                         |
| :---------------------------------------------------- | :---------------- | :---------------------------------- |
| `coinbase convert quote from=<c> to=<c> amount=<n>`   | `convert_quote`   | Get a conversion quote (rate + fee) |
| `coinbase convert execute <quote_id> from=<c> to=<c>` | `convert_execute` | Execute a quoted conversion         |
| `coinbase convert get <quote_id>`                     | `convert_get`     | Check conversion status             |

### Info and session

| CLI command     | MCP tool | Description                                    |
| :-------------- | :------- | :--------------------------------------------- |
| `coinbase fees` | `fees`   | Fee tier (maker/taker rates) and 30-day volume |
| `coinbase env`  | —        | View and manage credential environments        |
| `coinbase mcp`  | —        | Start the local MCP server (stdio)             |

***

## Global flags

These flags work on any CLI command:

| Flag          | What it does                                                                  | When to use                                                                                                                                |
| :------------ | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `--watch`     | Live-stream updates over WebSocket (local CLI + CDP API key; not OAuth)       | Only on `orders list`, `products ticker`, `products book` — e.g. watch a price live, or add `--until "price > 70k"` to exit on a condition |
| `--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](https://jqlang.github.io/jq/) expression | Extract specific fields: `--jq '.price'`, `--jq '.accounts[].currency'`                                                                    |
| `-e <env>`    | Override the active environment                                               | Switch between configured environments                                                                                                     |

## Field syntax

CLI commands use the following 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`                |

## Troubleshooting

| Error                              | Cause                                        | Fix                                                                                     |
| :--------------------------------- | :------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `HTTP 401`                         | Expired credentials                          | Create a new key in the [CDP Portal](https://portal.cdp.coinbase.com/projects/api-keys) |
| `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`)                               |

***

## 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 and authorizing any trades, transfers, or account changes made through agentic workflows.