NAV Navbar
shell
  • Introduction
  • General
  • REST Public Endpoints
  • REST Authenticated Endpoints
  • Websocket General
  • Websocket Public Channels
  • Websocket Private Channels
  • Websocket Actions
  • Introduction

    This page describes Onederx Exchange API. If you are looking for instrument specifications, please visit https://info.onederx.com/.

    A sample implementation of the API client for Python3 is available at https://github.com/onederx/onederx-python/. It can be installed on most systems via python3 -m pip install onederx.

    General

    The API overview

    All interactions with the exchange could be divided into the following groups:

    All interactions can be done both via REST API and via websocket connection.

    Authentication

    In order to receive private data or run actions, you need to generate an API key. This can be done after login at https://trade.onederx.com/user/api.

    An API key consists of the key itself (which is key id on our servers) and key's secret, which is never transmitted over the network after key generation and is used only for generating HMACs.

    The signature is always generated as hex-encoded HMAC-SHA512 with key equal to API secret and the data of the form url_path || <payload>, where || stands for string concatenation. The form of a payload is different for REST and websocket requests.

    For REST requests, the key and the signature are transmitted via APIKEY and SIGNATURE request headers (more). For websocket requests they are transmitted as fields of the websocket message (see corresponding section).

    Error Codes

    $ curl -s 'https://api.onederx.com/invalid_api_method'
    {
      "error_code": 404,
      "error_msg": "the requested resource does not exist"
    }
    
    $ curl -s 'https://api.onederx.com/v1/order/new' --header "APIKEY: this_is_invalid_key"
    {
      "error_code": 7,
      "error_msg": "invalid key",
      "data": {
        "key": "this_is_invalid_key"
      }
    }
    

    In case of error you receive a JSON message containing the error code in the error_code field and a human-readable error description in the error_msg field. It may optionally include additional data in the data field in a machine-readable form.

    Timestamps

    All timestamps are encoded as the number of nanoseconds since Unix Epoch (1 January 1970 GMT).

    REST request encoding

    All REST requests always receive their parameters inside the HTTP request body with content type application/json. The GET HTTP method can be used in case there are no parameters, otherwise POST HTTP method should be used.

    Sequence number

    Every event in the exchange (order addition, order cancellation, or a trade) has its own sequence number. This number is transmitted over the websocket. In a snapshot (received via websocket or http) the sequence number of all items will be the same and represents the sequence number of the last event included in the snapshot.

    Level 2 data has its own sequence number, which is not related to the sequence number of the Level 3 data.

    Rate limits

    Currently, Onederx allows 50 requests/sec for an API key or IP address (both limitations apply). The limit applies both to HTTP endpoints and to websocket actions.

    The rate limit may be lower for endpoints with large responses (e.g. l3/l2 orderbook snapshots).

    REST Public Endpoints

    Status

    $ curl -s 'https://api.onederx.com/v1/status'
    {
      "error_code": 0,
      "error_msg": "the operation was completed successfully"
    }
    

    Endpoint URL: https://api.onederx.com/v1/status

    This endpoint checks the connection of the specified backend with the exchange engine and validates the status of the exchange engine.

    Symbol details

    $ curl -s "https://api.onederx.com/v1/symbol_details"
    [
      {
        "symbol_type": "futures",
        "symbol": "BTCUSD_P",
        "quote_curr": "BTC",
        "quote_curr_precision": 8,
        "price_units": "USD",
        "maker_fee": "-0.0002",
        "taker_fee": "0.0007",
        "price_step": "0.5",
        "contract_type": "inverse",
        "contract_size": "100",
        "underlying_index": "BTCUSD",
        "max_leverage": 20,
        "index_termination_payment": "5"
      }
    ]
    

    Endpoint URL: https://api.onederx.com/v1/symbol_details

    This endpoint returns details for all supported symbols. Most fields of the response have self-descriptive names (see example), but note the following:

    Ticker

    curl -s "https://api.onederx.com/v1/ticker" --data '{"symbol": "BTCUSD_P"}'
    {
      "symbol": "BTCUSD_P",
      "last_trade_id": 1708408,
      "time": 1543927575577695500,
      "last_trade_price": "3949",
      "price_24h_ago": "3990",
      "low_price_24h": "3788.5",
      "high_price_24h": "3993",
      "volume_24h": "78785",
      "mark_price": "3983.87"
    }
    

    Endpoint URL: https://api.onederx.com/v1/ticker

    This endpoint returns basic trade information for a given symbol. All fields of the response have self-descriptive names (see example).

    L2 snapshot

    curl -s "https://api.onederx.com/v1/l2" --data '{"symbol": "BTCUSD_P"}'
    [
      {
        "seq_num": 4762,
        "symbol": "BTCUSD_P",
        "side": "buy",
        "price": "3052.5",
        "volume": "162",
        "count": 1,
        "timestamp": 1543861085701615000
      },
      ...
    ]
    

    Endpoint URL: https://api.onederx.com/v1/l2

    This endpoint returns L2 order book snapshot. It requires a symbol name and returns the array of all quotes. Most fields of the response have self-descriptive names, but note the following:

    L3 snapshot

    curl -s "https://api.onederx.com/v1/l3" --data '{"symbol": "BTCUSD_P"}'
    [
      {
        "seq_num": 4762,
        "action": 1,
        "symbol": "BTCUSD_P",
        "order_id": 2377,
        "cl_ord_id_sha256": "5441688e46c72a05d4dc1f52afe94a5e4cbf41ce37c4d60f10326ed079c92be0",
        "side": "buy",
        "type": "limit",
        "time_in_force": "gtc",
        "price": "3052.5",
        "volume": "162",
        "initial_volume": "162",
        "event_time": 1543838783521817300
      },
      ...
    ]
    

    Endpoint URL: https://api.onederx.com/v1/l3

    This endpoint returns L3 order book snapshot. It requires a symbol name and returns the array of all active orders. Most fields of the response have self-descriptive names, but note the following:

    Trades snapshot

    Endpoint URL: https://api.onederx.com/v1/trades

    curl -s "https://api.onederx.com/v1/trades" --data '{"symbol": "BTCUSD_P"}'
    [
      {
        "symbol": "BTCUSD_P",
        "id": 1700904,
        "maker_id": 3010052,
        "taker_id": 3010054,
        "type": "normal",
        "side": "buy",
        "price": "3937",
        "volume": "2",
        "event_time": 1543923139114689300
      },
      ...
    ]
    

    This endpoint returns the last 100 trades for a specific symbol. It requires the symbol name and returns an array of last trades. Most fields of the response have self-descriptive names, but note the following:

    The type field can be one of the following:

    Candlesticks History

    curl -s "https://api.onederx.com/v1/candles" -d '{
                                                        "symbol":"BTCUSD_P",
                                                        "resolution":"1m",
                                                        "from":1543839025139307008,
                                                        "to":1543925391632289792
                                                      }'
    [
      {
        "symbol": "BTCUSD_P",
        "resolution": "1m",
        "close_deal_id": 1647610,
        "time": 1543839060000000000,
        "open": "3974",
        "close": "3976",
        "low": "3960",
        "high": "3976",
        "volume": "230"
      },
      ...
    ]
    

    Endpoint URL: https://api.onederx.com/v1/candles

    This endpoint returns all candles for a given symbol of specific resolution in a period of time [from, to]. The parameters from and to are encoded as the number of nanoseconds elapsed since Unix Epoch (1 January 1970 GMT).

    The resolution parameter must be one of the following:

    All fields of the response have self-descriptive names.

    REST Authenticated Endpoints

    How to sign a message

    Authentication is done using the API key and a secret.

    The authentication procedure is as follows:

    Note that:

    All authenticated Endpoints use POST requests. For websocket authentication see the corresponding section of this manual.

    Place Order

    $ curl "https://api.onederx.com/v1/order/new" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 7f79fb1a514f5357232b50cb51ebec653bc55ce6a361d39ef5ca6ecfc12d88366dae3ae67a9b2c8ea2cf0d2aa10f956608a7633f54a318c49a64f4cd94299938" \
             --data '{
                         "post_only": false,
                         "price": "5000",
                         "side": "sell",
                         "symbol": "BTCUSD_P",
                         "time_in_force": "gtc",
                         "timestamp": 1543940390985261824,
                         "type": "limit",
                         "volume": 3
                     }'
    {
      "order_id": 3043841,
      "error_code": 0
    }
    

    Endpoint URL: https://api.onederx.com/v1/order/new

    This endpoint places a new order.

    It takes the following parameters:

    Place a Stop

    $ curl "https://api.onederx.com/v1/order/new" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 11153c2daf946fb54a36c46efc862304127d4b1526f0237af5608a137ecaf5379e4f8336f91d2f3555f2d242eb6e637364f4f2558338df0e0514724c539f201d" \
             --data '{
                         "cl_ord_id": "my stop order #42",
                         "price": "10000",
                         "side": "buy",
                         "stop": true,
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543943418381992960,
                         "type": "market",
                         "volume": 1
                     }'
    {
      "order_id": 3044529,
      "error_code": 0
    }
    

    Endpoint URL: https://api.onederx.com/v1/order/new

    This endpoint creates a new stop order. It takes the same parameters as place order endpoint with the following differences:

    Cancel Order

    $ curl "https://api.onederx.com/v1/order/cancel" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: f35caabb8f0960c222d93a793288740111a568cc43eca4f7367b619c4d297d1f292418929342eb48060b2a8bd4c6d1351205c752322ef2492dc79b35655bc650" \
             --data '{
                         "order_id": 3044321,
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543941110075161856
                     }'
    {
      "error_code": 0,
      "error_msg": "the operation was completed successfully"
    }
    

    Endpoint URL: https://api.onederx.com/v1/order/cancel

    This endpoint cancels the order with an id order_id. It can be applied to both regular and stop orders. The symbol shall be provided in the field symbol.

    Cancel All Orders

    $ curl "https://api.onederx.com/v1/order/cancel/all" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 1ac693764c225ea33ec22c07bd2a11e981078ae5231ea87b888980efb338addceb15dbb8466c9a0c0119cb896e538a66a88e8874953f5d4a530f8c08312a48e4" \
             --data '{
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543941365539789824
                     }'
    {
      "error_code": 0,
      "error_msg": "the operation was completed successfully"
    }
    

    Endpoint URL: https://api.onederx.com/v1/order/cancel/all

    This endpoint cancels all user's active orders for a specific symbol.

    Cancel All Stops

    $ curl "https://api.onederx.com/v1/order/cancel_all_stop" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 5e8c816fdde2562167771d1d7c19f5b2eccfcf313ce4266615a98a166c529d9e940eec6e386f315f8a735730eabf9003df14689afae4ed799eb747bc9e3c44fb" \
             --data '{
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543941423439654144
                     }'
    {
      "error_code": 0,
      "error_msg": "the operation was completed successfully"
    }
    

    Endpoint URL: https://api.onederx.com/v1/order/cancel_all_stop

    This endpoint cancels all user's stop orders for a specific order book.

    List User Orders

    $ curl "https://api.onederx.com/v1/l3_private" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 81d0be720f37fcd38969f3f482cabb9295974fb2ad2b6f9db3e471288bbf27300d7af686baa16e91ae0c93b82d3e050c700750c3ce8e9bea6148031ff3e12764" \
             --data '{
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543942966915552000
                     }'
    [
      {
        "seq_num": 7230420,
        "action": 1,
        "symbol": "BTCUSD_P",
        "order_id": 3044527,
        "cl_ord_id": "my order #31337",
        "side": "sell",
        "type": "limit",
        "time_in_force": "gtc",
        "price": "5000",
        "volume": "3",
        "initial_volume": "3",
        "event_time": 1543942748384414700
      }
    ]
    

    Endpoint URL: https://api.onederx.com/v1/l3_private

    This endpoint returns information about all user's orders for a given symbol. All response fields match corresponding fields for the place order endpoint with the following differences:

    List User Stops

    $ curl "https://api.onederx.com/v1/stop_orders" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 701a793a3fd3bb046a749c0ad8c35c5bff60857961d56d3e4d9c8bca684833853df98c58b6e953ccd357ddc1c99e699b462a94850bfa50e9992c4fadd82fb6a4" \
             --data '{
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543943468517266944
                     }'
    [
      {
        "action": "accepted",
        "symbol": "BTCUSD_P",
        "order_id": 3044529,
        "side": "buy",
        "price": "10000",
        "volume": "1",
        "event_time": 1543943418995757000,
        "cl_ord_id": "my stop order #42"
      }
    ]
    

    Endpoint URL: https://api.onederx.com/v1/stop_orders

    This endpoint returns information about all user's active stop orders for a given symbol. All response fields match corresponding fields for place stop endpoint. The action field is always equal to accepted.

    Balances

    $ curl "https://api.onederx.com/v1/balances" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: 352fd519af63275454d713af98bb661ad6ea972a6937931612e6895debe146a17776ef0ef2382b0e263756b28700039c7c438462a149d47e28c89a2a087ccab8" \
             --data '{
                         "timestamp": 1543942448062115072
                     }'
    [
      {
        "curr": "BTC",
        "balance": "1.9999983269183010449",
        "blocked": "0.000007548622565097",
        "upnl": "-0.0000011053299957"
      }
    ]
    

    Endpoint URL: https://api.onederx.com/v1/balances

    This endpoint returns information about a user's money for all available currencies.

    Positions

    $ curl "https://api.onederx.com/v1/positions" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: de7b1967b1d9af030af177cab06cfb58663315b9faecc7c3c53da651512fde4bd1e4533ce8c634d3c257be80c298481e2f64d42f63b8a856ec82248ed86bf508" \
             --data '{
                         "timestamp": 1543942123327339008
                     }'
    [
      {
        "symbol": "BTCUSD_P",
        "quote_curr": "BTC",
        "position": -3,
        "rpnl": "0",
        "upnl": "-0.0000014965228671",
        "open_price": "3963.0000000000681636",
        "margin": "0.000007548622565097",
        "liquidation_price": "-1",
        "effective_leverage": "0.0003777532639631",
        "event_time": 1543942105931765000
      }
    ]
    

    Endpoint URL: https://api.onederx.com/v1/positions

    This endpoint takes no parameters and returns information about all user's positions. Most of the response fields have self-descriptive names.

    The liquidation_price has special value -1, which means "no liquidation price".

    Private trades

    $ curl "https://api.onederx.com/v1/trades_private" \
             --header "APIKEY: 9147c07be7072c62b68c542bbfeb286f" \
             --header "SIGNATURE: f081e538b33fe5b0d430f48177900f45bd73c478187426dd3dcb6259eff5bd342e9d3f277011b83d4b0296a8b7a39d1af29d56ef3aa09650fd549374c8968aba" \
             --data '{
                         "symbol": "BTCUSD_P",
                         "timestamp": 1543942280094852096
                     }'
    [
      {
        "symbol": "BTCUSD_P",
        "order_id": 3040670,
        "trade_id": 1721840,
        "fee": "0.0000005677517032551",
        "rpnl": "0",
        "rpnl_calculated": false,
        "order_type": "market",
        "order_price": "2967.5",
        "initial_volume": "3",
        "is_maker": false,
        "trade_type": "normal",
        "user_order_side": "sell",
        "trade_price": "3963",
        "trade_volume": "3",
        "remaining_volume": "0",
        "trade_time": 1543938343658893800
      }
    ]
    

    Endpoint URL: https://api.onederx.com/v1/trades_private

    This endpoint returns information about user's last trades for a specific symbol. Most of the response fields have self-descriptive names.

    If rpnl_calculated is false, the trade was an opening trade and rpnl was not calculated.

    Websocket General

    Overview

    Websocket endpoint URL: wss://api.onederx.com/v1/ws.

    In order to begin interacting with Onederx via websocket connection you must connect to the websocket endpoint.

    All messages in both directions are json encoded. Every message has the following fields:

    Payload might be omitted if it is empty.

    Channels

    The data from the exchange to the user is transmitted via channels. A channel carries all messages of a specific type.

    The channels are divided into streams. A stream is a part of a channel associated with specific parameters (e.g. a specific symbol). So, a stream is defined by a pair of channel name and parameters. The schema of the parameters is different for different channels.

    A user can receive multiple streams and multiple channels in one websocket connection.

    To subscribe to some streams, a user must send subscribe message. After that, the exchange will send all data that arrives in this streams to this websocket until the user unsubscribes using unsubscribe message.

    Channels that carry public market data are called public. To see the list of all public channels, refer to the corresponding section.

    Channels that carry private data are called private. In order to subscribe to them, a user must send an auth message first. To see the list of all private channels, refer to the corresponding section.

    All messages from the exchange to the user which belong to a channel have channel and params fields on the top level, identifying the stream they belong to.

    After subscription to a stream, a user will receive a snapshot message in this stream (which has type=snapshot). This message contains the state of the object in question (for example, a snapshot for a stream from l2 channel contains all quotes in the specified order book).

    After the snapshot is received, the user will eventually receive update messages (type=update) for this channel.

    Actions

    A user can send actions via websocket. Each action has its own message type. The schema of the payload depends on the action.

    The reply to an action can be received in different ways:

    Subscribe

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l2"
          },
          {
            "channel": "balances"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "type": "subscribe_response",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l2",
            "success": true
          },
          {
            "channel": "balances",
            "success": false,
            "error": {
              "error_code": 65,
              "error_msg": "user is not authorized"
            }
          }
        ]
      }
    }
    

    The payload of the subscribe message contains only one field named subscriptions. Each item of this array specifies one subscription request. It must contain channel field which must contain the name of the channel to subscribe and params if parameters are applicable to this channel.

    In response the exchange sends a subscribe_response message. Again, only subscription is present in the payload. Each item of the array contains the reply to the corresponding item of the subscribe message payload. The field success shows up if the subscriptions were successful. In case success=false there will be an error field describing what happened.

    Unsubscribe

    user -> exchange

    {
      "type": "unsubscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l2"
          },
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l3"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "type": "unsubscribe_response",
      "payload": {
        "subscriptions": [
          {
            "reason": "user request",
            "reason_code": 1,
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l2",
            "success": true
          },
          {
            "success": false,
            "reason_code": 1,
            "reason": "user request",
            "params": {
              "symbol": "BTCUSD_P"
            },
            "error": {
              "error_code": 63,
              "error_msg": "not subscribed"
            },
            "channel": "l3"
          }
        ]
      }
    }
    

    The unsubscribe message undoes the previous subscribe message. Its structure is very similar to the subscribe message.

    The exchange will acknowledge the message by sending unsubscribe_response. Its schema is very similar to the subscribed_response, except for the following two fields:

    Correct values in these fields are the following:

    Auth

    user -> exchange

    {
      "type": "auth",
      "payload": {
        "timestamp": "1543955052797251072",
        "api_key": "9147c07be7072c62b68c542bbfeb286f",
        "signature": "f7cdc4c9c5551030ecf23b6252c7aadb0c05a77019af33766dfee2bef007d88957020e517f1f1071bb5e8eee9aec8dad2724af95f2fae2ac7bab3f591b863b14"
      }
    }
    

    exchange -> user

    {
      "type": "auth_response",
      "payload": {
        "api_key": "9147c07be7072c62b68c542bbfeb286f",
        "success": true
      }
    }
    

    The auth message authorized the user in this websocket connection.

    The payload of the message must contain the following fields:

    The signature generation scheme differs from the one used in http and is as follows:

    1. You must include timestamp instead of payload in your message. Note that timestamp here must be converted to string.

    2. To sign a message you must apply HMAC-SHA512 to the string /v1/ws || <timestamp>.

    So, the signature is generated as described above with <payload> equal to timestamp sent in the auth message.

    The exchange will acknowledge the message by sending an auth_response message. Note that you can't authorize twice using one websocket connection.

    Deauth

    user -> exchange

    {
      "type": "deauth"
    }
    

    exchange -> user

    {
      "type": "deauth_response",
      "payload": {
        "dropped_subscriptions": [
          {
            "channel": "positions"
          }
        ],
        "success": true
      }
    }
    

    The deauth message undoes the previous authentication. In response you will receive deauth_response message and will be automatically unsubscribed from all private channels.

    Heartbeats

    exchange -> user

    {
      "type": "heartbeat",
      "seq_num": 1337
    }
    

    In order to keep a connection alive you will receive from the exchange a heartbeat message once every second. The seq_num field in these messages enumerates natural numbers and it is scoped to a websocket connection.

    Websocket Public Channels

    Ticker channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "ticker"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "snapshot",
      "payload": {
        "last_trade_id": 1745545,
        "mark_price": "3891.305",
        "last_trade_price": "3874",
        "symbol": "BTCUSD_P",
        "low_price_24h": "3819",
        "volume_24h": "94412",
        "high_price_24h": "6009",
        "time": 1543957352855170800,
        "price_24h_ago": "3825"
      },
      "channel": "ticker"
    }
    
    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "update",
      "payload": {
        "last_trade_id": 1745546,
        "mark_price": "3891.305",
        "last_trade_price": "3874",
        "symbol": "BTCUSD_P",
        "low_price_24h": "3819",
        "volume_24h": "94414",
        "high_price_24h": "6009",
        "time": 1543957352890416400,
        "price_24h_ago": "3825"
      },
      "channel": "ticker"
    }
    

    Channel name: ticker

    This channel provides basic information for a symbol. A new update is sent every second or more frequently if any of the stats changes. An update fully replaces the previous state.

    The fields of update messages have self-descriptive names, except the time field, which is the time of the last trade.

    L2 channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l2"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "snapshot",
      "payload": {
        "snapshot": [
          {
            "count": 1,
            "seq_num": 3996130,
            "timestamp": 1543951133742313500,
            "price": "2943",
            "side": "buy",
            "volume": "121",
            "symbol": "BTCUSD_P"
          },
          ...
        ],
        "updates": [
          {
            "count": 1,
            "seq_num": 3996131,
            "timestamp": 1543957400643094800,
            "price": "3872.5",
            "side": "buy",
            "volume": "47",
            "symbol": "BTCUSD_P"
          },
          ...
        ]
      },
      "channel": "l2"
    }
    
    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "update",
      "payload": {
        "count": 1,
        "seq_num": 3996132,
        "timestamp": 1543957401163098000,
        "price": "3872.5",
        "side": "buy",
        "volume": "45",
        "symbol": "BTCUSD_P"
      },
      "channel": "l2"
    }
    

    Channel name: l2

    L2 channel provides information about the level 2 order book. After subscription you will receive a snapshot for a specific symbol and then real-time updates one by one.

    The sequence number of the current update always equals to the sequence number of the previous update plus one. All updates in the snapshot have the same sequence number. Each symbol has its own L2 sequence number.

    L3 channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l3"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "snapshot",
      "payload": {
        "snapshot": [
          {
            "volume": "121",
            "event_time": 1543951133742211800,
            "seq_num": 7334138,
            "order_id": 3066694,
            "symbol": "BTCUSD_P",
            "initial_volume": "121",
            "price": "2943",
            "time_in_force": "gtc",
            "cl_ord_id_sha256": "527f99d99ce0f56183c7935d276512305db12c5a663168190687dda7abed85d7",
            "action": 1,
            "type": "limit",
            "side": "buy"
          },
          ...
        ],
        "updates": [
          {
            "volume": "2",
            "event_time": 1543957463894523000,
            "seq_num": 7334139,
            "order_id": 3088860,
            "symbol": "BTCUSD_P",
            "initial_volume": "2",
            "price": "3874",
            "time_in_force": "gtc",
            "cl_ord_id_sha256": "b48d89d3155252d88c8dddf5dabcc868298ccdfb1e4454673c7ae70e508d741f",
            "action": 1,
            "type": "limit",
            "side": "buy"
          },
          ...
        ]
      },
      "channel": "l3"
    }
    
    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "update",
      "payload": {
        "volume": "3",
        "event_time": 1543957464776918800,
        "seq_num": 7334140,
        "order_id": 3088861,
        "symbol": "BTCUSD_P",
        "initial_volume": "3",
        "price": "3872",
        "time_in_force": "gtc",
        "cl_ord_id_sha256": "354490a0ed34e49df7575488957291f00c3db5eecbf7bac649609c184363c400",
        "action": 1,
        "type": "limit",
        "side": "buy"
      },
      "channel": "l3"
    }
    

    Channel name: l3

    This channel provides information about the level 3 order book for a specific symbol. After subscription you will receive a snapshot and next real-time updates one by one.

    The sequence number of the current update is always equal to the sequence number of the previous update plus one. All updates in the snapshot have the same sequence number. Each symbol has its own L3 sequence number.

    The action field can take the following values:

    You will not receive an action=3 (order cancelled) message for orders that were fully matched.

    The field cl_ord_id_sha256 contains cl_ord_id hashed with sha256. This can be used by a user to match l3 channel messages to their orders, but not discloses the original value of the cl_ord_id.

    Trades channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "trades"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "snapshot",
      "payload": [
        {
          "volume": "2",
          "event_time": 1543957511425035300,
          "maker_id": 3089020,
          "symbol": "BTCUSD_P",
          "side": "buy",
          "price": "3876",
          "taker_id": 3089021,
          "type": "normal",
          "id": 1745923
        },
        ...
      ],
      "channel": "trades"
    }
    

    Channel name: trades

    This channel provides information about trades for a specific symbol.

    A small number of last trades are pushed to a user in the snapshot message. After that only new trades are sent.

    Candles channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P",
              "resolution": "1m"
            },
            "channel": "candles"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "type": "snapshot",
      "channel": "candles",
      "params": {
        "symbol": "USDBTC_P",
        "resolution": "1m"
      },
      "payload": [
        {
          "symbol": "USDBTC_P",
          "resolution": "1m",
          "close_deal_id": 972,
          "time": 1566918780000000000,
          "open": "10282",
          "close": "10149",
          "low": "10137",
          "high": "10326",
          "volume": "93"
        },
        {
          "symbol": "USDBTC_P",
          "resolution": "1m",
          "close_deal_id": 1011,
          "time": 1566918840000000000,
          "open": "10137",
          "close": "10139",
          "low": "10126",
          "high": "10326",
          "volume": "50"
        }
      ]
    }
    
    {
      "type": "update",
      "channel": "candles",
      "params": {
        "symbol": "USDBTC_P",
        "resolution": "1m"
      },
      "payload": {
        "symbol": "USDBTC_P",
        "resolution": "1m",
        "close_deal_id": 1012,
        "time": 1566918840000000000,
        "open": "10137",
        "close": "10134",
        "low": "10126",
        "high": "10326",
        "volume": "53"
      }
    }
    

    Channel name: candles

    Candles channel provides information about candles for specific symbol and resolution. Snapshot message consists of the candles for the last 1440 ticks, for more candles see Candlesticks History.

    Supported resolutions are:

    Websocket Private Channels

    Private L3 Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "l3_private"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "snapshot",
      "payload": {
        "snapshot": [
          {
            "volume": "3",
            "cl_ord_id": "my order #31337",
            "event_time": 1543961172799799600,
            "seq_num": 7363236,
            "order_id": 3101760,
            "symbol": "BTCUSD_P",
            "price": "5000",
            "time_in_force": "gtc",
            "initial_volume": "3",
            "action": 1,
            "type": "limit",
            "side": "sell"
          }
        ],
        "updates": []
      },
      "channel": "l3_private"
    }
    
    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "update",
      "payload": {
        "volume": "3",
        "cl_ord_id": "my order #31338",
        "event_time": 1543961205865346800,
        "seq_num": 7363513,
        "order_id": 3101874,
        "symbol": "BTCUSD_P",
        "price": "5000",
        "time_in_force": "gtc",
        "initial_volume": "3",
        "action": 1,
        "type": "limit",
        "side": "sell"
      },
      "channel": "l3_private"
    }
    

    Channel name: l3_private

    This provides information about a user's active orders for a specific symbol. It is similar to public L3 channel with the following differences:

    See information on L3 channel for more details.

    Private Trades Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "params": {
              "symbol": "BTCUSD_P"
            },
            "channel": "trades_private"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "snapshot",
      "payload": [
        {
          "remaining_volume": "0",
          "fee": "0.0000005677517032551",
          "order_type": "market",
          "order_id": 3040670,
          "user_order_side": "sell",
          "symbol": "BTCUSD_P",
          "trade_volume": "3",
          "trade_id": 1721840,
          "trade_type": "normal",
          "rpnl_calculated": false,
          "order_price": "2967.5",
          "initial_volume": "3",
          "trade_time": 1543938343658893800,
          "trade_price": "3963",
          "rpnl": "0",
          "is_maker": false
        },
        ...
      ],
      "channel": "trades_private"
    }
    
    {
      "params": {
        "symbol": "BTCUSD_P"
      },
      "type": "update",
      "payload": {
        "remaining_volume": "0",
        "fee": "0.000000579150579150675",
        "order_type": "limit",
        "order_id": 3103843,
        "user_order_side": "sell",
        "symbol": "BTCUSD_P",
        "trade_volume": "3",
        "trade_id": 1753706,
        "trade_type": "normal",
        "rpnl_calculated": false,
        "order_price": "1000",
        "initial_volume": "3",
        "trade_time": 1543961764759663400,
        "trade_price": "3885",
        "rpnl": "0",
        "is_maker": false
      },
      "channel": "trades_private"
    }
    

    Channel name: trades_private

    This channel provides information about user's executions for a specific symbol. The format is similar to the one returned by the corresponding REST handler.

    Balances Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "channel": "balances"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": null,
      "type": "snapshot",
      "payload": [
        {
          "upnl": "0.000654040110573",
          "balance": "2.000653493208290894225",
          "curr": "BTC",
          "blocked": "0.000045949547396952"
        }
      ],
      "channel": "balances"
    }
    
    {
      "params": null,
      "type": "update",
      "payload": {
        "upnl": "0.0006542735237676",
        "balance": "2.000653726621485494225",
        "curr": "BTC",
        "blocked": "0.002297200259730408"
      },
      "channel": "balances"
    }
    

    Channel name: balances

    Balances channel provides information about user's money for each supported currency. Available money can be calculated as balance - blocked.

    Transactions Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "channel": "transactions"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "type": "snapshot",
      "channel": "transactions",
      "params": null,
      "payload": [
        {
          "type": "deposit",
          "id": 1,
          "curr": "BTC",
          "amount": "2",
          "done": true,
          "time": 1544783718574210800
        },
        {
          "type": "withdrawal",
          "id": 4,
          "curr": "BTC",
          "dest_address": "jhuyt1762t3gu1g23712g312311",
          "amount": "0.1",
          "fee": "0.001",
          "done": true,
          "time": 1545649509779791400
        },
        {
          "type": "withdrawal",
          "id": 5,
          "curr": "BTC",
          "dest_address": "3Afyt1762t3gu1g23712g312342",
          "amount": "0.1",
          "fee": "0.001",
          "done": true,
          "time": 1545649803053416200
        }
      ]
    }
    
    {
      "type": "update",
      "channel": "transactions",
      "params": null,
      "payload": {
        "type": "withdrawal",
        "id": 8,
        "curr": "BTC",
        "dest_address": "kjoasijdh874rf9uhe923e23",
        "amount": "0.2",
        "fee": "0.002",
        "done": false,
        "time": 1545658207871538200
      }
    }
    

    Channel name: transactions

    Transactions channel provides information about both deposits and withdrawals. Transactions are sorted by time.

    Positions Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "channel": "positions"
          }
        ]
      }
    }
    

    exchange -> user

    {
      "params": null,
      "type": "snapshot",
      "payload": [
        {
          "upnl": "0.0006467368918731",
          "event_time": 1543963155722557200,
          "effective_leverage": "0.0026727774114301",
          "quote_curr": "BTC",
          "symbol": "BTCUSD_P",
          "margin": "0.000053473893281382",
          "open_price": "4467.5684779248087563",
          "liquidation_price": "-1",
          "position": -21,
          "rpnl": "0"
        }
      ],
      "channel": "positions"
    }
    
    {
      "params": null,
      "type": "update",
      "payload": {
        "upnl": "0.0006437428696732",
        "event_time": 1543963183336179500,
        "effective_leverage": "0.0027999108324001",
        "quote_curr": "BTC",
        "symbol": "BTCUSD_P",
        "margin": "0.00155696275049747",
        "open_price": "4437.3827072442419299",
        "liquidation_price": "-1",
        "position": -22,
        "rpnl": "0"
      },
      "channel": "positions"
    }
    

    Channel name: positions

    Positions channel provides information about all user's positions.

    Stop Orders Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "channel": "stop_orders",
            "params": {"symbol": "BTCUSD_P"}
          }
        ]
      }
    }
    

    exchange -> user

    {
       "type" : "snapshot",
       "channel": "stop_orders",
       "params": {"symbol": "BTCUSD_P"},
       "payload" : [
          {
             "price" : "5030",
             "volume" : "30",
             "order_id" : 6124,
             "event_time" : 1531396809972902619,
             "action" : "accepted",
             "symbol" : "BTCUSD_P",
             "side" : "sell"
          }
       ]
    }
    
    {
       "type" : "update",
       "channel": "stop_orders",
       "params": {"symbol": "BTCUSD_P"},
       "payload" : {
          "price" : "4848",
          "event_time" : 1531396540082034288,
          "order_id" : 4303,
          "action" : "accepted",
          "side" : "sell",
          "volume" : "20",
          "symbol" : "BTCUSD_P"
       }
    }
    
    {
       "type" : "update",
       "channel": "stop_orders",
       "params": {"symbol": "BTCUSD_P"},
       "payload" : {
          "event_time" : 1531396742684877213,
          "symbol" : "BTCUSD_P",
          "order_id" : 5672,
          "action" : "deleted"
       }
    }
    
    {
       "type" : "update",
       "channel": "stop_orders",
       "params": {"symbol": "BTCUSD_P"},
       "payload" : {
          "event_time" : 1531396541140495690,
          "symbol" : "BTCUSD_P",
          "action" : "triggered",
          "order_id" : 4303
       }
    }
    

    Channel name: stop_orders

    Stop orders channel provides information about user's stop orders for a specific symbol.

    The action field can take the following values:

    Action Replies Channel

    user -> exchange

    {
      "type": "subscribe",
      "payload": {
        "subscriptions": [
          {
            "channel": "action_replies",
            "params": {"symbol": "BTCUSD_P"}
          }
        ]
      }
    }
    

    exchange -> user

    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol": "BTCUSD_P"},
      "payload": {
        "type": "action_error",
        "symbol": "BTCUSD_P",
        "cl_req_id": 777,
        "success": false,
        "data": {
          "error_code": 48,
          "error_msg": "not enough money",
          "data": {
            "action": "add",
            "cl_ord_id": "45dc55c523a311f01a6bc9af8497cd098300cf70288483177295a09fa2db92a39c7a57c1a293b167008ce642ccb6cad749f5238b747ab976e6260eed81c948ed"
          }
        }
      }
    }
    
    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol": "BTCUSD_P"},
      "payload": {
        "type": "order_new",
        "symbol": "BTCUSD_P",
        "cl_req_id": 777,
        "success": true,
        "data": {
          "order_id": 217
        }
      }
    }
    
    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol": "BTCUSD_P"},
      "payload": {
        "type": "order_cancel",
        "symbol": "BTCUSD_P",
        "cl_req_id": 778,
        "success": true
      }
    }
    
    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol": "BTCUSD_P"},
      "payload": {
        "type": "order_cancel_all",
        "symbol": "BTCUSD_P",
        "cl_req_id": 779,
        "success": true
      }
    }
    
    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol": "BTCUSD_P"},
      "payload": {
        "type": "order_cancel_all_stop",
        "symbol": "BTCUSD_P",
        "cl_req_id": 800,
        "success": true
      }
    }
    

    Channel name: action_replies

    Action replies channel provides confirmations on user's actions such as order creation, order cancellation, etc (see next section . The type of message inside the payload can be one of the following:

    The corresponding action can be identified using cl_req_id (see below).

    Websocket Actions

    Actions overview

    All actions except symbol details pseudo-action require authentication. The authentication should be done by sending a correct auth message to the websocket connection before sending any actions.

    The action might be immediately rejected or processed. In this case, an immediate_action_reply is sent as the response to this action.

    Otherwise, the response (representing either success or error) will be sent to action replies channel. The messages in action replies channel will be received by other connections which belong to this user (that means, corresponding auth message was sent). For more information, see the example of replies for a place order action

    In order to distinguish replies for different actions, one must use cl_req_id field. It is accepted by all actions and is sent back both in immediate_action_reply messages and in corresponding messages inside the action_replies channel.

    Place Order Action

    user -> exchange

    {
      "type": "order_new",
      "payload": {
        "symbol": "BTCUSD_P",
        "side": "buy",
        "volume": "1",
        "price": "5000",
        "type": "limit",
        "time_in_force": "gtc",
        "cl_req_id": 777
      }
    }
    

    exchange -> user

    {
      "type": "immediate_action_reply",
      "action": "order_new",
      "cl_req_id": 777,
      "success": false,
      "payload": {
        "error_code": 12345,
        "error_msg": "some cryptic error occurred"
      }
    }
    

    or

    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol":"BTCUSD_P"},
      "payload": {
        "type": "order_new",
        "symbol": "BTCUSD_P",
        "cl_req_id": 777,
        "success": true,
        "data": {
          "order_id": 217
        }
      }
    }
    

    or

    {
      "type": "update",
      "channel": "action_replies",
      "params": {"symbol": "BTCUSD_P"},
      "payload": {
        "type": "action_error",
        "symbol": "BTCUSD_P",
        "cl_req_id": 777,
        "success": false,
        "data": {
          "error_code": 48,
          "error_msg": "not enough money",
          "data": {
            "action": "add",
            "cl_ord_id": "45dc55c523a311f01a6bc9af8497cd098300cf70288483177295a09fa2db92a39c7a57c1a293b167008ce642ccb6cad749f5238b747ab976e6260eed81c948ed"
          }
        }
      }
    }
    

    Action name: order_new

    The payload of the message is the same as in the corresponding REST message. In case of error you will receive an immediate reply. In case of success you will receive a confirmation in action_replies channel with type order_new. Also, an error with an action_error type may be sent in action_replies channel.

    Cancel Order Action

    user -> exchange

    {
      "type": "order_cancel",
      "payload": {
        "symbol": "BTCUSD_P",
        "order_id": 123,
        "cl_req_id": 778
      }
    }
    

    Action name: order_cancel

    The payload of the message is the same as in the corresponding REST message. In case of error you will receive an immediate reply. In case of success you will receive a confirmation in action_replies channel with type order_cancel. Also, an error with an action_error type may be sent in action_replies channel.

    Cancel All Orders Action

    user -> exchange

    {
      "type": "order_cancel_all",
      "payload": {
        "symbol": "BTCUSD_P",
        "cl_req_id": 779
      }
    }
    

    Action name: order_cancel_all

    The payload of the message is the same as in the corresponding REST message. In case of error you will receive an immediate reply. In case of success you will receive a confirmation in action_replies channel with an order_cancel_all type. Also, an error with an action_error type may be sent in action_replies channel.

    Cancel All Stops Action

    user -> exchange

    {
      "type": "order_cancel_all_stop",
      "payload": {
        "symbol": "BTCUSD_P",
        "cl_req_id": 800
      }
    }
    

    Action name: order_cancel_all_stop

    The payload of the message is the same as in the corresponding REST message. In case of error you will receive an immediate reply. In case of success you will receive a confirmation in action_replies channel with an order_cancel_all_stops type. Also, an error with an action_error type may be sent in action_replies channel.

    Symbol Details Action

    user -> exchange

    {
      "type": "symbol_details"
    }
    

    exchange -> user

    {
      "action": "symbol_details",
      "cl_req_id": 0,
      "type": "immediate_action_reply",
      "payload": [
        {
          "underlying_index": "BTCUSD",
          "price_step": "0.5",
          "contract_size": "100",
          "maker_fee": "-0.0002",
          "quote_curr": "BTC",
          "symbol": "BTCUSD_P",
          "max_leverage": 20,
          "contract_type": "inverse",
          "taker_fee": "0.0007",
          "quote_curr_precision": 8,
          "symbol_type": "futures",
          "price_units": "USD",
          "index_termination_payment": "5"
        }
      ],
      "success": true
    }
    

    Action name: symbol_details

    This is pseudo-action. The reply will always arrive as immediate_action_reply. The contents of the reply are the same as the response to the corresponding REST request