WebSocket Best Practices & Usage Guidelines

Amberdata's WebSocket services provide real-time, low-latency data streaming across multiple feeds. To ensure a consistent and reliable experience, we enforce structured connection and subscription management policies.

To maintain optimal performance, customers must subscribe to specific instruments explicitly rather than using wildcard instrument subscriptions.

WebSocket Subscription Guidelines

To optimize stability and ensure efficient data streaming, keep the following in mind:

• Explicit instrument subscriptions are required – Wildcard instrument subscriptions ("instrument": "ALL") are not supported.
• Exchange wildcard subscriptions are available for Spot markets only. Support for derivatives (Futures & Options) is coming in a future update.
• Connection and subscription parameters are customizable – Contact support if you have specific needs.

Best Practices for WebSocket Connections

Following these recommendations will help maintain a stable, low-latency connection:

Recommended Practices:

• Use explicit instrument subscriptions instead of wildcard-based requests.
• Use exchange-wide subscriptions where applicable (see Wildcard Exchange Subscription example below).
• Distribute subscriptions efficiently across multiple connections when handling high-volume data.

Avoid:

• Subscribing to all instruments via wildcards – This is not supported.
• Overloading a single connection with excessive subscriptions – Utilize multiple connections as needed.

Error Handling & Response Codes

1. Wildcard Instrument Subscription Not Allowed

Error Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "description": "Wildcard subscription is not allowed for instruments. Please subscribe with each instrument name explicitly.",
    "code": 400
  }
}

Solution: Subscribe to each instrument explicitly instead of using "instrument": "ALL".

2. Subscription Limit Reached

Error Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "description": "Max subscription limit reached on this connection. Please open additional connections to subscribe to more instruments.",
    "code": 400
  }
}

Solution: Use additional WebSocket connections to manage high-volume subscriptions.

Example Subscription Requests

Single Exchange & Instrument Subscription

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["feed:type", {"exchange": "bitget", "pair": "btc_usdt"}]
}

Multiple Instrument Subscriptions (Valid Example)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["feed:type", {"exchange": "bitget", "pair": "btc_usdt"}]
}
...
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscribe",
  "params": ["feed:type", {"exchange": "bitget", "pair": "eth_usdt"}]
}

Wildcard Exchange Subscription (Valid for Spot Markets Only)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["feed:type", {"pair": "btc_usdt"}]
}

Note: Exchange wildcard subscriptions are currently supported for Spot markets only. Support for derivatives (Futures & Options) is planned for a future update but is not yet available.

Wildcard Instrument Subscription (Invalid Example)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["feed:type", {"exchange": "bitget"}]
}

This request will return an error. Instead, subscribe to specific instruments explicitly.

WebSocket Rate Limits

Amberdata’s WebSocket service supports customizable connection and subscription parameters tailored to different use cases. If your application requires specific configurations, please contact our Sales team for assistance.

Conclusion

By following these best practices, you can:

• Ensure better connection stability
• Reduce event latency during high-volume periods
• Optimize data retrieval efficiency

For further details, please refer to our API documentation or contact support for assistance.