## 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
}
```
Sign in with Wallet
Connect another wallet