Archived

Order Events (Archived)

Copy page

Order Events

Order events is a private API that gives you information about your orders in real time. When you connect, you get a book of your active orders. Then in real time you receive information about order events like acceptance, booking, fills, cancels, and more.

WebSocket Request

wss://api.gemini.com/v1/order/events

The API key must have the Trader or Auditor role assigned.

Headers

Header	Value
X-GEMINI-APIKEY	Your Gemini API session key
X-GEMINI-PAYLOAD	Base64-encoded JSON: {"request": "/v1/order/events", "nonce": 123456}
X-GEMINI-SIGNATURE	See Private API Invocation

URL Parameters

Parameter	Type	Required	Description
symbolFilter	string	No	Optional symbol filter
apiSessionFilter	string	No	Optional API session key filter
eventTypeFilter	string	No	Optional event type filter
heartbeat	boolean	No	Stream heartbeats (default: false)

Python Example

Code
 
import ssl, websocket, json, base64, hmac, hashlib, time

gemini_api_key = "mykey"
gemini_api_secret = "1234abcd".encode()

payload = {"request": "/v1/order/events", "nonce": time.time()}
encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)
signature = hmac.new(gemini_api_secret, b64, hashlib.sha384).hexdigest()

ws = websocket.WebSocketApp(
    "wss://api.gemini.com/v1/order/events?symbolFilter=btcusd&eventTypeFilter=fill&eventTypeFilter=closed&heartbeat=true",
    on_message=lambda ws, msg: print(msg),
    header={
        'X-GEMINI-PAYLOAD': b64.decode(),
        'X-GEMINI-APIKEY': gemini_api_key,
        'X-GEMINI-SIGNATURE': signature
    })
ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})

---

Response

Once your WebSocket session is established, you will receive:

1. A subscription acknowledgement
2. A list of your active orders (unless filtered out)
3. Ongoing order events interspersed with heartbeats every five seconds

Common Fields

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

Field	Type	Required	Description
type	string	Yes	Event type: accepted, booked, fill, cancelled, etc.
socket_sequence	integer	Yes	Monotonic increasing sequence number
order_id	string	Yes	Order ID assigned by Gemini
event_id	string	Yes*	Event ID (not present for initial events)
account_name	string	No	Account name (Master scoped API keys only)
api_session	string	Yes*	API session key (UI for website orders)
client_order_id	string	No	Client-specified order ID
symbol	string	Yes	Symbol of the order
side	string	Yes	buy or sell
behavior	string	No	immediate-or-cancel, fill-or-kill, or maker-or-cancel
order_type	string	Yes	Description of the order
timestamp	string	Yes	Timestamp in seconds (use timestampms instead)
timestampms	timestampms	Yes	Timestamp in milliseconds
is_live	boolean	Yes	true if the order is active on the book
is_cancelled	boolean	Yes	true if the order has been canceled
is_hidden	boolean	Yes	true if the order is active but not visible
avg_execution_price	decimal	No	Average execution price (0 if unfilled)
executed_amount	decimal	No	Amount filled
remaining_amount	decimal	No	Amount remaining (absent for market buys)
original_amount	decimal	No	Original quantity (absent for market buys)
price	decimal	No	Limit order price (absent for market orders)
total_spend	decimal	No	Total spend for market buys

---

Event Types

Event Type	Filterable	Description
subscription_ack	No	Acknowledges your subscription and echoes back parsed filters
heartbeat	Yes	Sent every 5 seconds to show connection is alive
initial	Yes	Current active orders at subscription time
accepted	Yes	Order accepted for initial processing
rejected	Yes	Order rejected
booked	Yes	Order visible on the order book
fill	Yes	Order filled (partial or complete)
cancelled	Yes	Order cancelled
cancel_rejected	Yes	Cancel request could not be fulfilled
closed	Yes	Last event in order lifecycle

Subscription Acknowledgement

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

Heartbeat

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

Active Orders (Initial)

Code
 
[
  {
    "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
  }
]

Accepted

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

• Immediate fill followed by booked (remaining qty) or closed (fully filled)
• cancelled then closed (behavior constraints not met)
• Market orders: fill event(s) followed by closed

Code
 
[
  {
    "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
  }
]

Rejected

Code
 
[
  {
    "type": "rejected",
    "order_id": "104246",
    "event_id": "104247",
    "reason": "InvalidPrice",
    "symbol": "btcusd",
    "side": "buy",
    "order_type": "exchange limit",
    "is_live": false,
    "original_amount": "5",
    "price": "703.14444444",
    "socket_sequence": 310311
  }
]

Booked

When limit orders are booked, they have a non-zero quantity visible on the exchange. Market orders are never booked.

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

Fill

A fill event indicates a partial or complete fill. A complete fill is distinguished by remaining_amount of 0. The fill.price is the execution price (always present), while price is the original limit order price.

Field	Type	Description
fill.trade_id	string	Event id the order was filled at
fill.liquidity	string	Maker or Taker
fill.price	decimal	Execution price
fill.amount	decimal	Amount of the trade fill
fill.fee	decimal	Fee for this side of the trade
fill.fee_currency	string	Currency code of the fee

Code
 
[
  {
    "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
  }
]

Cancelled

Orders may be cancelled because you requested it, behavior constraints couldn't be fulfilled, FIX connection was disconnected, or heartbeat timeout.

Field	Type	Description
cancel_command_id	string	Event id of the cancel command
reason	string	Reason for cancellation

Code
 
[
  {
    "type": "cancelled",
    "order_id": "109944118",
    "event_id": "109964524",
    "cancel_command_id": "109964523",
    "reason": "Requested",
    "symbol": "bchusd",
    "side": "buy",
    "order_type": "exchange limit",
    "is_live": false,
    "is_cancelled": true,
    "socket_sequence": 22
  }
]

Cancel Rejected

Code
 
[
  {
    "type": "cancel_rejected",
    "order_id": "6425",
    "event_id": "6434",
    "cancel_command_id": "6433",
    "reason": "OrderNotFound",
    "symbol": "btcusd",
    "side": "buy",
    "socket_sequence": 312300
  }
]

Closed

The closed event is the last event in the lifecycle of any order that has been accepted. Your order has been removed from the book.

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

---

Filtering

Filtering is completely optional. If you don't specify any filters, you'll see all your order events for every symbol, every API session and the UI, every event type.

Filtering works by whitelisting. You can filter on any combination of:

1. One or more supported symbols
2. One or more API session keys (use UI for website orders)
3. One or more event types

To provide multiple arguments, repeat the parameter:

Code
 
wss://api.gemini.com/v1/order/events?symbolFilter=btcusd&symbolFilter=ethbtc&eventTypeFilter=fill&eventTypeFilter=closed

---

Workflow

1. Client submits order to Gemini exchange
2. Is the order accepted?
   • Yes: Gemini sends accepted, then zero or more fill events
     • If remaining quantity: booked event, order rests until cancelled or filled
     • If fully filled: closed event
   • No: Gemini sends rejected, no further events