---
# System prepended metadata

title: Untitled

---


## Websockets 2.0 Beta


:::danger
Documentation now hosted at https://docs.kraken.com/websockets-v2/ 
:::

:::info
Last updated: 6 Oct 2021
:::

[TOC]

### Notes


#### Connecting

:::success
The beta Websockets v2 endpoints can be reached via `wss://beta-ws.kraken.com/v2` (public market data) and `wss://beta-ws-auth.kraken.com/v2` (private data and trading). 
:::

When released to production, the v2 code will remain accessible via this `/v2` path in parallel to the existing v1 code (same URL `wss://beta-ws.kraken.com`), allowing clients to migrate over time. Apart from critical bug fixes, all future enhancements and changes will take place only on `/v2` until the old code is deprecated entirely.

:::warning
The beta endpoints should be used for testing and feedback, and not relied upon solely for trading. They may be redeployed, repurposed or brought offline without warning.
:::

#### Description

* Timestamps are RFC3339 format (e.g. `2021-05-11T19:47:09.896860Z`) to be both machine readable and human readable.
* Payloads are normalised JSON objects with no/minimal positional or variable length fields, to allow for maximum future flexibility without breaking client code.
* Websockets v2 aims to incorporate a number of bug fixes and to clean up many idiosyncrasies and ambiguities from v1, requiring breaking changes, such that integrating with the API from scratch is a much easier and more pleasant experience.

#### `Method` (Request/Response)
* Requests are made for a particular `method`, with the required `params` for that method specified by the client.
* All requests accept a client-specified integer request ID (`req_id`) for matching up the response, when received.
    * Note: Uniqueness of the `req_id` is not enforced.
* All responses include both `time_in` and `time_out` to reflect when our Websockets server recieved the request and sent the response, to help further isolate and measure network/client/server latency.
* `success` indicates if the request was handled successfully. `result` includes details of the response, if applicable. Otherwise `error`, if present, gives details of what error occurred.
* `method` can be considered as analagous to and consistent with a specific combination of REST endpoint and HTTP method in a future improved REST API. (e.g. Websockets v2 `cancel_order` will correspond to a REST v2 `DELETE /api/order`, etc.)

#### `Channel` (Snapshot/Update)
* Channel messages include a `data` payload specific to that channel, and either provide a `snapshot` of or `update` to data, depending on the `type` of the channel message.

### Updates
- 11 May 2021: Initial docs for `ticker`, `trade`
- 27 June 2021: Added details for `instrument`, `book`
- 6 Oct 2021: `trade_id` now active on `trade` channel. Added `balances` channel.

### Known Issues
- [x] ~~`ticker`: `volume` should be 24-hour volume, not last trade.~~
- [x] ~~`trade`: `trade_id` is a placeholder (0) and not yet implemented. This will be a monotonically increasing integer unique by symbol.~~
- [x] ~~Only the 'new' style is accepted for recently updated tickers (e.g. XBT/USD vs. BTC/USD and XDG/USD vs. DOGE/USD) even though these aren't queryable by REST API, etc.~~ Assets/pairs now available on `instrument` channel
- [ ] Some inactive assets/pairs are still showing on `instrument` channel 

### Methods


#### subscribe

* Subscriptions to a particular channel can be made for multiple symbols at once, but are confirmed and responded to individually

##### Example Request

```yaml
{
  "method": "subscribe",
  "params": {
    "channel": "ticker",
    "snapshot": true,
    "symbol": [
      "ETH/USD"
    ]
  },
  "req_id": 1620770462625
}
```

##### Example Response (Success)

```yaml
{
  "method": "subscribe",
  "req_id": 1620770462625,
  "result": {
    "channel": "trade",
    "snapshot": false,
    "symbol": "ETH/USD"
  },
  "success": true,
  "time_in": "2021-05-11T21:42:06.095369Z",
  "time_out": "2021-05-11T21:42:06.095420Z"
}
```

##### Example Response (Failure)

```yaml
{
  "error": "Already subscribed",
  "method": "subscribe",
  "req_id": 1620770462625,
  "success": false,
  "time_in": "2021-05-11T21:42:24.807559Z",
  "time_out": "2021-05-11T21:42:24.807597Z"
}
```

#### unsubscribe

##### Example Response (Success)

```yaml
{
  "method": "unsubscribe",
  "req_id": 1620768449862,
  "result": {
    "channel": "trade",
    "symbol": "ETH/USD"
  },
  "success": true,
  "time_in": "2021-05-11T21:52:23.806133Z",
  "time_out": "2021-05-11T21:52:23.806174Z"
}
```




#### ping

##### Example Request

```yaml
{"method":"ping"}
```

##### Example Response

```json
{
  "method": "pong",
  "time_in": "2021-05-11T21:54:01.138830Z",
  "time_out": "2021-05-11T21:54:01.138848Z"
}
```

### Channels

#### Instrument
* `instrument` gives a snapshot of all active assets and tradeable pairs, along with the relevant trading parameters and rules (precisions, minimums, etc)
* In the future, it will also implement updates to trading parameters and status in real-time 

##### Subscription params

| param  | required | type             | description | example |
| ------ | --| ---------------- | ----------- | ------- |
| channel | yes | string | channel name | instrument |
| snapshot | no | boolean        | default false | true |

##### Subscribe Request
```yaml
{
  "method": "subscribe",
  "params": {
    "channel": "instrument",
    "snapshot": true
  },
  "req_id": 1624858826970
}
```

##### Subscribe Response

```yaml
{
  "method": "subscribe",
  "req_id": 1624858826970,
  "result": {
    "channel": "instrument",
    "snapshot": true
  },
  "success": true,
  "time_in": "2021-06-28T05:40:27.204252Z",
  "time_out": "2021-06-28T05:40:27.204283Z"
}
```

##### Payload (assets)

| field      | required | type   | description                        | example         |
| ---------- | -------- | ------ | ---------------------------------- | --------------- |
| id | yes | string | Asset ID | BTC |
| status | yes | string | Status of asset (online, maintenance) | online |
| precision | yes | integer | Maximum precision for asset ledger, balances | 10 |
| precision_display | yes | integer | Recommended display precision | 5 |
| collateral_value | no | float | Valuation as margin collateral (if applicable) | 0.50 |


##### Payload (pairs)

| field      | required | type   | description                        | example         |
| ---------- | -------- | ------ | ---------------------------------- | --------------- |
| symbol | yes | string | Pair symbol for subscriptions, etc | BTC/USD |
| base | yes | string | Asset ID of base curency | BTC |
| quote | yes | string | Asset ID of quote curency | USD |
| status | yes | string | Status of pair (online, maintenance, etc.) | online |
| qty_precision | yes | integer | Maximum precision used for order quantities | 8 |
| qty_min | yes | float | Minimum quantity (in base ccy) for new orders | 0.0001 |
| qty_increment | yes | float | Minimum quantity increment for new orders | 0.00000001 
| price_precision | yes | integer | Maximum precision used for order quantities | 5 |
| price_increment | yes | float | Minimum price increment for new orders | 0.1 |
| marginable | yes | bool | Whether the pair can be traded on margin | true |
| margin_initial | no | float | Initial margin requirement (in %, if marginable) | 0.20 |
| has_index | yes | bool | Whether the pair has an index available for e.g. stop-loss triggers | true |

##### Snapshot

```yaml
{
  "channel": "instrument",
  "type": "snapshot",
  "data": {
    "assets": [
      {
        "id": "USD",
        "status": "online",
        "precision": 4,
        "precision_display": 2,
        "collateral_value": 1
      },
      {
        "id": "EUR",
        "status": "online",
        "precision": 4,
        "precision_display": 2,
        "collateral_value": 1
      },
      {
        "id": "BTC",
        "status": "online",
        "precision": 10,
        "precision_display": 5,
        "collateral_value": 1
      },
      {
        "id": "LTC",
        "status": "online",
        "precision": 10,
        "precision_display": 5
      },
      {
        "id": "XTZ",
        "status": "online",
        "precision": 8,
        "precision_display": 6,
        "collateral_value": 0.5
      }
    ],
    "pairs": [
      {
        "symbol": "EUR/USD",
        "base": "EUR",
        "quote": "USD",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 5,
        "qty_increment": 0.00000001,
        "price_precision": 5,
        "price_increment": 0.00001,
        "marginable": false
      },
      {
        "symbol": "BTC/USD",
        "base": "BTC",
        "quote": "USD",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 0.0001,
        "qty_increment": 0.00000001,
        "price_precision": 5,
        "price_increment": 0.1,
        "marginable": true,
        "margin_initial": 0.2
      },
      {
        "symbol": "BTC/EUR",
        "base": "BTC",
        "quote": "EUR",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 0.0001,
        "qty_increment": 0.00000001,
        "price_precision": 5,
        "price_increment": 0.1,
        "marginable": true,
        "margin_initial": 0.2
      },
      {
        "symbol": "LTC/USD",
        "base": "LTC",
        "quote": "USD",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 0.03,
        "qty_increment": 0.00000001,
        "price_precision": 5,
        "price_increment": 0.01,
        "marginable": true,
        "margin_initial": 0.33
      },
      {
        "symbol": "LTC/EUR",
        "base": "LTC",
        "quote": "EUR",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 0.03,
        "qty_increment": 0.00000001,
        "price_precision": 5,
        "price_increment": 0.01,
        "marginable": true,
        "margin_initial": 0.33
      },
      {
        "symbol": "XTZ/BTC",
        "base": "XTZ",
        "quote": "BTC",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 1,
        "qty_increment": 0.00000001,
        "price_precision": 8,
        "price_increment": 1e-7,
        "marginable": true,
        "margin_initial": 0.5
      },
      {
        "symbol": "XTZ/USD",
        "base": "XTZ",
        "quote": "USD",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 1,
        "qty_increment": 0.00000001,
        "price_precision": 6,
        "price_increment": 0.0001,
        "marginable": true,
        "margin_initial": 0.33
      },
      {
        "symbol": "XTZ/EUR",
        "base": "XTZ",
        "quote": "EUR",
        "status": "online",
        "qty_precision": 8,
        "qty_min": 1,
        "qty_increment": 0.00000001,
        "price_precision": 6,
        "price_increment": 0.0001,
        "marginable": true,
        "margin_initial": 0.33
      }
    ]
  }
}
```

#### Ticker

* `ticker` pushes updates whenever there is a trade or there is a change (price or quantity) at the top-of-book
* Snapshots reflect the current state of the market.

##### Subscription params

| param  | required | type             | description | example |
| ------ | --| ---------------- | ----------- | ------- |
| channel | yes | string | channel name | ticker |
| symbol | yes | string[] | symbols to subscribe to | ["ETH/USD", "BTC/USD"] |
| snapshot | no | boolean        | default false | true |


<!-- ##### Wildcard Ticker Sub  -->

##### Subscribe Request
```yaml
{
  "method": "subscribe",
  "params": {
    "channel": "ticker",
    "snapshot": true,
    "symbol": [
      "ETH/USD"
    ]
  },
  "req_id": 1620762429391
}
```

##### Subscribe Response

```yaml
{
  "method": "subscribe",
  "req_id": 1620762429391,
  "result": {
    "channel": "ticker",
    "snapshot": true,
    "symbol": "ETH/USD"
  },
  "success": true,
  "time_in": "2021-05-11T19:47:09.896860Z",
  "time_out": "2021-05-11T19:47:09.896902Z"
}
```

##### Payload

| field      | required | type   | description                        | example         |
| ---------- | -------- | ------ | ---------------------------------- | --------------- |
| symbol     | yes      | string | relevant symbol                    | "ETH/USD"       |
| bid_qty    | yes      | float  | best (top-of-book) bid quantity    | 0.55452781      |
| bid        | yes      | float  | best (top-of-book) bid             | 4047.83         |
| ask        | yes      | float  | best (top-of-book) ask             | 4048.82         |
| ask_qty    | yes      | float  | best (top-of-book) ask quantity    | 8.3             |
| last       | yes      | float  | last traded price                  | 4047.82         |
| volume     | yes      | float  | 24-hour traded volume (in base ccy terms)              | 154841.48767793 |
| change     | yes      | float  | 24-hour price change (in quote ccy terms)   | 98.55           |
| change_pct | yes      | float  | 24-hour price change (in pct. points) | 2.5             |

##### Snapshot

```yaml
{
  "channel": "ticker",
  "type": "snapshot",
  "data": [
    {
      "symbol": "ETH/USD",
      "bid": 4047.83,
      "bid_qty": 0.55452781,
      "ask": 4048.82,
      "ask_qty": 8.3,
      "last": 4047.82,
      "volume": 154841.48767793,
      "change": 98.55,
      "change_pct": 2.5
    }
  ]
}
```

##### Update
```yaml
{
  "channel": "ticker",
  "type": "update",
  "data": [
    {
      "symbol": "ETH/USD",
      "bid": 4056.4,
      "bid_qty": 26.79,
      "ask": 4056.75,
      "ask_qty": 0.4,
      "last": 4056.41,
      "volume": 155478.39083986,
      "change": 107.14,
      "change_pct": 2.71
    }
  ]
}
```

#### Trade

* `trade` pushes trades in real-time. Multiple trades may be batched in a single message but that does not necessarily mean that all of the trades in a single message resulted from a single taker order.
* Snapshots reflect the most recent 100 trades.

##### Subscription params

| param  | required | type             | description | example |
| ------ | --| ---------------- | ----------- | ------- |
| channel | yes | string | channel name | trade |
| symbol | yes | string[] | symbols to subscribe to | ["ETH/USD", "BTC/USD"] |
| snapshot | no | boolean        | default false | true |


##### Subscribe Request
```yaml
{
  "method": "subscribe",
  "params": {
    "channel": "trade",
    "snapshot": false,
    "symbol": [
      "ETH/USD"
    ]
  },
  "req_id": 1620762429417
}
```

##### Subscribe Response
```yaml
{
  "method": "subscribe",
  "req_id": 1620762429417,
  "result": {
    "channel": "trade",
    "snapshot": false,
    "symbol": "ETH/USD"
  },
  "success": true,
  "time_in": "2021-05-11T19:47:09.918548Z",
  "time_out": "2021-05-11T19:47:09.918580Z"
}
```

##### Payload

| field    | required | type    | description                     | example    |
| -------- | -------- | ------- | ------------------------------- | ---------- |
| symbol   | yes      | string  | relevant symbol                 | "ETH/USD"  |
| side     | yes      | string  | taker order direction           | "sell"     |
| price    | yes      | float   | execution price                 | 4136.4     |
| qty      | yes      | float   | execution quantity              | 0.23374249 |
| ord_type | yes      | string  | taker order type                | "market"   |
| trade_id | yes      | integer | unique trade ID for this symbol | 1234       |
| timestamp         |yes|string| timestamp (RFC3339) of trade | "2021-05-11T21:42:09.891627Z"|

##### Update
```yaml
{
  "channel": "trade",
  "type": "update",
  "data": [
    {
      "symbol": "ETH/USD",
      "side": "sell",
      "price": 4136.4,
      "qty": 0.23374249,
      "ord_type": "market",
      "trade_id": 0,
      "timestamp": "2021-05-11T21:42:09.891627Z"
    },
    {
      "symbol": "ETH/USD",
      "side": "sell",
      "price": 4136.4,
      "qty": 0.00060615,
      "ord_type": "market",
      "trade_id": 0,
      "timestamp": "2021-05-11T21:42:09.896920Z"
    },
    {
      "symbol": "ETH/USD",
      "side": "sell",
      "price": 4136.4,
      "qty": 0.00000136,
      "ord_type": "market",
      "trade_id": 0,
      "timestamp": "2021-05-11T21:42:09.898804Z"
    }
  ]
}
```


#### Book

* `book` pushes order book snapshots and real-time updates. 
* Subscriptions can be requested for multiple books at one time, but will be confirmed and have their snapshots, etc. sent individually.

##### Maintaining the book
* All book updates in a message should be processed before the book is considered updated and the checksum confirmed. Update messages may contain updates to either the bids and/or asks.
* An update with `"qty": 0` indicates that price level should be removed from your book.
* Additionally, after each update, the book should be truncated to your subscribed depth as you won't receive `"qty": 0` for price levels that fall out of scope. (i.e. if you are subscribed with `"depth": 10` and an insert into the middle of the book results in you having 11 bids, you must remove the 11th worst bid) 
* Checksum logic is the same as in [v1](https://docs.kraken.com/websockets/#book-checksum). Prices and quantities are now sent as floats -- for the checksum input string, they can be formatted to `price_precision` and `qty_precision` precisions (from the `instrument` channel).


##### Subscription params

| param  | required | type             | description | example |
| ------ | --| ---------------- | ----------- | ------- |
| channel | yes | string | channel name | book |
| symbol | yes | string[] | symbols to subscribe to | ["ETH/USD", "BTC/USD"] |
| snapshot | no | boolean        | default true | true |
| depth | no | integer | book depth for subscription (10, 25, 100, 500 or 1000; default 10) | 10 |


##### Subscribe Request
```yaml
{
  "method": "subscribe",
  "params": {
    "channel": "book",
    "snapshot": true,
    "symbol": [
      "BTC/USD"
    ],
    "depth": 10
  },
  "req_id": 1624864967044
}
```

##### Subscribe Response
```yaml
{
  "method": "subscribe",
  "req_id": 1624864967044,
  "result": {
    "channel": "book",
    "depth": 10,
    "snapshot": true,
    "symbol": "BTC/USD"
  },
  "success": true,
  "time_in": "2021-06-28T07:22:47.442255Z",
  "time_out": "2021-06-28T07:22:47.442287Z"
}
```

##### Payload

| field    | required | type    | description                     | example    |
| -------- | -------- | ------- | ------------------------------- | ---------- |
| symbol   | yes      | string  | relevant symbol                 | "ETH/USD"  |
| bids     | yes      | []{"price" (float), "qty" (float)}  | bids           | [see below]     |
| asks    | yes      | []{"price" (float), "qty" (float)}   | asks                 | [see below]     |
| checksum      | yes      | int   | CRC32 result of checksum for 10 best bids/asks              | 87331041 |
| timestamp         |no|string| timestamp (RFC3339) of order book update (not present for snapshots) | "2021-05-11T21:42:09.891627Z"|

##### Snapshot

```yaml
{
  "channel": "book",
  "type": "snapshot",
  "data": [
    {
      "symbol": "BTC/USD",
      "bids": [
        {
          "price": 34717.6,
          "qty": 0.13
        },
        {
          "price": 34714.1,
          "qty": 0.08572098
        },
        {
          "price": 34713.9,
          "qty": 0.38
        },
        {
          "price": 34712.6,
          "qty": 0.028808
        },
        {
          "price": 34711.8,
          "qty": 0.86
        },
        {
          "price": 34710.2,
          "qty": 1.67978564
        },
        {
          "price": 34710,
          "qty": 0.71990644
        },
        {
          "price": 34709.3,
          "qty": 0.26085746
        },
        {
          "price": 34707.9,
          "qty": 0.16037166
        },
        {
          "price": 34707.8,
          "qty": 0.05682871
        }
      ],
      "asks": [
        {
          "price": 34726.4,
          "qty": 0.25
        },
        {
          "price": 34727.7,
          "qty": 0.21
        },
        {
          "price": 34727.8,
          "qty": 0.05
        },
        {
          "price": 34731.6,
          "qty": 0.3459
        },
        {
          "price": 34731.7,
          "qty": 0.07103557
        },
        {
          "price": 34731.9,
          "qty": 0.28802536
        },
        {
          "price": 34733,
          "qty": 0.72004074
        },
        {
          "price": 34736.2,
          "qty": 0.31988209
        },
        {
          "price": 34738,
          "qty": 0.143
        },
        {
          "price": 34739,
          "qty": 0.24041
        }
      ],
      "checksum": 87331041
    }
  ]
}
```

##### Update
```yaml
{
  "channel": "book",
  "type": "update",
  "data": [
    {
      "symbol": "BTC/USD",
      "bids": [],
      "asks": [
        {
          "price": 34726.4,
          "qty": 0
        },
        {
          "price": 34739.7,
          "qty": 2.1541
        }
      ],
      "checksum": 4022926185,
      "timestamp": "2021-06-28T07:22:47.907236Z"
    }
  ]
}
```


#### Status

* Sent upon connection and upon change to our system/trading status (`online`, `maintenance`, `cancel_only`, `post_only`)

##### Update

```yaml
{
  "channel": "status",
  "data": [
    {
      "api_version": "v2",
      "connection_id": 17182357368067543000,
      "system": "online",
      "version": "1.8.5"
    }
  ],
  "type": "update"
}
```

#### Balances

* `balances` snapshots reflect the client's current balances upon subscription.
* Updates are pushed whenever a ledger entry occurs which affects balances.

##### Subscription params

| param  | required | type             | description | example |
| ------ | --| ---------------- | ----------- | ------- |
| channel | yes | string | channel name | balances |
| snapshot | no | boolean        | default true | true |
| token | yes | string | auth token | GHbx1ofu1qeBQMjhrsvTrofPBULz16eZF1RthFil5ig |


<!-- ##### Wildcard Ticker Sub  -->

##### Subscribe Request
```yaml
{
  "method": "subscribe",
  "params": {
    "channel": "balances",
    "snapshot": true,
    "token": "GHbx1ofu1qeBQMjhrsvTrofPBULz16eZF1RthFil5ig"
  },
  "req_id": 1620762429391
}
```

##### Subscribe Response

```yaml
{
  "method": "subscribe",
  "req_id": 1620762429391,
  "result": {
    "channel": "balances",
    "snapshot": true
  },
  "success": true,
  "time_in": "2021-05-11T19:47:09.896860Z",
  "time_out": "2021-05-11T19:47:09.896902Z"
}
```

##### Payload

| field      | required | type   | description                        | example         |
| ---------- | -------- | ------ | ---------------------------------- | --------------- |
| asset      | yes      | string | asset symbol                       | "ETH"           |
| balance    | yes      | float  | current asset balance              | 0.55452781      |
|  |  |  |  |  |
|  |  |  |  |  |
|  |  |  |  |  |
|  |  |  |  |  |
|  |  |  |  |  |
|  |  |  |  |  |

##### Snapshot

```yaml
{
  "channel": "balances",
  "data": [
    {
      "asset": "USD",
      "balance": 178621.9727
    },
    {
      "asset": "EUR",
      "balance": 499817.627
    },
    {
      "asset": "BTC",
      "balance": 1007.51595838
    },
    {
      "asset": "XRP",
      "balance": 100000
    },
    {
      "asset": "LTC",
      "balance": 1991.54655875
    },
    {
      "asset": "ETH",
      "balance": 1000
    },
    {
      "asset": "DOT.S",
      "balance": 269.13613236
    }
  ],
  "type": "snapshot",
  "sequence": 2
}
```

##### Update
```yaml
{
  "channel": "balances",
  "type": "update",
  "data": [
    {
      "ledger_id": "LEINIA-7VA4A-KKUURP",
      "ref_id": "TV55SY-DKOPF-CVSX3Y",
      "timestamp": "2021-10-07T01:31:50.604869Z",
      "type": "trade",
      "asset": "USD",
      "amount": 20000,
      "fee": 32,
      "balance": 198587.4097
    }
  ],
  "sequence": 5
}
```