> ## Documentation Index
> Fetch the complete documentation index at: https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Place a Crypto Order with the Coinbase Advanced Trade API

> Learn how to place market, limit, and stop-limit crypto orders using the Coinbase Advanced Trade API POST /api/v3/brokerage/orders endpoint.

The Coinbase Advanced Trade API gives you full programmatic control over order placement, letting you buy and sell crypto assets directly from your application. Whether you need to execute an immediate market order, set a precise limit price, or define a stop-limit trigger, a single `POST /api/v3/brokerage/orders` endpoint handles all order types through a flexible `order_configuration` object. This guide walks you through each step of the process and shows you concrete examples for the most common order types.

## Prerequisites

Before placing orders, make sure you have:

* A valid JWT token (see [Authentication](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/authentication.md))
* Sufficient funds in your Coinbase account for the order side and size
* The correct `product_id` for the trading pair you want to trade (e.g., `BTC-USD`)

## Place an order

**1. Choose your product and side**

Every order targets a specific trading pair called a **product**. Products follow the format `BASE-QUOTE` (e.g., `BTC-USD`, `ETH-USDC`). You can retrieve the full list of available products with `GET /api/v3/brokerage/products`.

Along with the product, you must specify a **side**:

| Side | Description |
| - | - |
| `BUY` | Purchase the base currency using quote funds |
| `SELL` | Sell the base currency to receive quote funds |

For example, a `BUY` on `BTC-USD` spends US dollars to acquire Bitcoin; a `SELL` on `BTC-USD` sells Bitcoin for US dollars.

**2. Choose your order type and set parameters**

The `order_configuration` object determines the order type and its parameters. Each type uses a distinct key inside `order_configuration`:

| Key | Order Type | Key Parameters |
| - | - | - |
| `market_market_ioc` | Market order (immediate-or-cancel) | `quote_size` or `base_size` |
| `limit_limit_gtc` | Limit order (good-till-cancelled) | `base_size`, `limit_price` |
| `limit_limit_gtd` | Limit order (good-till-date) | `base_size`, `limit_price`, `end_time` |
| `stop_limit_stop_limit_gtc` | Stop-limit (good-till-cancelled) | `base_size`, `limit_price`, `stop_price`, `stop_direction` |

For market buys, use `quote_size` to specify how many dollars (or quote currency units) to spend. For market sells, use `base_size` to specify how much of the base asset to sell.

**3. Submit POST /api/v3/brokerage/orders**

Send a `POST` request to `https://api.coinbase.com/api/v3/brokerage/orders` with your JWT in the `Authorization` header and a JSON body containing at minimum:

* `client_order_id` — a unique string you generate to identify this order
* `product_id` — the trading pair
* `side` — `BUY` or `SELL`
* `order_configuration` — the order type object with its parameters

See the code examples below for market, limit, and stop-limit orders.

**4. Handle the response and confirm your order ID**

A successful response returns `"success": true` along with an `order_id` (a UUID assigned by Coinbase) and an `order_configuration` echo. Store the `order_id` — you will need it to query order status, cancel the order, or reconcile fills.

If the request fails, the response body contains a `preview_failure_reason` or `error_response` field explaining why. See the [Error handling](#error-handling) section below for common error codes.

## Code examples

### Market buy order

A market buy executes immediately at the best available price. Use `quote_size` to specify the amount of quote currency (e.g., USD) you want to spend.

```bash curl theme={null}
curl -X POST https://api.coinbase.com/api/v3/brokerage/orders \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "my-order-001",
    "product_id": "BTC-USD",
    "side": "BUY",
    "order_configuration": {
      "market_market_ioc": {
        "quote_size": "100"
      }
    }
  }'
```

```python Python theme={null}
import requests
import json

url = "https://api.coinbase.com/api/v3/brokerage/orders"
headers = {
    "Authorization": f"Bearer {JWT}",
    "Content-Type": "application/json",
}
payload = {
    "client_order_id": "my-order-001",
    "product_id": "BTC-USD",
    "side": "BUY",
    "order_configuration": {
        "market_market_ioc": {
            "quote_size": "100"
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print("Order ID:", data["order_id"])
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://api.coinbase.com/api/v3/brokerage/orders",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${JWT}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_order_id: "my-order-001",
      product_id: "BTC-USD",
      side: "BUY",
      order_configuration: {
        market_market_ioc: {
          quote_size: "100",
        },
      },
    }),
  }
);

const data = await response.json();
console.log("Order ID:", data.order_id);
```

### Limit sell order

A limit sell places an order on the order book that executes only when the market price reaches your specified `limit_price` or better. The order remains open until filled or cancelled (`gtc` = good-till-cancelled).

```bash curl theme={null}
curl -X POST https://api.coinbase.com/api/v3/brokerage/orders \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "limit-sell-001",
    "product_id": "BTC-USD",
    "side": "SELL",
    "order_configuration": {
      "limit_limit_gtc": {
        "base_size": "0.001",
        "limit_price": "70000"
      }
    }
  }'
```

```python Python theme={null}
import requests

url = "https://api.coinbase.com/api/v3/brokerage/orders"
headers = {
    "Authorization": f"Bearer {JWT}",
    "Content-Type": "application/json",
}
payload = {
    "client_order_id": "limit-sell-001",
    "product_id": "BTC-USD",
    "side": "SELL",
    "order_configuration": {
        "limit_limit_gtc": {
            "base_size": "0.001",
            "limit_price": "70000"
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print("Order ID:", data["order_id"])
print("Status:", data.get("success"))
```

### Stop-limit order

A stop-limit order triggers a limit order when the market reaches your `stop_price`. Use `STOP_DIRECTION_STOP_UP` to trigger on a price rise, or `STOP_DIRECTION_STOP_DOWN` to trigger on a price drop.

```bash curl theme={null}
curl -X POST https://api.coinbase.com/api/v3/brokerage/orders \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "stop-limit-001",
    "product_id": "BTC-USD",
    "side": "SELL",
    "order_configuration": {
      "stop_limit_stop_limit_gtc": {
        "base_size": "0.01",
        "limit_price": "59500",
        "stop_price": "60000",
        "stop_direction": "STOP_DIRECTION_STOP_DOWN"
      }
    }
  }'
```

```python Python theme={null}
import requests

url = "https://api.coinbase.com/api/v3/brokerage/orders"
headers = {
    "Authorization": f"Bearer {JWT}",
    "Content-Type": "application/json",
}
payload = {
    "client_order_id": "stop-limit-001",
    "product_id": "BTC-USD",
    "side": "SELL",
    "order_configuration": {
        "stop_limit_stop_limit_gtc": {
            "base_size": "0.01",
            "limit_price": "59500",
            "stop_price": "60000",
            "stop_direction": "STOP_DIRECTION_STOP_DOWN",
        }
    },
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print("Order ID:", data["order_id"])
print("Success:", data.get("success"))
```

## Success response

A successful `POST /orders` response looks like this:

```json theme={null}
{
  "success": true,
  "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_order_id": "my-order-001",
  "order_configuration": {
    "market_market_ioc": {
      "quote_size": "100"
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `success` | boolean | `true` when the order was accepted |
| `order_id` | string | Coinbase-assigned UUID for this order |
| `client_order_id` | string | The ID you supplied in the request |
| `order_configuration` | object | Echo of the order type and parameters you submitted |

> [!WARNING]
>
> Always generate a unique `client_order_id` for every order request. If a network timeout causes you to retry, submitting the same `client_order_id` will be rejected as a duplicate rather than creating a second order — protecting you from accidental double-fills.

## Error handling

When `"success": false` or the HTTP status is 4xx, the response includes an error code you can use to diagnose the problem programmatically.

```json theme={null}
{
  "success": false,
  "failure_reason": "INSUFFICIENT_FUND",
  "preview_failure_reason": "PREVIEW_INSUFFICIENT_FUND",
  "error_response": {
    "error": "INSUFFICIENT_FUND",
    "message": "Insufficient funds to place this order.",
    "preview_failure_reason": "PREVIEW_INSUFFICIENT_FUND"
  }
}
```

| Error Code | HTTP Status | Cause & Resolution |
| - | - | - |
| `INSUFFICIENT_FUND` | 400 | Your account does not have enough balance. Check your available funds and reduce order size. |
| `INVALID_PRODUCT_ID` | 400 | The `product_id` does not exist or is misspelled. Fetch `/api/v3/brokerage/products` to verify. |
| `ORDER_ENTRY_DISABLED` | 400 | Trading is temporarily suspended for this product. Retry after the suspension lifts. |
| `INVALID_LIMIT_PRICE` | 400 | The limit price violates the product's minimum price increment. Check product details. |
| `PERMISSION_DENIED` | 403 | Your API key lacks trading permissions. Regenerate a key with the correct scopes. |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests. Back off and retry using exponential backoff. |

> [!TIP]
>
> Before placing a large order, call `GET /api/v3/brokerage/products/{product_id}` to check the `base_min_size`, `base_max_size`, `quote_increment`, and `base_increment` fields. Submitting an order below the minimum size or with an incorrect increment is a common source of validation errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.