Connection Management

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

Implement exponential backoff for reconnection attempts
Track active subscriptions to restore them after reconnecting
Use sequence numbers to detect missed messages (for orderbook updates)
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

Error	Cause
`Unknown topic type '{name}'`	Unrecognized channel name
`Missing user address for {topic} topic`	Topic requires a user/account address but none provided
`Missing market address for {topic} topic`	Topic 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 topic`	Must be one of: `1`, `2`, `5`, `10`, `100`, `1000`
`Invalid interval '{interval}' for market_candlestick topic`	Must be one of: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `1d`, `1w`, `1mo`
`Maximum client topic subscription count of 150 reached`	Too many active subscriptions on one connection

WebSocket Overview

Channel catalog and topic names

Authentication

Token and header setup

​Timeout

​Heartbeat

​Authentication and Gateway Boundary

​Subscribe/Unsubscribe

​Success Response

​Error Response

​Handling Reconnection

​Best Practices

​Error Messages

​Common Errors

​Related