REST API

Orders (1.0.0)

Endpointhttps://api.sandbox.gemini.com

Create New Order

POST

https://api.sandbox.gemini.com

/v1/order/new

If you wish orders to be automatically cancelled when your session ends, see the require heartbeat section, or manually send the cancel all session orders message.

Master API keys do not support cancelation on disconnect via heartbeat.

Enabled for perpetuals accounts from July 10th, 0100hrs ET onwards.

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 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 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).

Create New Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Create New Order › Request Body

request

string · required

The literal string "/v1/order/new"

Example: /v1/order/new

nonce

number · required

The nonce, as described in Private API Invocation

symbol

string · required

The symbol for the new order

Example: BTCUSD

amount

string · required

Quoted decimal amount to purchase

Example: 5

price

string · required

Quoted decimal amount to spend per unit

Example: 3633.00

side

string · enum · required

Enum values:

buy

sell

Example: buy

type

string · 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 limit

exchange stop limit

exchange market

Example: exchange limit

client_order_id

string

Recommended. A client-specified order id

options

string[]

An optional array containing at most one supported order execution option. See Order execution options for details.

Enum values:

maker-or-cancel

immediate-or-cancel

fill-or-kill

Example: ["maker-or-cancel"]

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 for details.

Example: false

account

string

Required for Master API keys as described in 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.

Create New Order › Responses

Response will be the fields included in Order Status

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Limit Order Response:

order_id

string

id

string

symbol

string

exchange

string

avg_execution_price

string

side

string · enum

Enum values:

buy

sell

type

string · enum

Enum values:

exchange limit

exchange stop limit

exchange market

timestamp

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

POST/v1/order/new

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/order/new \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/order/new",
  "nonce": "<nonce>",
  "client_order_id": "470135",
  "symbol": "BTCUSD",
  "amount": "5",
  "price": "3633.00",
  "side": "buy",
  "type": "exchange limit"
}
'

shell

Example Request Body

{
  "request": "/v1/order/new",
  "nonce": "<nonce>",
  "client_order_id": "470135",
  "symbol": "BTCUSD",
  "amount": "5",
  "price": "3633.00",
  "side": "buy",
  "type": "exchange limit"
}

json

JSON limit order payload

application/json

Example Responses

{
  "order_id": "106817811",
  "id": "106817811",
  "symbol": "BTCUSD",
  "exchange": "gemini",
  "avg_execution_price": "3632.8508430064554",
  "side": "buy",
  "type": "exchange limit",
  "timestamp": "1547220404",
  "timestampms": 1547220404836,
  "is_live": true,
  "is_cancelled": false,
  "is_hidden": false,
  "was_forced": false,
  "executed_amount": "3.7567928949",
  "remaining_amount": "1.2432071051",
  "client_order_id": "20190110-4738721",
  "options": [],
  "price": "3633.00",
  "original_amount": "5"
}

json

JSON limit order response

application/json

Cancel Order

POST

https://api.sandbox.gemini.com

/v1/order/cancel

This will cancel an order. If the order is already canceled, the message will succeed but have no effect.

Enabled for perpetuals accounts from July 10th, 0100hrs ET onwards.

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 for more information.

All Cancellation Reasons

Under unique circumstances, orders may be automatically cancelled by the exchange. These scenarios are detailed in the table below:

Cancel Reason	Description
`MakerOrCancelWouldTake`	Occurs when the "maker-or-cancel" execution option is included in the order request and any part of the requested order could be filled immediately.
`ExceedsPriceLimits`	Occurs when there is not sufficient liquidity on the order book to support the entered trade. Orders will be automatically cancelled when liquidity conditions are such that the order would move price +/- 5%.
`SelfCrossPrevented`	Occurs when a user enters a bid that is higher than that user's lowest open ask or enters an ask that is lower than their highest open bid on the same pair.
`ImmediateOrCancelWouldPost`	Occurs when the "immediate-or-cancel" execution option is included in the order request and the requested order cannot be fully filled immediately. This type of cancellation will only cancel the unfulfilled part of any impacted order.
`FillOrKillWouldNotFill`	Occurs when the "fill-or-kill" execution option is included in the new order request and the entire order cannot be filled immediately. Unlike "immediate-or-cancel" orders, this execution option will result in the entire order being cancelled rather than just the unfulfilled portion.
`Requested`	Cancelled via user request to /v1/order/cancel endpoint.
`MarketClosed`	Occurs when an order is placed for a trading pair that is currently closed.
`TradingClosed`	Occurs when an order is placed while the exchange is closed for trading.

Cancel Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Cancel Order › Request Body

request

string · required

The literal string "/v1/order/cancel"

Example: /v1/order/cancel

required

timestamp

order_id

integer · required

The order ID given by /order/new

Example: 106817811

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to cancel the order. Only available for exchange accounts.

Example: primary

Cancel Order › Responses

Response will be the fields included in Order Status. If the order was already canceled, then the request will have no effect and the status will be returned. Note the is_cancelled node will have a value of 'true'

order_id

string · integer

id

string · integer

symbol

string

exchange

string

avg_execution_price

string · double

side

string · enum

Enum values:

buy

sell

type

string · enum

Enum values:

exchange limit

exchange stop limit

exchange market

timestamp

is_live

boolean

is_cancelled

boolean

is_hidden

boolean

was_forced

boolean

executed_amount

string · double

remaining_amount

string · double

reason

string · enum

Enum values:

MakerOrCancelWouldTake

ExceedsPriceLimits

SelfCrossPrevented

ImmediateOrCancelWouldPost

FillOrKillWouldNotFill

Requested

MarketClosed

TradingClosed

options

string[]

price

string · double

original_amount

string · double

POST/v1/order/cancel

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/order/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/order/cancel",
  "nonce": "<nonce>",
  "order_id": 106817811
}
'

shell

Example Request Body

{
  "request": "/v1/order/cancel",
  "nonce": "<nonce>",
  "order_id": 106817811
}

json

JSON payload to cancel an order using its order_id

application/json

Example Responses

{
  "order_id": "106817811",
  "id": "106817811",
  "symbol": "btcusd",
  "exchange": "gemini",
  "avg_execution_price": "3632.85101103",
  "side": "buy",
  "type": "exchange limit",
  "timestamp": "1495742383",
  "timestampms": 1495742383345,
  "is_live": false,
  "is_cancelled": true,
  "is_hidden": false,
  "was_forced": false,
  "executed_amount": "3.7610296649",
  "remaining_amount": "1.2389703351",
  "reason": "Requested",
  "options": [],
  "price": "2960.00",
  "original_amount": "5"
}

json

JSON response for a cancelled order

application/json

Cancel All Active Orders

POST

https://api.sandbox.gemini.com

/v1/order/cancel/all

This will cancel all outstanding orders created by all sessions owned by this account, including interactive orders placed through the UI.

Note that this cancels orders that were not placed using this API key. Enabled for perpetuals accounts from July 10th, 0100hrs ET onwards.

Typically Cancel All Session Orders is preferable, so that only orders related to the current connected session are cancelled.

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 for more information.

Cancel All Active Orders › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Cancel All Active Orders › Request Body

request

string · required

The literal string "/v1/order/cancel/all"

Example: /v1/order/cancel/all

required

timestamp

account

string

Example: primary

Cancel All Active Orders › Responses

JSON response

result

string

object

cancelledOrders/cancelRejects with IDs of both

POST/v1/order/cancel/all

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/order/cancel/all \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/order/cancel/all",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/order/cancel/all",
  "nonce": "<nonce>"
}

json

JSON payload to cancel all orders

application/json

Example Responses

{
  "result": "ok",
  "details": {
    "cancelRejects": [],
    "cancelledOrders": [
      330429106,
      330429079,
      330429082
    ]
  }
}

json

application/json

Cancel All Session Orders

POST

https://api.sandbox.gemini.com

/v1/order/cancel/session

This will cancel all orders opened by this session.

This will have the same effect as heartbeat expiration if "Require Heartbeat" is selected for the session.

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 for more information.

Cancel All Session Orders › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Cancel All Session Orders › Request Body

request

string · required

The literal string "/v1/order/cancel/session"

Example: /v1/order/cancel/session

required

timestamp

account

string

Example: primary

Cancel All Session Orders › Responses

JSON response

result

string

object

cancelledOrders/cancelRejects with IDs of both

POST/v1/order/cancel/session

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/order/cancel/session \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/order/cancel/session",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/order/cancel/session",
  "nonce": "<nonce>"
}

json

JSON payload to cancel all orders opened by this session

application/json

Example Responses

{
  "result": "ok",
  "details": {
    "cancelRejects": [
      330429345
    ],
    "cancelledOrders": []
  }
}

json

application/json

Get Order Status

POST

https://api.sandbox.gemini.com

/v1/order/status

Gemini recommends using our WebSocket Order Events API to receive order status changes. It's much better because you'll be notified of order status changes as they happen.

Under the terms of the Gemini API Agreement, polling this endpoint may be subject to rate limiting.

Enabled for perpetuals accounts from July 10th, 0100hrs ET onwards. Trade info for all perpetuals orders submitted prior to this timing, will not be available through this API.

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:read assigned to access this endpoint. See OAuth Scopes for more information.

Get Order Status › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Get Order Status › Request Body

request

string · required

The API endpoint path

Example: /v1/order/status

required

timestamp

order_id

integer · required

The order id to get information on. The order_id represents a whole number and is transmitted as an unsigned 64-bit integer in JSON format. order_id cannot be used in combination with client_order_id.

Example: 123456789012345

account

string

Example: primary

client_order_id

string

The client_order_id used when placing the order. client_order_id cannot be used in combination with order_id

include_trades

boolean

Either True or False. If True the endpoint will return individual trade details of all fills from the order.

Get Order Status › Responses

The order status

order_id

string · integer

The order id

client_order_id

string · integer

An optional client-specified order id

symbol

string

The symbol of the order

exchange

string

Will always be "gemini"

price

string · decimal

The price the order was issued at

avg_execution_price

string · decimal

The average price at which this order as been executed so far. 0 if the order has not been executed at all.

side

string · enum

Enum values:

buy

sell

type

string · enum

Description of the order

Enum values:

exchange limit

exchange stop limit

exchange market

options

string[]

An array containing at most one supported order execution option. See Order execution options for details.

timestamp

is_live

boolean

true if the order is active on the book (has remaining quantity and has not been canceled)

is_cancelled

boolean

true if the order has been canceled. Note the spelling, "cancelled" instead of "canceled". This is for compatibility reasons.

reason

string

Populated with the reason your order was canceled, if available.

was_forced

boolean

Will always be false.

executed_amount

string · decimal

The amount of the order that has been filled.

remaining_amount

string · decimal

The amount of the order that has not been filled.

original_amount

string · decimal

The originally submitted amount of the order.

is_hidden

boolean

Will always return false.

object[]

Contains an array of JSON objects with trade details.

POST/v1/order/status

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/order/status \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/order/status",
  "nonce": "<nonce>",
  "order_id": 123456789012345,
  "include_trades": true
}
'

shell

Example Request Body

{
  "request": "/v1/order/status",
  "nonce": "<nonce>",
  "order_id": 123456789012345,
  "include_trades": true
}

json

application/json

Example Responses

{
  "order_id": "123456789012345",
  "id": "123456789012345",
  "symbol": "btcusd",
  "exchange": "gemini",
  "avg_execution_price": "400.00",
  "side": "buy",
  "type": "exchange limit",
  "timestamp": "1494870642",
  "timestampms": 1494870642156,
  "is_live": false,
  "is_cancelled": false,
  "is_hidden": false,
  "was_forced": false,
  "executed_amount": "3",
  "remaining_amount": "0",
  "options": [],
  "price": "400.00",
  "original_amount": "3"
}

json

JSON response for limit buy

application/json

List Active Orders

POST

https://api.sandbox.gemini.com

/v1/orders

Gemini recommends using our WebSocket Order Events API to maintain a current view of your active orders. It's both faster and more efficient than polling this endpoint.

Under the terms of the Gemini API Agreement, polling this endpoint may be subject to rate limiting.

Enabled for perpetuals accounts from July 10th, 0100hrs ET onwards.

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

List Active Orders › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

List Active Orders › Request Body

request

string · required

The API endpoint path

Example: /v1/orders

TimestampType · required

timestamp

account

string

Example: primary

List Active Orders › Responses

The active orders

object[]

order_id

string · integer

The order id

client_order_id

string · integer

An optional client-specified order id

symbol

string

The symbol of the order

exchange

string

Will always be "gemini"

price

string · decimal

The price the order was issued at

avg_execution_price

string · decimal

The average price at which this order as been executed so far. 0 if the order has not been executed at all.

side

string · enum

Enum values:

buy

sell

type

string · enum

Description of the order

Enum values:

exchange limit

exchange stop limit

exchange market

options

string[]

An array containing at most one supported order execution option. See Order execution options for details.

timestamp

is_live

boolean

true if the order is active on the book (has remaining quantity and has not been canceled)

is_cancelled

boolean

true if the order has been canceled. Note the spelling, "cancelled" instead of "canceled". This is for compatibility reasons.

reason

string

Populated with the reason your order was canceled, if available.

was_forced

boolean

Will always be false.

executed_amount

string · decimal

The amount of the order that has been filled.

remaining_amount

string · decimal

The amount of the order that has not been filled.

original_amount

string · decimal

The originally submitted amount of the order.

is_hidden

boolean

Will always return false.

object[]

Contains an array of JSON objects with trade details.

POST/v1/orders

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/orders",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/orders",
  "nonce": "<nonce>"
}

json

Basic request to get active orders

application/json

Example Responses

[
  {
    "order_id": "107421210",
    "id": "107421210",
    "symbol": "ethusd",
    "exchange": "gemini",
    "avg_execution_price": "0.00",
    "side": "sell",
    "type": "exchange limit",
    "timestamp": "1547241628",
    "timestampms": 1547241628042,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "was_forced": false,
    "executed_amount": "0",
    "remaining_amount": "1",
    "options": [],
    "price": "125.51",
    "original_amount": "1"
  },
  {
    "order_id": "107421205",
    "id": "107421205",
    "symbol": "ethusd",
    "exchange": "gemini",
    "avg_execution_price": "125.41",
    "side": "buy",
    "type": "exchange limit",
    "timestamp": "1547241626",
    "timestampms": 1547241626991,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "was_forced": false,
    "executed_amount": "0.029147",
    "remaining_amount": "0.970853",
    "options": [],
    "price": "125.42",
    "original_amount": "1"
  }
]

json

Response with multiple active orders

application/json

List Past Orders

POST

https://api.sandbox.gemini.com

/v1/orders/history

This API retrieves (closed) orders history for an account.

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

How to retrieve your order history

To retrieve your full order history walking backwards,

Initial request: POST to https://api.gemini.com/v1/orders/history with a JSON payload including a timestamp key with value 0 and a limit_orders key with value 500
When you receive the list of orders, it will be sorted by timestamp descending - so the first element in the list will have the highest timestamp value. For this example, say that value is X.
Create a second POST request with a JSON payload including a timestamp key with value X+1 and a limit_orders key with value 500.
Take the first element of the list returned with highest timestamp value Y and create a third POST request with a JSON payload including a timestamp key with value Y+1 and a limit_orders key with value 500.
Continue creating POST requests and retrieving orders until an empty list is returned.

Break Types

In the rare event that a trade has been reversed (broken), the trade that is broken will have this flag set. The field will contain one of these values

Value	Description
manual	The trade was reversed manually. This means that all fees, proceeds, and debits associated with the trade have been credited or debited to the account seperately. That means that this reported trade must be included for order for the account balance to be correct.
full	The trade was fully broken. The reported trade should not be accounted for. It will be as though the transfer of fund associated with the trade had simply not happened.

List Past Orders › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

List Past Orders › Request Body

request

string · required

The API endpoint /v1/orders/history

required

The nonce, as described in Private API Invocation

symbol

string

The symbol to retrieve orders for

limit_orders

integer

The maximum number of orders to return. Default is 50, max is 500.

Default: 50

In iso datetime with timezone format from that date you will get order history

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

List Past Orders › Responses

Successful operation

object[]

order_id

string · integer

The order id

client_order_id

string · integer

An optional client-specified order id

symbol

string

The symbol of the order

exchange

string

Will always be "gemini"

price

string · decimal

The price the order was issued at

avg_execution_price

string · decimal

The average price at which this order as been executed so far. 0 if the order has not been executed at all.

side

string · enum

Enum values:

buy

sell

type

string · enum

Description of the order

Enum values:

exchange limit

exchange stop limit

exchange market

options

string[]

An array containing at most one supported order execution option. See Order execution options for details.

timestamp

is_live

boolean

true if the order is active on the book (has remaining quantity and has not been canceled)

is_cancelled

boolean

true if the order has been canceled. Note the spelling, "cancelled" instead of "canceled". This is for compatibility reasons.

reason

string

Populated with the reason your order was canceled, if available.

was_forced

boolean

Will always be false.

executed_amount

string · decimal

The amount of the order that has been filled.

remaining_amount

string · decimal

The amount of the order that has not been filled.

original_amount

string · decimal

The originally submitted amount of the order.

is_hidden

boolean

Will always return false.

object[]

Contains an array of JSON objects with trade details.

POST/v1/orders/history

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/orders/history \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/orders/history",
  "nonce": "<nonce>",
  "limit_orders": 50
}
'

shell

Example Request Body

{
  "request": "/v1/orders/history",
  "nonce": "<nonce>",
  "limit_orders": 50
}

json

Basic request to get order history

application/json

Example Responses

[
  {
    "order_id": "73751560172006688",
    "id": "73751560172006688",
    "symbol": "ethgusd",
    "exchange": "gemini",
    "avg_execution_price": "0.00",
    "side": "buy",
    "type": "exchange limit",
    "timestamp": "1695629298",
    "timestampms": 1695629298505,
    "is_live": false,
    "is_cancelled": true,
    "is_hidden": false,
    "was_forced": false,
    "executed_amount": "0",
    "client_order_id": "fb5321b0-2114-47fd-8cca-531a66d7feaf",
    "options": [],
    "price": "420.00",
    "original_amount": "0.69",
    "remaining_amount": "0.69",
    "trades": []
  }
]

json

Response with a cancelled order

application/json

List Past Trades

POST

https://api.sandbox.gemini.com

/v1/mytrades

Gemini recommends using our WebSocket Order Events API to be notified when a trade executes on your account instead of polling this endpoint.

Under the terms of the Gemini API Agreement, polling this endpoint may be subject to rate limiting.

Enabled for perpetuals accounts from July 10th, 0100hrs ET onwards. Trade info for all perpetuals orders submitted prior to this timing, will not be available through this API.

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

How to retrieve your trade history

To retrieve your full trade history walking backwards,

Initial request: POST to https://api.gemini.com/v1/mytrades with a JSON payload including a timestamp key with value 0 and a limit_trades key with value 500
When you receive the list of trades, it will be sorted by timestamp descending - so the first element in the list will have the highest timestamp value. For this example, say that value is X.
Create a second POST request with a JSON payload including a timestamp key with value X+1 and a limit_trades key with value 500.
Take the first element of the list returned with highest timestamp value Y and create a third POST request with a JSON payload including a timestamp key with value Y+1 and a limit_trades key with value 500.
Continue creating POST requests and retrieving trades until an empty list is returned.

Break Types

In the rare event that a trade has been reversed (broken), the trade that is broken will have this flag set. The field will contain one of these values

Value	Description
manual	The trade was reversed manually. This means that all fees, proceeds, and debits associated with the trade have been credited or debited to the account seperately. That means that this reported trade must be included for order for the account balance to be correct.
full	The trade was fully broken. The reported trade should not be accounted for. It will be as though the transfer of fund associated with the trade had simply not happened.

List Past Trades › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

List Past Trades › Request Body

request

string · required

The API endpoint path

Example: /v1/mytrades

required

timestamp

account

string

Example: primary

symbol

string

The symbol to retrieve trades for

Example: btcusd

limit_trades

integer

The maximum number of trades to return. Default is 50, max is 500.

Example: 50

timestamp

List Past Trades › Responses

The past trades

object[]

price

string

amount

string

timestamp

type

string · enum

Enum values:

Buy

Sell

Example: Buy

aggressor

boolean

fee_currency

string

fee_amount

string

tid

integer

order_id

string

client_order_id

string

exchange

string

is_auction_fill

boolean

break

string · enum

Enum values:

trade correct

Example:

POST/v1/mytrades

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/mytrades \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/mytrades",
  "nonce": "<nonce>",
  "symbol": "btcusd"
}
'

shell

Example Request Body

{
  "request": "/v1/mytrades",
  "nonce": "<nonce>",
  "symbol": "btcusd"
}

json

Basic request to get past trades for a symbol

application/json

Example Responses

[
  {
    "price": "3648.09",
    "amount": "0.0027343246",
    "timestamp": 1547232911,
    "timestampms": 1547232911021,
    "type": "Buy",
    "aggressor": true,
    "fee_currency": "USD",
    "fee_amount": "0.024937655575035",
    "tid": 107317526,
    "order_id": "107317524",
    "exchange": "gemini",
    "is_clearing_fill": false,
    "symbol": "BTCUSD"
  },
  {
    "price": "3633.00",
    "amount": "0.00423677",
    "timestamp": 1547220640,
    "timestampms": 1547220640195,
    "type": "Buy",
    "aggressor": false,
    "fee_currency": "USD",
    "fee_amount": "0.038480463525",
    "tid": 106921823,
    "order_id": "106817811",
    "exchange": "gemini",
    "is_clearing_fill": false,
    "symbol": "BTCUSD"
  }
]

json

Response with multiple trades

application/json

Get Trading Volume

POST

https://api.sandbox.gemini.com

/v1/tradevolume

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

Get Trading Volume › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Get Trading Volume › Request Body

request

string · required

The API endpoint path

Example: /v1/tradevolume

TimestampType · required

timestamp

account

string

Example: primary

Get Trading Volume › Responses

The trade volume

object[]

symbol

string

base_currency

string

quote_currency

string

notional_currency

string

data_date

string

total_volume_base

string

maker_buy_sell_ratio

string

buy_maker_base

string

buy_maker_notional

string

buy_maker_count

integer

sell_maker_base

string

sell_maker_notional

string

sell_maker_count

integer

buy_taker_base

string

buy_taker_notional

string

buy_taker_count

integer

sell_taker_base

string

sell_taker_notional

string

sell_taker_count

integer

POST/v1/tradevolume

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/tradevolume \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/tradevolume",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/tradevolume",
  "nonce": "<nonce>"
}

json

Basic request to get trade volume

application/json

Example Responses

[
  [
    {
      "symbol": "btcusd",
      "base_currency": "BTC",
      "notional_currency": "USD",
      "data_date": "2019-01-10",
      "total_volume_base": 8.06021756,
      "maker_buy_sell_ratio": 1,
      "buy_maker_base": 6.06021756,
      "buy_maker_notional": 23461.3515203844,
      "buy_maker_count": 34,
      "sell_maker_base": 0,
      "sell_maker_notional": 0,
      "sell_maker_count": 0,
      "buy_taker_base": 0,
      "buy_taker_notional": 0,
      "buy_taker_count": 0,
      "sell_taker_base": 2,
      "sell_taker_notional": 7935.66,
      "sell_taker_count": 2
    },
    {
      "symbol": "ltcusd",
      "base_currency": "LTC",
      "notional_currency": "USD",
      "data_date": "2019-01-11",
      "total_volume_base": 3,
      "maker_buy_sell_ratio": 0,
      "buy_maker_base": 0,
      "buy_maker_notional": 0,
      "buy_maker_count": 0,
      "sell_maker_base": 0,
      "sell_maker_notional": 0,
      "sell_maker_count": 0,
      "buy_taker_base": 3,
      "buy_taker_notional": 98.22,
      "buy_taker_count": 3,
      "sell_taker_base": 0,
      "sell_taker_notional": 0,
      "sell_taker_count": 0
    }
  ]
]

json

Response with trade volume for multiple symbols

application/json

Get Notional Trading Volume

POST

https://api.sandbox.gemini.com

/v1/notionalvolume

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

Get Notional Trading Volume › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Get Notional Trading Volume › Request Body

request

string · required

The API endpoint path

Example: /v1/notionalvolume

TimestampType · required

timestamp

account

string

Example: primary

Get Notional Trading Volume › Responses

The notional volume

date

string · date

last_updated_ms

integer

web_maker_fee_bps

integer

web_taker_fee_bps

integer

web_auction_fee_bps

integer

api_maker_fee_bps

integer

api_taker_fee_bps

integer

api_auction_fee_bps

integer

fix_maker_fee_bps

integer

fix_taker_fee_bps

integer

fix_auction_fee_bps

integer

notional_30d_volume

string

object[]

api_notional_30d_volume

string

object

POST/v1/notionalvolume

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/notionalvolume \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/notionalvolume",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/notionalvolume",
  "nonce": "<nonce>"
}

json

Basic request to get notional volume

application/json

Example Responses

{
  "web_maker_fee_bps": 25,
  "web_taker_fee_bps": 35,
  "web_auction_fee_bps": 25,
  "api_maker_fee_bps": 10,
  "api_taker_fee_bps": 35,
  "api_auction_fee_bps": 20,
  "fix_maker_fee_bps": 10,
  "fix_taker_fee_bps": 35,
  "fix_auction_fee_bps": 20,
  "notional_30d_volume": 150,
  "last_updated_ms": 1551371446000,
  "date": "2019-02-28",
  "notional_1d_volume": [
    {
      "date": "2019-02-22",
      "notional_volume": 75
    },
    {
      "date": "2019-02-14",
      "notional_volume": 75
    }
  ]
}

json

Response with notional volume and fee information

application/json

Wrap Order

POST

https://api.sandbox.gemini.com

/v1/wrap/{symbol}

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 for more information.

Wrap Order › path Parameters

symbol

string · required

Trading pair symbol

BTCUSD, etc. See symbols and minimums.

Wrap Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Wrap Order › Request Body

request

string · required

The literal string "/v1/wrap/symbol"

required

The nonce, as described in Private API Invocation

amount

string · required

The amount to wrap

side

string · enum

"buy" or "sell"

Enum values:

buy

sell

client_order_id

string

A client-specified order id

account

string

Required for Master API keys. The name of the account within the subaccount group.

Wrap Order › Responses

Successful operation

orderId

string

The order ID

pair

string

Trading pair symbol

price

string

The price of the order

priceCurrency

string

The currency in which the order is priced

side

string

Either "buy" or "sell"

quantity

string

The amount that was executed

quantityCurrency

string

The currency label for the quantity field

totalSpend

string

Total quantity spent for the order

totalSpendCurrency

string

Currency of the totalSpend

fee

string

The amount charged

feeCurrency

string

Currency that the fee was paid in

depositFee

string

The deposit fee quantity

depositFeeCurrency

string

Currency in which depositFee is taken

POST/v1/wrap/{symbol}

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/wrap/:symbol \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/wrap/GUSDUSD",
  "nonce": "<nonce>",
  "amount": "1",
  "side": "buy",
  "client_order_id": "4ac6f45f-baf1-40f8-83c5-001e3ea73c7f"
}
'

shell

Example Request Body

{
  "request": "/v1/wrap/GUSDUSD",
  "nonce": "<nonce>",
  "amount": "1",
  "side": "buy",
  "client_order_id": "4ac6f45f-baf1-40f8-83c5-001e3ea73c7f"
}

json

application/json

Example Responses

{
  "orderId": 429135395,
  "pair": "GUSDUSD",
  "price": "1",
  "priceCurrency": "USD",
  "side": "buy",
  "quantity": "1",
  "quantityCurrency": "GUSD",
  "totalSpend": "1",
  "totalSpendCurrency": "USD",
  "fee": "0",
  "feeCurrency": "USD",
  "depositFee": "0",
  "depositFeeCurrency": "USD"
}

json

application/json

Market Data Fund Management