NAV
json

Introduction

WebSockets application programming interface (API) offers real-time market data updates. WebSockets is a bidirectional protocol offering the fastest real-time data, helping you build real-time applications.

The public message types presented below do not require authentication.

Private-data messages can be subscribed to on a separate authenticated endpoint.

Your use of the Kraken WebSockets API is subject to the Kraken Terms & Conditions, Privacy Notice, as well as all other applicable terms and disclosures made available on www.kraken.com.

General Considerations

Normal operation
Attempt reconnection instantly up to a handful of times if the websocket is dropped randomly.
After maintenance or extended downtime
Attempt to reconnect no more quickly than once every five (5) seconds.
There is no advantage to reconnecting more rapidly after maintenance during `cancel_only` mode.

Endpoints

The WebSockets v2 endpoints can be reached via two endpoints.

Public Market Data

wss://ws.kraken.com/v2

Private Market Data

wss://ws-auth.kraken.com/v2

Authentication

The API client must request an authentication "token" via the following REST API endpoint GetWebSocketsToken to connect to WebSockets Private endpoints. The token should be used within 15 minutes of creation. The token does not expire once a connection to a WebSockets API private-data message (feed) is maintained.

Endpoint Uniform Resource Locator (URL): https://api.kraken.com/0/private/GetWebSocketsToken

The resulting token must be provided in the "token" field of any WebSockets API private-data message (feed) subscription.

Data Format Notes

Timestamps using the 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.

Methods

method can be considered as analogous 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.)

Requests

Requests are made for a particular method, with the required params for that method specified by the client.

All requests accept an optional client-specified integer request identifier (req_id) for matching up the response, when returned.

Note: Uniqueness of the req_id is not enforced.

Responses

All responses include both time_in and time_out to reflect when our Websockets server received the request and sent the response, to help further isolate and measure network/client/server latency.

success indicates if the request was handled successfully.

resultincludes details of the response, if applicable.

error, if present, gives details of what error occurred.

Channels (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.

Public Messages

Messages without the need of authentication.

Ping

Example Ping Request

{
  "method": "ping"
}

Example Ping (Pong) Response

{
  "method": "pong",
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Ping (Pong) Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "method": {
      "const": "pong",
      "type": "string"
    },
    "time_in": {
      "type": "string"
    },
    "time_out": {
      "type": "string"
    }
  },
  "required": [
    "method",
    "time_in",
    "time_out"
  ],
  "title": "Ping (pong) response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

Clients can ping server to determine whether connection is alive; the server responds with pong. This is an application level ping, distinct from the protocol-level ping in the WebSockets standard, the latter of being server-initiated.

Request Fields

Field Required Type Description
method yes string ping method name
req_id no integer Client originated request identifier sent as acknowledgment in the response message

Subscribe

Example Subscribe Request

{
  "method": "subscribe",
  "params": {
    "channel": "book",
    "snapshot": false,
    "symbol": [
      "BTC/USD"
    ]
  },
  "req_id": 1234567890
}

Example Subscribe Response

{
  "method": "subscribe",
  "req_id": 1234567890,
  "result": {
    "channel": "book",
    "snapshot": false,
    "symbol": "BTC/USD"
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Subscriptions to a particular channel can be made for multiple symbols at once. They are individually confirmed and responded to.

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Unsubscribe

Example Unsubscribe Request

{
  "method": "unsubscribe",
  "params": {
    "channel": "book",
    "symbol": [
      "BTC/USD"
    ]
  },
  "req_id": 1234567890
}

Example Unsubscribe Response

{
  "method": "unsubscribe",
  "req_id": 1234567890,
  "result": {
    "channel": "book",
    "symbol": "BTC/USD"
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Canceling the subscriptions of a particular channel can be made for multiple symbols at once. They are individually confirmed and responded to.

Request Fields

Field Required Type Description
method yes string unsubscribe method name.
params yes object Parameters for the given unsubscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Private Messages

Add Order

Example Add Order Request

{
  "method": "add_order",
  "params": {
    "limit_price": 1010.10,
    "order_type": "limit",
    "order_userref": 1,
    "order_qty": 0.123456789,
    "side": "buy",
    "symbol": "BTC/USD",
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN"
  },
  "req_id": 1234567890
}

Example Add Order Response

{
  "method": "add_order",
  "result": {
    "order_id": "ORDERX-IDXXX-XXXXX1",
    "order_userref": 1
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Allows you to place a new order.

Request Fields

Field Required Type Description
method yes string add_order method name.
params yes object Parameters for the given add_order method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
cash_order_qty no integer Order volume expressed in quote currency.
Note: this is supported for "market" orders only.
conditional no object Conditional parameters, see below.
deadline no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z). Range of valid offsets from now: 500 milliseconds to 60 seconds, default is 5 seconds.
The engine will prevent this order from matching after this time, it provides protection against latency on time sensitive orders.
display_qty no float The visible quantity shown in the book while hiding remaining order_qty. This can only be used with iceberg order type.
effective_time no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z) of scheduled start time.
expire_time no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z) of expiration time.
fee_preference no string Fee preference base or quote currency.
Accepted Values
base
quote
Default Value (buy)
quote
Default Value (sell)
base
limit_price no float Limit price for limit orders
limit_price_type no string The units for the limit price - only available on trailing-stop-limit orders.
  • static: a static market price for the asset, i.e. 30000 for BTC/USD.
  • pct: a percentage offset from the reference price, i.e. -10% from index price.
  • quote: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price
Note, for trailing-stop-limit order type, the value represents offset from the trigger price. 0 would set a limit price the same as the trigger price.
margin no boolean Uses margin trading.
no_mpp no boolean Disable market price protection for market orders.
Default Value
false
order_qty no float Order quantity in terms of the base asset.
order_type yes string Sets order type.
Accepted Values
limit
market
iceberg
stop-loss
stop-loss-limit
take-profit
take-profit-limit
trailing-stop
trailing-stop-limit
settle-position
order_userref no integer User reference that identifies one or more orders.
post_only no boolean Post-only order.
Default Value
false

Note: this is supported for limit orders only.
reduce_only no boolean If set as true, it reduces an existing position without opening an opposite long or short position worth more than the current value of your leveraged assets.
Default Value
false
side yes string Side type.
Accepted Values
buy
sell
stp_type no string Self trade prevention behavior definition.
cancel_both
If self trade is triggered, both arriving and resting orders will be canceled.
cancel_newest
If self trade is triggered, arriving order will be canceled.
cancel_oldest
If self trade is triggered, resting order will be canceled.
Accepted Values
cancel_both
cancel_newest
cancel_oldest
Default Value
cancel_newest
symbol yes string Currency pair.
time_in_force no string Time-in-force of the order to specify how long it should remain in the order book before being cancelled.
GTC
Good-'til-cancelled is the default if the parameter is omitted.
GTD
Good-'til-date. If specified, must coincide with a desired expire_time.
IOC
Immediate-or-cancel will immediately execute the amount possible and cancel any remaining balance rather than resting in the book.
Accepted Values
GTC
GTD
IOC
Default Value
GTC
token yes string Session token.
validate no boolean If set to true, validate inputs only; do not submit order.
stop_price no float DEPRECATED: Use triggers.price
trigger no string DEPRECATED: Use triggers.reference
Request Params-Order-Triggers Fields

The triggers objects contains the parameters for setting the trigger price conditions.

Field Required Type Description
reference no string The reference price to track for triggering orders.
  • index: the index price in the broader market (for this pair). To keep triggers servicable during connectivity issues with external index feeds, the last price will be used as the reference price.
  • last(default): the last traded price in the Kraken order book.
price yes float Specifies the amount for the trigger price - it supports both static market prices and relative prices. This field is used in combination with the price_type field below to determine the effective trigger price.
Examples:
  • To trigger at 29000.5 BTC/USD, use price=29000.5, price_type=static.
  • To trigger when price rises by 5%, use price=5, price_type=pct.
  • To trigger when price drops by 150 BTC/USD, use price=-150, price_type=quote.
price_type no string The units for the trigger price. Default value: static.
  • static: a static market price for the asset, i.e. 30000 for BTC/USD.
  • pct: a percentage offset from the reference price, i.e. -10% from index price.
  • quote: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price
Request Params-Order-Conditional Fields

The conditional objects contains order type and price fields:

Field Required Type Description
order_type yes string Conditional close order type.
Accepted Values
limit
market
iceberg
stop-loss
stop-loss-limit
take-profit
take-profit-limit
trailing-stop
trailing-stop-limit
settle-position
limit_price no float Limit price for limit orders
limit_price_type no string The units for the limit price - only available on trailing-stop-limit orders.
  • static: a static market price for the asset, i.e. 30000 for BTC/USD.
  • pct: a percentage offset from the reference price, i.e. -10% from index price.
  • quote: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price
Note, for trailing-stop-limit order type, the value represents offset from the trigger price. 0 would set a limit price the same as the trigger price.
trigger_price yes float Specifies the amount for the trigger price - it supports both static market prices and relative prices. This field is used in combination with the price_type field below to determine the effective trigger price.
Examples:
  • To trigger at 29000.5 BTC/USD, use price=29000.5, price_type=static.
  • To trigger when price rises by 5%, use price=5, price_type=pct.
  • To trigger when price drops by 150 BTC/USD, use price=-150, price_type=quote.
trigger_price_type no string The units for the trigger price. Default value: static.
  • static: a static market price for the asset, i.e. 30000 for BTC/USD.
  • pct: a percentage offset from the reference price, i.e. -10% from index price.
  • quote: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price
stop_price no float Conditional stop order price.

Note: Conditional close orders are triggered by execution of the primary order in the same quantity and opposite direction, but once triggered are independent orders that may reduce or increase net position.

Batch Add

Example Batch Add Request

{
  "method": "batch_add",
  "params": {
    "deadline": "2022-06-13T08:09:10.123456Z",
    "orders": [
      {
        "limit_price": 1010.10,
        "order_qty": 0.123456789,
        "order_type": "limit",
        "order_userref": 1,
        "side": "buy"
      },
      {
        "limit_price": 2020.20,
        "order_qty": 0.987654321,
        "order_type": "limit",
        "order_userref": 2,
        "side": "sell",
        "stp_type": "cancel_both"
      }
    ],
    "symbol": "BTC/USD",
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN",
    "validate": false
  },
  "req_id": 1234567890
}

Example Batch Add Response

{
  "method": "batch_add",
  "req_id": 1234567890,
  "result": [
    {
      "order_id": "ORDERX-IDXXX-XXXXX1",
      "order_userref": 1
    },
    {
      "order_id": "ORDERX-IDXXX-XXXXX2",
      "order_userref": 2
    }
  ],
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Multiple orders can be submitted in one request via batch_add method.

Request Fields

Field Required Type Description
method yes string batch_add method name.
params yes object Parameters for the given batch_add method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
deadline no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z). Range of valid offsets from now: 500 milliseconds to 60 seconds, default is 5 seconds.
The engine will prevent this order from matching after this time, it provides protection against latency on time sensitive orders.
orders yes array Array of orders to add.
Note: must contain between 2 and 15 orders.
symbol yes string Currency pair.
token yes string Session token.
validate no boolean If set to true, validate inputs only; do not submit order.
Default Value
false
Request Params-Order Fields

orders is an array of individual objects representing add orders, individual objects have these possible fields:

Field Required Type Description
cash_order_qty no float Order volume expressed in quote currency.
Note: this is supported for market orders only.
conditional no object Conditional parameters.
display_qty no float The visible quantity shown in the book while hiding remaining order_qty. This can only be used with iceberg order type.
effective_time no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z) of scheduled start time.
expire_time no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z) of expiration time.
fee_preference no string Fee preference base or quote currency.
Accepted Values
base
quote
Default Value (buy)
quote
Default Value (sell)
base
limit_price no float Limit price for limit orders.
margin no boolean Uses margin trading.
no_mpp no boolean Disable market price protection for market orders.
Default Value
false
order_qty no float Order quantity in terms of the base asset.
order_type yes string Sets order type.
Accepted Values
limit
market
iceberg
stop-loss
stop-loss-limit
take-profit
take-profit-limit
settle-position
order_userref no integer User reference that identifies one or more orders.
post_only no boolean Post-only order.
Default Value
false

Note: this is supported for limit orders only.
reduce_only no boolean If set as true, it reduces an existing position without opening an opposite long or short position worth more than the current value of your leveraged assets.
Default Value
false
side yes string Side type.
Accepted Values
buy
sell
stp_type no string Self trade prevention behavior definition.
cancel_both
If self trade is triggered, both arriving and resting orders will be canceled.
cancel_newest
If self trade is triggered, arriving order will be canceled.
cancel_oldest
If self trade is triggered, resting order will be canceled.
Accepted Values
cancel_both
cancel_newest
cancel_oldest
Default Value
cancel_newest
time_in_force no string Time-in-force of the order to specify how long it should remain in the order book before being cancelled.
GTC
Good-'til-cancelled is the default if the parameter is omitted.
GTD
Good-'til-date. If specified, must coincide with a desired expire_time.
IOC
Immediate-or-cancel will immediately execute the amount possible and cancel any remaining balance rather than resting in the book.
Accepted Values
GTC
GTD
IOC
Default Value
GTC
stop_price no float DEPRECATED: Use triggers.price
trigger no string DEPRECATED: Use triggers.reference
Request Params-Order-Triggers Fields

The triggers objects contains the parameters for setting the trigger price conditions.

Field Required Type Description
reference no string The reference price to track for triggering orders.
  • index: the index price in the broader market (for this pair). To keep triggers servicable during connectivity issues with external index feeds, the last price will be used as the reference price.
  • last (default): the last traded price in the Kraken order book.
price yes float Specifies the amount for the trigger price - it supports both static market prices and relative prices. This field is used in combination with the price_type field below to determine the effective trigger price.
Examples:
  • To trigger at 29000.5 BTC/USD, use price=29000.5, price_type=static.
  • To trigger when price rises by 5%, use price=5, price_type=pct.
  • To trigger when price drops by 150 BTC/USD, use price=-150, price_type=quote.
price_type no string The units for the trigger price. Default value: static.
  • static: a static market price for the asset, i.e. 30000 for BTC/USD.
  • pct: a percentage offset from the reference price, i.e. -10% from index price.
  • quote: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price
Request Params-Order-Conditional Fields

The conditional objects contains order type and price fields:

Field Required Type Description
limit_price no float Conditional limit order price.
order_type no string Conditional close order type.
Accepted Values
limit
iceberg
stop-loss
stop-loss-limit
take-profit
take-profit-limit
trailing-stop
trailing-stop-limit
settle-position
stop_price no float Conditional stop order price.

Note: Conditional close orders are triggered by execution of the primary order in the same quantity and opposite direction, but once triggered are independent orders that may reduce or increase net position.

Batch Cancel

Example Batch Cancel Request

{
  "method": "batch_cancel",
  "params": {
    "orders": [
      "1",
      "2",
      "ORDERX-IDXXX-XXXXX3"
    ],
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN"
  },
  "req_id": 1234567890
}

Example Batch Cancel Response

{
  "method": "batch_cancel",
  "req_id": 1234567890,
  "result": {
    "count": 3
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Multiple orders can be canceled in one request via batch_cancel method.

Request Fields

Field Required Type Description
method yes string batch_cancel method name.
params yes object Parameters for the given batch_cancel method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
orders yes array Array of strings representing either: order_userref(s) or order_id(s)
Note: array must contain between 2 and 50 items.
token yes string Session token.

Cancel All Orders

Example Cancel All Request

{
  "method": "cancel_all",
  "params": {
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN"
  },
  "req_id": 1234567890
}

Example Cancel All Response

{
  "method": "cancel_all",
  "req_id": 1234567890,
  "result": {
    "count": 123
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Request Fields

Field Required Type Description
method yes string cancel_all method name.
params yes object Parameters for the given cancel_all method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
token yes string Session token.

Cancel All Orders After

Example Cancel All Orders After Request

{
  "method": "cancel_all_orders_after",
  "params": {
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN",
    "timeout": 100
  },
  "req_id": 1234567890
}

Example Cancel All Orders After Response

{
  "method": "cancel_all_orders_after",
  "req_id": 1234567890,
  "result": {
    "currentTime": "2022-06-13T08:09:10Z",
    "triggerTime": "2022-06-13T08:09:20Z"
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

cancel_all_orders_after provides a "Dead Man's Switch" mechanism to protect the client from network malfunction, extreme latency or unexpected matching engine downtime. The client can send a request with a timeout (in seconds), that will start a countdown timer which will cancel all client orders when the timer expires. The client has to keep sending new requests to push back the trigger time, or deactivate the mechanism by specifying a timeout of 0. If the timer expires, all orders are cancelled and then the timer remains disabled until the client provides a new (non-zero) timeout.

The recommended use is to make a call every 15 to 30 seconds, providing a timeout of 60 seconds. This allows the client to keep the orders in place in case of a brief disconnection or transient delay, while keeping them safe in case of a network breakdown. It is also recommended to disable the timer ahead of regularly scheduled trading engine maintenance (if the timer is enabled, all orders will be cancelled when the trading engine comes back from downtime - planned or otherwise).

Request Fields

Field Required Type Description
method yes string cancel_all_orders_after method name.
params yes object Parameters for the given cancel_all_orders_after method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
token yes string Session token.
timeout yes integer Duration (in seconds) to set/extend the timer by. Note: should be less than 86400 seconds.

Cancel Order

Example Cancel Order Request

{
  "method": "cancel_order",
  "params": {
    "order_id": [
      "ORDERX-IDXXX-XXXXX1",
      "ORDERX-IDXXX-XXXXX2"
    ],
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN"
  },
  "req_id": 1234567890
}

Example Cancel Order response for ORDERX-IDXXX-XXXXX1

{
  "method": "cancel_order",
  "req_id": 1234567890,
  "result": {
    "order_id": "ORDERX-IDXXX-XXXXX1"
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Example Cancel Order response for ORDERX-IDXXX-XXXXX2

{
  "method": "cancel_order",
  "req_id": 1234567890,
  "result": {
    "order_id": "ORDERX-IDXXX-XXXXX2"
  },
  "success": true,
  "time_in": "2022-06-13T08:09:10.123456Z",
  "time_out": "2022-06-13T08:09:10.7890123"
}

Cancels a particular open order (or set of open orders) by order_id or user reference.

Request Fields

Field Required Type Description
method yes string cancel_order method name.
params yes object Parameters for the given cancel_order method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
order_id no array Array of strings representing order_id(s).
order_userref no array Array of integers representing order_userref(s).
token yes string Session token.

Note: Though order_id and order_userref are individually optional, at least one of them must be filled.

Edit Order

Example Edit order Request

{
  "method": "edit_order",
  "params": {
    "order_id": "ORDERX-IDXXX-XXXXX1",
    "order_qty": 0.2123456789,
    "symbol": "BTC/USD",
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN"
  },
  "req_id": 1234567890
}

Example Edit Order response

{
  "method": "edit_order",
  "req_id": 1234567890,
  "result": {
    "order_id": "ORDERX-IDXXX-XXXXX2",
    "original_order_id": "ORDERX-IDXXX-XXXXX1"
  },
  "success": true,
  "time_in": "2022-07-15T12:56:09.876488Z",
  "time_out": "2022-07-15T12:56:09.923422Z"
}

Edit volume and price on open orders. Un-editable orders include triggered stop/profit orders, orders with conditional close terms attached, those already cancelled or filled and those where the executed volume is greater than the newly supplied volume. post_only flag is not retained from original order after successful edit.

Request Fields

Field Required Type Description
method yes string edit_order method name.
params yes object Parameters for the given edit_order method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Field Required Type Description
deadline no string RFC3339 timestamp (e.g. 2021-04-01T00:18:45Z). Range of valid offsets from now: 500 milliseconds to 60 seconds, default is 5 seconds.
The engine will prevent this order from matching after this time, it provides protection against latency on time sensitive orders.
display_qty no float The visible quantity shown in the book while hiding remaining order_qty. This can only be used with iceberg order type.
fee_preference no string Fee preference base or quote currency.
Accepted Values
base
quote
Default Value (buy)
quote
Default Value (sell)
base
limit_price no float Limit price.
no_mpp no boolean Disable market price protection for market orders.
Default Value
false
order_id yes string Either order_id or order_userref of the order to be edited.
order_qty no float Order quantity in terms of the base asset.
order_userref no string User reference that identifies one or more orders.
post_only no boolean Post-only order.
Default Value
false

Note: this is supported for limit orders only.
price no float DEPRECATED: use limit_price. Limit price for limit orders.
reduce_only no boolean If set as true, it reduces an existing position without opening an opposite long or short position worth more than the current value of your leveraged assets.
Default Value
false
stop_price no float Stop price for stop-loss-limit, take-profit-limit, trailing-stop-limit orders.
symbol yes string Currency pair.
token yes string Session token.
trigger no string Price signal used to trigger stop-loss, stop-loss-limit, take-profit and take-profit-limit orders.
Accepted Values
index
last
Default Value
last
validate no boolean If set to true, validate inputs only; do not submit order.

Note: Though limit_price and order_qty and stop_price are individually optional, at least one of them must be present.

Channels

Book

Example Subscribe Book Request

{
  "method": "subscribe",
  "params": {
    "channel": "book",
    "depth": 10,
    "snapshot": true,
    "symbol": [
      "BTC/USD"
    ]
  },
  "req_id": 1234567890
}

The channel book pushes order book snapshots and real-time updates.

Subscriptions to channel book can be made for multiple symbols at once. They are individually confirmed and responded to.

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

param Required Type Description
channel yes string book channel name.
depth no integer Book depth for subscription.
Accepted Values
10
25
100
500
1000
Default Value
10
snapshot no boolean Request a snapshot after subscribing.
Default Value
true
symbol yes array Symbol(s) to subscribe to.

Snapshot Response

Example Book Snapshot Response

{
  "channel": "book",
  "type": "snapshot",
  "data": [
    {
      "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
        }
      ],
      "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.0,
          "qty": 0.71990644
        },
        {
          "price": 34709.3,
          "qty": 0.26085746
        },
        {
          "price": 34707.9,
          "qty": 0.16037166
        },
        {
          "price": 34707.8,
          "qty": 0.05682871
        }
      ],
      "checksum": 2645840827,
      "symbol": "BTC/USD"
    }
  ]
}

Book Snapshot Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "channel": {
      "const": "book",
      "type": "string"
    },
    "data": {
      "items": {
        "properties": {
          "asks": {
            "items": {
              "properties": {
                "price": {
                  "type": "number"
                },
                "qty": {
                  "type": "number"
                }
              },
              "required": [
                "price",
                "qty"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "bids": {
            "items": {
              "properties": {
                "price": {
                  "type": "number"
                },
                "qty": {
                  "type": "number"
                }
              },
              "required": [
                "price",
                "qty"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "checksum": {
            "type": "integer"
          },
          "symbol": {
            "type": "string"
          }
        },
        "required": [
          "asks",
          "bids",
          "checksum",
          "symbol"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "type": {
      "const": "snapshot",
      "type": "string"
    }
  },
  "required": [
    "channel",
    "data",
    "type"
  ],
  "title": "Book snapshot response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

The returned snapshot data contains the top 10 bids and asks for the relevant symbol including a CRC32 checksum of the top 10 bids and asks.

Response Fields

Field Required Type Description
channel yes string book channel name.
data yes object The snapshot data payload.
type yes string The snapshot data payload type.
Response Data Fields
Field Required Type Description
asks yes array The top 10 asks.
bids yes array The top 10 bids.
checksum yes integer CRC32 checksum for the top 10 bids and asks.
symbol yes string The relevant symbol.
Response Data-Asks Fields
Field Required Type Description
price yes float The ask price.
qty yes float The ask quantity
Response Data-Bids Fields
Field Required Type Description
price yes float The bid price.
qty yes float The bid quantity

Update Response

Example Book Update Response

{
  "channel": "book",
  "data": [
    {
      "asks": [
        {
          "price": 34726.4,
          "qty": 0
        },
        {
          "price": 34739.7,
          "qty": 2.1541
        }
      ],
      "bids": [],
      "checksum": 4022926185,
      "symbol": "BTC/USD",
      "timestamp": "2022-06-13T08:09:10.123456Z"
    }
  ],
  "type": "update"
}

Book Update Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "channel": {
      "const": "book",
      "type": "string"
    },
    "data": {
      "items": {
        "properties": {
          "asks": {
            "items": {
              "properties": {
                "price": {
                  "type": "number"
                },
                "qty": {
                  "type": "number"
                }
              },
              "required": [],
              "type": "object"
            },
            "type": "array"
          },
          "bids": {
            "items": {
              "properties": {
                "price": {
                  "type": "number"
                },
                "qty": {
                  "type": "number"
                }
              },
              "required": [],
              "type": "object"
            },
            "type": "array"
          },
          "checksum": {
            "type": "integer"
          },
          "symbol": {
            "type": "string"
          },
          "timestamp": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "asks",
          "bids",
          "checksum",
          "symbol",
          "timestamp"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "type": {
      "const": "update",
      "type": "string"
    }
  },
  "required": [
    "channel",
    "data",
    "type"
  ],
  "title": "Book update response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

The returned snapshot data contains the updates of the bids and asks for the relevant symbol including a CRC32 checksum of the top 10 bids and asks.

Response Fields

Field Required Type Description
channel yes string book channel name.
data yes object The update data payload.
type yes string The update data payload type.
Response Data Fields
Field Required Type Description
asks yes array The top 10 asks. Note: can be empty if no updates.
bids yes array The top 10 bids. Note: can be empty if no updates.
checksum yes integer CRC32 checksum for the top 10 bids and asks.
symbol yes string The relevant symbol.
timestamp yes string The book order update timestamp (RFC3339).
Response Data-Asks Fields
Field Required Type Description
price yes float The ask price.
qty yes float The ask quantity
Response Data-Bids Fields
Field Required Type Description
price yes float The bid price.
qty yes float The bid quantity

Executions

Example Subscribe Executions Request

{
  "method": "subscribe",
  "params": {
    "channel": "executions",
    "snapshot": true,
    "snapshot_trades": false,
    "order_status": true,
    "ratecounter": true,
    "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN"
  },
  "req_id": 1234567890
}

The executions channel sends both order updates, corresponding to the "openOrders" channel in WS API v1, and trade execution updates, corresponding to the "ownTrades" channel in WS API v1.

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

param Required Type Description
channel yes string executions channel name.
snapshot no boolean Request a snapshot containing all open orders and latest 50 trades
Default Value
true
snapshot_trades no boolean If true snapshot only provides trade events.
Default Value
false
order_status no boolean If true client will receive a message for all possible execution status transitions. If false client will only receive updates when order enters the book (new) and when order is closed (filled, canceled or expired).
Default Value
true
ratecounter no boolean Send rate-limit counter in updates.
Default Value
false
token yes string Session token.

Example Subscribe Executions Response

{
  "channel": "executions",
  "data": [
    {
      "cum_cost": 0.00000000,
      "exec_type": "new",
      "fee_ccy_pref": "fciq",
      "fee_usd_equiv": 0.00000000,
      "limit_price": 59.00000,
      "order_id": "ORDERX-IDXXX-XXXXX1",
      "order_qty": 5.00000000,
      "order_status": "new",
      "order_type": "limit",
      "order_userref": 1,
      "side": "sell",
      "stop_price": 0.00000,
      "symbol": "BTC/USD",
      "time_in_force": "GTC",
      "timestamp": "2022-06-13T08:09:10.123456Z"
    },
    {
      "cost": 95.45000000,
      "exec_id": "EXECXX-IDXXX-XXXXX1",
      "exec_type": "trade",
      "fees": [
        {
          "asset": "USD",
          "qty": 0.24817000
        }
      ],
      "liquidity_ind": "t",
      "ord_type": "market",
      "order_id": "ORDERX-IDXXX-XXXXX2",
      "last_qty": 5.00000000,
      "order_userref": 0,
      "last_price": 19.09000,
      "side": "buy",
      "symbol": "XRP/USD",
      "timestamp": "2022-06-13T08:09:10.123456Z",
      "trade_id": 123456
    }
  ],
  "sequence": 1,
  "type": "snapshot"
}

Example Subscribe Executions Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "channel": {
      "type": "string"
    },
    "data": {
      "items": {
        "properties": {
          "avg_price": {
            "type": "number"
          },
          "cancel_reason": {
            "type": "string"
          },
          "cost": {
            "type": "number"
          },
          "cum_cost": {
            "type": "number"
          },
          "cum_qty": {
            "type": "number"
          },
          "display_qty": {
            "type": "number"
          },
          "display_qty_remain": {
            "type": "number"
          },
          "effective_time": {
            "format": "date-time",
            "type": "string"
          },
          "exec_id": {
            "type": "string"
          },
          "exec_type": {
            "type": "string"
          },
          "expire_time": {
            "format": "date-time",
            "type": "string"
          },
          "fee_ccy_pref": {
            "type": "string"
          },
          "fee_usd_equiv": {
            "type": "number"
          },
          "fees": {
            "items": {
              "properties": {
                "asset": {
                  "type": "string"
                },
                "qty": {
                  "type": "number"
                }
              },
              "required": [
                "asset",
                "qty"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "limit_price": {
            "type": "number"
          },
          "liquidity_ind": {
            "type": "string"
          },
          "no_mpp": {
            "type": "boolean"
          },
          "ord_ref_id": {
            "type": "number"
          },
          "order_id": {
            "type": "string"
          },
          "order_qty": {
            "type": "number"
          },
          "last_qty": {
            "type": "number"
          },
          "order_status": {
            "type": "string"
          },
          "order_type": {
            "type": "string"
          },
          "order_userref": {
            "type": "number"
          },
          "post_only": {
            "type": "boolean"
          },
          "last_price": {
            "type": "number"
          },
          "reduce_only": {
            "type": "boolean"
          },
          "side": {
            "type": "string"
          },
          "stop_price": {
            "type": "number"
          },
          "symbol": {
            "type": "string"
          },
          "time_in_force": {
            "type": "string"
          },
          "timestamp": {
            "format": "date-time",
            "type": "string"
          },
          "trade_id": {
            "type": "number"
          },
          "trigger": {
            "type": "string"
          },
          "triggered_price": {
            "type": "number"
          }
        },
        "required": [
          "exec_type",
          "order_id",
          "order_status",
          "timestamp"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "sequence": {
      "type": "number"
    },
    "type": {
      "type": "string"
    }
  },
  "required": [
    "channel",
    "data",
    "sequence",
    "type"
  ],
  "title": "Subscribe executions update response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

Response Fields

param Required Type Description
channel yes string executions channel name.
data yes object The executions data payload.
sequence yes integer The running sequence number.
type yes string The executions data payload type.
Response Data Fields
Field Required Type Description
avg_price no float Order's average fill price.
cancel_reason no string Cancel reason.
cash_order_qty no float Order volume expressed in quote currency.
cost no float Cost of trade (only when exec_type:"trade").
cum_cost no float Order's cumulative cost.
cum_qty no float Order's cumulative executed quantity.
display_qty no float Display quantity (iceberg's only).
display_qty_remain no float Display quantity remaining (iceberg's only).
effective_time no string Timestamp (RFC3339) of order's start time.
exec_id no string Execution identifier (only when exec_type:"trade").
exec_type yes string Execution update type.
Possible Values:
pending_new
new
filled
canceled
expired
trade
restated
status
expire_time no string Timestamp (RFC3339) of order's end time.
fee_ccy_pref no string Fee Preference.
Possible Values:
fcib (prefer fee in base currency)
fciq (prefer fee in quote currency)
fee_usd_equiv no float Total fee (USD).
fees no object Fee's object (WIP) (only when exec_type:"trade").
last_price no float Filled price (only when exec_type:"trade").
last_qty no float Filled quantity when exec_type:"trade".
limit_price no float Order's limit price.
liquidity_ind no string The liquidity indicator.
Possible Values:
t (taker)
m (maker)
margin no boolean true if the order funded on margin.
no_mpp no boolean true if the order has no market price protection.
ord_ref_id no integer Referral order transaction id that created this order.
order_id yes string The order identifier.
order_qty no float Order's quantity.
order_status yes string Order status.
Possible Values:
pending_new
new
filled
canceled
expired
triggered
partially_filled
order_type no string Order type.
Possible Values:
market
limit
stop-loss
stop-loss-limit
take-profit
take-profit-limit
trailing-stop
trailing-stop-limit
order_userref no integer The user order reference.
post_only no boolean If order's flagged for post only.
reduce_only no boolean If order's flagged for reduce only.
side no string Order's side.
Possible Values:
buy
sell
symbol no string Currency pair.
time_in_force no string Time in force.
Possible Values:
IOC
GTD
GTC
timestamp yes string Timestamp (RFC3339) of execution event.
trade_id no integer The trade identifier.
trigger no string DEPRECATED: Use triggers.reference
triggered_price no float DEPRECATED: Use triggers.last_price
stop_price no float DEPRECATED: Use triggers.actual_price
Executions-Triggers Fields

The triggers objects describes the parameters and status of the price trigger for triggered order types.

Field Required Type Description
reference no string The reference price to track for triggering orders.
price yes float Specifies the amount for the trigger price - it supports both static market prices and relative prices. This field is used in combination with the price_type field below to determine the effective trigger price.
price_type no string The units for the trigger price.
  • static: a static market price for the asset, i.e. 30000 for BTC/USD.
  • pct: a percentage offset from the reference price, i.e. -10% from index price.
  • quote: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price
actual_price no float The current value of the effective trigger price, this is useful if the trigger was entered using a relative price or the trigger price changes over time.
last_price no float On trigger activation, the value of the reference last price that triggered the order.
status no string The status is set to triggered when the trigger conditions are met and the order becomes active.
timestamp no string On trigger activation, the timestamp of the trigger event. Example is "2022-12-25T09:30:59.123456Z"
Response Data-Fees Fields
Field Required Type Description
asset yes string The fee currency.
qty yes float The fee amount.

Heartbeat

Example Heartbeat Response

{
  "channel": "heartbeat"
}

Heartbeat Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "channel": {
      "const": "heartbeat",
      "type": "string"
    }
  },
  "required": [
    "channel"
  ],
  "title": "Heartbeat response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

Once subscribed to at least one channel, heartbeat messages are sent approximately once every second in the absence of subscription data.

Response Fields

Field Required Type Description
channel yes string heartbeat channel name.

Instrument

Example Subscribe Instrument Request

{
  "method": "subscribe",
  "params": {
    "channel": "instrument",
    "snapshot": true
  },
  "req_id": 1234567890
}

The instrument channel provides a snapshot of all active assets and tradeable pairs, along with the relevant trading parameters and rules (precisions, minimums, and so on).

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

param Required Type Description
channel yes string instrument channel name.
snapshot no boolean Request a snapshot after subscribing.
Default Value
true

Example Instrument Snapshot Response

{
  "channel": "instrument",
  "data": {
    "assets": [
      {
        "borrowable": true,
        "collateral_value": 1.00,
        "id": "USD",
        "margin_rate": 0.015000,
        "precision": 4,
        "precision_display": 2,
        "status": "enabled"
      },
      {
        "borrowable": true,
        "collateral_value": 1.00,
        "id": "EUR",
        "margin_rate": 0.015000,
        "precision": 4,
        "precision_display": 2,
        "status": "enabled"
      },
      {
        "borrowable": true,
        "collateral_value": 1.00,
        "id": "BTC",
        "margin_rate": 0.010000,
        "precision": 10,
        "precision_display": 5,
        "status": "enabled"
      }
    ],
    "pairs": [
      {
        "base": "BTC",
        "cost_min": 0.50,
        "cost_precision": 5,
        "has_index": true,
        "margin_initial": 0.20,
        "marginable": true,
        "position_limit_long": 200,
        "position_limit_short": 200,
        "price_increment": 0.1,
        "price_precision": 1,
        "qty_increment": 0.00000001,
        "qty_min": 0.00010000,
        "qty_precision": 8,
        "quote": "USD",
        "status": "online",
        "symbol": "BTC/USD",
      },
      {
        "base": "EUR",
        "cost_min": 0.50,
        "cost_precision": 5,
        "has_index": true,
        "marginable": false,
        "price_increment": 0.00001,
        "price_precision": 5,
        "qty_increment": 0.00000001,
        "qty_min": 5.00000000,
        "qty_precision": 8,
        "quote": "USD",
        "status": "online",
        "symbol": "EUR/USD",
      }
    ]
  },
  "type": "snapshot"
}

Response Fields

Field Required Type Description
channel yes string instrument channel name.
data yes object The instrument data payload.
type yes string The instrument data payload type.
Response Data Fields
Field Required Type Description
assets yes array Array with objects of all the available assets.
pairs yes array Array with objects of all the available asset pairs.
Response Data-Assets Fields
Field Required Type Description
borrowable yes boolean Flag if asset is borrowable.
collateral_value yes float Valuation as margin collateral (if applicable).
id yes string Asset identifier.
margin_rate no float Interest rate to borrow the asset.
precision yes integer Maximum precision for asset ledger, balances.
precision_display yes integer Recommended display precision.
status yes string Status of asset.
Possible Values
depositonly
disabled
enabled
fundingtemporarilydisabled
withdrawalonly
workinprogress
Response Data-Pairs Fields
Field Required Type Description
base yes string Asset identifier of the base currency.
cost_min yes float Minimum cost (price * qty) for new orders.
cost_precision yes integer Maximum precision used for cost prices.
has_index yes boolean Whether the pair has an index available for example stop-loss triggers.
margin_initial no float Initial margin requirement (in percent, if marginable).
marginable yes boolean Whether the pair can be traded on margin.
position_limit_long no integer Limit for long positions (marginable pairs).
position_limit_short no integer Limit for short positions (marginable pairs).
price_increment yes float Minimum price increment for new orders.
price_precision yes integer Maximum precision used for order prices.
qty_increment yes float Minimum quantity increment for new orders.
qty_min yes float Minimum quantity (in base currency) for new orders.
qty_precision yes integer Maximum precision used for order quantities.
quote yes string Asset identifier of the quote currency.
status yes string Status of pair.
Possible Values
cancel_only
delisted
limit_only
maintenance
online
post_only
reduce_only
work_in_progress
symbol yes string Asset pair identifier.
tick_size no float DEPRECATED: use price_increment.

Open, High, Low, and Close (OHLC)

Example Open, High, Low, and Close (OHLC) Request

{
  "method": "subscribe",
  "params": {
    "channel": "ohlc",
    "symbol": [
      "BTC/USD"
    ],
    "interval": 5
  }
}

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

Param Required Type Description
channel yes string ohlc channel name.
symbol yes array Symbol(s) to subscribe to.
interval no int Timeframe for interval in minutes.
Accepted Values
1, 5, 15, 30, 60, 240, 1440, 10080, 21600
Default Value
1
snapshot no boolean Request a snapshot after subscribing.
Default Value
true

Example Open, High, Low, and Close (OHLC) Response

{
  "channel": "ohlc",
  "timestamp": "2022-06-13T08:09:10.123456Z",
  "data": [
    {
      "close": 30001.4,
      "high": 3000.9,
      "low": 3000.1,
      "open": 3000.3,
      "symbol": "BTC/USD",
      "interval_begin": "2022-06-12T08:09:10.123456Z",
      "trades": 1,
      "volume": 0.0001,
      "vwap": 3000.3,
      "interval": 5,
      "timestamp": "2022-06-13T08:09:10.123456Z",
    }
  ],
  "type": "snapshot"
}

OHLC Candle feed for a given currency pair.

Response Fields

Field Required Type Description
channel yes string ohlc channel name.
data yes object The ohlc data payload.
type yes string The ohlc data payload type.
timestamp yes string Timestamp of the OHLC response
Response Data Fields
Field Required Type Description
close yes float The close (last traded) price within the interval.
high yes float Highest traded price within the interval.
low yes float Lowest traded price within the interval.
open yes float The open (first traded) price within the interval.
symbol yes string Currency pair.
interval_begin yes string The timestamp of start of the interval (RFC3339).
interval yes float Timeframe for interval in minutes.
trades yes integer Number of trades within the interval.
volume yes float Total traded volume (in base currency terms) within the interval.
vwap yes float Volume-weight average price within the interval.
timestamp no string DEPRECATED: use interval_begin.

Ticker

Example Subscribe Ticker Request

{
  "method": "subscribe",
  "params": {
    "channel": "ticker",
    "snapshot": true,
    "symbol": [
      "BTC/USD"
    ]
  },
  "req_id": 1234567890
}

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

param Required Type Description
channel yes string ticker channel name.
symbol yes array Symbol(s) to subscribe to.
event_trigger no string Event trigger for the updates, default Value: trades.
Possible Values
bbo
trades
snapshot no boolean Request a snapshot after subscribing.
Default Value
true

Snapshot Response

Example Ticker Snapshot Response

{
  "channel": "ticker",
  "data": [
    {
      "ask": 7000.3,
      "ask_qty": 0.01,
      "bid": 6000.0,
      "bid_qty": 0.01,
      "change": -100.0,
      "change_pct": -1.54,
      "high": 6500.9,
      "last": 6400.6,
      "low": 6400.1,
      "symbol": "BTC/EUR",
      "volume": 0.02,
      "vwap": 6450.2
    }
  ],
  "type": "snapshot"
}

ticker snapshots reflect the current state of the market.

Response Fields

Field Required Type Description
channel yes string ticker channel name.
data yes object The ticker data payload.
type yes string The ticker data payload type.
Response Data Fields
Field Required Type Description
ask yes float Best (top-of-book) ask.
ask_qty yes float Best (top-of-book) ask quantity.
bid yes float Best (top-of-book) bid.
bid_qty yes float Best (top-of-book) bid quantity.
change yes float 24-hour price change (in quote currency terms).
change_pct yes float 24-hour price change (in percentage points).
high yes float 24-hour highest trade price.
last yes float Last traded price.
low yes float 24-hour lowest trade price.
symbol yes string Currency pair.
volume yes float 24-hour traded volume (in base currency terms).
vwap yes float 24-hour volume-weight average price.

Update Response

Example Ticker Update Response

{
  "channel": "ticker",
  "data": [
    {
      "ask": 7000.3,
      "ask_qty": 0.01,
      "bid": 6000.0,
      "bid_qty": 0.01,
      "change": -100.0,
      "change_pct": -1.54,
      "high": 6500.9,
      "last": 6400.6,
      "low": 6400.1,
      "symbol": "BTC/EUR",
      "volume": 0.02,
      "vwap": 6450.2
    }
  ],
  "type": "update"
}

ticker pushes updates whenever there is a trade or there is a change (price or quantity) at the top-of-book.

Response Fields

Field Required Type Description
channel yes string ticker channel name.
data yes object The ticker data payload.
type yes string The ticker data payload type.
Response Data Fields
Field Required Type Description
ask yes float Best (top-of-book) ask.
ask_qty yes float Best (top-of-book) ask quantity.
bid yes float Best (top-of-book) bid.
bid_qty yes float Best (top-of-book) bid quantity.
change yes float 24-hour price change (in quote currency terms).
change_pct yes float 24-hour price change (in percentage points).
high yes float 24-hour highest trade price.
last yes float Last traded price.
low yes float 24-hour lowest trade price.
symbol yes string Currency pair.
volume yes float 24-hour traded volume (in base currency terms).
vwap yes float 24-hour volume-weight average price.

Trade

Example Subscribe Trade Request

{
  "method": "subscribe",
  "params": {
    "channel": "trade",
    "snapshot": true,
    "symbol": [
      "BTC/USD"
    ]
  },
  "req_id": 1234567890
}

Request Fields

Field Required Type Description
method yes string subscribe method name.
params yes object Parameters for the given subscribe method.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.

Request Params Fields

param Required Type Description
channel yes string trade channel name.
symbol yes array Symbol(s) to subscribe to.
snapshot no boolean Request a snapshot after subscribing.
Default Value
true

Example Trade Update Response

{
  "channel": "trade",
  "data": [
    {
      "ord_type": "market",
      "price": 4136.4,
      "qty": 0.23374249,
      "side": "sell",
      "symbol": "BTC/USD",
      "timestamp": "2022-06-13T08:09:10.123456Z",
      "trade_id": 0
    },
    {
      "ord_type": "market",
      "price": 4136.4,
      "qty": 0.00060615,
      "side": "sell",
      "symbol": "BTC/USD",
      "timestamp": "2022-06-13T08:09:20.123456Z",
      "trade_id": 0
    },
    {
      "ord_type": "market",
      "price": 4136.4,
      "qty": 0.00000136,
      "side": "sell",
      "symbol": "BTC/USD",
      "timestamp": "2022-06-13T08:09:30.123456Z",
      "trade_id": 0
    }
  ],
  "type": "update"
}

trade pushes trades in real-time. Multiple trades may be batched in a single message but that does not necessarily mean that every trade in a single message resulted from a single taker order.

Response Fields

Field Required Type Description
channel yes string trade channel name.
data yes object The trade data payload.
type yes string The trade data payload type.
Response Data Fields
Field Required Type Description
ord_type yes string Taker order type.
price yes float Execution price.
qty yes float Execution quantity.
side yes string Taker order direction.
symbol yes string The relevant symbol.
timestamp yes string The book order update timestamp (RFC3339).
trade_id yes integer Unique trade identifier for this symbol.

Status

Example Status Update Response

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

Example Status Update Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "channel": {
      "const": "status",
      "type": "string"
    },
    "data": {
      "items": {
        "properties": {
          "api_version": {
            "type": "string"
          },
          "connection_id": {
            "type": "number"
          },
          "system": {
            "enum": [
              "cancel_only",
              "maintenance",
              "online",
              "post_only"
            ],
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "api_version",
          "connection_id",
          "system",
          "version"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "type": {
      "type": "string"
    }
  },
  "required": [
    "channel",
    "data",
    "type"
  ],
  "title": "Status update response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

Sent upon connection and upon change to our system/trading status.

Response Fields

Field Required Type Description
channel yes string status channel name.
data yes object The status data payload.
type yes string The status data payload type.

Response Data Fields

Field Required Type Description
api_version yes string The version of the application programming interface.
connection_id yes integer The connection identifier.
system yes string The system/trading status.
Possible Values
cancel_only
maintenance
online
post_only
version yes string The active WebSockets application programming interface (API) version.

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. In other words, 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, but prices and volumes are now sent as floats and so their precisions will need to be determined from the instrument channel in order to compute the checksum (specifically, fields price_precision and qty_precision). Detailed instructions can be found in the Calculate Book Checksum section.

Calculate Book Checksum

Example ADA/USD Book

ask price: 0.3501, quantity: 0.01
ask price: 0.3502, quantity: 0.02
ask price: 0.3503, quantity: 0.03
ask price: 0.3504, quantity: 0.04
ask price: 0.3505, quantity: 0.05
ask price: 0.3506, quantity: 0.06
ask price: 0.3507, quantity: 0.07
ask price: 0.3508, quantity: 0.08
ask price: 0.3509, quantity: 0.09
ask price: 0.3510, quantity: 0.10

bid price: 0.3410, quantity: 0.10
bid price: 0.3409, quantity: 0.09
bid price: 0.3408, quantity: 0.08
bid price: 0.3407, quantity: 0.07
bid price: 0.3406, quantity: 0.06
bid price: 0.3405, quantity: 0.05
bid price: 0.3404, quantity: 0.04
bid price: 0.3403, quantity: 0.03
bid price: 0.3402, quantity: 0.02
bid price: 0.3401, quantity: 0.01

Example ADA/USD Price and Quantity Precision

price_precision: 6
qty_precision  : 8

The checksum is a CRC32 value based on the top 10 bids and 10 asks. It can be used to verify that your data is correct and up to date by calculating the checksum independently and comparing it against the value provided.

The checksum is computed by concatenating the top 10 bids and asks in the current book in a particular format and then taking the CRC32 checksum of that string.

Note: The following results are based in on the Example ADA/USD Book and Example ADA/USD Price and Quantity Precision.

  1. Sort the asks by price from low to high:
    0.3501, 0.3502, ..., 0.3510
  2. For each of the top ten asks:
    1. Convert the price-quantity pair to a string by:
      1. Change price using the price_precision (6) to a string:
        0.3501 -> "0.350100"
      2. Remove the decimal point (.) from the price:
        "0.350100" -> "0350100"
      3. Remove all leading zero (0) characters from the price:
        "0350100" -> "350100"
      4. Change quantity using the qty_precision (8) to a string
        0.01 -> "0.01000000"
      5. Remove the decimal point (.) from the quantity:
        "0.01000000" -> "001000000"
      6. Remove all leading zero (0) characters from the quantity:
        "001000000" -> "1000000"
      7. Combine converted price ("350100") and quantity ("1000000"):
        "3501001000000"
    2. Combine the converted top 10 asks price-quantity strings:
      "35010010000003502002000000350300300000035040040000003505005000000350600600000035070070000003508008000000350900900000035100010000000"
  3. Sort the bids by price from high to low:
    0.3410, 0.3409, ..., 0.3401
  4. For each of the top ten bids:
    1. Convert the price-quantity pair to a string by:
      1. Change price using the price_precision (6) to a string:
        0.3410 -> "0.341000"
      2. Remove the decimal point (.) from the price:
        "0.341000" -> "0341000"
      3. Remove all leading zero (0) characters from the price:
        "0341000" -> "341000"
      4. Change quantity using the qty_precision (8) to a string
        0.10 -> "0.10000000"
      5. Remove the decimal point (.) from the quantity:
        "0.10000000" -> "010000000"
      6. Remove all leading zero (0) characters from the quantity:
        "010000000" -> "10000000"
      7. Combine converted price ("341000") and quantity ("10000000"):
        "34100010000000"
    2. Combine the converted top 10 bids price-quantity strings:
      "34100010000000340900900000034080080000003407007000000340600600000034050050000003404004000000340300300000034020020000003401001000000"
  5. Combine the asks and bids results:
    "3501001000000350200200000035030030000003504004000000350500500000035060060000003507007000000350800800000035090090000003510001000000034100010000000340900900000034080080000003407007000000340600600000034050050000003404004000000340300300000034020020000003401001000000"
  6. Use the combined asks-and-bids value as input to a CRC32 checksum function
  7. Feed the concatenated string to a CRC32 checksum function:
    187053740

Note: If needed, cast the result (comprising 32 bits) as an unsigned 32-bit integer.

This value can now be compared to the checksum received to ensure your local book is accurate.

Rate Limits

Matching Engine Rate Limits

Limits

Separate limits apply to the number of orders clients may have open in each pair at a time, and the speed with which they may add and cancel orders in each pair. These limits vary by the account verification tier:

Tier Max. Orders Count Max. Rate-limit Count Rate-limit Count Delay
Starter 60 60 - 1/s
Intermediate 80 125 - 2.34/s
Pro 225 180 - 3.75/s

Penalties

The speed is controlled by a rate-limit counter for each (client, pair) which starts at zero, is incremented when penalties are applied, and decremented according to the decay rates above.

A penalty is added to the rate-limit counter for each new order placed (add_order and batch_add) or cancelled (batch_cancel, cancel_all, cancel_all_orders_after, and cancel_order) on the pair. The cancellation penalty varies according to the lifetime of the order.

Add Actions

Action / Order Lifetime
add_order + 1
batch_add1 + (n/2)
1
n represents the number of orders in a batch.

Cancel And Edit Actions

Action / Order Lifetime < 5 s < 10 s < 15 s < 45 s < 90 s < 300 s >  300 s
batch_cancel1 + 8 + 6 + 5 + 4 + 2 + 1 0
edit_order + 6 + 5 + 4 + 2 + 1 0 0
cancel_all + 8 + 6 + 5 + 4 + 2 + 1 0
cancel_all_orders_after + 8 + 6 + 5 + 4 + 2 + 1 0
cancel_order + 8 + 6 + 5 + 4 + 2 + 1 0
1
Rate limits penalty for batch_batch will be cumulative sum of individual orders' penalty, accumulated up to the maximum rate-limit count. In case, the cumulative penalty in the batch exceeds maximum rate-limit count, cancel requests in batch are still accepted.

Note: A client's exact rate-limit counter values can be monitored via the Websockets executions channel.

Errors

"EOrder:Orders limit exceeded"
If the number of open orders in a given pair is exceeded.
"EOrder:Rate limit exceeded""
If the user's max rate count for a given pair is exceeded.

Additional Information

Additional information can be found on our support center.

Errors

Example Error Response

{
  "error": "Already subscribed",
  "method": "subscribe",
  "success": false,
  "time_in": "2021-06-28T07:22:47.907236Z",
  "time_out": "2021-06-28T07:22:48.907236Z"
}

Example Example Error Response

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "error": {
      "type": "string"
    },
    "method": {
      "type": "string"
    },
    "req_id": {
      "maximum": 18446744073709551615,
      "minimum": 0,
      "type": "integer"
    },
    "success": {
      "const": false,
      "type": "boolean"
    },
    "time_in": {
      "format": "date-time",
      "type": "string"
    },
    "time_out": {
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [
    "error",
    "method",
    "success",
    "time_in",
    "time_out"
  ],
  "title": "Error response JavaScript Object Notation (JSON) schema",
  "type": "object"
}

Error responses are request specific and contain at least the following fields:

Response Fields

Field Required Type Description
error yes string The error description.
method yes object The error causing request method name.
req_id no integer Client originated request identifier sent as acknowledgment in the response message.
success yes boolean The status of the error response. Note: always false.
time_in yes string RFC3339 timestamp when the Websockets server received the request.
time_out yes string RFC3339 timestamp when the Websockets server sent the response.

Public Data Errors

The following error messages can be thrown as part of the Subscribe request:

Private Data Errors

The following error messages may be thrown for private data requests. Segments in brackets ([]) indicate additional information that may or not be present in the error message.

FAQs

The Frequently Asked Questions (FAQs) section tries to answer the most common questions that users can encounter.

Connection times out

The server closes any open websocket connection within approximately one (1) minute of inactivity.

Any, for example a ping, request can be used to keep the connection alive.

EOrder:Reduce only:Non-PC

The "EOrder:Reduce only:Non-PC" error response indicated to a problem with the Permitted Client (PC).

For more information please see the Kraken support article Margin trading and Permitted Client self-certification for Ontario, Canada clients.

XBT/USD pair is missing

If you are getting the error "Currency pair not supported XBT/USD" that is because we are using BTC instead of XBT for bitcoin in v2.

Please use the instrument channel to fetch the list of pairs which can be subscribed to via WebSockets API.

API Clients

Below is sample code that can be referenced when writing your own application programming interface (API) client. Please keep in mind that neither Payward nor the third party authors are responsible for losses due to bugs or improper use of the APIs.

Payward has performed an initial review of the safety of the third party code before listing them but cannot vouch for any changes added since then. If you have concerns, please contact support.

Python

Kraken Sample WS API v2 Client (source)

About

Version

The content of this documentation relates to the WebSockets application programming interface (API) version 2.0.1 release.

Note: The Status channel describes the websockets release version and API version.

Change Log

2024-03-01
  • Added event_trigger parameter to the ticker channel. Ticker events can be now triggered by a choice of trades or book updates.
2024-02-15
  • Added cash_order_qty to the executions channel.
2024-01-10
  • Range of valid offsets (from current time) for the deadline parameter changed to 500 milliseconds to 60 seconds, default is 5 seconds.
2023-12-12
  • Added trailing-stop and trailing-stop-limit order types with support for relative price limits.
  • To help maintain trigger protection, switch the trigger reference from index to the last traded price during connectivity issues with index providers.
2023-07-14
  • Add Order, Edit Order requests: added iceberg order type.
2023-04-03
  • OHLC channel: interval field added to the request parameters.
2023-03-22
  • Edit Order request: limit_price field added, price field deprecated.
  • Executions channel: margin field added to order details in snapshot and update responses.
  • Instrument channel: price_precision additional support added. tick_size deprecated.
2023-03-15
  • Executions channel: Added last_qty and last_price fields to trade events.
  • OHLC channel: Added interval and interval_begin fields to responses. timestamp deprecated.
  • Corrected default time_in_force settings.
2022-11-28
Corrected several details in the channel's Executions, Heartbeat, and Instrument sections.
2022-11-23
Corrected the Websockets executions channel hypertext reference in the note regarding how to monitor the exact rate-limit in the Rate Limits's Matching Engine Rate Limits section.
2022-11-22
  • Removed the document's (internal) version from the About section to align it with the production release version (v2.0.0) of the WebSockets application programming interface (API).
    Replacing change log item 2022-07-29 action.
  • Corrected the response data fields in the channel's Status section.
  • Reformatted the style of all items in the Change Log section.
  • Moved Change Log section to become sub-section in About section
  • Corrected stop_price's type to float in the private message's Add Order section.
  • Corrected the types of cash_order_qty, limit_price, and stop_price to float in the private message's Batch Add section.
  • Corrected the types of price, and stop_price to float in the private message's Edit Order section.
2022-11-21
Corrected order_qty's type to float in the private message's Edit Order section.
2022-11-18
  • Added Connection times out entry to the Frequently Asked Questions (FAQs) section.
  • Corrected response data fields in the channel's Open, High, Low, and Close (OHLC) section.
2022-11-16
Added EOrder:Reduce only:Non-PC entry to the Errors and Frequently Asked Questions (FAQs) sections.
2022-11-07
Added Frequently Asked Questions (FAQs) section.
2022-10-21
Corrected stp_type's accepted values in all examples.
2022-10-10
Removed misleading entry from change log item 2021-10-06.
2022-10-04
Corrected channel's Executions parameter to refer to order_qty and added display_qty to channel's Batch Add section.
2022-09-02
Corrected req_id's value maximum value and updated each req_id's value in all examples.
2022-08-12
Enhanced description of conditional field in private messages's Add Order section.
2022-08-05
Style changes in the Change Log section.
2022-08-02
Changed Introduction section to refer to the channel's Instrument section to fetch the list of pairs.
2022-07-29
Added About section to version the documentation.
2022-07-28
Finalized documentation structure for release.
2022-07-07
Clean-up of documentation and added JavaScript Object Notation (JSON) schemas.
2022-01-10
Minor clean-up and clarification.
2021-10-06
trade_id now active on trade channel.
2021-06-27
Added details for instrument and book.
2021-05-11
Initial docs for ticker and trade.
json