# Market Data v2 (Archived)

:::warning
This documentation is archived for reference only. These APIs have been replaced by the [**new WebSocket API**](/websocket/introduction). **Start new integrations with the new WebSocket API.**
:::

# Market Data v2

The initial response will show the existing state of the order books and last 50 trades. Subsequent messages show all executed trades and order book changes.

## WebSocket Request

`wss://api.gemini.com/v2/marketdata`

After connecting, subscribe by sending a message:

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `subscribe` |
| `subscriptions` | array | |
| -- `name` | string | `l2`, `candles_1m`, `candles_5m`, `candles_15m`, `candles_30m`, `candles_1h`, `candles_6h`, `candles_1d` |
| -- `symbols` | array | `["BTCUSD", "ETHBTC", ...]` |

### Subscription Example

```json
{
  "type": "subscribe",
  "subscriptions": [
    {
      "name": "l2",
      "symbols": ["BTCUSD", "ETHUSD"]
    }
  ]
}
```

```python
import ssl, websocket, _thread as thread

def on_message(ws, message):
    print(message)

def on_open(ws):
    def run(*args):
        ws.send('{"type": "subscribe","subscriptions":[{"name":"l2","symbols":["BTCUSD","ETHUSD"]}]}')
    thread.start_new_thread(run, ())

ws = websocket.WebSocketApp("wss://api.gemini.com/v2/marketdata",
                            on_message=on_message,
                            on_open=on_open)
ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})
```

## Unsubscribe

```json
{
  "type": "unsubscribe",
  "subscriptions": [
    {
      "name": "l2",
      "symbols": ["BTCUSD", "ETHBTC"]
    }
  ]
}
```

---

## Level 2 Data

### L2 Update Response

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `l2_updates` |
| `symbol` | string | `BTCUSD`, etc. |
| `changes` | array of arrays | [side, price, quantity] |

### Trade Response

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `trade` |
| `symbol` | string | `BTCUSD`, etc. |
| `event_id` | long | Event ID of the trade |
| `timestamp` | long | Time in milliseconds |
| `price` | string | Price of the trade |
| `quantity` | string | Quantity traded |
| `side` | string | Taker side: `buy` or `sell` |
| `tid` | long | Trade ID |

### Examples

Initial L2 response:

```json
{
  "type": "l2_updates",
  "symbol": "BTCUSD",
  "changes": [
    ["buy", "9122.04", "0.00121425"],
    ["sell", "9122.07", "0.98942292"]
  ],
  "trades": [
    {
      "type": "trade",
      "symbol": "BTCUSD",
      "eventid": 169841458,
      "timestamp": 1560976400428,
      "price": "9122.04",
      "quantity": "0.0073173",
      "side": "sell",
      "tid": 2840140800042677
    }
  ]
}
```

L2 update:

```json
{
  "type": "l2_updates",
  "symbol": "BTCUSD",
  "changes": [["sell", "9160.20", "0.1921229751"]]
}
```

---

## Candles Data Feed

The Candle Data feed provides periodic updates with OHLCV data for the given timeframe.

### Subscribe

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `subscribe` |
| `subscriptions` | array | |
| -- `name` | string | `candles_1m`, `candles_5m`, `candles_15m`, `candles_30m`, `candles_1h`, `candles_6h`, `candles_1d` |
| -- `symbols` | array | `["BTCUSD", ...]` |

### Response

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `candles_1m_updates`, `candles_5m_updates`, etc. |
| `symbol` | string | `BTCUSD`, etc. |
| `changes` | array of arrays | [time, open, high, low, close, volume] |

```json
{
  "type": "subscribe",
  "subscriptions": [
    {
      "name": "candles_15m",
      "symbols": ["BTCUSD"]
    }
  ]
}
```

```json
{
  "type": "candles_15m_updates",
  "symbol": "BTCUSD",
  "changes": [
    [1561054500000, 9350.18, 9358.35, 9350.18, 9355.51, 2.07],
    [1561053600000, 9357.33, 9357.33, 9350.18, 9350.18, 1.5900161]
  ]
}
```

---

## Mark Price Feed

The mark price feed provides mark price updates for perpetual instruments and select spot pairs.

### Subscribe

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `subscribe` |
| `subscriptions` | array | |
| -- `name` | string | `mark_price` |
| -- `symbols` | array | `["BTCGUSDPERP", "BTCUSD", ...]` |

### Response

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `mark_price_updates` |
| `symbol` | string | `BTCGUSDPERP` |
| `changes` | array | |

Each element of `changes`:

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `timestamp` | integer | nanoseconds |
| `mark_price` | string | mark price |
| `spot_index` | string | spot index |

```json
{
  "type": "mark_price_updates",
  "symbol": "BTCGUSDPERP",
  "changes": [
    {
      "timestamp": 1673932381478308169,
      "mark_price": "21154.098",
      "spot_index": "21175.27333"
    }
  ]
}
```

---

## Funding Amount Feed

The Funding Amount feed provides funding amount updates for perpetual instruments.

### Subscribe

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `subscribe` |
| `subscriptions` | array | |
| -- `name` | string | `funding_amount` |
| -- `symbols` | array | `["BTC-GUSD-PERP", ...]` |

### Response

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `type` | string | `funding_amount_updates` |
| `symbol` | string | `BTCGUSDPERP` |
| `changes` | array | |

Each element of `changes`:

| Field Name | Type | Values |
| ---------- | ---- | ------ |
| `timestamp` | integer | nanoseconds |
| `funding_amount` | string | funding amount |
| `funding_date_time` | integer | funding date time |
| `funding_interval_in_minutes` | integer | funding interval in minutes |
| `is_realized` | boolean | is realized funding |

```json
{
  "type": "funding_amount_updates",
  "symbol": "BTCGUSDPERP",
  "changes": [
    {
      "timestamp": 1673932380007696874,
      "funding_amount": "0",
      "funding_date_time": 1673932380007696874,
      "funding_interval_in_minutes": 60,
      "is_realized": false
    }
  ]
}
```