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

# Futures

> Real-time market data for futures trading.

## Funding Rates

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:funding_rates", { "instrument": "ICXUSDT", "exchange": "binance" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "8d5b4e5a-435d-40d4-9701-b3d8c2d15148",
        "result": {
            "exchange": "binance",
            "instrument": "GASUSDT",
            "timestamp": 1711571101000,
            "insertionTimestamp": 1711571101000,
            "fundingInterval": null,
            "fundingRate": 0.00019676,
            "nextFundingRate": null,
            "nextFundingTime": 1711584000000,
            "isActualFundingRate": false
        }
    }
}
```

| Field               | Type               | Description                                                                                                                                                                 |
| :------------------ | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| exchange            | `string`           | The exchange.                                                                                                                                                               |
| instrument          | `string`           | The asset pair                                                                                                                                                              |
| timestamp           | `number`           | The time at which the funding rate took place.                                                                                                                              |
| insertionTimestamp  | `number`           | The time at which the funding rate insert to database                                                                                                                       |
| fundingInterval     | `number` \| `null` | The interval funding                                                                                                                                                        |
| fundingRate         | `number`           | The funding rate value                                                                                                                                                      |
| nextFundingRate     | `number`           | The next funding rate  for which data is available.                                                                                                                         |
| nextFundingTime     | `number` \| `null` | The next funding time for which data is available.                                                                                                                          |
| isActualFundingRate | `boolean`          | If `true`, then it's the actual funding rate that has been realized and applied. If `false`, then it's a projected/estimated funding rate for an upcoming funding interval. |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:funding_rates', {'instrument': 'BTCUSD_PERP', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Insurance Funds

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:insurance_funds", { "instrument": "EOS", "exchange": "huobi" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
"result": {
  "exchange": "huobi",
  "instrument": "EOS",
  "timestamp": 1613289600,
  "fund": 1056094
}
```

| Field      | Type     | Description                                      |
| :--------- | :------- | :----------------------------------------------- |
| exchange   | `string` | The exchange.                                    |
| instrument | `string` | The asset pair                                   |
| timestamp  | `number` | The time at which the insurance fund took place. |
| fund       | `number` | The insurance fund value                         |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:insurance_funds', {'instrument': 'EOS', 'exchange': 'huobi'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Liquidations

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:liquidations", { "instrument": "BTCUSDT", "exchange": "binance" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "bc79013c-6051-49ff-b4d5-754082bf8e47",
        "result": {
            "exchange": "binance",
            "instrument": "AEVOUSDT",
            "timestamp": 1711571204802,
            "price": 2.9643448,
            "side": "SELL",
            "status": "FILLED",
            "type": "LIMIT",
            "timeInForce": "IOC",
            "action": null,
            "orderId": null,
            "volume": 31
        }
    }
}
```

| Field       | Type     | Description                                                                                                                             |
| :---------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| exchange    | `string` | The exchange name.                                                                                                                      |
| instrument  | `string` | The instrument name.                                                                                                                    |
| timestamp   | `number` | The time at which the liquidation took place.                                                                                           |
| price       | `number` | The price at which the liquidation occurred.                                                                                            |
| side        | `string` | Indicates whether the liquidated position was a buy or sell.                                                                            |
| status      | `string` | The status of the order at the time of the message.                                                                                     |
| type        | `string` | The type of order that was liquidated.                                                                                                  |
| timeInForce | `string` | Describes how long an order will remain active before it is executed or expires.                                                        |
| action      | `string` | This field will show as `null` for all exchanges except Bitmex.                                                                         |
| orderId     |          | An identifier for the specific order that was liquidated (this field will show as `null` for most exchanges except Deribit and Bitmex). |
| volume      | `number` | The amount of the asset that was liquidated.                                                                                            |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:liquidations', {'instrument': 'XRPUSDT', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Long/Short Ratios

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:long_short_ratios", { "instrument": "XRPUSDT", "exchange": "binance", "period": "minutely" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "1a71b04a-4f9f-4638-8cb2-b0f2d9c7e51e",
        "result": {
            "exchange": "binance",
            "instrument": "BTCUSDT",
            "timestamp": 1711571100000,
            "longAccount": 0.6069,
            "ratio": 1.5439,
            "shortAccount": 0.3931,
            "period": 5
        }
    }
}
```

| Field        | Type     | Description                                                                                                                                                             |
| :----------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| exchange     | `string` | The exchange name.                                                                                                                                                      |
| instrument   | `string` | The instrument name.                                                                                                                                                    |
| timestamp    | `number` | The time at which the long/short ratio was updated.                                                                                                                     |
| longAccount  | `number` | The proportion of accounts on the long side of the futures contract.                                                                                                    |
| ratio        | `number` | The long/short ratio.                                                                                                                                                   |
| shortAccount | `number` | The proportion of accounts on the short side of the futures contract.                                                                                                   |
| period       | `number` | The frequency of the timeInterval. When `timeInterval=minutes`, the period is `5`, indicating 5 minutes. When `timeInterval=days`, the period is `1`, indicating 1 day. |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:long_short_ratios', {'instrument': 'XRPUSDT', 'exchange': 'binance', 'period': 'minutely'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## OHLCV

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:ohlcv", { "instrument": "XRPUSDT", "exchange": "binance"} ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "c17c567a-6bd0-4335-85ed-61197c845f3f",
        "result": {
            "exchange": "binance",
            "instrument": "ADAUSD_PERP",
            "timestamp": 1711570860000,
            "open": 0.6478,
            "high": 0.6478,
            "low": 0.6476,
            "close": 0.6476,
            "volume": 4075.73706105
        }
    }
}
```

| Field      | Type     | Description                                                              |
| :--------- | :------- | :----------------------------------------------------------------------- |
| exchange   | `string` | The exchange name.                                                       |
| instrument | `string` | The instrument name.                                                     |
| timestamp  | `number` | The timestamp associated with this record in UTC.                        |
| open       | `number` | The price at which the first trade occurred during the specified period. |
| high       | `number` | The highest price at which a trade took place during the period.         |
| low        | `number` | The lowest price at which a trade occurred during the period.            |
| close      | `number` | The price at which the last trade occurred during the specified period.  |
| volume     | `number` | The total quantity traded during the period.                             |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:ohlcv', {'instrument': 'XRPUSDT', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Open Interest

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:open_interests", { "instrument": "XRPUSDT", "exchange": "binance" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "e91d68fa-84c8-445b-8da4-62c9e6036b56",
        "result": {
            "exchange": "binance",
            "instrument": "BTCUSDT",
            "timestamp": 1711582494214,
            "value": "82862.305",
            "type": null
        }
    }
}
```

| Field      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| exchange   | `string` | The exchange name.                                    |
| instrument | `string` | The instrument name.                                  |
| timestamp  | `number` | The time at which the data was received.              |
| value      | `string` | The total open interest for the specified instrument. |
| type       | `string` | The type of futures contract.                         |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:open_interests', {'instrument': 'XRPUSDT', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Order Book Events

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:order:events", { "instrument": "XRPUSDT", "exchange": "binance" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "daa10b81-e434-417c-a172-a0ac73a6cb25",
        "result": {
            "exchange": "binance",
            "instrument": "BTCUSDT",
            "timestamp": 1711570943299,
            "exchangeTimestamp": 1711570943297,
            "exchangeTimestampNanoseconds": 0,
            "receivedTimestamp": 1711570943299,
            "receivedTimestampNanoseconds": 658463,
            "isBid": false,
            "data": [
                [
                    69020,
                    0.353,
                    null
                ],
                [
                    69028.7,
                    0.112,
                    null
                ],
                [
                    69030.4,
                    0.009,
                    null
                ]
            ],
            "sequence": 4292890252329
        }
    }
}
```

| Field                        | Type      | Description                                                                                      |
| :--------------------------- | :-------- | :----------------------------------------------------------------------------------------------- |
| exchange                     | `string`  | The exchange name.                                                                               |
| instrument                   | `string`  | The instrument name.                                                                             |
| timestamp                    | `number`  | The timestamp at which the order book event took place.                                          |
| exchangeTimestamp            | `number`  | The timestamp at which the event was recorded by the exchange.                                   |
| exchangeTimestampNanoseconds | `number`  | The nanosecond timestamp at which the event was recorded by the exchange.                        |
| receivedTimestamp            | `number`  | The timestamp for when the update was received by our system.                                    |
| receivedTimestampNanoseconds | `number`  | The nanosecond timestamp for when the update was received by our system.                         |
| isBid                        | `boolean` | A boolean value indicating whether the data pertains to bid orders (true) or ask orders (false). |
| data\[0]                     | `number`  | The price level of the order(s).                                                                 |
| data\[1]                     | `number`  | The quantity of the contract(s) at that price level.                                             |
| data\[2]                     | `number`  | The number of individual orders at the specified price level.                                    |
| sequence                     | `number`  | A unique identifier for the order book event.                                                    |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:order:events', {'instrument': 'XRPUSDT', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Order Book Snapshots

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:order:snapshots", { "instrument": "XRPUSDT", "exchange": "binance" } ]
}
```

| Param      | Type     | Description                                                      |
| :--------- | :------- | :--------------------------------------------------------------- |
| instrument | `string` | The asset instrument. (REQUIRED)                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. (OPTIONAL) |

### Response

```
{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
      "subscription": "8e1f5873-5023-4989-8573-2e91a6e4112c",
      "result": [
          {
              "exchange": "binance",
              "instrument": "BTCUSDT",
              "timestamp": 0,
              "exchangeTimestamp": 1711570980336,
              "isBid": false,
              "data": [
                  [
                      69135.8,
                      0.07,
                      null
                  ],
                  [
                      69136.4,
                      0.029,
                      null
                  ]
              ],
              "sequence": 4292893574687,
              "currentFunding": null
          }
      ]
  }
}
```

| Field             | Type      | Description                                                                       |
| :---------------- | :-------- | :-------------------------------------------------------------------------------- |
| exchange          | `string`  | The exchange name.                                                                |
| instrument        | `string`  | The instrument name.                                                              |
| timestamp         | `number`  | The time at which the order book snapshot took place.                             |
| exchangeTimestamp | `number`  | The timestamp at which the event was recorded by the exchange.                    |
| isBid             | `boolean` | A boolean indicator of whether the orders in the snapshot are buy (bid) orders.   |
| data\[0]          | `number`  | The price level of the order.                                                     |
| data\[1]          | `number`  | The quantity of the asset available at the specified price level.                 |
| data\[2]          | `number`  | The number of individual orders that are aggregated at the specified price level. |
| sequence          | `number`  | A unique identifier for the order book state.                                     |
| currentFunding    | `number`  | The current funding rate for perpetual futures contracts.                         |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.io/', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:order:snapshots'],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Tickers Snapshots

<Note>
  This subscription delivers 1-second snapshots. For each instrument/pair and exchange, we emit at most one update per second, using the first ticker event observed in that UTC-second. If your workflow requires event-level (tick-by-tick) tickers, they are available on our Enterprise plan. Please contact your Amberdata sales representative for details.
</Note>

### Request

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

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```json theme={null}
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "d5475b6c-552a-4ab6-903a-ba054e468ab5",
        "result": {
            "exchange": "binance",
            "instrument": "BTCUSDT",
            "exchangeTimestamp": 1711571015981,
            "exchangeTimestampNanoseconds": 0,
            "timestamp": 1711571015981,
            "bid": 69135.9,
            "ask": 69136,
            "mid": 69135.95,
            "last": null,
            "sequence": 4292896044090,
            "markPrice": 69136.1,
            "lastVolume": null,
            "bidVolume": 9.517,
            "askVolume": 0.527
        }
    }
}
```

| Field                        | Type     | Description                                                                                        |
| :--------------------------- | :------- | :------------------------------------------------------------------------------------------------- |
| exchange                     | `string` | The exchange name.                                                                                 |
| instrument                   | `string` | The instrument name.                                                                               |
| exchangeTimestamp            | `number` | The exchange provided timestamp.                                                                   |
| exchangeTimestampNanoseconds | `number` | The exchange provided nanosecond part of the `exchangeTimestamp` (if available from the exchange). |
| timestamp                    | `number` | The timestamp at which the event took place.                                                       |
| bid                          | `number` | The bid of the instrument.                                                                         |
| ask                          | `number` | The ask of the instrument.                                                                         |
| mid                          | `number` | The mid of the instrument.                                                                         |
| last                         | `number` | The last of the instrument.                                                                        |
| sequence                     | `number` | The sequence number (equal to `null` if it is not provided by the exchange).                       |
| lastVolume                   | `number` | The last volume for the instrument.                                                                |
| bidVolume                    | `number` | The order size of the best bid.                                                                    |
| askVolume                    | `number` | The order size of the best ask.                                                                    |

#### Example

```javascript theme={null}
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:tickers:snapshots', {'instrument': 'BTCUSDT', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```

## Trades

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:futures:trades", { "instrument": "XRPUSDT", "exchange": "binance" } ]
}
```

| Param      | Type     | Description                                           |
| :--------- | :------- | :---------------------------------------------------- |
| instrument | `string` | The asset instrument.                                 |
| exchange   | `string` | The exchange for which to retrieve asset instruments. |

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "1e235200-b099-457c-956d-e981605ab105",
        "result": {
            "exchange": "binance",
            "instrument": "XRPUSDT",
            "exchangeTimestamp": 1711571031275,
            "exchangeTimestampNanoseconds": 0,
            "isBuySide": false,
            "quoteSize": null,
            "price": 0.6159,
            "size": 211.4,
            "tradeId": "1443425767"
        }
    }
}
```

| Field                        | Type      | Description                                                                                  |
| :--------------------------- | :-------- | :------------------------------------------------------------------------------------------- |
| exchange                     | `string`  | The exchange name.                                                                           |
| instrument                   | `string`  | The instrument name.                                                                         |
| exchangeTimestamp            | `number`  | The timestamp at which the event was recorded by the exchange.                               |
| exchangeTimestampNanoseconds | `number`  | The nanosecond timestamp at which the event was recorded by the exchange.                    |
| isBuySide                    | `boolean` | A boolean value indicating the direction of the trade from the perspective of the initiator. |
| quoteSize                    | `number`  | The total amount of the quote asset of the instrument that was traded.                       |
| price                        | `number`  | The price at which the futures contract was traded.                                          |
| size                         | `number`  | The quantity of the contract that was traded.                                                |
| tradeId                      | `string`  | A unique identifier for this specific trade.                                                 |

#### Example

```
const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.amberdata.com/futures', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:futures:trades', {'instrument': 'XRPUSDT', 'exchange': 'binance'}],
      id: 1,
    }));
});

ws.on('message', data => {
  console.log(JSON.stringify(JSON.parse(data), null, 2));
});
```