> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/websocket-api/market-data/instrument-list.md).

# Instrument List

Real-time instrument list with metadata and status updates.

**Channel:** `instruments`

## Overview

The instruments channel provides a list of all available trading instruments with their metadata, including trading parameters, precision, and activity status. Upon subscription, all active instruments are sent immediately. Afterward, updates are sent when instrument details change or new instruments are added.

## Connection

Connect to the WebSocket endpoint:

```
wss://marketdata.app.hello.trade/ws
```

## Subscription Request

```json
{
  "type": "subscribe",
  "channel": "instruments"
}
```

| Field     | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `type`    | string | Yes      | Must be `"subscribe"`   |
| `channel` | string | Yes      | Must be `"instruments"` |

**Note:** The instruments channel does not require symbols - it streams all instruments.

## Unsubscription Request

```json
{
  "type": "unsubscribe",
  "channel": "instruments",
  "symbols": []
}
```

## Response

```json
{
  "type": "marketData",
  "channel": "instruments",
  "data": {
    "id": 13,
    "symbol": "BTC",
    "activityStatus": "ACTIVE",
    "minQuantity": "0.00000001",
    "maxQuantity": "1000000",
    "pricePrecision": 8,
    "quantityPrecision": 8,
    "quantityIncrement": "0.00000001",
    "maxOrderValue": "10000000.00",
    "maxDepth": "1000000.00",
    "quoteCurrency": "USD",
    "storkMark": "BTC/USD",
    "storkIndex": "BTC/USD",
    "fundingMax": "0.0005",
    "fundingMin": "-0.0005",
    "interestRate": "0.0001",
    "maxLeverage": 10
  }
}
```

| Field               | Type   | Description                                         |
| ------------------- | ------ | --------------------------------------------------- |
| `id`                | Number | Instrument ID                                       |
| `symbol`            | string | Instrument symbol                                   |
| `activityStatus`    | string | Trading status: `ACTIVE`, `DISABLED`, or `ARCHIVED` |
| `minQuantity`       | string | Minimum order quantity                              |
| `maxQuantity`       | string | Maximum order quantity                              |
| `pricePrecision`    | Number | Decimal places for price                            |
| `quantityPrecision` | Number | Decimal places for quantity                         |
| `quantityIncrement` | string | Minimum quantity increment (may be null)            |
| `maxOrderValue`     | string | Maximum order value in quote currency (may be null) |
| `maxDepth`          | string | Maximum depth of order book (may be null)           |
| `quoteCurrency`     | string | Quote currency (e.g., `USD`)                        |
| `storkMark`         | string | Stork Oracle mark price identifier (may be null)    |
| `storkIndex`        | string | Stork Oracle index price identifier (may be null)   |
| `fundingMax`        | string | Maximum funding rate cap (may be null)              |
| `fundingMin`        | string | Minimum funding rate floor (may be null)            |
| `interestRate`      | string | Base interest rate for funding (may be null)        |
| `maxLeverage`       | Number | Maximum leverage allowed (may be null)              |

## End-of-Snapshot Marker

After all instruments in the initial snapshot have been sent, a final marker message is sent:

```json
{
  "type": "marketData",
  "channel": "instruments",
  "data": {
    "lastMessage": "Y"
  }
}
```

This marker indicates that the initial snapshot is complete. Any subsequent messages are live updates.

## Error Response

```json
{
  "type": "error",
  "message": "Invalid subscription request",
  "code": 400
}
```

## Notes

* Initial snapshot sends all active instruments followed by end-of-snapshot marker
* Updates sent when instrument metadata changes
* New instruments are streamed as they become available