Order Events

Event Types

Types

Event Type	Can be filtered?	Description
`subscription_ack`	N	Acknowledges your order events subscription and echoes back your parsed filters.
`heartbeat`	Y	Sent at five-second intervals to show that your WebSocket connection to Gemini is alive. This is filtered independently from the `eventTypeFilter` as `heartbeat=true`. The default for the `heartbeat` parameter is `true`.
`initial`	Y	At the time you begin your subscription, you receive a list of your current active orders. Each active order will have the `initial` event type. You only see this event type at the beginning of each subscription.
`accepted`	Y	Acknowledges that the exchange has received your order for initial processing. An order which cannot be accepted for initial processing receives a `rejected` event.
`rejected`	Y	When an order is rejected.
`booked`	Y	Your order is now visible on the Gemini order book. Under certain conditions, when you place an order you will not receive a `booked` event. These include: When your order is completely filled after being accepted When your order is accepted for initial processing but then immediately cancelled because some condition cannot be fulfilled (for instance, if you submit a maker-or-cancel order but your order would cross)
`fill`	Y	When an order is filled.
`cancelled`	Y	When an order is cancelled.
`cancel_rejected`	Y	When your request to cancel an order cannot be fulfilled. Reasons this might happen include: The order cannot be found
`closed`	Y	The last event in the order lifecycle: whether this order was completely filled or cancelled, the consumer can use the `closed` event as a signal that the order is off the book on the Gemini side.

Subscription Acknowledgement

The first message you receive acknowledges your subscription.

Compare the filters to the ones you requested to make sure your request was parsed as you expected.

Field	Type	Required?	Description
`type`	order event type	Y	`subscription_ack`
`accountId`	integer	Y	The account ID associated with the API session key you supplied in your `X-GEMINI-APIKEY` header. When using a master API key, it will be the account group ID associated with the API session key. See Private API Invocation for more details.
`subscriptionId`	string	Y	The ID associated with this websocket subscription; the component after the last dash is a request trace ID that will be echoed back in the heartbeat `traceId` field.
`symbolFilter`	string array	Y	An array of zero or more supported symbols. An empty array means your subscription is not filtered by symbol.
`apiSessionFilter`	string array	Y	An array of zero or more API session keys associated with your account. The string `"UI"` means you want to see orders placed by your website users. An empty array means you want to see all orders on your account, regardless of whether they were placed via API or UI.
`eventTypeFilter`	string array	Y	An array of zero or more order event types. An empty array means your subscription is not filtered by event type.

Subscription acknowledgement response:

{
  "type": "subscription_ack",
  "accountId": 5365,
  "subscriptionId": "ws-order-events-5365-b8bk32clqeb13g9tk8p0",
  "symbolFilter": ["btcusd"],
  "apiSessionFilter": ["UI"],
  "eventTypeFilter": ["fill", "closed"]
}

json

Heartbeats

Gemini will send a heartbeat every five seconds so you'll know your WebSocket connection is active.

Gemini recommends logging and retaining all heartbeat messages. If your WebSocket connection is unreliable, please contact Gemini support with this log.

Field	Type	Required?	Description
`type`	order event type	N	`heartbeat`. This can be set to true in the heartbeat URL parameter. Defaults to `true`
`timestampms`	timestampms	Y	Gemini adds a timestamp so if you get disconnected, you may contact Gemini support with the timestamp of the last heartbeat you received.
`sequence`	integer	Y	Gemini adds a monotonically incrementing sequence to make it easy to tell if you've missed a heartbeat. Not the same as `socket_sequence`!
`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.
`trace_id`	string	Y	Gemini adds a trace id to each WebSocket request that our networking team can use to trace your request in our logs.

If you miss one or more heartbeats, disconnect and reconnect. If the socket sequence number contains a gap, disconnect and reconnect.

{
  "type": "heartbeat",
  "timestampms": 1547742998508,
  "sequence": 31,
  "trace_id": "b8biknoqppr32kc7gfgg",
  "socket_sequence": 37
}

json

Active Orders

The next group of messages you receive shows all your current active orders at the time you subscribed. (Unless you've chosen to filter out the initial order event type, in which case you will not receive these messages.)

Field	Type	Required?	Description
`type`	order event type	Y	`initial`

[
  {
    "type": "initial",
    "order_id": "109939984",
    "account_name": "primary",
    "api_session": "myapikey",
    "symbol": "btcusd",
    "side": "sell",
    "order_type": "exchange limit",
    "timestamp": "1547754474",
    "timestampms": 1547754474438,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "avg_execution_price": "0.00",
    "executed_amount": "0",
    "remaining_amount": "1",
    "original_amount": "1",
    "price": "3631.23",
    "socket_sequence": 0
  },
  {
    "type": "initial",
    "order_id": "109940168",
    "api_session": "UI",
    "symbol": "solusd",
    "side": "buy",
    "order_type": "exchange limit",
    "timestamp": "1547754480",
    "timestampms": 1547754480759,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "avg_execution_price": "0.00",
    "executed_amount": "0",
    "remaining_amount": "1",
    "original_amount": "1",
    "price": "53.83",
    "socket_sequence": 1
  }
]

json

Accepted

When you place an order on the exchange, Gemini acknowledges that your order has been accepted for initial processing by sending you an accepted event.

Your order is now live on the exchange. Possible outcomes are:

if your limit order can be immediately filled and you have not chosen maker-or-cancel behavior, you will get zero or more initial fill events, followed by
- if your order has remaining quantity, then you will receive a booked event to let you know that the remaining quantity is now visible on the exchange
- if your order has been completely filled, you will receive a closed event
if your limit order includes behavior such as maker-or-cancel which cannot be fulfilled, cancelled and then closed
market orders will be immediately filled with one or more fill events followed by a closed event

Field	Type	Required?	Description
`type`	order event type	Y	`accepted`

Rejected

If your order cannot be accepted by the exchange, you will receive a single rejected event.

Note: the is_live field of a rejected order event is always false but so is the is_cancelled field: is_cancelled is reserved for orders that are actually cancelled, and rejected orders are not live but they are also not cancelled.

Field	Type	Required?	Description
`type`	order event type	Y	`rejected`
`reason`	string	Y	The reason your order was rejected. Contact trading@gemini.com for clarification.

This order was rejected because its price does not conform to the market price tick specified in Symbols and minimums.

[
  {
    "type": "rejected",
    "order_id": "104246",
    "event_id": "104247",
    "reason": "InvalidPrice",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "btcusd",
    "side": "buy",
    "order_type": "exchange limit",
    "timestamp": "1478205545",
    "timestampms": 1478205545047,
    "is_live": false,
    "original_amount": "5",
    "price": "703.14444444",
    "socket_sequence": 310311
  }
]

json

Booked

When limit orders are booked, they have a non-zero quantity visible on the exchange. These orders remain on the exchange until they are completed filled or cancelled.

Market orders are never booked: they are accepted, filled, and then closed.

Field	Type	Required?	Description
`type`	order event type	Y	`booked`

[
  {
    "type": "booked",
    "order_id": "109535955",
    "event_id": "109535957",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "btcusd",
    "side": "sell",
    "order_type": "exchange limit",
    "timestamp": "1547742952",
    "timestampms": 1547742952725,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "avg_execution_price": "0.00",
    "executed_amount": "0",
    "remaining_amount": "1",
    "original_amount": "1",
    "price": "3592.23",
    "socket_sequence": 25
  }
]

json

Filled

A fill event indicates a partial or a complete fill. A complete fill is distinguished by a remaining_amount of 0.

Note that here executed_amount is the total amount of the order that has been filled. The quantity filled by this specific trade is fill.amount.

Similarly, price is an optional field that denotes the original price of a limit order (absent for market buys and sells), while fill.price is the execution price of the trade (always present).

Field	Type	Required?	Description
`type`	order event type	Y	`fill`
`fill.trade_id`	string	Y	the event id the order was filled at
`fill.liquidity`	string	Y	whether this side of the trade represents `Maker` or `Taker` liquidity
`fill.price`	decimal	Y	the price the trade filled at
`fill.amount`	decimal	Y	the amount of the trade fill
`fill.fee`	decimal	Y	the fee associated with this side of the trade
`fill.fee_currency`	string	Y	the three-letter code of the currency associated with the fee

Example Complete Fill on Limit Order:

[
  {
    "type": "fill",
    "order_id": "109535955",
    "api_session": "UI",
    "symbol": "btcusd",
    "side": "sell",
    "order_type": "exchange limit",
    "timestamp": "1547743216",
    "timestampms": 1547743216580,
    "is_live": false,
    "is_cancelled": false,
    "is_hidden": false,
    "avg_execution_price": "3592.23",
    "executed_amount": "1",
    "remaining_amount": "0",
    "original_amount": "1",
    "price": "3592.23",
    "fill": {
      "trade_id": "109535970",
      "liquidity": "Maker",
      "price": "3592.23",
      "amount": "1",
      "fee": "8.980575",
      "fee_currency": "USD"
    },
    "socket_sequence": 81
  }
]

json

Example Partial Fill on Limit Order:

[
  {
    "type": "fill",
    "order_id": 556309,
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "ethbtc",
    "side": "sell",
    "order_type": "exchange limit",
    "timestamp": "1478729284",
    "timestampMs": 1478729284169,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": false,
    "avg_execution_price": "0.01514",
    "total_executed_amount": "481.95988631",
    "remaining_amount": "303.06099969",
    "original_amount": "785.020886",
    "original_price": "0.01514",
    "fill": {
      "trade_id": "557315",
      "liquidity": "Maker",
      "price": "0.01514",
      "amount": "481.95988631",
      "fee": "0.0182421816968335",
      "fee_currency": "BTC"
    },
    "socket_sequence": 471177
  }
]

json

Cancelled

Your order could be cancelled because:

you requested it
when you placed the order, you added a behavior such as immediate-or-cancel, fill-or-kill, or maker-or-cancel which the exchange could not fulfil - in this case, your order is cancelled and closed instead of being booked
your FIX connection was disconnected, and all your orders have been cancelled
your API session key has been provisioned to require a heartbeat and due to a heartbeat timeout, all your orders have been cancelled

Field	Type	Required?	Description
`type`	order event type	Y	`fill`
`cancel_command_id`	string	N	The event id of the command to cancel your order.
`reason`	string	N	When possible, Gemini will supply the reason your order was cancelled.

[
  {
    "type": "cancelled",
    "order_id": "109944118",
    "event_id": "109964524",
    "cancel_command_id": "109964523",
    "reason": "Requested",
    "account_name": "primary",
    "api_session": "myapikey",
    "symbol": "bchusd",
    "side": "buy",
    "order_type": "exchange limit",
    "timestamp": "1547756060",
    "timestampms": 1547756060142,
    "is_live": false,
    "is_cancelled": true,
    "is_hidden": false,
    "avg_execution_price": "0.00",
    "executed_amount": "0",
    "remaining_amount": "1",
    "original_amount": "1",
    "price": "128.72",
    "socket_sequence": 22
  }
]

json

Cancel Rejected

When Gemini cannot fulfil your request to cancel an order, you'll receive a cancel_rejected notification.

Reasons this might happen include:

the order you tried to cancel can't be found

Field	Type	Required?	Description
`type`	order event type	Y	`cancel_rejected`
`cancel_command_id`	string	Y	The event id of the command to cancel your order.
`reason`	string	Y	The reason Gemini could not fulfil your request to cancel your order.

[
  {
    "type": "cancel_rejected",
    "order_id": "6425",
    "event_id": "6434",
    "cancel_command_id": "6433",
    "reason": "OrderNotFound",
    "account_name": "primary",
    "api_session": "UI",
    "symbol": "btcusd",
    "side": "buy",
    "order_type": "limit",
    "timestamp": "1478204773",
    "timestampms": 1478204773113,
    "is_live": true,
    "is_cancelled": false,
    "is_hidden": true,
    "avg_execution_price": "0.00",
    "executed_amount": "0",
    "remaining_amount": "5",
    "original_amount": "5",
    "price": "721.24",
    "socket_sequence": 312300
  }
]

json

Closed

The closed event is the last event in the workflow of any order that has been accepted on the exchange. When you receive this event, you will know that your order has been removed from the book.

Field	Type	Required?	Description
`type`	order event type	Y	`closed`

[
  {
    "type": "closed",
    "order_id": "109535955",
    "event_id": "109535971",
    "api_session": "UI",
    "symbol": "btcusd",
    "side": "sell",
    "order_type": "exchange limit",
    "timestamp": "1547743216",
    "timestampms": 1547743216580,
    "is_live": false,
    "is_cancelled": false,
    "is_hidden": false,
    "avg_execution_price": "3592.23",
    "executed_amount": "1",
    "remaining_amount": "0",
    "original_amount": "1",
    "price": "3592.23",
    "socket_sequence": 82
  }
]

json

Response About

​Event Types

​Types

​Subscription Acknowledgement

​Heartbeats

​Active Orders

​Accepted

​Rejected

​Booked

​Filled

​Cancelled

​Cancel Rejected

​Closed

Event Types

Types

Subscription Acknowledgement

Heartbeats

Active Orders

Accepted

Rejected

Booked

Filled

Cancelled

Cancel Rejected

Closed