POST
/
api
/
v3
/
brokerage
/
orders
/
preview
Preview Order
curl --request POST \
  --url https://api.coinbase.com/api/v3/brokerage/orders/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "product_id": "<string>",
  "side": "BUY",
  "order_configuration": {
    "market_market_ioc": {
      "quote_size": "10.00",
      "base_size": "0.001"
    },
    "market_market_fok": {
      "quote_size": "10.00",
      "base_size": "0.001"
    },
    "sor_limit_ioc": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00"
    },
    "limit_limit_gtc": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00",
      "post_only": false
    },
    "limit_limit_gtd": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00",
      "end_time": "2021-05-31T09:59:59.000Z",
      "post_only": false
    },
    "limit_limit_fok": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00"
    },
    "twap_limit_gtd": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "start_time": "2021-05-31T07:59:59.000Z",
      "end_time": "2021-05-31T09:59:59.000Z",
      "limit_price": "10000.00",
      "number_buckets": "5",
      "bucket_size": "2.00",
      "bucket_duration": "300s"
    },
    "stop_limit_stop_limit_gtc": {
      "base_size": "0.001",
      "limit_price": "10000.00",
      "stop_price": "20000.00",
      "stop_direction": "20000.00"
    },
    "stop_limit_stop_limit_gtd": {
      "base_size": 0.001,
      "limit_price": "10000.00",
      "stop_price": "20000.00",
      "end_time": "2021-05-31T09:59:59.000Z",
      "stop_direction": "20000.00"
    },
    "trigger_bracket_gtc": {
      "base_size": 0.001,
      "limit_price": "10000.00",
      "stop_trigger_price": "20000.00"
    },
    "trigger_bracket_gtd": {
      "base_size": 0.001,
      "limit_price": "10000.00",
      "stop_trigger_price": "20000.00",
      "end_time": "2021-05-31T09:59:59.000Z"
    }
  },
  "leverage": "2.0",
  "margin_type": "CROSS",
  "retail_portfolio_id": "11111111-1111-1111-1111-111111111111",
  "attached_order_configuration": {
    "market_market_ioc": {
      "quote_size": "10.00",
      "base_size": "0.001"
    },
    "market_market_fok": {
      "quote_size": "10.00",
      "base_size": "0.001"
    },
    "sor_limit_ioc": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00"
    },
    "limit_limit_gtc": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00",
      "post_only": false
    },
    "limit_limit_gtd": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00",
      "end_time": "2021-05-31T09:59:59.000Z",
      "post_only": false
    },
    "limit_limit_fok": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "limit_price": "10000.00"
    },
    "twap_limit_gtd": {
      "quote_size": "10.00",
      "base_size": "0.001",
      "start_time": "2021-05-31T07:59:59.000Z",
      "end_time": "2021-05-31T09:59:59.000Z",
      "limit_price": "10000.00",
      "number_buckets": "5",
      "bucket_size": "2.00",
      "bucket_duration": "300s"
    },
    "stop_limit_stop_limit_gtc": {
      "base_size": "0.001",
      "limit_price": "10000.00",
      "stop_price": "20000.00",
      "stop_direction": "20000.00"
    },
    "stop_limit_stop_limit_gtd": {
      "base_size": 0.001,
      "limit_price": "10000.00",
      "stop_price": "20000.00",
      "end_time": "2021-05-31T09:59:59.000Z",
      "stop_direction": "20000.00"
    },
    "trigger_bracket_gtc": {
      "base_size": 0.001,
      "limit_price": "10000.00",
      "stop_trigger_price": "20000.00"
    },
    "trigger_bracket_gtd": {
      "base_size": 0.001,
      "limit_price": "10000.00",
      "stop_trigger_price": "20000.00",
      "end_time": "2021-05-31T09:59:59.000Z"
    }
  }
}'
{
  "order_total": "<string>",
  "commission_total": "<string>",
  "errs": [
    "UNKNOWN_PREVIEW_FAILURE_REASON"
  ],
  "warning": [
    "UNKNOWN"
  ],
  "quote_size": 10,
  "base_size": 0.001,
  "best_bid": "<string>",
  "best_ask": "<string>",
  "is_max": true,
  "order_margin_total": "<string>",
  "leverage": "2.0",
  "long_leverage": "<string>",
  "short_leverage": "<string>",
  "slippage": "<string>",
  "preview_id": "<string>",
  "current_liquidation_buffer": "<string>",
  "projected_liquidation_buffer": "<string>",
  "max_leverage": "<string>",
  "pnl_configuration": {
    "trigger_bracket_pnl": {
      "take_profit_pnl": "<string>",
      "stop_loss_pnl": "<string>"
    }
  },
  "twap_bucket_metadata": {
    "bucket_duration": "<string>",
    "bucket_size": "<string>",
    "number_buckets": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "position_notional_limit": "<string>",
  "max_notional_at_requested_leverage": "<string>",
  "margin_ratio_data": {
    "current_margin_ratio": "<string>",
    "projected_margin_ratio": "<string>"
  },
  "commission_detail_total": {
    "total_commission": "<string>",
    "gst_commission": "<string>",
    "withholding_commission": "<string>",
    "client_commission": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Creating API Keys section of our Coinbase App Authentication docs for information on how to generate your Bearer Token.

Body

application/json
​
product_id
string
required

The trading pair (e.g. 'BTC-USD').

​
side
enum<string>
default:""
required

The side of the market that the order is on (e.g. 'BUY', 'SELL').

Available options:
BUY,
SELL
​
order_configuration
object
required

The configuration of the order (e.g. the order type, size, etc).

​
leverage
string

The amount of leverage for the order (default is 1.0).

Example:

"2.0"

​
margin_type
enum<string>
default:""

Margin Type for this order (default is CROSS).

  • CROSS: Cross margin applies margin to the position of the entire portfolio
  • ISOLATED: Isolated margin applies margin to a single position
Available options:
CROSS,
ISOLATED
​
retail_portfolio_id
string

(Deprecated) The ID of the portfolio to associate the order with. Only applicable for legacy keys. CDP keys will default to the key's permissioned portfolio.

Example:

"11111111-1111-1111-1111-111111111111"

​
attached_order_configuration
object

The configuration of the attached order. Only TriggerBracketGtc is eligible. Size field must be omitted as the size of the attached order is the same as that of the parent order.

Response

A successful response.

​
order_total
string
required
​
commission_total
string
required

Currency amount of the applied commission (so not the rate that was used on input)

​
errs
enum<string>[]
required

List of potential failure reasons were this order to be submitted

​
warning
enum<string>[]
required
​
quote_size
string
required

The amount of the second Asset in the Trading Pair. For example, on the BTC/USD Order Book, USD is the Quote Asset.

Example:

10

​
base_size
string
required

The amount of the first Asset in the Trading Pair. For example, on the BTC-USD Order Book, BTC is the Base Asset.

Example:

0.001

​
best_bid
string
required
​
best_ask
string
required
​
is_max
boolean
required

Indicates whether tradable_balance should be set to the maximum amount.

​
order_margin_total
string
​
leverage
string

The amount of leverage for the order (default is 1.0).

Example:

"2.0"

​
long_leverage
string
​
short_leverage
string
​
slippage
string
​
preview_id
string
​
current_liquidation_buffer
string
​
projected_liquidation_buffer
string
​
max_leverage
string
​
pnl_configuration
object

Expected PNL of an order. This value is an estimate and does not take into account fees and slippage.

​
twap_bucket_metadata
object
​
position_notional_limit
string
​
max_notional_at_requested_leverage
string
​
margin_ratio_data
object
​
commission_detail_total
object

Breakdown of commission charges for the order