Order Events

Response

Once your WebSocket session is established, you will receive:

a subscription acknowledgement
a list of your active orders, if you supply either
- no eventTypeFilter, or
- an explicit eventTypeFilter=initial argument as part of one or more eventTypeFilter arguments in your WebSocket request
ongoing order events interspersed with heartbeats every five seconds
- A response is a JSON array containing one or more order event objects
- Order events will arrive in real time, in the sequence that they happened on the exchange
- Each order event pertains to a single order but a batch of order events may contain order events pertaining to multiple orders.
- Use the order_id field in the initial order to keep track of what's happening to each order
- Heartbeats are never batched with other order events

The JSON format of the response objects maintains compatibility with the Order Status and Get Active Orders APIs.

Common Fields

These fields are common to all order events except subscription_ack and heartbeat.

Field	Type	Required?	Description
`type`	string	Y	An order event type, e.g. `accepted`, `booked`, `fill`, `cancelled`.
`socket_sequence`	integer	Y	Zero-indexed monotonic increasing sequence number attached to each message sent. If there is a gap in this sequence, you have missed a message. See Sequence Numbers for more information.
`order_id`	string	Y	The order ID that Gemini has assigned to this order, first provided in the `accepted` or `rejected` message. All further events (`fill`, `booked`, `cancelled`, `closed`) will refer to this `order_id`.
`event_id`	string	Y*	The event ID associated with this specific order event. `event_id` is supplied for every order event type except the `initial` events that supply the active orders when you initially subscribe.
`account_name`	string	N	Returned when using a Master scoped API key. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.
`api_session`	string	Y*	The API session key associated with this order. Note: orders placed by website users show `UI` as the API session key.
`client_order_id`	Client Order ID	N	The optional client-specified order ID.
`symbol`	string	Y	The symbol of the order.
`side`	string	Y	Either `buy` or `sell`.
`behavior`	string	N	When limit orders are placed with `immediate-or-cancel`, `fill-or-kill`, or `maker-or-cancel` behavior, this field will indicate the order behavior.
`order_type`	string	Y	Description of the order.
`timestamp`	string	Y	The timestamp the order was submitted. For compatibility reasons, this is returned as a string. It is recommended to use the `timestampms` field instead.
`timestampms`	timestampms	Y	The timestamp the order was submitted in milliseconds.
`is_live`	boolean	Y	`true` if the order is active on the book (has remaining quantity and has not been canceled).
`is_cancelled`	boolean	Y	`true` if the order has been canceled. Note the spelling: "cancelled" instead of "canceled" (for compatibility reasons).
`is_hidden`	boolean	Y	`true` if the order is active but not visible.
`avg_execution_price`	decimal	N	The average price at which this order has been executed so far. `0` if the order has not been executed at all.
`executed_amount`	decimal	N	The amount of the order that has been filled.
`remaining_amount`	decimal	N	The amount of the order that has not been filled. Present for limit and market sell orders; absent for market buy orders.
`original_amount`	decimal	N	For limit orders and market sells, the quantity the order was placed for. Not present for market buys.
`price`	decimal	N	For limit orders, the price the order was placed for. Not present for market buys and sells.
`total_spend`	decimal	N	For market buys, the total spend (fee-inclusive notional value) the order was placed for. Not present for limit orders and market sells.

Examples

Limit Order accepted

[
  {
    "type": "accepted",
    "order_id": "109535951",
    "event_id": "109535952",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "btcusd",
    "side": "buy",
    "order_type": "exchange limit",
    "timestamp": "1547742904",
    "timestampms": 1547742904989,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "original_amount": "1",
    "price": "3592.00",
    "socket_sequence": 13
  }
]

json

Market Buy accepted

[
  {
    "type": "accepted",
    "order_id": "109964529",
    "event_id": "109964530",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "bchusd",
    "side": "buy",
    "order_type": "market buy",
    "timestamp": "1547756076",
    "timestampms": 1547756076644,
    "is_live": false,
    "is_cancelled": false,
    "is_hidden": false,
    "total_spend": "200.00",
    "socket_sequence": 29
  }
]

json

Market Sell accepted

[
  {
    "type": "accepted",
    "order_id": "109964616",
    "event_id": "109964617",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "ethusd",
    "side": "sell",
    "order_type": "market sell",
    "timestamp": "1547756893",
    "timestampms": 1547756893937,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "original_amount": "25",
    "socket_sequence": 26
  }
]

json

Maker-or-cancel limit order accepted

[
  {
    "type": "accepted",
    "order_id": "109964647",
    "event_id": "109964648",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "ethusd",
    "side": "sell",
    "order_type": "exchange limit",
    "timestamp": "1547757139",
    "timestampms": 1547757139783,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "original_amount": "5",
    "price": "122.30",
    "behavior": "maker-or-cancel",
    "socket_sequence": 16
  }
]

json

Immediate-or-cancel limit order accepted, then immediately filled and closed

[{
  "type" : "accepted",
  "order_id" : "652164",
  "event_id" : "652165",
  "account_name": "primary",
  "api_session" : "UI",
  "symbol" : "btcusd",
  "side" : "buy",
  "order_type" : "exchange limit",
  "timestamp" : "1478790127",
  "timestampms" : 1478790127297,
  "is_live" : true,
  "is_cancelled" : false,
  "is_hidden" : false,
  "original_amount" : "2",
  "price" : "714.01",
  "behavior" : "immediate-or-cancel",
  "socket_sequence" : 131419
}]
    ...
[{
  "type" : "fill",
  "order_id" : "652164",
  "account_name": "primary",
  "api_session" : "UI",
  "symbol" : "btcusd",
  "side" : "buy",
  "order_type" : "exchange limit",
  "timestamp" : "1478790127",
  "timestampms" : 1478790127297,
  "is_live" : false,
  "is_cancelled" : false,
  "is_hidden" : false,
  "avg_execution_price" : "714.00",
  "executed_amount" : "2",
  "remaining_amount" : "0",
  "original_amount" : "2",
  "price" : "714.01",
  "fill" : {
    "trade_id" : "652166",
    "liquidity" : "Taker",
    "price" : "714.00",
    "amount" : "2",
    "fee" : "3.57",
    "fee_currency" : "USD"
  },
  "socket_sequence" : 131420
}, {
  "type" : "closed",
  "order_id" : "652164",
  "event_id" : "652168",
  "account_name": "primary",
  "api_session" : "UI",
  "symbol" : "btcusd",
  "side" : "buy",
  "order_type" : "exchange limit",
  "timestamp" : "1478790127",
  "timestampms" : 1478790127297,
  "is_live" : false,
  "is_cancelled" : false,
  "is_hidden" : false,
  "avg_execution_price" : "714.00",
  "executed_amount" : "2",
  "remaining_amount" : "0",
  "original_amount" : "2",
  "price" : "714.01",
  "socket_sequence" : 131421
}]

json

WebSocket Request Event Types

​Response

​Common Fields

​Examples

​Limit Order accepted

​Market Buy accepted

​Market Sell accepted

​Maker-or-cancel limit order accepted

​Immediate-or-cancel limit order accepted, then immediately filled and closed

Response

Common Fields

Examples

Limit Order accepted

Market Buy accepted

Market Sell accepted

Maker-or-cancel limit order accepted

Immediate-or-cancel limit order accepted, then immediately filled and closed