> ## 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));
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.