Trading API

General information

B2Trader provides both HTTP and WebSocket APIs for interacting with the exchange. You can use either of these APIs to get read access to public market data and use a private API to get private read access to your account.

The public HTTP endpoints are accessed via GET requests while the private endpoints are accessed via HMAC-SHA512-signed POST and DELETE requests using API keys. Both types of HTTP endpoints return results in the JSON format.

You can use the WebSocket API to receive push notifications informing you about any updates to public order books and your private account. Similar to the HTTP API, information related to your private account is obtained via HMAC-SHA512-signed requests using API keys.

All endpoints are relative and resolved based on a specified host name. Both the host name and your administrator credentials are configured when setting up the exchange.

Required parameters are marked with *.

Private API

The following two HTTP headers must be present in any REST request:

  • Key — specifies a public key

  • Sign — specifies a hash for decrypting the payload

The payload is contained in a JSON request body. The HMAC-SHA512 algorithm is used for payload hashing.

All private REST requests should include the following fields:

  • ts — a string value indicating the current date and time in the UTC format, for example: “2019-12-20T08:20:51”

  • nonce — a 64-bit integer value used for authentication of encrypted requests; based on a time frame defined for a public key used for encryption, each nonce value must be unique for any request sent within every 22 seconds (for example, once nonce is assigned a value of 12345, next time this value can be used only in 22 seconds)

Obtaining API keys

Important

The recommended approach to obtaining the public and private API keys, is to switch to Profile > API key management in the B2Core UI and click Generate New Key.

The API keys are provided in the form of a UTF-8-encoded UUID string, for example: “ca3a03e1-fc5c-4954-99dc-876db3997d8f”. You can copy the keys to the clipboard and use them in your application.

Obtaining API keys via API

If for some reason you cannot use the recommended approach described above, use the following method to obtain the list of API keys via API.

Request

No parameters.

GET[base]/frontoffice/api/key

Response

publicKey string

The public key, in the UTF-8-encoded UUID string format.

name string

The public key name.

isInfo boolean

If true, the public key enables obtaining the market data via API.

isTrade boolean

If true, the public key enables trading via API.

ipWhiteList array

An array of string values, indicating the IP addresses included in the safelist.

RESPONSE BODY EXAMPLE
[
  {
      "publicKey": "1b674a45-9f1b-4b08-b69a-f02041a1d0f4",
      "name": "Trading key",
      "isInfo": true,
      "isTrade": true,
      "ipWhiteList": []
  },
  {
      "publicKey": "d39a6af3-ab28-4686-8526-3589452be74f",
      "name": "Market data key",
      "isInfo": true,
      "isTrade": false,
      "ipWhiteList": [
        "127.0.0.1"
      ]
  }
]

API rate limits

  • /frontoffice/*1 request per second

  • /marketdata/*2 requests per second


Public REST methods

Supported instruments

Returns up-to-date information about all currency pairs (instruments) supported by the exchange.

Request

No parameters.

GET[base]/frontoffice/api/info

GET /frontoffice/api/info HTTP/1.1
Host: host.name

Response

baseAsset string

The base asset

quoteAsset string

The quote asset

minAmount number

The minimum asset amount that can be traded

priceDeviation number

The allowed price deviation for limit orders, upon exceeding which an order will be cancelled

hidden number

The instrument availability: 0 — available; 1 — hidden (trading is not recommended because this instrument may be due to be disconnected)

fee number

The fee charged for trades involving the instrument

makerFee number

The maker fee charged for orders providing market liquidity

makerFeeLimit number

The minimum maker fee charged for a trade

takerFee number

The taker fee charged for orders diminishing market liquidity

takerFeeLimit number

The minimum taker fee charged for a trade

priceScale number

The minimum increment with which an asset price can be changed at a time

amountScale number

The minimum increment with which an asset amount can be changed at a time

createdAt string

The date and time when an instrument has been created: YYYY-MM-DDThh:mm:ss

updatedAt string

The date and time when an instrument has last been updated: YYYY-MM-DDThh:mm:ss

status number

The instrument status:

  • 0 — open

  • 1 — halted (new orders are not accepted, open orders are cancelled)

  • 2 — paused (new orders are not accepted, open orders are awaiting execution)

side number

The order sides permitted for instrument trading:

  • 0 — buy and sell

  • 1 — buy

  • 2 — sell

RESPONSE BODY EXAMPLE
{
  "serverTime": 636880696809972288,
  "pairs": {
    "btc_usdt": {
      "baseAsset": "btc",
      "quoteAsset": "usdt",
      "minAmount": 0,
      "priceDeviation": 0,
      "hidden": 0,
      "fee": 0,
      "makerFee": 0,
      "makerFeeLimit": 0,
      "takerFee": 0.001,
      "takerFeeLimit": 0,
      "priceScale": 6,
      "amountScale": 6,
      "createdAt": "2019-11-14T16:18:49.253354",
      "updatedAt": "2019-11-14T16:18:49.253354",
      "status": 0,
      "side": 0
    },
    "gnt_usdt": {
      "baseAsset": "gnt",
      "quoteAsset": "usdt",
      "minAmount": 0,
      "priceDeviation": 0,
      "hidden": 0,
      "fee": 0,
      "makerFee": 0,
      "makerFeeLimit": 0,
      "takerFee": 0.001,
      "takerFeeLimit": 0,
      "priceScale": 5,
      "amountScale": 5,
      "createdAt": "2019-11-14T16:18:49.255354",
      "updatedAt": "2019-11-14T16:18:49.255354",
      "status": 0,
      "side": 0
    }
  }
}

Order book snapshot

Returns an order book information for a specified currency pair (instrument).

Request

Path parameters:

instrument *

The instrument identifier: {baseAsset}_{quoteAsset}

GET[base]/marketdata/instruments/{instrument}/depth

GET /marketdata/instruments/eth_btc/depth HTTP/1.1
Host: host.name

Response

instrument string

The instrument identifier (the one specified in the request)

bids array

Each element of the array represents a particular order and contains numeric fields amount and price

asks array

Each element of the array represents a particular order and contains numeric fields amount and price

version number

The current order book snapshot version

askTotalAmount number

The total amount of all ask (sell) orders

bidTotalAmount number

The total amount of all bid (buy) orders

snapshot boolean

A self-contained snapshot (always true for this request)

RESPONSE BODY EXAMPLE
{
  "instrument": "eth_btc",
  "bids": [
    {
      "amount": 0.3092258,
      "price": 0.01734264
    },
    {
      "amount": 51.61494099,
      "price": 0.01734363
    }
  ],
  "asks": [
    {
      "amount": 133.52370356,
      "price": 0.01739337
    },
    {
      "amount": 9.16854518,
      "price": 0.01739838
    }
  ],
  "version": 1891724,
  "askTotalAmount": 1849.11363582,
  "bidTotalAmount": 809.23878372,
  "snapshot": true
}

Instrument candles

Returns candlestick chart data for a specified currency pair (instrument).

Request

Path parameters:

instrument *

The instrument identifier: {baseAsset}_{quoteAsset}

Query parameters:

startDate *

The date and time indicating the beginning of a required time interval: YYYY-MM-DDThh:mm:ss

endDate *

The date and time indicating the end of a required time interval: YYYY-MM-DDThh:mm:ss

type *

The detail level of the chart data; the following values are supported:

  • 1m1 minute

  • 5m5 minutes

  • 15m15 minutes

  • 30m30 minutes

  • 1h1 hour

  • 12h12 hours

  • 1d1 day

  • 1w1 week

  • 1M1 month

count number

The number of candles to return; the default value is 1000 (which is the maximum supported value)

GET[base]/marketdata/instruments/{instrument}/history

GET /marketdata/instruments/btc_usdt/history?startDate=2019-03-13T09:00:00&endDate=2019-03-13T11:00:00&type=1h&count=2 HTTP/1.1
Host: host.name

Response

instrument string

The same as in the request

start string

The same as in the request

end string

The same as in the request

low number

The lowest trade price

high number

The highest trade price

volume number

The total volume of trades

quoteVolume number

The total traded volume of a quote asset

open number

The opening price

close number

The closing price

RESPONSE BODY EXAMPLE
{
  "success": true,
  "instrument": "btc_usdt",
  "data": [
    {
      "instrument": "btc_usdt",
      "start": "2019-03-13T09:00:00Z",
      "end": "2019-03-13T10:00:00Z",
      "low": 3842.855,
      "high": 3855.445,
      "volume": 4,
      "quoteVolume": 0,
      "open": 3855.105,
      "close": 3842.855
    },
    {
      "instrument": "btc_usdt",
      "start": "2019-03-13T10:00:00Z",
      "end": "2019-03-13T11:00:00Z",
      "low": 3834.355,
      "high": 3848.855,
      "volume": 26,
      "quoteVolume": 0,
      "open": 3842.865,
      "close": 3835.655
    }
  ],
  "startDateTime": "2019-03-13T09:00:00Z",
  "endDateTime": "2019-03-13T11:00:00Z"
}

Asset info

Returns up-to-date information about supported assets.

Request

No parameters.

GET[base2]/asset

GET /asset HTTP/1.1
Host: host.name

Response

name string

The asset name

can_withdraw string

If true, the asset can be withdrawn

can_deposit string

If true, the asset can be deposited

min_withdraw string

The minimum withdrawal/deposit amount

max_withdraw string

The maximum withdrawal/deposit amount

RESPONSE BODY EXAMPLE
{
  "BTC": {
    "name": "btc",
    "can_withdraw": true,
    "can_deposit": true,
    "min_withdraw": "0.00000001",
    "max_withdraw": "100000000"
  },
  "USDT": {
    "name": "usdt",
    "can_withdraw": true,
    "can_deposit": true,
    "min_withdraw": "0.00000001",
    "max_withdraw": "100000000"
}

Summary

Returns summary information about a specified market. The data is aggregated for the last 24 hours.

Request

No parameters.

GET[base2]/summary

GET /summary HTTP/1.1
Host: host.name

Response

id string

The market identifier

last string

The price of the most recent trade executed within the last 24 hours; 0 if more than 24 hours have passed since the most recent trade has been executed on this market

lowestAsk string

The lowest ask (sell) price by this time

highestBid string

The highest bid (buy) price by this time

percentChange string

The price change within the last 24 hours, in percents

baseVolume string

The total volume of assets traded within the last 24 hours (converted to a base asset)

quoteVolume string

The total volume of assets traded within the last 24 hours (converted to a quote asset)

isFrozen string

The current market status: 0 — active (orders can be placed and are being processed); 1 — temporarily suspended (orders cannot be placed and are not processed)

high24hr string

The maximum trade price within the last 24 hours

low24hr string

The minimum trade price within the last 24 hours

RESPONSE BODY EXAMPLE
{
  "BTC_USDT": {
    "id": "btc_usdt",
    "last": "10978.93578",
    "lowestAsk": "10979.0",
    "highestBid": "10978.71",
    "percentChange": "0.0813730364297798727996051454",
    "baseVolume": "6.47119743",
    "quoteVolume": "70829.9781692126756",
    "isFrozen": "0",
    "high24hr": "10985.0049",
    "low24hr": "10857.95376"
  },
  "BTC_USD": {
    "id": "btc_usd",
    "last": "0",
    "lowestAsk": "0",
    "highestBid": "0",
    "percentChange": "0",
    "baseVolume": "0",
    "quoteVolume": "0",
    "isFrozen": "0",
    "high24hr": "0",
    "low24hr": "0"
  }
}

Ticker info

Returns up-to-date ticker information.

Request

No parameters.

GET[base2]/ticker

GET /ticker HTTP/1.1
Host: host.name

Response

base_name string

The base asset name

quote_name string

The quote asset name

last_price string

The price of the most recent trade executed within the last 24 hours; 0 if more than 24 hours have passed since the most recent trade has been executed on this market

base_volume string

The total base asset volume traded within the last 24 hours

quote_volume string

The total quote asset volume traded within the last 24 hours

isFrozen string

The current market status: 0 — active (orders can be placed and are being processed); 1 — temporarily suspended (orders cannot be placed and are not processed)

RESPONSE BODY EXAMPLE
{
  "dash_btc": {
    "base_name": "dash",
    "quote_name": "btc",
    "last_price": "0",
    "base_volume": "0",
    "quote_volume": "0",
    "isFrozen": "1"
  },
  "eth_usdt": {
    "base_name": "eth",
    "quote_name": "usdt",
    "last_price": "423.9936",
    "base_volume": "2942.97774",
    "quote_volume": "1273092.080666887",
    "isFrozen": "0"
  }
}

Trades info

Returns information about all trades related to a specified currency pair (instrument) and executed within the last 24 hours.

Request

Path parameters:

instrument *

The instrument identifier: {baseAsset}_{quoteAsset}

GET[base2]/trades/{instrument}

GET /trades/btc_usd HTTP/1.1
Host: host.name

Response

tradeID string

The trade identifier

price string

The trade price

base_volume string

The base asset amount

quote_volume string

The quote asset amount

trade_timestamp string

The date and time when a trade has been executed, in the format of a Unix time stamp

type string

The trade side: buy or sell

RESPONSE BODY EXAMPLE
[
  {
    "tradeID": "1247307",
    "price": "10093.92246491",
    "base_volume": "0.0259",
    "quote_volume": "261.432591841169",
    "trade_timestamp": "1599577070",
    "type": "buy"
  },
  {
    "tradeID": "1247309",
    "price": "10091.69185435",
    "base_volume": "0.0754",
    "quote_volume": "760.913565817990",
    "trade_timestamp": "1599577128",
    "type": "sell"
  }
]

Private REST methods

Place an order

Places a new order on the exchange.

Request

The ts and nonce values should be specified for a request.

Body:

instrument* string

The order currency pair identifier: {baseAsset}_{quoteAsset}

type* string

The order side: buy or sell

amount* number

The order amount (must be greater than 0)

price number

The order price (required for limit orders, optional for market orders); if isLimit is true, this value must be greater than 0; otherwise, it can be equal to 0

activationPrice number Currently not supported

This parameter should be specified only if isStop is set to true

isLimit boolean

Set this value to true to place a limit order; set this value to false to place a market order (see Flags combinations to learn more)

isStop boolean Currently not supported

Set this value to true to place a stop market or stop limit order, depending on the isLimit setting (see Flags combinations to learn more)

isFok boolean

If true, the order is supposed to be executed immediately in a full amount or cancelled if not filled (see Flags combinations to learn more)

clientOrderId number

The order identifier provided by a client (can be any UUID strings, except for 00000000-0000-0000-0000-000000000000); must be unique among the orders placed on behalf of a particular client, meaning that an order with a clientOrderId identical to the one of an already placed order will not by placed

POST[base]/frontoffice/api/order

POST /frontoffice/api/order HTTP/1.1
Host: host.name
Key: 7fa6ceec-d8fc...
Sign: 7ae49b5b-99db...

{
  "ts": "2019-12-12T01:01:01",
  "nonce": 4,
  "order": {
    "instrument": "btc_usdt",
    "type": "sell",
    "amount": 1,
    "price": 1,
    "isLimit": true,
    "isStop": false,
    "isFok": false,
    "activationPrice": 0,
    "clientOrderId": "6fdf688e-00b0-4c68-82dd-3aee5c727ed1"
  }
}
const crypto = require('crypto');
const https = require('https');
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Host = "host.name"; // Change to your host name
const Method = '/frontoffice/api/order'
const Payload = new Date().toISOString();
const body = {
  ts: Payload,
  nonce:1,
  order: {
    instrument: 'eth_usd',
    type: 'buy',
    amount: 1,
    price: 1,
    isLimit: true
  }
};
const data = JSON.stringify(body);
const Sign = crypto
  .createHmac('sha512', Secret)
  .update(data)
  .digest('hex')
  .toUpperCase();
const options = {
  hostname: Host,
  path: Method,
  port: Port,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Key,
    'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
    Sign
  }
};
const req = https.request(options, res => {
  console.log(`statusCode: ${res.statusCode}`);
  res.on('data', d => {
    process.stdout.write(d);
  });
});
req.on('error', e => {
  console.error(e);
});
req.write(data);
req.end();

Response

Returns an Order Object.


Cancel an order

Cancels a specified order.

Request

The ts and nonce values should be specified for a request.

Path parameters:

id *

The order identifier: either orderId (the one specified in a response to a Place an Order request) or clientOrderId (the one specified in the Place an Order request)

DELETE[base]/frontoffice/api/orders/{id}

DELETE /frontoffice/api/orders/-72057594037927933&ts=2019-12-12T01:01:01&nonce=4 HTTP/1.1
Host: host.name
Key: 7fa6ceec-d8fc...
Sign: 7ae49b5b-99db...
const crypto = require('crypto');
const https = require('https');
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Host = "host.name"; // Change to your host name
const Payload = new Date().toISOString();
const OrderId = '-72057594037927933';
const Method = `/frontoffice/api/orders?OrderId=${OrderId}&ts=${Payload}&nonce=2`
async function deleteOrder() {
  const Sign = crypto
    .createHmac('sha512', Secret)
    .update(`?OrderId=${OrderId}&ts=${Payload}&nonce=2`)
    .digest('hex')
    .toUpperCase();
  const options = {
    hostname: Host,
    path: Method,
    port: Port,
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
      Key,
      Sign
    }
  };
  const req = https.request(options, res => {
    console.log(`statusCode: ${res.statusCode}`);
    console.log(`statusMessage: ${res.statusMessage}`);
    res.on('data', d => {
      process.stdout.write(d);
    });
  });
  req.on('error', e => {
    console.error(e);
  });
  req.end();
}
deleteOrder().catch(err => {
  console.log(err);
});

Response

Returns an HTTP status code indicating the request result:

  • 200 — the order has been cancelled

  • 400 — the request has not been processed due to an unexpected error

  • 404 — the order with a specified ID has not been found


Orders history

Returns a history of orders meeting specified criteria or a history of all orders if no parameters are defined in a request.

Request

The ts and nonce values should be specified for a request.

Query parameters:

market

The currency pair for which the orders history should be obtained (for example, btc_usdt)

side

The order side: buy or sell

status

The current order status: Working, Rejected, Cancelled or Completed

startDate

The date and time indicating the beginning of a required time interval: YYYY-MM-DDThh:mm:ss.s

endDate

The date and time indicating the end of a required time interval: YYYY-MM-DDThh:mm:ss.s

AscOrder

The field to be used as a criteria for sorting response data in ascending order; any of the following fields can be specified:

  • TradeSeq

  • TradeTime

  • OrderId

  • Amount

  • Instrument

  • Side

  • ExecutionPrice

  • Commission

DescOrder

The field to be used as a criteria for sorting response data in descending order; for a list of support fields, see the AscOrder parameter description

isHideCanceled

If true, canceled orders are not returned

page

The number of a page listing the orders to be returned (when the perPage parameter is defined)

perPage

The number of orders to be listed on a single page

GET[base]/frontoffice/api/order_history

GET /frontoffice/api/order_history?market=btc_usdt&ts=2019-12-12T01:01:01&nonce=4 HTTP/1.1
Host: host.name
Key: 7fa6ceec-d8fc...
Sign: 7ae49b5b-99db...
const crypto = require('crypto');
const https = require('https');
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Host = "host.name"; // Change to your host name
const Payload = new Date().toISOString();
const Method = `/frontoffice/api/order_history?ts=${Payload}&market=btc_usd&nonce=4`;
async function GetOrders() {

    const Sign = crypto
        .createHmac('sha512', Secret)
        .update(`?ts=${Payload}&market=btc_usd&nonce=4`)
        .digest('hex')
        .toUpperCase();
    const options = {
        hostname: Host,
        port: Port,
        path: Method,
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
            'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
            Key,
            Sign
        }
    };
    const req = https.request(options, res => {
        console.log(`statusCode: ${res.statusCode}`);
        console.log(`statusMessage: ${res.statusMessage}`);
        res.on('data', d => {
            process.stdout.write(d);
        });
    });
    req.on('error', e => {
        console.error(e);
    });
    req.end();
}

GetOrders().catch(err => {
    console.log(err);
});

Response

Returns an array of Order Objects.


Trades history

Returns a history of trades meeting specified criteria or a history of all trades if no parameters are defined in a request.

Request

The ts and nonce values should be specified for a request.

Query parameters:

orderId

The order identifier by which you can get information about all related trades

market

The currency pair for which the trades history should be obtained (for example, btc_usdt)

side

The trade side: 0 — buy; 1 — sell

startDate

The date and time indicating the beginning of a required time interval: YYYY-MM-DDThh:mm:ss.s

endDate

The date and time indicating the end of a required time interval: YYYY-MM-DDThh:mm:ss.s

AscOrder

The field to be used as a criteria for sorting response data in ascending order; any of the following fields can be specified:

  • TradeSeq

  • TradeTime

  • OrderId

  • Amount

  • Instrument

  • Side

  • ExecutionPrice

  • Commission

DescOrder

The field to be used as a criteria for sorting response data in descending order; for a list of support fields, see the AscOrder parameter description

page

The number of a page listing the trades to be returned (when the perPage parameter is defined)

perPage

The number of trades to be listed on a single page

GET[base]/frontoffice/api/trade_history

GET /frontoffice/api/trade_history?market=btc_usdt&ts=2019-12-12T01:01:01&nonce=4 HTTP/1.1
Host: host.name
Key: 7fa6ceec-d8fc...
Sign: 7ae49b5b-99db...
const crypto = require('crypto');
const https = require('https');
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Host = "host.name"; // Change to your host name
const Payload = new Date().toISOString();
const Method = `/frontoffice/api/trade_history?ts=${Payload}&market=btc_usd&startDate=2020-01-12T01:01:01&nonce=5&ascOrder=Side`;
async function GetTrades() {

    const Sign = crypto
        .createHmac('sha512', Secret)
        .update(`?ts=${Payload}&market=btc_usd&startDate=2020-01-12T01:01:01&nonce=5&ascOrder=Side`)
        .digest('hex')
        .toUpperCase();
    const options = {
        hostname: Host,
        port: Port,
        path: Method,
        method: 'GET',
        headers: {
            'Content-Type': 'application/json',
            'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
            Key,
            Sign
        }
    };
    const req = https.request(options, res => {
        console.log(`statusCode: ${res.statusCode}`);
        console.log(`statusMessage: ${res.statusMessage}`);
        res.on('data', d => {
            process.stdout.write(d);
        });
    });
    req.on('error', e => {
        console.error(e);
    });
    req.end();
}
GetTrades().catch(err => {
    console.log(err);
});

Response

tradeSeq number

The trade sequence number

tradeTime string

The date and time when a trade has been executed

amount number

The trade amount

executionPrice number

The trade execution price

instrument string

The traded currency pair (instrument)

side number

The trade side: 0 — buy; 1 — sell

commission number

The commission charged for a trade

orderId number

The identifier of a related order

RESPONSE BODY EXAMPLE
{
  "filters": {
    "market": "btc_usdt",
    "ascOrder": [
      "Side"
    ]
  },
  "paging": {
    "page": 1,
    "per_page": 15,
    "total": 1
  },
  "data": [
    {
      "tradeSeq": 0,
      "tradeTime": "2019-12-20T06:17:03.093597",
      "amount": 0.00000001,
      "executionPrice": 0.00000001,
      "instrument": "btc_usdt",
      "side": 0,
      "commission": 0.00000000,
      "orderId": -72057593704402280
    },
    {
      "tradeSeq": 3927,
      "tradeTime": "2019-12-20T06:17:03.093597",
      "amount": 0.00000001,
      "executionPrice": 0.00000001,
      "instrument": "btc_usdt",
      "side": 1,
      "commission": 0.00000000,
      "orderId": -72057593704402281
    }
  ]
}

User balance

Returns up-to-date information about the total and locked amount of each asset on user balances.

Request

The ts and nonce values should be specified for a request.

No parameters.

GET[base]/frontoffice/api/balances

GET /frontoffice/api/balances HTTP/1.1
Host: host.name
Key: 7fa6ceec-d8fc...
Sign: 7ae49b5b-99db...
const crypto = require('crypto');
const https = require('https');
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Host = "host.name"; // Change to your host name
const Payload = new Date().toISOString();
const Method = `/frontoffice/api/balances?ts=${Payload}&nonce=6`;
async function GetBalances() {
  const Sign = crypto
    .createHmac('sha512', Secret)
    .update(`?ts=${Payload}&nonce=6`)
    .digest('hex')
    .toUpperCase();
  const options = {
    hostname: Host,
    port: Port,
    path: Method,
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
      Key,
      Sign
    }
  };
  const req = https.request(options, res => {
    console.log(`statusCode: ${res.statusCode}`);
    console.log(`statusMessage: ${res.statusMessage}`);
    res.on('data', d => {
      process.stdout.write(d);
    });
  });
  req.on('error', e => {
    console.error(e);
  });
  req.end();
}
GetBalances().catch(err => {
  console.log(err);
});

Response

asset string

The asset name

balance number

The total asset amount on a user’s balance

locked number

The locked asset amount on a user’s balance

RESPONSE BODY EXAMPLE
[
  {
    "asset": "btc",
    "balance": 10.0,
    "locked": 0.0
  },
  {
    "asset": "usdt",
    "balance": 80000.0,
    "locked": 7.0
  }
]

Order info

Returns order details based on a specified order ID or client order ID.

Request

The ts and nonce values should be specified for a request.

Query parameters:

orderId *

The order identifier: either orderId (the one specified in a response to a Place an Order request) or clientOrderId (the one specified in the Place an Order request)

GET[base]/frontoffice/api/orders

GET /frontoffice/api/orders?orderId=-72057594037927933
    &ts=2019-12-12T01:01:01
    &nonce=4 HTTP/1.1
Host: host.name

Response

Returns an Order Object.


My orders info

Returns up-to-date information about orders placed by a current user.

Request

The ts and nonce values should be specified for a request.

No parameters.

GET[base]/frontoffice/api/orders/my

GET /frontoffice/api/orders/my?ts=2019-12-12T01:01:01&nonce=4 HTTP/1.1
Host: host.name
Key: 7fa6ceec-d8fc...
Sign: 7ae49b5b-99db...

Response

Returns an array of Order Objects.


Public WebSocket methods

Real-time order book data

Open a connection to a public hub: [base]/marketdata/info

The order book channel name is Book.

Attention

Upon subscription, a complete order book snapshot will be sent (snapshot: true); all subsequent responses will contain only updates to it, and not the entire book (snapshot: false).

REQUEST EXAMPLE
const { HubConnectionBuilder } = require("@microsoft/signalr"); // Package version must be >= 5.0.0

const url = "https://host.name/trading/marketdata/info"; // Change [host.name] to your host name
const instrument = "btc_usd";
const channel = 'Book';

let connection = new HubConnectionBuilder()
    .withUrl(url)
    .build();

connection.start().then(function () {
connection.stream(channel, instrument)
    .subscribe({
        next: (item) => {
		console.log(JSON.stringify(item));
        },
        error: (err) => {
            console.log(err);
        },
}); 
});

Response

See Order book snapshot to learn more about response data.


Real-time exchange status

Open a connection to a public hub: [base]/status-api/status

One of the following exchange statuses is returned:

  • online

  • maintenance

  • down

RESPONSE BODY EXAMPLE
    {
        "exchangeStatus":"maintenance",
    }

Private WebSocket methods

Orders data

Open a connection to a private hub: [base]/ws/account

The channel name for receiving data about placed orders is OpenOrders.

REQUEST EXAMPLE
const { HubConnectionBuilder } = require("@microsoft/signalr"); // Package version must be >= 5.0.0
const crypto = require("crypto");
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Payload = new Date().toISOString();
	const Sign = crypto
	.createHmac('sha512', Secret)
	.update(Payload)
	.digest('hex')
	.toUpperCase();
const headers = {
    Key,
    Payload,
    Sign
};

const url = "https://host.name/trading/frontoffice/ws/account"; // Change [host.name] to your host name
const channel = "OpenOrders";
let connection = new HubConnectionBuilder()
    .withUrl(url, {headers: headers})
    .build();

connection.start().then(function () {
connection.stream(channel)
    .subscribe({
        next: (item) => {
		console.log(JSON.stringify(item));
        },
        error: (err) => {
            console.log(err);
        },
}); 
});

Response

Upon subscription, returns an Order Object.


Real-time balances

Open a connection to a private hub: [base]/ws/account

The channel name for receiving balance updates is FullBalance.

REQUEST EXAMPLE
const { HubConnectionBuilder } = require("@microsoft/signalr"); // Package version must be >= 5.0.0
const crypto = require("crypto");
const Key = "7fa6ceec-d8fc..."; // Change to your PublicKey
const Secret = "7ae49b5b-99db..."; // Change to your Secret
const Payload = new Date().toISOString();
	const Sign = crypto
	.createHmac('sha512', Secret)
	.update(Payload)
	.digest('hex')
	.toUpperCase();
const headers = {
    Key,
    Payload,
    Sign
};

const url = "https://host.name/trading/frontoffice/ws/account"; // Change [host.name] to your host name
const channel = "FullBalance";
let connection = new HubConnectionBuilder()
    .withUrl(url, {headers: headers})
    .build();

connection.start().then(function () {
connection.stream(channel, {})
    .subscribe({
        next: (item) => {
		console.log(JSON.stringify(item));
        },
        error: (err) => {
            console.log(err);
        },
}); 
});

Response

asset string

The asset name

amount number

The asset amount

balance number

The total asset amount on a balance

locked number

The locked asset amount on a balance

RESPONSE BODY EXAMPLE
[
    {
        "asset": "ada",
        "amount": 1000000000,
        "balance": 1000000000,
        "locked": 0
    },
    {
        "asset": "bch",
        "amount": 9999999.99999999,
        "balance": 9999999.99999999,
        "locked": 0
    }
]

Models

Order object

clientOrderId number

The client order identifier

orderId string

The system order identifier

total number

The quote amount, meaning the total traded amount of a quote asset

orderType number

The order type:

  • 0 — a limit order

  • 1 — a market IOC (immediate-or-cancel) order

  • 2 — a stop limit order (currently not supported)

  • 3 — a stop market order (currently not supported)

  • 4 — a market FOK (fill-or-kill) order

commission number

The commission charged for an order, in a quote asset

createdAt string

The date and time when an order has been created

unitsFilled number

The filled order amount

isPending boolean

If true, the order is awaiting execution (it has not been rejected, cancelled or completed)

status string

The order status: Working, Rejected, Cancelled or Completed

type string

The order side: buy or sell

amount number

The order amount, must be greater than 0

remaining number

The remaining order amount awaiting to be filled

price number

Obsolete. This parameter is assigned the executionPrice value for market and stop orders, and the requestedPrice value for stop orders

executionPrice number

The order execution price

requestedPrice number

The requested (ask/bid) price for the order

stopPrice number

Currently not supported. The order stop price

isLimit boolean

If true, indicates a limit order; if false, indicates a market order

isStop boolean

Currently not supported. A true value indicates a stop market or stop limit order, depending on the isLimit setting (see Flags combinations to learn more)

isFok boolean

Obsolete. If true, indicates a “fill-or-kill” order that is supposed to be executed immediately in a full amount or cancelled if not filled (see Flags combinations to learn more)

instrument string

The order instrument identifier: {baseAsset}_{quoteAsset}

side number

The order side: 0 — buy; 1 — sell

cancelReason string

The reason why an order has been cancelled:

  • 0 — the order has not been cancelled

  • 1 — the order has been explicitly cancelled by an exchange user

  • 2 — the order has been cancelled by the system or the exchange administrator

  • 3 — the order has been cancelled by a self-match prevention mechanism

rejectDetails string

Detailed information about why an order has been rejected

When calling [base]/frontoffice/api/orders methods, the following additional fields are included into order details:

updatedAt string

The date and time when an order has last been updated

averageFillPrice number

The average order fill price

timeInForce string

The Time in Force setting applied to an order

ORDER OBJECT
{
  "order": {
    "updatedAt": "2020-06-19T11:21:30.532789",
    "averageFillPrice": "1000",
    "timeInForce": "GTC",
    "clientOrderId": "",
    "orderId": "-72057594037927934",
    "total": 100.0,
    "orderType": 0,
    "commission": 0.0001,
    "createdAt": "2020-06-19T11:21:30.532784Z",
    "unitsFilled": 0.1,
    "isPending": false,
    "status": "completed",
    "type": "buy",
    "amount": 0.1,
    "remaining": 0.0,
    "price": 1000.0,
    "executionPrice": 1000.0,
    "requestedPrice": 1000.0,
    "stopPrice": 0.0,
    "isLimit": true,
    "instrument": "btc_usdt",
    "side": 0,
    "cancelReason": 0,
    "rejectDetails": ""
  }
}

Flags combinations

In the following table you can find information about various combinations of flags corresponding to specific order types:

Order

Description

Flags

Limit

Limit order

isLimit is true

isStop is false

isFok is false

Market (Market IOС)

Market order (Immediate-or-Cancel market order) — the order must be executed immediately with any unfilled portion being cancelled

isLimit is false

isStop is false

isFok is false

Market FOK

Fill-or-Kill market order — the order must be executed immediately in a full amount or cancelled if not filled

isLimit is false

isStop is false

isFok is true


HTTP status codes

200 OK

400 Bad Request: incorrect parameters

{
  "errors": [
    {
      "message": "Unknown instrument 'gold_silver'",
      "value": "gold_silver",
      "key": "instrument"
    }
  ]
}

401 Unauthorized: incorrect keys or ts value differs from the current time by more than 5 seconds

404 Not Found

{
  "errors": [
    {
      "message": "Not Found",
      "key": "instrument"
    }
  ]
}

429 Too Many Requests: API Rate Limits violated

500 Internal Server Error

{
  "errors": [
    {
      "message": "Stop orders are not supported."
    }
  ]
}

503 Service Unavailable A JSON object or a string

{
  "errors": [
    {
      "message": "System is currently overloaded."
    }
  ]
}
"This service is currently undergoing maintenance."