Create a new order

Create an order. You can place two types of orders: limit and market. Orders can only be placed if your account has sufficient funds. Once an order is placed, your account funds will be put on hold for the duration of the order. How much and which funds are put on hold depends on the order type and parameters specified.

Each profile can place a maximum of 500 open orders on a product. Once reached, the profile cannot place any new orders until the total number of open orders is below 500.

API Key Permissions

This endpoint requires the “trade” permission.

Limit Order Parameters

Parameter	Description
price	Price per bitcoin
size	[optional]* Amount of BTC to buy or sell
funds	[optional]* Desired amount of quote currency to use (See Limit Order With Funds for details)
time_in_force	[optional] GTC, GTT, IOC, or FOK (default is GTC)
cancel_after	[optional]** min, hour, day
post_only	[optional]*** Post only flag

* One of size or funds is required. Only one may be specified
** Requires time_in_force to be GTT
*** Invalid when time_in_force is IOC or FOK

Market Order Parameters

Parameter	Description
size	[optional]* Desired amount in BTC
funds	[optional]* Desired amount of quote currency to use

* One of size or funds is required.

Product ID

The product_id must match a valid product. The products list is available via the /products endpoint.

Client Order ID

The optional client_oid field must be a variant 1 UUIDv4 that follows the standard format. This means all lowercase and hyphens that group the characters in sequences of 8, 4, 4, 4, 12 (e.g. 1985ca2d-61ef-49f1-bfce-6c39d8462914) generated by your trading application. This field value is broadcast in the public feed for received messages. You can use this field to identify your orders in the public feed.

The client_oid is different than the server-assigned order ID. If you are consuming the public feed and see a received message with your client_oid, you should record the server-assigned order_id as it is used for future order status updates. The client_oid is NOT used after the received message is sent.

The server-assigned order id is also returned as the id field to this HTTP POST request.

If the client_oid is not in the correct UUIDv4 format it will be accepted via REST but NOT processed and will not be visible in future REST calls.

Type

When placing an order, you can specify the order type. The order type you specify influences which other order parameters are required as well as how your order is executed by the matching engine. If type is not specified, the order defaults to a limit order.

Limit orders are both the default and basic order type. A limit order requires that you specify a price and one of either size or funds. The size parameter denotes the amount in fiat, and funds denotes the number of bitcoin to buy or sell. The price is the price per bitcoin. Limit orders are filled at the price specified or better. A sell order can be filled at the specified price per bitcoin or a higher price per bitcoin, and a buy order can be filled at the specified price or a lower price depending on market conditions. If market conditions cannot fill the limit order immediately, then the limit order becomes part of the open order book until filled by another incoming order or canceled by the user.

Market orders differ from limit orders in that they provide no pricing guarantees. They however do provide a way to buy or sell specific amounts of bitcoin or fiat without having to specify the price. Market orders execute immediately and no part of the market order goes on the open order book. Market orders are always considered takers and incur taker fees. When placing a market order you can specify funds and/or size. Funds limit how much of your quote currency account balance is used and size limits the bitcoin amount transacted.

Stop Orders

Stop orders become active and wait to trigger based on the movement of the last trade price. There are two types of stop orders, stop loss and stop entry:

stop: 'loss': Triggers when the last trade price changes to a value at or below the stop_price.

stop: 'entry': Triggers when the last trade price changes to a value at or above the stop_price.

The last trade price is the last price at which an order was filled. This price can be found in the latest match message. Not all match messages may be received due to dropped messages.

When stop orders are triggered, they execute as limit orders and are therefore subject to holds.

Price

The price must be specified in quote_increment product units. The quote increment is the smallest unit of price. For the BTC-USD product, the quote increment is 0.01 or 1 penny. Prices less than 1 penny are not accepted, and no fractional penny prices are accepted. Not required for market orders.

Size

Order Size Limits Removed

The properties base_max_size, base_min_size, max_market_funds were removed on June 30, 2022.

The property, min_market_funds, has been repurposed as the notional minimum size for limit orders.

The size must be greater than the base_min_size for the product and no larger than the base_max_size. The size can be in incremented in units of base_increment. size indicates the amount of BTC (or base currency) to buy or sell.

size indicates the amount of base currency to buy or sell. The size must be no less than the base_min_size and no larger than the base_max_size for the product. However, for post-only limit orders, there is no enforced base_max_size. The size can be in any increment of the base currency (e.g. BTC for the BTC-USD product).

There is no max size restriction for post_only limit orders.

Funds

The funds field is optionally used for market or limit orders. When specified it indicates how much of the product quote currency to buy or sell. For example, a market buy for BTC-USD with funds specified as 150.00 will spend 150 USD to buy BTC (including any fees). If the funds field is not specified for a market buy order, size must be specified and Coinbase Exchange uses available funds in your account to buy bitcoin.

A market sell order can also specify the funds. If funds is specified, it limits the sell to the amount of funds specified. You can use funds with sell orders to limit the amount of quote currency funds received.

A limit order that specifies funds functions similarly to a market order but provides more control in its ability to specify price. See Limit Order With Funds for more information on how this order works.

Time In Force

Time in force policies provide guarantees about the lifetime of an order. There are four policies: good till canceled GTC, good till date GTD, immediate or cancel IOC, and fill or kill FOK.

GTC Good till canceled orders remain open on the book until canceled. This is the default behavior if no policy is specified.

GTD Good till date orders are valid till a specified date or time (within a 90-day hard limit) unless it has been already fulfilled or cancelled.

IOC Immediate or cancel orders instantly cancel the remaining size of the limit order instead of opening it on the book.

FOK Fill or kill orders are rejected if the entire size cannot be matched.

Match also refers to self trades.

Post Only

The post-only flag indicates that the order should only make liquidity. If any part of the order results in taking liquidity, the order will be rejected and no part of it will execute.

Holds

For limit buy orders, we hold price x size x (1 + fee-percent) USD. For sell orders, we hold the number of Bitcoin you wish to sell. Actual fees are assessed at time of trade. If you cancel a partially filled or unfilled order, any remaining funds are released from hold.

For market buy orders where funds is specified, the funds amount is put on hold. If only size is specified, all of your account balance (in the quote account) is put on hold for the duration of the market order (usually a trivially short time). For a sell order, the size in BTC is put on hold. If size is not specified (and only funds is specified), your entire BTC balance is put on hold for the duration of the market order.

Self-Trade Prevention

Self-trading is not allowed on the exchange. Two orders from the same user are not allowed to match with one another. To change the self-trade behavior, specify the stp flag.

Flag	Name
dc	Decrease and Cancel (default)
co	Cancel oldest
cn	Cancel newest
cb	Cancel both

See the self-trade prevention documentation for details about these fields.

Order Lifecycle

The HTTP Request responds when an order is either rejected (insufficient funds, invalid parameters, etc) or received (accepted by the matching engine). A 200 response indicates that the order was received and is active. Active orders may execute immediately (depending on price and market conditions) either partially or fully. A partial execution puts the remaining size of the order in the open state. An order that is filled completely, goes into the done state.

Users listening to streaming market data are encouraged to use the client_oid field to identify their received messages in the feed. The REST response with a server order_id may come after the received message in the public data feed.

Response

A successful order is assigned an order id. A successful order is defined as one that has been accepted by the matching engine.

Open orders do not expire and remain open until they are either filled or canceled.

Authorizations

cb-access-key · string · header · required

cb-access-passphrase · string · header · required

cb-access-sign · string · header · required

cb-access-timestamp · string · header · required

Body

application/json

side · enum<string> · default: buy · required

Available options:

buy,

sell

product_id · string · required

Book on which to place an order

profile_id · string · default: default profile_id

Create order on a specific profile_id. If none is passed, defaults to default profile.

type · enum<string> · default: limit

Available options:

limit,

market,

stop

stp · enum<string> · default: dc

Available options:

dc,

co,

cn,

cb

stop · enum<string> · default: loss

Available options:

loss,

entry

stop_price · string

Price threshold at which a stop order will be placed on the book

price · string

Price per unit of cryptocurrency - required for limit/stop orders

size · string

Amount of base currency to buy or sell - required for limit/stop orders and market sells

funds · string

Amount of quote currency to buy - required for market buys

time_in_force · enum<string> · default: GTC

Available options:

GTC,

GTT,

IOC,

FOK

cancel_after · enum<string> · default: min

Available options:

min,

hour,

day

post_only · boolean · default: false

If true, order will only execute as a maker order

client_oid · string

Optional Order ID selected by the user or the frontend client to identify their order

max_floor · string

Placing an iceberg order. Use this to specify how much to show

stop_limit_price · string

Required for take profit/stop loss orders. Denotes the updated limit price upon the activation of the stop loss trigger

Response

200

application/json

The new order that was successfully created

id · string · required

uuid

product_id · string · required

book the order was placed on

side · enum<string> · default: buy · required

Available options:

buy,

sell

type · enum<string> · default: limit · required

Available options:

limit,

market,

stop

post_only · boolean · required

if true, forces order to be maker only

created_at · string<date-time> · required

timestamp at which order was placed

fill_fees · string · required

fees paid on current filled amount

filled_size · string · required

amount (in base currency) of the order that has been filled

status · enum<string> · default: open · required

Available options:

open,

pending,

rejected,

done,

active,

received,

all

settled · boolean · required

true if funds have been exchanged and settled

price · string

price per unit of base currency

size · string

amount of base currency to buy/sell

profile_id · string

profile_id that placed the order

funds · string

amount of quote currency to spend (for market orders)

specified_funds · string

funds with fees

time_in_force · enum<string> · default: GTC

Available options:

GTC,

GTT,

IOC,

FOK

expire_time · string<date-time>

timestamp at which order expires

done_at · string<date-time>

timestamp at which order was done

done_reason · string

reason order was done (filled, rejected, or otherwise)

reject_reason · string

reason order was rejected by engine

executed_value · string

stop · enum<string> · default: loss

Available options:

loss,

entry

stop_price · string

price (in quote currency) at which to execute the order

funding_amount · string

client_oid · string

client order id

market_type · string

market type where order was traded

max_floor · string

maximum visible quantity for iceberg order

secondary_order_id · string

order id for the visible order for iceberg order

stop_limit_price · string

stop limit price for TPSL order