> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcus.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Channels

> WebSocket channel reference for Arcus

| Channel                                     | Auth   | ID format                | Notes                                                                 |
| ------------------------------------------- | ------ | ------------------------ | --------------------------------------------------------------------- |
| [`l2Orderbook`](#l2orderbook)               | public | market (e.g. `BTC-PERP`) | Full snapshot every \~500 ms. `nLevels` 1–100, default 20.            |
| [`l2OrderbookUpdates`](#l2orderbookupdates) | public | market                   | Initial snapshot, then incremental updates. Same `nLevels` parameter. |
| [`trades`](#trades)                         | public | market                   | Live public trade stream; no snapshot on subscribe.                   |
| [`markets`](#markets)                       | public | *(global, no `id`)*      | Snapshot on subscribe plus per-market updates.                        |
| [`oraclePrices`](#oracleprices)             | public | market                   | Per-market oracle prices from the on-chain Slinky aggregator.         |
| [`bbo`](#bbo)                               | public | market                   | Best bid / offer (top of book).                                       |
| [`account`](#account)                       | public | Ethereum address         | Snapshot of positions, balances, margin; re-snapshots every 5 s.      |
| [`positions`](#positions)                   | public | Ethereum address         | Open positions only.                                                  |
| [`userFills`](#userfills)                   | public | Ethereum address         | Snapshot then live fills.                                             |
| [`orders`](#orders)                         | public | Ethereum address         | Open and recently closed orders (up to 100 closed in snapshot).       |
| [`candles`](#candles)                       | public | `<market>/<timeframe>`   | Up to 200-candle snapshot plus real-time updates.                     |

## l2Orderbook

Periodic full snapshots every \~500 ms.

```json theme={null}
{
  "type": "subscribe",
  "channel": "l2Orderbook",
  "id": "BTC-PERP",
  "nLevels": 20
}
```

Parameters: `nLevels` (integer 1–100, default 20).

```json theme={null}
{
  "type": "channel_data",
  "channel": "l2Orderbook",
  "id": "BTC-PERP",
  "contents": {
    "bids": [["94500.0", "1.5"]],
    "asks": [["94501.0", "0.8"]],
    "sequenceNumber": 1042
  }
}
```

## l2OrderbookUpdates

Initial snapshot followed by event-driven incremental updates with the same shape as `l2Orderbook`.

```json theme={null}
{
  "type": "subscribe",
  "channel": "l2OrderbookUpdates",
  "id": "BTC-PERP",
  "nLevels": 20
}
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "l2OrderbookUpdates",
  "id": "BTC-PERP",
  "contents": {
    "bids": [["94500.0", "1.4"]],
    "asks": [],
    "sequenceNumber": 1043
  }
}
```

## trades

Live public trade stream. No snapshot on subscribe.

```json theme={null}
{ "type": "subscribe", "channel": "trades", "id": "BTC-PERP" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "trades",
  "id": "BTC-PERP",
  "contents": {
    "tradeId": "7f3a1b9c-2a1d-4c8e-9b0f-1234567890ab",
    "price": "94500.00",
    "size": "0.25",
    "side": "BUY",
    "createdAt": 1712345678000
  }
}
```

## markets

Global channel. Subscribe with no `id`. Snapshot on subscribe plus per-market updates.

```json theme={null}
{ "type": "subscribe", "channel": "markets" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "markets",
  "contents": {
    "marketId": 0,
    "displayName": "BTC-USD",
    "oraclePrice": "94500.00",
    "indexPrice": "94498.00",
    "fundingRate": "0.0001",
    "volume24h": "890123.45"
  }
}
```

## oraclePrices

Per-market oracle prices from the on-chain Slinky aggregator.

```json theme={null}
{ "type": "subscribe", "channel": "oraclePrices", "id": "BTC-PERP" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "oraclePrices",
  "id": "BTC-PERP",
  "contents": {
    "marketId": 0,
    "oraclePrice": "94501.00",
    "timestamp": 1712345679000
  }
}
```

## bbo

Best bid and offer (top of book).

```json theme={null}
{ "type": "subscribe", "channel": "bbo", "id": "BTC-PERP" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "bbo",
  "id": "BTC-PERP",
  "contents": {
    "bidPrice": "94500.00",
    "bidSize": "1.5",
    "askPrice": "94501.00",
    "askSize": "0.8",
    "sequenceNumber": 1042
  }
}
```

## account

Account state snapshot and updates (positions, balances, margin). Re-snapshots every 5 seconds.

```json theme={null}
{ "type": "subscribe", "channel": "account", "id": "0xAbCd...1234" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "account",
  "id": "0xAbCd1234",
  "contents": {
    "type": "ORDER",
    "freeCollateral": "10000.00"
  }
}
```

## positions

Open positions only.

```json theme={null}
{ "type": "subscribe", "channel": "positions", "id": "0xAbCd...1234" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "positions",
  "id": "0xAbCd1234",
  "contents": {
    "isSnapshot": true,
    "positions": [
      { "marketId": 0, "side": "LONG", "size": "0.1" }
    ]
  }
}
```

## userFills

Per-user fill stream. Snapshot on subscribe, then live updates.

```json theme={null}
{ "type": "subscribe", "channel": "userFills", "id": "0xAbCd...1234" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "userFills",
  "id": "0xAbCd1234",
  "contents": {
    "isSnapshot": false,
    "tradeId": "f1-2-3-4-5-6-7-8-9-0a",
    "orderId": "ord-99",
    "market": "BTC-PERP",
    "side": "BUY",
    "fillPrice": "50000.00",
    "fillSize": "0.01"
  }
}
```

## orders

Open and recently closed orders (up to 100 closed orders in snapshot).

```json theme={null}
{ "type": "subscribe", "channel": "orders", "id": "0xAbCd...1234" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "orders",
  "id": "0xAbCd1234",
  "contents": {
    "orderId": "ord-1",
    "clientId": "c1",
    "marketId": 0,
    "side": "BUY",
    "status": "OPEN",
    "price": "50000.00",
    "remainingSize": "0.5",
    "statusTimestamp": 1712345678000
  }
}
```

Order statuses: `OPEN`, `FILLED`, `CANCELED`, `MARGIN_CANCELED`, `REJECTED`, `TPSL_PLACED`, `TPSL_CANCELED`, `TPSL_TRIGGERED`.

## candles

OHLCV candlesticks. Snapshot of up to 200 candles plus real-time updates. Subscription `id` is `<market>/<timeframe>`.

Available timeframes: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`.

```json theme={null}
{ "type": "subscribe", "channel": "candles", "id": "BTC-PERP/1m" }
```

```json theme={null}
{
  "type": "channel_data",
  "channel": "candles",
  "id": "BTC-PERP/1m",
  "contents": {
    "marketDisplayName": "BTC-PERP",
    "marketId": 0,
    "timeframe": "1m",
    "openTime": 1712345640000,
    "open": "94500.00",
    "high": "94510.00",
    "low": "94490.00",
    "close": "94505.00",
    "volume": "12.34",
    "takerBuyVolume": "7.50",
    "tradeCount": 42,
    "isFinal": false
  }
}
```