Skip to main content
This page covers WebSocket connection lifecycle, auth headers, topic subscription format, and reconnection behavior.

​
Timeout

Maximum session timeout is 1 hour. Clients must reconnect and restore subscriptions.

​
Heartbeat

The server sends WebSocket ping frames every 30 seconds. The keepalive timer is refreshed when:
  • A pong frame is received
  • Any subscribe or unsubscribe activity occurs

​
Authentication and Gateway Boundary

Use Sec-WebSocket-Protocol: 
Sec-WebSocket-Protocol: decibel, <API_KEY>
  • decibel is the accepted subprotocol
  • <API_KEY> is your bearer token from Geomi
Implementation note: the WebSocket service itself enforces protocol/topic/message shape and subscription limits. API-key validation is typically enforced at the gateway/proxy layer before traffic reaches the service. See REST Authentication for credential setup.

​
Subscribe/Unsubscribe

Send JSON with method and topic: 
{"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}

​
Success Response

{"success":true,"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}

​
Error Response

{"success":false,"method":"subscribe","topic":"asd:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba","error":"Unknown topic type 'asd'"}
To unsubscribe, use "method":"unsubscribe" with the same topic.

​
Handling Reconnection

Since the maximum session timeout is 1 hour, your client must handle reconnections gracefully.

​
Best Practices

  1. Implement exponential backoff for reconnection attempts
  2. Track active subscriptions to restore them after reconnecting
  3. Use sequence numbers to detect missed messages (for orderbook updates)
  4. For withdraw_queue, backfill full state from GET /api/v1/withdraw_queue and merge WS deltas by request_id.

​
Error Messages

Error responses use the same format as subscribe/unsubscribe responses: 
{
  "success": false,
  "method": "subscribe",
  "topic": "depth:invalid_address",
  "error": "Invalid market address 'invalid_address' for depth topic"
}

​
Common Errors

ErrorCause
Unknown topic type '{name}'Unrecognized channel name
Missing user address for {topic} topicTopic requires a user/account address but none provided
Missing market address for {topic} topicTopic requires a market address but none provided
Invalid user address '{addr}'Malformed address
Invalid market address '{addr}'Malformed address
Invalid aggregation level '{level}' for depth topicMust be one of: 1, 2, 5, 10, 100, 1000
Invalid interval '{interval}' for market_candlestick topicMust be one of: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1w, 1mo
Maximum client topic subscription count of 100 reachedToo many active subscriptions on one connection

WebSocket Overview

Channel catalog and topic names

Authentication

Token and header setup