To ensure optimal performance and maintain stable connections, follow these subscription guidelines and best practices for Amberdata’s WebSocket services.

​
Core Subscription Rules

​
✅ Required Practices

Explicit Instrument Subscriptions
  • Always subscribe to specific instruments explicitly
  • Each instrument requires a separate subscription request
  • This ensures optimal performance and predictable data delivery
Use Appropriate Connection Endpoints
  • Connect to the dedicated URL for your data type
  • This reduces latency and improves connection stability
  • See getting started guide for endpoint details

​
❌ Restrictions

No Instrument Wildcards
  • "instrument": "ALL" subscriptions are not supported
  • Wildcard instrument subscriptions will return an error
  • Subscribe to each instrument individually instead
Limited Exchange Wildcards
  • Exchange wildcards are only available for Spot markets
  • Futures and Options wildcards are coming in a future update
  • Use explicit exchange parameters for derivatives

​
Subscription Patterns

​
Valid Subscription Examples

Single Exchange & Instrument: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "bitget", "pair": "btc_usdt"}]
}
Exchange Wildcard (Spot Markets Only): 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"pair": "btc_usdt"}]
}
Multiple Instruments - Correct Approach: 
// Request 1
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "bitget", "pair": "btc_usdt"}]
}

// Request 2
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "bitget", "pair": "eth_usdt"}]
}

​
Invalid Subscription Examples

❌ Instrument Wildcard (Not Allowed): 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:spot:trades", {"exchange": "bitget"}]
}
❌ Exchange Wildcard for Derivatives: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:futures:trades", {"pair": "btc_usdt"}]
}

​
Connection Management

​
Distribute High-Volume Subscriptions

Single Connection Limits:
  • Each connection has a maximum subscription limit
  • When limit is reached, open additional connections
  • Distribute subscriptions strategically across connections
Multi-Connection Strategy: 
// Connection 1: Major pairs (as separate connections)
const conn1 = new WebSocket('wss://ws.amberdata.com/spot');
// Subscribe to BTC, ETH major pairs

// Connection 2: Altcoin pairs
const conn2 = new WebSocket('wss://ws.amberdata.com/spot');
// Subscribe to smaller altcoin pairs

// Connection 3: Futures data
const conn3 = new WebSocket('wss://ws.amberdata.com/futures');
// Subscribe to futures instruments

​
Connection Optimization

Dedicated Endpoints by Data Type:
Data CategoryOptimal EndpointSubscription Types
Spotwss://ws.amberdata.com/spottrades, tickers, ohlcv, order events
Futureswss://ws.amberdata.com/futurestrades, tickers, ohlcv, order events, funding rates, liquidations, open interest
Optionswss://ws.amberdata.com/optionstrades, tickers, ohlcv, order events, liquidations, open interest
Blockchainwss://ws.amberdata.comblocks, transactions, logs

​
Rate Limits by Access Tier

Access LevelAPI Key TypeConcurrent ConnectionsSubscriptions/ConnectionWildcards
TrialUAT5100❌ Not supported
On-DemandUAO20100❌ Not supported
EnterpriseUAKCustomCustom✅ Available

​
Rate Limit Guidelines

Trial & On-Demand Users:
  • Plan subscriptions within your connection and subscription limits
  • Use multiple connections to maximize throughput
  • Consider upgrading to Enterprise for wildcard support
Enterprise Users:
  • Contact support for custom rate limit configuration
  • Wildcard subscriptions available for qualifying use cases
  • Advanced connection management options available

​
Performance Best Practices

​
Connection Stability

Implement Proper Error Handling:
  • Monitor connection health continuously
  • Implement automatic reconnection with exponential backoff
  • Handle subscription errors gracefully
Resource Management:
  • Monitor subscription count per connection
  • Distribute load evenly across connections
  • Close unused subscriptions promptly

​
Data Processing Efficiency

Handle High-Frequency Data:
  • Buffer incoming messages for batch processing
  • Implement proper message queuing
  • Use connection-specific threading if needed
Memory Management:
  • Process messages promptly to avoid buildup
  • Implement proper cleanup for closed subscriptions
  • Monitor memory usage in high-volume scenarios

​
Common Patterns

​
Market Data Collection

// Subscribe to comprehensive spot market data
const subscriptions = [
  ["market:spot:trades", {"exchange": "binance", "pair": "btc_usdt"}],
  ["market:spot:tickers", {"exchange": "binance", "pair": "btc_usdt"}],
  ["market:spot:ohlcv", {"exchange": "binance", "pair": "btc_usdt"}]
];

subscriptions.forEach((sub, index) => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: index + 1,
    method: "subscribe",
    params: sub
  }));
});

​
Cross-Exchange Monitoring

// Monitor same pair across multiple exchanges
const exchanges = ["binance", "gdax", "bitget"];
exchanges.forEach((exchange, index) => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: index + 1,
    method: "subscribe",
    params: ["market:spot:trades", {"exchange": exchange, "pair": "btc_usdt"}]
  }));
});

​
Troubleshooting Tips

  1. Start Small: Begin with a few subscriptions and scale up
  2. Monitor Performance: Track connection health and message rates
  3. Use Appropriate Endpoints: Match endpoint to data type for best performance
  4. Plan for Scale: Design with multiple connections from the start
  5. Test Error Scenarios: Ensure robust error handling and recovery

​
Next Steps