> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amberdata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Guidelines & Best Practices

> This page outlines recommended usage patterns and operational guidelines for Amberdata’s real-time WebSocket APIs to help ensure stable, scalable, and efficient integrations.

## Wildcard Subscription Support

### General rule:

* ✅ **All WebSocket features support wildcard subscriptions**
* ❌ **Except for Tickers and Order Book Events**

Wildcard subscriptions allow you to subscribe broadly (for example, all instruments on an exchange) without specifying every instrument individually.

***

### Example — wildcard subscription (supported features)

Subscribe to **all spot OHLCV data on Binance**:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": [
    "market:spot:ohlcv",
    { "exchange": "binance" }
  ]
}
```

This will stream OHLCV updates for **all spot instruments** available on Binance.

***

### ❌ Tickers & Order Book Events (No wildcards)

For Tickers and Order Book Event streams:

* Wildcard subscriptions are **not supported**
* You **must explicitly specify both**:
  * exchange
  * pair/instrument

Subscriptions that omit either field will be rejected.

### Example — valid subscription

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": [
    "market:spot:tickers",
    { "exchange": "binance", "instrument": "btc_usdt" }
  ]
}
```

### Example — invalid subscription

```json theme={null}
// ❌ instrument missing
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": [
    "market:spot:tickers",
    { "exchange": "binance" }
  ]
}
```

***

## Instrument Wildcards on Futures & Options

While wildcard subscriptions are supported across all features (except Tickers and Order Book Events), **instrument-level wildcards on Futures and Options should be used with caution.**

### Why this matters

Unlike Spot markets, **Futures and Options instrument names are not normalized across exchanges.**
The same underlying asset may have different instrument identifiers depending on the venue.

For example:

* BTCUSDT
* BTC-USD-PERP
* XBTUSD
* BTC\_USDT\_240329

Because of this:

* Subscribing with an instrument wildcard such as:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:futures:trades", { "instrument": "BTCUSDT" }]
}
```

may return **incomplete or unexpected coverage** across exchanges.

### Recommended approach for Futures & Options

Best practices

* Prefer exchange-scoped wildcard subscriptions, for example:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": ["market:futures:trades", { "exchange": "binance" }]
}
```

* Or explicitly subscribe to specific instruments per exchange using known instrument identifiers.
* Avoid assuming a single instrument name maps consistently across venues.

### When instrument wildcards make sense

* Spot markets, where instrument naming is normalized
* Use cases where you intentionally want only instruments that match a specific naming convention on a single exchange

***

## Throughput & Connection Strategy

### High-throughput instruments

Some instruments — particularly major pairs on top exchanges — produce very high message volumes.

**Best practices**

* Use dedicated WebSocket connections for high-throughput instruments
* Avoid mixing high-volume and low-volume subscriptions on the same connection
* This improves reliability and simplifies monitoring and troubleshooting

***

### Scaling subscriptions

As subscription counts grow:

* Distribute subscriptions across multiple connections
* Group subscriptions logically, for example:
  * Connection A: A **single high-throughput instrument** (e.g., BTC/USDT trades on a major exchange)
  * Connection B: Long-tail instruments
  * Connection C: Aggregated wildcard feeds

This helps avoid connection-level bottlenecks and keeps message handling predictable.

***

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

***

## Rate Limits by Access Tier

| Access Level   | API Key Type | Concurrent Connections | Subscriptions/Connection |
| -------------- | ------------ | ---------------------- | ------------------------ |
| **Trial**      | UAT          | 5                      | 100                      |
| **On-Demand**  | UAO          | 20                     | 100                      |
| **Enterprise** | UAK          | Custom                 | Custom                   |