The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.
The OAuth scope must have orders:create assigned to access this endpoint. See OAuth Scopes for more information.
Margin Orders
Set margin_order: true to place an order using borrowed funds on a margin-enabled account. This allows you to trade with leverage beyond your available balance.
Important
Margin trading amplifies both gains and losses. Monitor your account using the Margin Account Summary endpoint and preview order impacts with Order Preview before placing margin orders.
Stop-Limit Orders
A Stop-Limit order is an order type that allows for order placement when a price reaches a specified level. Stop-Limit orders take in both a price and a stop_price as parameters. The stop_price is the price that triggers the order to be placed on the continuous live order book at the price. For buy orders, the stop_price must be below the price while sell orders require the stop_price to be greater than the price.
What about market orders?
The API doesn't directly support market orders because they provide you with no price protection.
Instead, use the "immediate-or-cancel" order execution option, coupled with an aggressive limit price (i.e. very high for a buy order or very low for a sell order), to achieve the same result.
Order execution options
Note that options is an array. If you omit options or provide an empty array, your order will be a standard limit order - it will immediately fill against any open orders at an equal or better price, then the remainder of the order will be posted to the order book.
If you specify more than one option (or an unsupported option) in the options array, the exchange will reject your order.
No options can be applied to stop-limit orders at this time.
The available limit order options are:
Option
Description
"maker-or-cancel"
This order will only add liquidity to the order book.
If any part of the order could be filled immediately, the whole order will instead be canceled before any execution occurs.
If that happens, the response back from the API will indicate that the order has already been canceled ("is_cancelled": true in JSON).
Note: some other exchanges call this option "post-only".
"immediate-or-cancel"
This order will only remove liquidity from the order book.
It will fill whatever part of the order it can immediately, then cancel any remaining amount so that no part of the order is added to the order book.
If the order doesn't fully fill immediately, the response back from the API will indicate that the order has already been canceled ("is_cancelled": true in JSON).
"fill-or-kill"
This order will only remove liquidity from the order book.
It will fill the entire order immediately or cancel.
If the order doesn't fully fill immediately, the response back from the API will indicate that the order has already been canceled ("is_cancelled": true in JSON).
Headers
X-GEMINI-APIKEYstring·required
Your API key
X-GEMINI-SIGNATUREstring·required
HEX-encoded HMAC-SHA384 of payload signed with API secret
X-GEMINI-PAYLOADstring·required
Base64-encoded JSON payload
Content-Typestring
Default: text/plain
Content-Lengthstring
Default: 0
Cache-Controlstring
Default: no-cache
Request Body
requeststring·required
The literal string "/v1/order/new"Example: /v1/order/new
noncenumber·required
The nonce, as described in [Private API Invocation](/authentication/api-key#private-api-invocation)
client_order_idstring
*Recommended*. A [client-specified order id](/client-order-id)
symbolstring·required
The [symbol](/market-data/symbols-and-minimums) for the new orderExample: BTCUSD
amountstring·required
Quoted decimal amount to purchaseExample: 5
pricestring·required
Quoted decimal amount to spend per unitExample: 3633.00
sidestring·enum·required
Enum values: buysellExample: buy
typestring·enum·required
The order type. "exchange limit" for all order types except for stop-limit orders. "exchange stop limit" for stop-limit orders.Enum values: exchange limitexchange stop limitexchange marketExample: exchange limit
optionsarray
An optional array containing at most one supported order execution option. See Order execution options for details.Example: maker-or-cancel
stop_pricestring
The price to trigger a stop-limit order. Only available for stop-limit orders.
margin_orderboolean
Set to `true` to place this order on a margin account using borrowed funds. Defaults to `false`. Only available for margin-enabled accounts. See [Margin Trading](/margin/account-summary) for details.Example: false
accountstring
Required for Master API keys as described in [Private API Invocation](/authentication/api-key#private-api-invocation). The name of the account within the subaccount group. Specifies the account on which you intend to place the order. Only available for exchange accounts.
