Advanced Trade Orders API — Submit, Cancel & Query Orders

The Advanced Trade Orders endpoints cover the full order lifecycle: previewing, submitting, editing, cancelling, and querying historical orders and fills. The client_order_id field is optional — if omitted, the SDK automatically generates a unique value prefixed with cbnode. Bracket and stop-limit order types are supported alongside standard market and limit orders.

submitOrder

Create a new order. The order_configuration field determines the order type and time-in-force. Exactly one configuration key must be provided.


Auth	Required
HTTP	`POST /api/v3/brokerage/orders`

product_id

string

required

The trading pair to trade, e.g. BTC-USD or ETH-USDC.

side

string

required

Order direction. Must be "BUY" or "SELL".

order_configuration

OrderConfiguration

required

Exactly one order type object. See the configuration types table below.

client_order_id

string

A unique client-supplied identifier. The SDK auto-generates one (prefixed cbnode) if omitted. Custom values must also start with cbnode.

leverage

string

Leverage multiplier for margin/futures orders, e.g. "3".

margin_type

string

Margin mode for leveraged orders. One of "CROSS" or "ISOLATED".

attached_order_configuration

OrderConfiguration

An optional secondary order configuration attached to this order (e.g. a take-profit or stop-loss leg).

preview_id

string

The preview_id returned by previewOrder() — links this order to a prior preview.

Order configuration types

Key	Description	Required fields
`market_market_ioc`	Market order, immediate-or-cancel	`base_size` or `quote_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`
`limit_limit_fok`	Limit order, fill-or-kill	`base_size`, `limit_price`
`sor_limit_ioc`	SOR limit, immediate-or-cancel	`base_size`, `limit_price`
`stop_limit_stop_limit_gtc`	Stop-limit, good-till-cancelled	`base_size`, `limit_price`, `stop_price`, `stop_direction`
`stop_limit_stop_limit_gtd`	Stop-limit, good-till-date	`base_size`, `limit_price`, `stop_price`, `stop_direction`, `end_time`
`trigger_bracket_gtc`	Bracket order, good-till-cancelled	`base_size`, `limit_price`, `stop_trigger_price`
`trigger_bracket_gtd`	Bracket order, good-till-date	`base_size`, `limit_price`, `stop_trigger_price`, `end_time`
`twap_limit_gtd`	TWAP limit, good-till-date	`quote_size`, `base_size`, `start_time`, `end_time`, `limit_price`

Returns: Promise<AdvTradeSubmitOrderResponse> — contains success boolean, an optional success_response with order_id, product_id, side, and client_order_id, and an optional error_response on failure.

import { CBAdvancedTradeClient } from 'coinbase-api';

const client = new CBAdvancedTradeClient({
  apiKey: 'your-api-key-name',
  apiSecret: '-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----\n',
});

// Place a limit GTC buy order for 0.001 BTC at $60,000
const result = await client.submitOrder({
  product_id: 'BTC-USD',
  side: 'BUY',
  order_configuration: {
    limit_limit_gtc: {
      base_size: '0.001',
      limit_price: '60000.00',
      post_only: false,
    },
  },
});

if (result.success) {
  console.log('Order placed:', result.success_response?.order_id);
} else {
  console.error('Order failed:', result.error_response?.message);
}

cancelOrders

Initiate cancel requests for one or more orders in a single batch call. A maximum of 100 order IDs may be submitted per request.


Auth	Required
HTTP	`POST /api/v3/brokerage/orders/batch_cancel`

order_ids

string[]

required

Array of order IDs to cancel. Maximum 100 entries per request.

Returns: Promise<AdvTradeCancelOrdersResponse> — an object with a results array. Each entry contains order_id, success boolean, and failure_reason.

const { results } = await client.cancelOrders({
  order_ids: [
    'afe6bb33-7a2a-4aa2-af41-3e9f09428e2b',
    '11d15534-0b0a-4beb-9e27-a5d2b6b5c5e3',
  ],
});

results.forEach(r => {
  if (r.success) {
    console.log(`Cancelled: ${r.order_id}`);
  } else {
    console.warn(`Failed to cancel ${r.order_id}: ${r.failure_reason}`);
  }
});

updateOrder

Edit the price or size of an existing open limit GTC order. Note the queue-position rules: increasing size or changing price moves your order to the back of the queue; decreasing size keeps your place.


Auth	Required
HTTP	`POST /api/v3/brokerage/orders/edit`

order_id

string

required

The ID of the order to edit. Only open limit GTC orders can be edited.

price

string

New limit price as a decimal string, e.g. "62000.00".

size

string

New base size as a decimal string, e.g. "0.002".

Returns: Promise<AdvTradeEditOrderResponse> — contains success boolean, an optional success_response with order_id, and an optional error_response detailing failure reasons.

const edit = await client.updateOrder({
  order_id: 'afe6bb33-7a2a-4aa2-af41-3e9f09428e2b',
  price: '61500.00',
  size: '0.002',
});

if (edit.success) {
  console.log('Order updated successfully');
} else {
  console.error('Edit failed:', edit.error_response?.edit_order_failure_reason);
}

updateOrderPreview

Preview the outcome of editing an order — including slippage, new totals, and best bid/ask — before committing the change.


Auth	Required
HTTP	`POST /api/v3/brokerage/orders/edit_preview`

order_id

string

required

The ID of the order to preview editing.

price

string

Proposed new limit price as a decimal string.

size

string

Proposed new base size as a decimal string.

Returns: Promise<AdvTradeEditOrderPreviewResponse> — includes slippage, order_total, commission_total, quote_size, base_size, best_bid, best_ask, average_filled_price, and any errors.

const preview = await client.updateOrderPreview({
  order_id: 'afe6bb33-7a2a-4aa2-af41-3e9f09428e2b',
  price: '61500.00',
});

console.log('Estimated order total:', preview.order_total);
console.log('Commission:', preview.commission_total);

getOrders

List historical orders filtered by optional query parameters. Open orders are limited to a maximum of 1,000 results. The start_date and end_date filters do not apply to open orders.


Auth	Required
HTTP	`GET /api/v3/brokerage/orders/historical/batch`

order_ids

string[]

Filter to specific order IDs.

product_ids

string[]

Filter by one or more product IDs, e.g. ["BTC-USD", "ETH-USD"].

product_type

string

Filter by product type: "SPOT", "FUTURE", or "UNKNOWN_PRODUCT_TYPE".

order_status

string[]

Filter by status strings, e.g. ["OPEN"], ["FILLED"], ["CANCELLED"].

time_in_forces

string[]

Filter by time-in-force values, e.g. ["GOOD_UNTIL_CANCELLED"].

order_types

string[]

Filter by order type strings, e.g. ["LIMIT"], ["MARKET"].

order_side

string

Filter to "BUY" or "SELL" orders only.

start_date

string

RFC3339 timestamp. Start of the date range for filled/cancelled orders.

end_date

string

RFC3339 timestamp. End of the date range.

order_placement_source

string

Filter by order placement source: "UNKNOWN_PLACEMENT_SOURCE", "RETAIL_SIMPLE", or "RETAIL_ADVANCED".

contract_expiry_type

string

Filter futures by contract expiry: "UNKNOWN_CONTRACT_EXPIRY_TYPE", "PERPETUAL", or "EXPIRING".

asset_filters

string[]

Filter orders by asset identifiers.

limit

number

Maximum number of orders to return per page.

cursor

string

Pagination cursor from a previous response.

sort_by

string

Sort results by "UNKNOWN_SORT_BY", "LIMIT_PRICE", or "LAST_FILL_TIME".

Returns: Promise<{ orders: AdvTradeOrder[]; has_next: boolean; cursor?: string; sequence?: number }>.

// Fetch all open BTC-USD orders
const { orders, has_next, cursor } = await client.getOrders({
  product_ids: ['BTC-USD'],
  order_status: ['OPEN'],
  limit: 100,
});

console.log(`Found ${orders.length} open orders`);

getFills

Retrieve a list of fills (trade executions) filtered by order, product, or time range.


Auth	Required
HTTP	`GET /api/v3/brokerage/orders/historical/fills`

order_ids

string[]

Filter fills for specific order IDs.

trade_ids

string[]

Filter fills for specific trade IDs.

product_ids

string[]

Filter fills for specific products.

start_sequence_timestamp

string

RFC3339 timestamp. Return fills at or after this sequence time.

end_sequence_timestamp

string

RFC3339 timestamp. Return fills at or before this sequence time.

retail_portfolio_id

string

Filter fills by retail portfolio ID.

limit

number

Maximum number of fills to return per page.

cursor

string

Pagination cursor from a previous response.

sort_by

string

Sort fills by "UNKNOWN_SORT_BY", "PRICE", or "TRADE_TIME".

Returns: Promise<{ fills: AdvTradeFill[]; cursor?: string }> — each AdvTradeFill contains entry_id, trade_id, order_id, price, size, commission, side, and RFC3339 trade_time.

const { fills } = await client.getFills({
  product_ids: ['BTC-USD'],
  start_sequence_timestamp: '2024-01-01T00:00:00Z',
  end_sequence_timestamp: '2024-01-31T23:59:59Z',
  limit: 250,
});

const totalCommission = fills.reduce(
  (sum, f) => sum + parseFloat(f.commission),
  0,
);
console.log(`Total commission paid: ${totalCommission.toFixed(8)}`);

getOrder

Retrieve a single historical order by its order ID.


Auth	Required
HTTP	`GET /api/v3/brokerage/orders/historical/{order_id}`

order_id

string

required

The unique order ID returned by submitOrder().

client_order_id

string

Optionally filter by client-supplied order ID.

user_native_currency

string

Return values expressed in this currency, e.g. "EUR".

Returns: Promise<{ order: AdvTradeOrder }> — the full order record including status, filled_size, average_filled_price, total_fees, and order_configuration.

const { order } = await client.getOrder({
  order_id: 'afe6bb33-7a2a-4aa2-af41-3e9f09428e2b',
});

console.log(`Status: ${order.status}`);
console.log(`Filled: ${order.filled_size} @ ${order.average_filled_price}`);

previewOrder

Simulate submitting an order to see the estimated total, commission, leverage parameters, and possible errors — without actually placing the order.


Auth	Required
HTTP	`POST /api/v3/brokerage/orders/preview`

product_id

string

required

The trading pair to preview, e.g. "BTC-USD".

side

string

required

"BUY" or "SELL".

order_configuration

OrderConfiguration

required

The order configuration to preview. Uses the same structure as submitOrder().

leverage

string

Leverage multiplier for margin/futures previews.

margin_type

string

"ISOLATED" or "CROSS".

retail_portfolio_id

string

Optional retail portfolio ID to associate with the preview.

Returns: Promise<AdvTradeOrderPreview> — includes order_total, commission_total, base_size, quote_size, best_bid, best_ask, slippage, leverage, preview_id, and buffer fields for leveraged positions.

const preview = await client.previewOrder({
  product_id: 'BTC-USD',
  side: 'BUY',
  order_configuration: {
    limit_limit_gtc: {
      base_size: '0.01',
      limit_price: '60000.00',
    },
  },
});

console.log('Estimated order total:', preview.order_total);
console.log('Commission:', preview.commission_total);
// Use preview.preview_id in submitOrder() to link the two calls

closePosition

Place an order that closes any open position for the specified futures or perpetuals product. The SDK auto-generates client_order_id if omitted.


Auth	Required
HTTP	`POST /api/v3/brokerage/orders/close_position`

product_id

string

required

The futures or perpetuals product ID whose open position should be closed.

client_order_id

string

Optional client-supplied identifier. Auto-generated if omitted.

size

string

Quantity to close. Omit to close the entire open position.

Returns: Promise<AdvTradeClosePositionResponse> — contains success, an optional success_response with order details, and an optional error_response.

const result = await client.closePosition({
  product_id: 'BTC-28JUN24-CDE',
});

if (result.success) {
  console.log('Position closed, order ID:', result.success_response?.order_id);
}

Advanced Trade

Other Clients

WebSocket Reference

Advanced Trade Orders API — Submit, Cancel & Query Orders

submitOrder

Order configuration types

cancelOrders

updateOrder

updateOrderPreview

getOrders

getFills

getOrder

previewOrder

closePosition

Build docs developers (and LLMs) love

Advanced Trade

Other Clients

WebSocket Reference

Documentation Index

​submitOrder

​Order configuration types

​cancelOrders

​updateOrder

​updateOrderPreview

​getOrders

​getFills

​getOrder

​previewOrder

​closePosition

Build docs developers (and LLMs) love

submitOrder

Order configuration types

cancelOrders

updateOrder

updateOrderPreview

getOrders

getFills

getOrder

previewOrder

closePosition