Skip to main content
This page covers establishing a WebSocket connection, authentication, and handling disconnections.

​
Timeout

Maximum session timeout is 1 hour. Clients must manage reconnections.

​
Heartbeat

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

​
Authentication

All WebSocket connections require authentication via the Sec-Websocket-Protocol header: 
Sec-Websocket-Protocol: decibel, <API_KEY>
Replace <API_KEY> with your Bearer token from Geomi. See REST Authentication for how to get credentials.

​
Subscribe/Unsubscribe

Send a JSON message with method and topic: 
{"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}
Success response: 
{"success":true,"method":"subscribe","topic":"account_open_orders:0x54011252d627054ccf3401755ef1b068b740f8a1c45886354d1eef549d5907ba"}
Error response (invalid topic type): 
{"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)

​
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

​
SDK Managed Connections

The TypeScript SDK handles connection management automatically. See TypeScript SDK Overview.

WebSocket Overview

Available channels and message formats

Authentication

How to get bearer tokens