--- title: "Create New Order" method: POST path: "/v1/order/new" tags: ["Orders"] --- # Create New Order `POST /v1/order/new` ## Request - Base URL: `https://api.gemini.com` - URL: `https://api.gemini.com/v1/order/new` - Auth: API key in header `X-GEMINI-APIKEY` and API key in header `X-GEMINI-SIGNATURE` and API key in header `X-GEMINI-PAYLOAD` If you wish orders to be automatically cancelled when your session ends, see the [require heartbeat](/authentication/api-key#require-heartbeat) section, or manually send the [cancel all session orders](/rest/orders#cancel-all-session-orders) message. ### Roles 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](/authentication/oauth#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](/rest/margin-trading#get-margin-account-summary) endpoint and preview order impacts with [Order Preview](/rest/margin-trading#preview-margin-order-impact) 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 and a `stop_price` as parameters. The `stop_price` is the price that triggers the order to be placed on the continous 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-APIKEY` string, required - `X-GEMINI-SIGNATURE` string, required - `X-GEMINI-PAYLOAD` string, required - `Content-Type` string - `Content-Length` string - `Cache-Control` string ## Request body - NewOrderRequest - `request` string, required: The literal string "/v1/order/new" - `nonce` number, required: The nonce, as described in [Private API Invocation](/authentication/api-key#private-api-invocation) - `client_order_id` string: *Recommended*. A [client-specified order id](/client-order-id) - `symbol` string, required: The [symbol](/market-data/symbols-and-minimums) for the new order - `amount` string, required: Quoted decimal amount to purchase - `price` string, required: Quoted decimal amount to spend per unit - `side` 'buy' | 'sell', required - `type` 'exchange limit' | 'exchange stop limit' | 'exchange market', required: The order type. "exchange limit" for all order types except for stop-limit orders. "exchange stop limit" for stop-limit orders. - `options` string[]: An optional array containing at most one supported order execution option. See Order execution options for details. - `stop_price` string: The price to trigger a stop-limit order. Only available for stop-limit orders. - `margin_order` boolean: 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. - `account` string: 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. ## Response `200` Response will be the fields included in Order Status - union - LimitOrderResponse - `order_id` string - `id` string - `symbol` string - `exchange` string - `avg_execution_price` string - `side` 'buy' | 'sell' - `type` 'exchange limit' | 'exchange stop limit' | 'exchange market' - `timestamp` union: timestamp - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only | - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` | - `timestampms` union: timestamp - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only | - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` | - `is_live` boolean - `is_cancelled` boolean - `is_hidden` boolean - `was_forced` boolean - `executed_amount` string - `remaining_amount` string, double - `client_order_id` string - `options` string[] - `price` string, double - `original_amount` string, double - StopLimitOrderResponse - `order_id` string - `id` string - `symbol` string - `exchange` string - `avg_execution_price` string - `side` 'buy' | 'sell' - `type` 'exchange stop limit' - `timestamp` union: timestamp - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only | - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` | - `timestampms` union: timestamp - string: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------|-----------------------|------------------------| | string (seconds) | `1495127793` | `POST` only | | string (milliseconds) | `1495127793000` | `POST` only | - integer: Gemini strongly recommends using milliseconds instead of seconds for timestamps. | Timestamp format | Example | Supported request type | |-----------------------------|---------------------------|------------------------| | whole number (seconds) | `1495127793` | `GET`, `POST` | | whole number (milliseconds) | `1495127793000` | `GET`, `POST` | - `is_live` boolean - `is_cancelled` boolean - `is_hidden` boolean - `was_forced` boolean - `executed_amount` string - `options` string[] - `stop_price` string, double - `price` string, double - `original_amount` string, double ## Other responses - `400`: Bad request - malformed request or invalid parameters - `401`: Unauthorized - missing or invalid authentication - `403`: ApiKey fails IP Filtering Check - `404`: Resource not found - `429`: Too many requests - you have exceeded the rate limit - `500`: Internal server error --- [API](https://skmtc.dev/gemini/apis/rest-api.md) - [All operations](https://skmtc.dev/gemini/apis/rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gemini/apis/rest-api/revisions/24979792d748?raw)