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

# Spot

> Real-time market data for spot trading.

## OHLCV

### Request

```
{
  "jsonrpc" : "2.0",
  "id"      : 1,
  "method"  : "subscribe",
  "params"  : [ "market:spot:ohlcv", { "pair": "btc_usd", "exchange": "gdax" } ]
}
```

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

### Response

```
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "bff1a804-1cd6-48c7-ac7f-9e7242a3cdf3",
        "result": {
            "exchange": "gdax",
            "pair": "btc_usd",
            "timestamp": 1711570440000,
            "open": 68892.28,
            "high": 68925.5,
            "low": 68878.72,
            "close": 68904.59,
            "volume": 6.97651585
        }
    }
}
```

| Field     | Type     | Description                                                              |
| :-------- | :------- | :----------------------------------------------------------------------- |
| exchange  | `string` | The exchange name.                                                       |
| pair      | `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/spot', {headers: {x-api-key:'<api_key>'}});

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ['market:spot:ohlcv', {'pair': 'btc_usd', 'exchange': 'gdax'}],
      id: 1,
    }));
});

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

## Order Book Events

### Request

All exchanges:

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["market:spot:order:events",{"pair":"btc_usd"}]}
```

Specific exchange:

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["market:spot:order:events",{"pair":"btc_usd","exchange":"gdax"}]}
```

| Param    | Type     | Description                                     |
| :------- | :------- | :---------------------------------------------- |
| pair\*   | `string` | The asset pair.                                 |
| exchange | `string` | The exchange for which to retrieve asset pairs. |

\**required*

*Note*: Subscription response will include a field `metadata` which includes the names of the columns in the order in which they appeared in the event notification response.

### Response

```json theme={null}
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "0f46d7af-3c49-4f2d-8e20-711efb9dc49a",
        "result": [
            [
                "gdax",
                "btc_usd",
                1711570660806,
                782000,
                68894.26,
                0.01136045,
                false,
                480582155806700
            ]
        ]
    }
}
```

| Field                | Type     | Description                                                                         |
| :------------------- | :------- | :---------------------------------------------------------------------------------- |
| exchange             | `string` | The exchange name.                                                                  |
| pair                 | `string` | The pair name.                                                                      |
| timestamp            | `number` | The time at which the order book event took place.                                  |
| timestampNanoseconds | `number` | The nano second part of the `timestampMilliseconds`, where applicable.              |
| price                | `number` | The quote price of the asset pair.                                                  |
| volume               | `number` | The number of assets traded in a specific asset pair within a given period of time. |
| isBid                | `bool`   | Indicates if it is a bid or ask order: `true` for a bid and `false` for an ask.     |
| sequence             | `number` | A unique identifier for the order book event.                                       |

#### Example

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

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ["market:spot:order:events",  {"pair": "btc_usd", "exchange": "gdax"}],
      id: 1,
    }));
});

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

## Order Book Snapshots

### Request

All exchanges:

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["market:spot:order:snapshots",{"pair":"btc_usd"}]}
```

Specific exchange:

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["market:spot:order:snapshots",{"pair":"btc_usd","exchange":"gdax"}]}
```

| Param    | Type     | Description                                     |
| :------- | :------- | :---------------------------------------------- |
| pair\*   | `string` | The asset pair.                                 |
| exchange | `string` | The exchange for which to retrieve asset pairs. |

\**required*

*Note*: Subscription response will include a field `metadata` which includes the names of the columns in the order in which they appeared in the event notification response.

### Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "subscription",
  "params": {
      "subscription": "b6491c56-3660-47f3-896c-0890a551d42c",
      "result": [
          {
              "exchange": "gdax",
              "instrument": "btc_usd",
              "timestamp": 1711570680000,
              "exchangeTimestamp": 1711570680436,
              "isBid": false,
              "data": [
                  [
                      68886.37,
                      0.02257637,
                      1
                  ],
                  [
                      68886.85,
                      0.01000001,
                      1
                  ],
                  [
                      68887.58,
                      0.04482475,
                      1
                  ]
              ],
              "sequence": 76615491457
          }
      ]
  }
}
```

| Field             | Type     | Description                                                                         |
| :---------------- | :------- | :---------------------------------------------------------------------------------- |
| exchange          | `string` | The exchange name.                                                                  |
| instrument        | `string` | The pair name.                                                                      |
| timestamp         | `number` | The time at which the order book snapshot took place.                               |
| exchangeTimestamp | `number` | The timestamp from the exchange.                                                    |
| isBid             | `bool`   | Indicates if it is a bid or ask order: `true` for a bid and `false` for an ask.     |
| data.price        | `number` | The quote price of the asset pair.                                                  |
| data.volume       | `number` | The number of assets traded in a specific asset pair within a given period of time. |
| data.numOrders    | `number` | The number of orders aggregated at this price level.                                |
| sequence          | `string` | A unique identifier associated with this snapshot.                                  |

#### Example

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

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ["market:spot:order:snapshots",  {"pair": "btc_usd", "exchange": "gdax"}],
      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:spot:tickers:snapshots", { "pair": "btc_usdt", "exchange": "binance" } ]
}
```

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

### Response

```json JSON theme={null}
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "ac936208-0c53-4c0a-9bc4-63188a61eb7e",
        "result": {
            "exchange": "binance",
            "pair": "btc_usdt",
            "exchangeTimestamp": 1712238263524,
            "exchangeTimestampNanoseconds": 780195,
            "timestamp": 1712238263524,
            "bid": 67427.98,
            "ask": 67427.99,
            "mid": 67427.985,
            "last": null,
            "sequence": 45375530797,
            "lastVolume": null,
            "bidVolume": 3.25905,
            "askVolume": 2.17779,
            "open24H": null,
            "low24H": null,
            "high24H": null
        }
    }
}
```

| Field                        | Type     | Description                                                                                         |
| :--------------------------- | :------- | :-------------------------------------------------------------------------------------------------- |
| exchange                     | `string` | The exchange.                                                                                       |
| pair                         | `string` | The asset pair.                                                                                     |
| exchangeTimestamp            | `number` | The exchange provided timestamp at which the trade took place.                                      |
| exchangeTimestampNanoseconds | `number` | The exchange provided nano second part of the `exchangeTimestamp` (if available from the exchange). |
| timestamp                    | `number` | The timestamp.                                                                                      |
| bid                          | `number` | The bid of the pair.                                                                                |
| ask                          | `number` | The ask of the pair.                                                                                |
| mid                          | `number` | The mid of the pair.                                                                                |
| last                         | `number` | The last of the pair.                                                                               |
| sequence                     | `number` | The sequence number (equal to `null` if it is not provided by the exchange).                        |
| lastVolume                   | `number` | The last volume.                                                                                    |
| bidVolume                    | `number` | Best bid volume.                                                                                    |
| askVolume                    | `number` | Best ask volume.                                                                                    |
| open24H                      | `number` | The 24 hour open.                                                                                   |
| low24H                       | `number` | The 24 hour low.                                                                                    |
| high24H                      | `number` | The 24 hour high.                                                                                   |

#### Example

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

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

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

## Trades

### Request

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"subscribe","params":["market:spot:trades",{"pair":"btc_usd","exchange":"gdax"}]}
```

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

*Note*: Subscription response will include a field `metadata` which includes the names of the columns in the order in which they appeared in the event notification response.

### Response

```json theme={null}
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "subscription": "6ad60ce3-0738-452e-a6e9-6ce73b61e90d",
        "result": [
            [
                "gdax",
                "btc_usd",
                1712238290888,
                589000,
                "626365469",
                67431.41,
                0.10287182,
                false
            ]
        ]
    }
}
```

| Field                | Type     | Description                                                                            |
| :------------------- | :------- | :------------------------------------------------------------------------------------- |
| exchange             | `string` | The exchange.                                                                          |
| pair                 | `string` | The normalized pair name.                                                              |
| timestamp            | `number` | The time at which the trade took place.                                                |
| timestampNanoseconds | `number` | The nano second part of the `timestampMilliseconds`, where applicable.                 |
| tradeId              | `string` | The unique id given by an exchange.                                                    |
| price                | `number` | The quote price of the asset pair.                                                     |
| volume               | `number` | The number of assets traded in a specific asset pair within a given period of time.    |
| isBuy                | `bool`   | Indicates if it is a buy or sell trade: `true` for a buy trade and `false` for a sell. |

#### Example

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

ws.on('open', () => {
  ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method: 'subscribe',
      params: ["market:spot:trades",  {"pair": "btc_usd", "exchange": "gdax"}],
      id: 1,
    }));
});

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