NAV
protobuf json

Lykke High-Frequency Trading API

Lykke high-frequency trading API.

Lykke High-Frequency Trading API allows all our clients to carry out automated trading on specially designed sub-accounts. This API enables clients to get public Lykke Market data such as current prices, book orders and other parameters of the trading instruments.

If you are interested in API trading, please sign up in here and start trading with Lykke!

For more information about Lykke, please visit www.lykke.com.

Change Log

2020-09-02 | Public trades stream, fixes

Added public stream for trades. Fixed an issue with orderbook updates stream.

2020-08-25 | Side property in the Trade

Added Side property for the Trade.

2020-08-10 | The new method in Private API

Added a new method Get order by Id to search an order by ID.

Added to documentation details about default values to existing methods.

Added tp documentation information about Request Rate Limits

2020-07-01 | The release of a new HFT API.

The new release of the updated APIs now supports gRPC protocol. This protocol uses HTTP 2.0 Standard, WebSocket, and ProtoBuf, which helps to reduce latency, allows more efficient use of the CPU and provides access to network resources on the client's side.

The best part of the gRPC protocol is how easy it is to integrate the Lykke APIs in many programming languages by using the proto-files which generates a client library.Proto files with contracts. This generates a new response format, abstracted from the protocol itself, allowing you to work in a custom manner with the Lykke APIs regardless of the protocol.

The New Response of the server is no longer included in the gRPC protocol, enabling each user to work with the API in their unique manner. Additionally, the contracts in the Rest API protocol also had been updated. A new set of functions and models is being used, very similar to those of gRPC protocol.

Because of the gRPC protocol, the user now is able to receive Market Data Stream directly from the server:

We have also added the capability to receive data flow from your API account using gRPC protocol:

We have enhanced the overall performance of the APIs by optimising different areas such as: reducing data backlogs, prices, book orders, balances and active orders.

We have also optimised the API Keys management and enhanced overall security.

We have also increased the optimisation of internal serves and bug fixes.

Protocol description

Lykke HFT API allows users to use two kinds of protocols: gRPC API and Rest API. Both APIs support the same methods and data format, however, only gRPC API is able to receive streaming data from the platform.

gRPC API

The gRPC API utilises a new generation of RPC framework that includes working with HTTP 2, ProtoBuf, and WebSocket for faster and more efficient interaction with the platform. The gRPC framework uses the declarative description of the contract in the .proto files, on the basis of which it is simple to generate Client Library using numerous programming languages. Furthermore, the gRPC framework supports working with stream making it easy to receive events directly from the server.

Lykke team strongly recommends using gRPC API protocol to communicate with the platform

Read more about gRPC framework: https://grpc.io/

A useful tool for manual gRPC API requests:

API Endpoint:

Proto files

Rest API

Rest API uses a classic HTTP based framework that entails working with HTTP 1.1 and JSON. Rest API allows users to call RPC methods without streaming data from the server.

Disclaimer: The rest API has been added for backward compatibility. Lykke team recommends against using the Rest API protocol in favour of the gRPC protocol.

API Endpoint:

A useful tool for manual rest API requests: HFT API Swagger

API usage

Allowed HTTP Verbs

Description Of Usual HTTP Server Responses

Response structure

Every response contains two fields - payload and error. A successful response will contain the response data in the payload field and the null in the error field and vice versa for the error response.

Here you have a list of errors you might encounter in the paragraph Error codes at the end of the document.

Successful response. Property error is null.

{
    "payload": {
        ...
    },
    "error": null
}
package hft;

message Response {
    PayloadType payload = 1;
    hft.common.Error error = 2;  // error is NULL
}

Error response. Property error is not null.

{
    "error": {
        "code": "itemNotFound",
        "message": "Asset not found",
        "fields": {
            "assetId": "Asset not found"
        }
    },
    "payload": null
}
package hft.common;

message Error {
    ErrorCode code = 1;                  // 1100
    string message = 2;              // "Asset not found"
    map<string, string> fields = 3;  // "assetId" : "Asset not found"
}

enum ErrorCode {
    success = 0;
    runtimeError = 1001;
    itemNotFound = 1100;

/* Full list in the paragraph **Error codes** at the end of the document */

}

package hft;

message Response {
    PayloadType payload = 1;
    hft.common.Error error = 2;      // error is NOT NULL
}

Authorization

You can create your API keys in here. You can also check our step by step guide here. To use the API keys, you should just add a header Authorisation: Bearer <your API Key> with the bearer token on your request.

Request Header

  "Authorization": "Bearer **********************************"
  "Authorization": "Bearer **********************************"

Decimal type

Here you can see how to manage decimal types (Price, Volume, Amount, etc) in API contract.

In the gRPC API contract, the decimal type is presented as a string type, with a textual representation of the number. This is done in order to avoid issues with the non-strict precision double type.

In the Rest API contact, the decimal type is presented as a number with strict precision.

Example with decimal type

{
    "price": 222231.33420001911,
    "volume": 0.0000001
}
message Body {
    string price = 1;   // "222231.33420001911"
    string volume = 2;  // "0.0000001"
}

Timestamp type

Here you can see: How to manage the TimeStamp type in the API contract.

The timestamp is always used in the time zone UTC+0

In the Rest API contact, the TimeStamp type is presented as a number with "Milliseconds in Unix Epoch" format of date-time.

In the gRPC API contract, the TimeStamp type is presented as a google.protobuf.TimeStamp type.

Example with timestamp

{
   "Timestamp": 1592903724406
}
import "google/protobuf/timestamp.proto";

google.protobuf.Timestamp time_name = 1;  // 1592903724406

Order statuses

List of possible order states

Name Meaning
Placed Order in the Order Book.
PartiallyMatched Order in the Order Book and partially filled.
Matched Order is filled.
Pending Order is pending a trigger to be placed in the Order Book.
Cancelled Order is cancelled by the User.
Replaced Order is replaced (canceled) by the user.
Rejected Order rejected by the System.

Request rate limits

API has a request rate limits. If client hit limit then API return error: 429 Too Many Requests

Rate Limit settings:

API type methods Request rate limits
gRPC API hft.PrivateService.* 1000 request per minute per method
gRPC API hft.PublicService.* 300 request per minute per method
Rest API /api/orders/* 300 request per minute per method
Rest API /api/* 120 request per minute per method

Public APIs

Get all assets

Get a list of supported assets with parameters.

Request

gRPC: hft.PublicService.GetAssets

Rest API: GET /api/assets

Response

Array of assets:

Parameter Type Description
assetId string Asset unique identifier.
name string Asset name.
symbol string Asset symbol.
accuracy uint Maximum number of digits after the decimal point which are supported by the asset.
GET /api/assets

> Response 200 (application/json) - success response

{
    "payload": [
        {
            "assetId": "AUD",
            "name": "AUD",
            "displayName": "AUD",
            "accuracy": 2
        },
        {
            "assetId": "BTC",
            "name": "BTC",
            "displayName": "BTC",
            "accuracy": 8
        }
    ]
}
package hft;

service PublicService {
  rpc GetAssets (google.protobuf.Empty) returns (AssetsResponse);
}

message AssetsResponse {
    repeated Asset payload = 1;
    hft.common.Error error = 2;  // NULL
}

message Asset {
    string assetId = 1;  // BTC
    string name = 2;     // Bitcoin
    string symbol = 3;   // BTC
    int32 accuracy = 4;  // 8
}

Get Asset by ID

Get information about a specific asset.

Request

gRPC: hft.PublicService.GetAsset

RestAPI: GET /api/assets/{assetId}

Query Parameters

Parameter Type Place Default Description
assetId string path - Asset uniquie ID

Response

Asset description:

Property Type Description
assetId string Asset unique identifier.
name string Asset name.
symbol string Asset symbol.
accuracy uint Maximum number of digits after the decimal point which are supported by the asset.
GET /api/assets/{assetId}

> Response 200 (application/json) - success response

{
    "payload": {
        "assetId": "BTC",
        "name": "Bitcoin",
        "displayName": "BTC",
        "accuracy": 8
    }
}
package hft;

service PublicService {
  rpc GetAsset (AssetRequest) returns (AssetResponse);
}

message AssetRequest {
    string assetId = 1;   // BTC
}

message AssetResponse {
    Asset payload = 1;
    hft.common.Error error = 2;  // NULL
}

message Asset {
    string assetId = 1;  // BTC
    string name = 2;     // Bitcoin
    string symbol = 3;   // BTC
    int32 accuracy = 4;  // 8
}

Get all asset pairs

Get all supported asset pairs (symbols).

Request

gRPC: hft.PublicService.GetAssetPairs

RestAPI: GET /api/assetpairs

Response

Array of trading instruments.

Property Type Description
assetPairId string Symbol unique identifier.
baseAssetId string Base asset unique identifier.
quoteAssetId string Quote asset unique identifier.
name string Trading instrument name.
priceAccuracy uint Trading instrument price accuracy.
baseAssetAccuracy uint Base asset accuracy.
quoteAssetAccuracy uint Quote asset accuracy.
minVolume decimal Minimum order volume in base currency.
minOppositeVolume decimal Minimum order volume in quote currency.
GET /api/assetpairs

> Response 200 (application/json) - success response

{
  "payload": [
    {
      "assetPairId": "BTCUSD",
      "baseAssetId": "BTC",
      "quoteAssetId": "91960f78-7ea1-49f7-be27-34221a763b02",
      "name": "BTC/USD",
      "priceAccuracy": 3,
      "baseAssetAccuracy": 8,
      "quoteAssetAccuracy": 2,
      "minVolume": 0.0001,
      "minOppositeVolume": 1
    },
    {
      "assetPairId": "BTCLKK1Y",
      "baseAssetId": "BTC",
      "quoteAssetId": "LKK1Y",
      "name": "BTC/LKK1Y",
      "priceAccuracy": 2,
      "baseAssetAccuracy": 8,
      "quoteAssetAccuracy": 2,
      "minVolume": 0.0001,
      "minOppositeVolume": 4
    }
  ]
}
package hft;

service PublicService {
  rpc GetAssetPairs (google.protobuf.Empty) returns (AssetPairsResponse);
}

message AssetPairsResponse {
    repeated AssetPair payload = 1;
    hft.common.Error error = 2;      // NULL
}

message AssetPair {
    string assetPairId = 1;          // "BTCLKK1Y"
    string baseAssetId = 2;          // "BTC"
    string quoteAssetId = 3;         // "LKK1Y"
    string name = 4;                 // "BTC/LKK1Y"
    int32 priceAccuracy = 5;         // 2
    int32 baseAssetAccuracy = 6;     // 8
    int32 quoteAssetAccuracy = 7;    // 2
    string minVolume = 8;            // 0.0001
    string minOppositeVolume = 9;    // 4
}

Get a specific asset pair

Get a specific asset pair.

Request

gRPC: hft.PublicService.GetAssetPair

RestAPI: GET /api/assetpairs/{assetPairId}

Query Parameters

Parameter Type Place Default Description
assetPairId string path - Symbol unique ID

Responce

Trading instrument:

Property Type Description
assetPairId string Symbol unique identifier.
baseAssetId string Base asset unique identifier.
quoteAssetId string Quote asset unique identifier.
name string Trading instrument name.
priceAccuracy uint Trading instrument price accuracy.
baseAssetAccuracy uint Base asset accuracy.
quoteAssetAccuracy uint Quote asset accuracy.
minVolume decimal Minimum order volume in base currency.
minOppositeVolume decimal Minimum order volume in quote currency.
GET /api/assetpairs/{assetPairId}

> Response 200 (application/json) - success response

{
  "payload":
    {
      "assetPairId": "BTCUSD",
      "baseAssetId": "BTC",
      "quoteAssetId": "91960f78-7ea1-49f7-be27-34221a763b02",
      "name": "BTC/USD",
      "priceAccuracy": 3,
      "baseAssetAccuracy": 8,
      "quoteAssetAccuracy": 2,
      "minVolume": 0.0001,
      "minOppositeVolume": 1
    }
}
package hft;

service PublicService {
  rpc GetAssetPair (AssetPairRequest) returns (AssetPairResponse);
}

message AssetPairResponse {
    AssetPair payload = 1;
    hft.common.Error error = 2;      // NULL
}

message AssetPair {
    string assetPairId = 1;          // "BTCLKK1Y"
    string baseAssetId = 2;          // "BTC"
    string quoteAssetId = 3;         // "LKK1Y"
    string name = 4;                 // "BTC/LKK1Y"
    int32 priceAccuracy = 5;         // 2
    int32 baseAssetAccuracy = 6;     // 8
    int32 quoteAssetAccuracy = 7;    // 2
    string minVolume = 8;            // 0.0001
    string minOppositeVolume = 9;    // 4
}

Asset Pair Order Book Ticker

Get the Order Book by asset pair. The order books contain a list of Buy(Bid) and Sell(Ask) orders with their corresponding price and volume.

Request

gRPC: hft.PublicService.GetOrderbooks

RestAPI:

GET /api/orderbooks GET /api/orderbooks?assetPairId={assetPairId}&depth={depth}

Query Parameters

Parameter Type Place Default Description
assetPairId string query null (Optional) Identificator of specific symbol. By default return all symbols.
depth uint query 0 (Optional) How many levels need to include in order books. By default include all levels.

Response

Array of Order Books by instruments:

Property Type Description
assetPairId string Symbol unique identifier.
timestamp TimeStamp Timestamp of last order book update.
bids Array of PriceLevel List of buy orders.
asks Array of PriceLevel List of sell orders.

PriceLevel:

Property Type Description
p decimal Order price indicated in quoted asset per unit of base asset.
v decimal Order volume indicated in the base asset.
GET /api/orderbooks
GET /api/orderbooks?assetPairId={assetPairId}&depth={depth}

> Response 200 (application/json) - success response

{
  "payload": [
    {
      "assetPairId": "BTCUSD",
      "timestamp": 1594725117313
      "bids": [
        {
          "v": 0.06771538,
          "p": 9599
        },
        {
          "v": 0.05210805,
          "p": 9599
        }
      ],
      "asks": [
        {
          "v": -1.67230494,
          "p": 9633.613
        },
        {
          "v": -0.1,
          "p": 9641.42
        }
      ]
    }
  ]
}
package hft;

service PublicService {
  rpc GetOrderbooks (OrderbookRequest) returns (OrderbookResponse);
}

message OrderbookRequest {
    string assetPairId = 1;
    int32 depth = 2;
}

message OrderbookResponse {
    repeated Orderbook payload = 1;
    hft.common.Error error = 2;       // NULL
}

message Orderbook {
    string assetPairId = 1;           // "BTCUSD"
    google.protobuf.Timestamp timestamp = 2;  // "seconds": "1594742656", "nanos": 167000000
    repeated PriceVolume bids = 3;    // {p="9010", v="0.01"}, {p="9000", v="1.0"}
    repeated PriceVolume asks = 4;    // {p="9020", v="0.12"}, {p="9030", v="0.71001"}

    message PriceVolume {
        string p = 1;
        string v = 2;
    }
}

24hr Ticker Price Change Statistics

24-hour rolling-window price change statistics.

Request

gRPC: hft.PublicService.GetTickers

RestAPI:

GET /api/tickers GET /api/tickers?assetPairIds=BTCUSD&assetPairIds=BTCEUR

Query Parameters

Parameter Type Place Default Description
assetPairIds string query null (Optional) Filter by symbols. By default returns all asset pairs information.

Response

Asset description:

Property Type Description
assetPairId string Symbol unique identifier.
volumeBase decimal Trading volume for the last 24h in base asset.
volumeQuote decimal Trading volume for the last 24h in quote asset.
priceChange decimal Price changes(in %) in the last 24h.
lastPrice decimal The last trade price.
high decimal The maximum trade price from the last 24h.
low decimal The minimum trade price from the last 24h.
timestamp TimeStamp Last update timestamp.
`GET /api/tickers`
`GET /api/tickers?assetPairIds=BTCUSD&assetPairIds=BTCEUR`

> Response 200 (application/json) - success response

{
  "payload": [
    {
      "assetPairId": "BTCEUR",
      "volumeBase": 0.98657285,
      "volumeQuote": 8350.5868,
      "priceChange": 0.036057567781542336,
      "lastPrice": 8620,
      "high": 8620,
      "low": 8320,
      "timestamp": 1594725117313
    },
    {
      "assetPairId": "BTCUSD",
      "volumeBase": 2.15139075,
      "volumeQuote": 20649.0296,
      "priceChange": 0.023048622404312356,
      "lastPrice": 9637.117,
      "high": 9700,
      "low": 9397.999,
      "timestamp": 1594725117313
    }
  ]
}
package hft;

service PublicService {
  rpc GetTickers (TickersRequest) returns (TickersResponse);
}

message TickersRequest {
    repeated string assetPairIds = 1;
}

message TickersResponse {
    repeated TickerUpdate payload = 1;
    hft.common.Error error = 2;    // NULL
}

message TickerUpdate {
    string assetPairId = 1;
    string volumeBase = 2;
    string volumeQuote = 3;
    string priceChange = 4;
    string lastPrice = 5;
    string high = 6;
    string low = 7;
    google.protobuf.Timestamp timestamp = 8;
}

Get current prices

Get current prices by symbols.

Request

gRPC: hft.PublicService.GetPrices

RestAPI:

GET /api/prices

GET /api/prices?assetPairIds={AssetPairID-1}&assetPairIds={AssetPairID-2}&...

Query Parameters

Parameter Type Place Default Description
assetPairIds array of string query null (Optional) List of identificators of specific symbols. By default return all symbols.

Response

Array of prices by symbols:

Property Type Description
assetPairId string Symbol unique identifier.
timestamp TimeStamp Timestamp of last order book update.
bid decimal Bid price.
ask decimal Ask price.
GET /api/prices
GET /api/prices?assetPairId={assetPairId}&depth={depth}

> Response 200 (application/json) - success response

{
"payload": [
    {
      "assetPairId": "BTCEUR",
      "bid": 8089.122,
      "ask": 8149.614,
      "timestamp": 1594750211438
    },
    {
      "assetPairId": "BTCUSD",
      "bid": 9243.277,
      "ask": 9283.495,
      "timestamp": 1594750214503
    }
  ]
}
package hft;

service PublicService {
  rpc GetPrices (PricesRequest) returns (PricesResponse);
}

message PricesRequest {
    repeated string assetPairIds = 1;
}

message PricesResponse {
    repeated PriceUpdate payload = 1;
    hft.common.Error error = 2;
}

message PriceUpdate {
    string assetPairId = 1;
    string bid = 2;
    string ask = 3;
    google.protobuf.Timestamp timestamp = 4;
}

Private APIs

This group method requires API Key Authentication.

If you would like to create your API key, please sign up in here and start trading with Lykke!. If you need a step by step guide you may check our Help Center in here.

Get the current balance

Get the current balance from the API Key account.

Request

gRPC: hft.PrivateService.GetBalances

Rest API: GET /api/balance

Response

The array of balance by assets.

Property Type Description
assetId string Asset unique identifier.
available decimal Available amount.
reserved decimal Amount reserved in active orders.
timestamp TimeStamp Last balance update on current asset.
GET /api/balance

> Response 200 (application/json) - success response

{
  "payload": [
    {
      "assetId": "BTC",
      "available": 2.433002,
      "reserved": 0.35,
      "timestamp": 1592928606187
    },
    {
      "assetId": "USD",
      "available": 0,
      "reserved": 0,
      "timestamp": 1592928506187
    },
  ]
}
package hft;

service PrivateService {
  rpc GetBalances (google.protobuf.Empty) returns (BalancesResponse);
}

message BalancesResponse {
    repeated Balance payload = 1;
    hft.common.Error error = 2;
}

message Balance {
    string assetId = 1;
    string available = 2;
    string reserved = 3;
    google.protobuf.Timestamp timestamp = 4;
}

Get trade history

Gets the trading history of an account. Also, with the use of parameters, it can returns a single order.

Request

gRPC: hft.PrivateService.GetTrades

Rest API:

GET /api/trades

GET /api/trades/order/{orderId}

Query Parameters

Parameter Type Place Default Description
assetPairId string query null (optional) Symbol unique identifier.
side string query null (optional) Side of trade: buy or sell.
offset uint query 0 (optional) Skip the specified number of elements.
take uint query 100 (optional) Take the specified number of elements.
from TimeStamp query null (optional) From timestamp.
to TimeStamp query null (optional) To timestamp.

Query Parameters

Parameter Type Place Default Description
orderId string path - Unique Order ID

Response

Array of trades:

Property Type Description
id string Trade ID.
orderId string Order ID of this trade.
assetPairId string Trade asset pair ID (symbol).
timestamp TimeStamp Trade tamestamp.
role string Trade role. Maker or Taker.
price decimal Trade price.
baseVolume decimal Trade volume in base asset.
quoteVolume decimal Trade volume in quote asset.
baseAssetId string Base asset ID.
quoteAssetId string Quote asset ID.
fee TradeFee (optional) Trade Fee description.
side string Trade side: Sell or Buy.

TradeFee

Property Type Description
assetId string Asset ID
size decimal Fee size
GET /api/trades
GET /api/trades/order/{orderId}

> Response 200 (application/json) - success response

{
  "payload": [
    {
      "id": "b3a25228-5384-4b5f-95c3-3eb31f7e9aee",
      "timestamp": 1592938116360,
      "assetPairId": "BTCUSD",
      "orderId": "616374a2-02d0-4f01-8dce-6266fc30d4a1",
      "role": "Taker",
      "price": 9575.823,
      "baseVolume": 0.0001,
      "quoteVolume": 0.9576,
      "baseAssetId": "BTC",
      "quoteAssetId": "USD",
      "fee": null,
      "side": "buy"
    },
    {
      "id": "ebceb096-7766-437a-8e98-e1f6532f0268",
      "timestamp": 1592938016360,
      "assetPairId": "BTGUSD",
      "orderId": "fa19c315-b8b2-49bd-a426-45f9384fbad3",
      "role": "Taker",
      "price": 8.5,
      "baseVolume": 0.01,
      "quoteVolume": 0.085,
      "baseAssetId": "a4954205-48eb-4286-9c82-07792169f4db",
      "quoteAssetId": "USD",
      "fee": null,
      "side": "buy"
    }]
}
package hft;

service PrivateService {
  rpc GetTrades (TradesRequest) returns (TradesResponse);
}

message TradesRequest {
    string assetPairId = 1;
    oneof optional_side {
        Side side = 2;
    }
    int32 offset = 3;
    int32 take = 4;
    string from = 5;
    string to = 6;
}

message TradesResponse {
    repeated Trade payload = 1;
    hft.common.Error error = 2;
}

message Trade {
    string id = 1;
    google.protobuf.Timestamp timestamp = 2;
    string assetPairId = 3;
    string orderId = 4;
    string role = 5;
    string price = 6;
    string baseVolume = 7;
    string quoteVolume = 8;
    string baseAssetId = 9;
    string quoteAssetId = 10;
    TradeFee fee = 11;
    Side side = 12;
}

message TradeFee {
    string size = 1;
    string assetId = 2;
}

Get active or closed orders

Get active orders or closed orders from history.

Request

gRPC:

hft.PrivateService.GetActiveOrders

hft.PrivateService.GetClosedOrders

Rest API:

GET /api/orders/active

GET /api/orders/closed

Query Parameters

Parameter Type Place Default Description
assetPairId string query null (optional) Symbol unique identifier.
offset uint query 0 (optional) Skip the specified number of elements.
take uint query 100 (optional) Take the specified number of elements.

Response

Response description:

Property Type Description
id string Unique Order ID.
timestamp TimeStamp Timestamp for order creation.
lastTradeTimestamp TimeStamp Timestamp for last trade by order.
status string Order status. List of statuses here.
assetPairId string Symbol unique identifier.
type string Order type: Market or Limit.
side string Order side: Sell or Buy.
price decimal Order price (in quote asset for one unit of base asset).
volume decimal Order volume (in base asset).
filledVolume decimal Order filled volume (in base asset).
remainingVolume decimal Order remaining volume to be filled (in base asset).
GET /api/orders/active
GET /api/orders/closed

> Response 200 (application/json) - success response

{
  "payload": [
    {
      "id": "0c336213-0a64-44a8-9599-e88bf6aa1b69",
      "timestamp": 1592928606187,
      "lastTradeTimestamp": null,
      "status": "Placed",
      "assetPairId": "BTCUSD",
      "type": "Limit",
      "side": "Buy",
      "price": 4000,
      "volume": 0.0001,
      "filledVolume": 0,
      "remainingVolume": 0.0001
    }
  ]
}
package hft;

service PrivateService {
  rpc GetActiveOrders (OrdersRequest) returns (OrdersResponse);
  rpc GetClosedOrders (OrdersRequest) returns (OrdersResponse);
}

message OrdersRequest {
    string assetPairId = 1;
    int32 offset = 2;
    int32 take = 3;
}

message OrdersResponse {
    repeated Order payload = 1;
    hft.common.Error error = 2;
}

message Order {
    string id = 1;
    google.protobuf.Timestamp timestamp = 2;
    oneof optional_lastTradeTimestamp {
        google.protobuf.Timestamp lastTradeTimestamp = 3;
    }
    string status = 4;
    string assetPairId = 5;
    string type = 6;
    Side side = 7;
    string price = 8;
    string volume = 9;
    string filledVolume = 10;
    string remainingVolume = 11;
    string cost = 12;
}

Get order by Id

Get order by id from history.

Request

gRPC:

hft.PrivateService.GetOrder

Rest API:

GET /api/orders/{orderId}

Query Parameters

Parameter Type Place Default Description
orderId string query null Unique Order ID.

Response

Response description:

Property Type Description
id string Unique Order ID.
timestamp TimeStamp Timestamp for order creation.
lastTradeTimestamp TimeStamp Timestamp for last trade by order.
status string Order status. List of statuses here.
assetPairId string Symbol unique identifier.
type string Order type: Market or Limit.
side string Order side: Sell or Buy.
price decimal Order price (in quote asset for one unit of base asset).
volume decimal Order volume (in base asset).
filledVolume decimal Order filled volume (in base asset).
remainingVolume decimal Order remaining volume to be filled (in base asset).
GET /api/orders/0c336213-0a64-44a8-9599-e88bf6aa1b69

> Response 200 (application/json) - success response

{
  "payload":
    {
      "id": "0c336213-0a64-44a8-9599-e88bf6aa1b69",
      "timestamp": 1592928606187,
      "lastTradeTimestamp": null,
      "status": "Placed",
      "assetPairId": "BTCUSD",
      "type": "Limit",
      "side": "Buy",
      "price": 4000,
      "volume": 0.0001,
      "filledVolume": 0,
      "remainingVolume": 0.0001
    }
}
package hft;

service PrivateService {
  rpc GetOrder (OrderRequest) returns (OrderResponse);
}

message OrderRequest {
    string orderId = 1;
}

message OrderResponse {
    Order payload = 1;
    hft.common.Error error = 2;
}

message Order {
    string id = 1;
    google.protobuf.Timestamp timestamp = 2;
    oneof optional_lastTradeTimestamp {
        google.protobuf.Timestamp lastTradeTimestamp = 3;
    }
    string status = 4;
    string assetPairId = 5;
    string type = 6;
    Side side = 7;
    string price = 8;
    string volume = 9;
    string filledVolume = 10;
    string remainingVolume = 11;
    string cost = 12;
}

Place a limit order

Place a limit order.

Request

gRPC: hft.PrivateService.PlaceLimitOrder

Rest API: POST /api/orders/limit

Request

Parameter Type Place Default Description
assetPairId string body - Symbol unique identifier.
side string body - Order side: Sell or Buy.
volume decimal body - Order volume (in base asset).
price decimal body - Order price(in quote asset for one unit of base asset).
> Request to create a limit order

{
  "assetPairId": "BTCUSD",
  "side": "buy",
  "volume": 0.0001,
  "price": 4000
}

Response

Response description:

Property Type Description
orderId string Unique order ID
POST /api/orders/limit

> Response 200 (application/json) - success response

{
  "payload": {
    "orderId": "0c336213-0a64-44a8-9599-e88bf6aa1b69"
  },
  "error": null
}
package hft;

service PrivateService {
  rpc PlaceLimitOrder (LimitOrderRequest) returns (LimitOrderResponse);
}

message LimitOrderRequest {
    string assetPairId = 1;
    Side side = 2;
    string volume = 3;
    string price = 4;
}

message LimitOrderResponse {
    LimitOrderPayload payload = 1;
    hft.common.Error error = 2;

    message LimitOrderPayload {
        string orderId = 1;
    }
}

Place a market order

Place a Fill-Or-Kill market order.

Request

gRPC: hft.PrivateService.PlaceLimitOrder

Rest API: POST /api/orders/market

Request

Parameter Type Place Default Description
assetPairId string body - Symbol unique identifier.
side string body - Order side: Sell or Buy.
volume decimal body - Order volume (in base asset).
> Request to create a market order

{
  "assetPairId": "BTCUSD",
  "side": "Buy",
  "volume": 1.554
}

Response

Response description:

Property Type Description
orderId string Unique order ID.
price decimal Market order result price.
POST /api/orders/market

> Response 200 (application/json) - success response

{
  "payload": {
    "orderId": "string",
    "price": 6445.222311
  }
}
package hft;

service PrivateService {
  rpc PlaceMarketOrder (MarketOrderRequest) returns (MarketOrderResponse);
}

message MarketOrderRequest {
    string assetPairId = 1;
    Side side = 2;
    string volume = 3;
}

message MarketOrderResponse {
    MarketOrderPayload payload = 1;
    hft.common.Error error = 2;

    message MarketOrderPayload {
        string orderId = 1;
        string price = 2;
    }
}

Place multiple limit orders

Place multiple limit orders in one package. The method also allows you to replace orders in the order book. You can replace all orders completely, or each separately.

Request

gRPC: hft.PrivateService.PlaceBulkLimitOrder

Rest API: POST /api/orders/bulk

Request

Parameter Type Place Default Description
assetPairId string body - Symbol unique identifier.
cancelPreviousOrders bool body false Cancel existing orders by AssetPair before placing new orders. Default: False.
cancelMode string body null Strategy for canceling orders if the "cancelPreviousOrders" parameter is activated. bothSides, sellSide, buySide.
orders array of BulkOrder body List of new orders to place.

BulkOrder:

Parameter Type Place Default Description
orderAction string body - order side: Sell or Buy.
volume decimal body - Order volume (in base asset).
price decimal body - Order price(in quote asset for one unit of base asset).
oldId string body null Identifier of the order to be replaced. If the parameter is specified, the new order will replace the existing order with the specified ID. If there is no order with the specified ID, then the new order will not be placed.
> Request to create a limit order

{
  "assetPairId": "BTCUSD",
  "cancelPreviousOrders": true,
  "cancelMode": "bothSides",
  "orders": [
    {
      "orderAction": "buy",
      "volume": 1,
      "price": 9600,
      "oldId": "0c336213-0a64-44a8-9599-e88bf6aa1b69"
    }
  ]
}

Response

Response description:

Property Type Description
assetPairId string Symbol unique identifier.
statuses array of BulkOrderItemStatus Array with report about each new order.

BulkOrderItemStatus:

Property Type Description
id string Order ID
error ErrorCode Order result.
volume decimal Order volume (in base asset).
price decimal body
POST /api/orders/bulk

> Response 200 (application/json) - success response

{
  "payload": {
    "assetPairId": "BTCUSD",
    "statuses": [
      {
        "id": "0c113553-0a64-35a1-3221-a12bf6ba1564",
        "error": "success",
        "volume": 1,
        "price": 9600
      }
    ]
  },
  "error": null
}
package hft;

service PrivateService {
  rpc PlaceBulkLimitOrder (BulkLimitOrderRequest) returns (BulkLimitOrderResponse);
}

message BulkLimitOrderRequest {
    string assetPairId = 1;
    bool cancelPreviousOrders = 2;
    oneof optional_cancelMode {
        CancelMode cancelMode = 3;
    }
    repeated BulkOrder orders = 4;
}

message BulkLimitOrderResponse {
    BulkLimitOrderPayload payload = 1;
    hft.common.Error error = 2;

    message BulkLimitOrderPayload {
        string assetPairId = 1;
        repeated BulkOrderItemStatus statuses = 2;
    }
}

message BulkOrderItemStatus {
    string id = 1;
    hft.common.ErrorCode error = 2;
    string volume = 3;
    string price = 4;
}

Mass cancel orders

Cancel all active orders or filter order to cancel by AssetPair or Side.

Request

gRPC: hft.PrivateService.CancelAllOrders

Rest API: DELETE /api/orders

Query Parameters

Parameter Type Place Default Description
assetPairId string query null (Optional) Symbol unique identifier (All asset pairs by default).
side string query null (Optional) Order side Buy or Sell (both sides by default).

Response

No content

DELETE /api/orders

> Response 200 (application/json) - success response

{
  "payload": null
}
package hft;

service PrivateService {
  rpc CancelAllOrders (CancelOrdersRequest) returns (CancelOrderResponse);
}

message CancelOrdersRequest {
    string assetPairId = 1;
    Side side = 2;
}

message CancelOrderResponse {
    bool payload = 1;
    hft.common.Error error = 2;
}

Cancel orders by ID

Cancel a specific order by order ID.

Request

gRPC: hft.PrivateService.CancelAllOrders

Rest API: DELETE /api/orders/{orderId}

Query Parameters

Parameter Type Place Default Description
orderId string path - Unique Order ID.

Response

No content

DELETE /api/orders/{orderId}

> Response 200 (application/json) - success response

{
  "payload": null
}
package hft;

service PrivateService {
  rpc CancelOrder (CancelOrderRequest) returns (CancelOrderResponse);
}

message CancelOrderRequest {
    string orderId = 1;
}

message CancelOrderResponse {
    bool payload = 1;
    hft.common.Error error = 2;
}

Public Stream APIs

Streaming API allows you to subscribe to events from the server and receive them in streaming mode upon the occurrence of the event.

Streaming API is available only when working with the gRPC protocol. In the RestAPI protocol, streaming APIs are not available.

Public Streaming API allows you to receive live market data without authorization.

Follow the current prices

Get current prices online.

After subscribing you will get a data stream. The first packet in the stream will always contain a complete snapshot with the current prices. The following packages in the data stream will come after an asset price change.

Request

gRPC: hft.PublicService.GetPriceUpdates

Query Parameters

Parameter Type Default Description
assetPairIds array of string null Filter by Symbol unique ID. If the array is empty then the server return prices by all symbols.

Response

Array of prices by symbols:

Property Type Description
assetPairId string Symbol unique identifier.
timestamp TimeStamp Timestamp of last order book update.
bid decimal Bid price.
ask decimal Ask price.
package hft;

service PublicService {
  rpc GetPriceUpdates (PriceUpdatesRequest) returns (stream PriceUpdate);
}

message PriceUpdatesRequest {
    repeated string assetPairIds = 1;
}

message PriceUpdate {
    string assetPairId = 1;
    string bid = 2;
    string ask = 3;
    google.protobuf.Timestamp timestamp = 4;
}

Follow current 24hr Statistics

Get current 24hr Ticker Price Change Statistics online.

After subscribing you will get a data stream. The first packet in the stream will always contain a complete snapshot with the current 24hr Ticker Price Change Statistics. The following packages in the data stream will come after a data change.

Request

gRPC: hft.PublicService.GetTickerUpdates

Response

Array with asset description:

Property Type Description
assetPairId string Symbol unique identifier.
volumeBase decimal Trading volume for the last 24h in base asset.
volumeQuote decimal Trading volume for the last 24h in quote asset.
priceChange decimal Price changes(in %) in the last 24h.
lastPrice decimal The last trade price.
high decimal The maximum trade price from the last 24h.
low decimal The minimum trade price from the last 24h.
timestamp TimeStamp Last update timestamp.
package hft;

service PublicService {
  rpc GetTickerUpdates (google.protobuf.Empty) returns (stream TickerUpdate);
}

message TickerUpdate {
    string assetPairId = 1;
    string volumeBase = 2;
    string volumeQuote = 3;
    string priceChange = 4;
    string lastPrice = 5;
    string high = 6;
    string low = 7;
    google.protobuf.Timestamp timestamp = 8;
}

Follow Order Book Ticker

Get current asset pair order books online.

After subscribing you will get a data stream. The first packet in the stream will always contain a complete snapshot with current order books. The follow packages in data stream will only contain changed levels in the order book.

Please note that if a level is deleted at a specific price, a packet containing the level with the specified price will be sent to the stream with zero volume.

Query Parameters

Parameter Type Default Description
assetPairId string null (Optional) Identificator of specific symbol. By default return all symbols.

Request

gRPC: hft.PublicService.GetOrderbookUpdates

Response

Array with order books:

Property Type Description
assetPairId string Symbol unique identifier.
timestamp TimeStamp Timestamp of last order book update.
bids Array of PriceLevel List of changed buy orders.
asks Array of PriceLevel List of changed sell orders.

PriceLevel:

Property Type Description
p decimal Order price indicated in quoted asset per unit of base asset.
v decimal Order volume indicated in base asset.
package hft;

service PublicService {
  rpc GetOrderbookUpdates (OrderbookUpdatesRequest) returns (stream Orderbook);
}

message OrderbookUpdatesRequest {
    string assetPairId = 1;
}

message Orderbook {
    string assetPairId = 1;
    google.protobuf.Timestamp timestamp = 2;
    repeated PriceVolume bids = 3;
    repeated PriceVolume asks = 4;

    message PriceVolume {
        string p = 1;
        string v = 2;
    }
}

Get public trades

Get current public trades online.

After subscribing you will get 50 latest trades for provided asset pair. The first packet in the stream will always contain a complete snapshot with the 50 latest trades. The following packages in the data stream will come after the trade happen.

Request

gRPC: hft.PublicService.GetPublicTradeUpdates

Query Parameters

Parameter Type Default Description
assetPairId string - Filter by Symbol unique ID.

Response

Array of trades by symbols:

Property Type Description
id string Trade ID.
assetPairId string Symbol unique identifier.
dateTime TimeStamp Timestamp of the trade.
volume decimal Bid price.
price decimal Ask price.
side string Trade side: Sell or Buy.
package hft;

service PublicService {
  rpc GetPublicTradeUpdates (PublicTradesUpdatesRequest) returns (stream PublicTradeUpdate);
}

message PublicTradesUpdatesRequest {
    string assetPairId = 1;
}

message PublicTradeUpdate {
    repeated PublicTrade trades = 1;
}

message PublicTrade {
    string id = 1;
    string assetPairId = 2;
    google.protobuf.Timestamp dateTime = 3;
    string volume = 4;
    string price = 5;
    string side = 6;
}

Private Stream APIs

Streaming API allows you to subscribe to events from the server and receive them in streaming mode upon the occurrence of the event.

Streaming API is available only when working with the gRPC protocol. In the RestAPI protocol, streaming APIs are not available.

Private Streaming API allows you to receive your live API account data.

Follow the current balance

Get the current balance from the account.

After subscribing you will get a data stream. The first packet in the stream will always contain a complete snapshot with the current balances of your API account. The following packages in the data stream will come after an asset balance change.

Request

gRPC: hft.PublicService.GetBalanceUpdates

Response

The array of balance by assets.

Property Type Description
assetId string Asset unique identifier.
available decimal Available amount.
reserved decimal Amount reserved in active orders.
timestamp TimeStamp Last balance update on current asset.
package hft;

service PrivateService {
  rpc GetBalanceUpdates (google.protobuf.Empty) returns (stream BalanceUpdate);
}

message BalanceUpdate {
    repeated Balance balances = 1;
}

message Balance {
    string assetId = 1;
    string available = 2;
    string reserved = 3;
    google.protobuf.Timestamp timestamp = 4;
}

Follow trades

Get the flow of trades on the account.

After subscribing you will get a data stream. The packages in the data stream will come after the trade happen.

Request

gRPC: hft.PublicService.GetTradeUpdates

Response

Array of trades:

Property Type Description
id string Trade ID.
orderId string Order ID of this trade.
assetPairId string Trade asset pair ID (symbol).
timestamp TimeStamp Trade timestamp.
role string Trade role. Maker or Taker.
price decimal Trade price.
baseVolume decimal Trade volume in base asset.
quoteVolume decimal Trade volume in quote asset.
baseAssetId string Base asset ID.
quoteAssetId string Quote asset ID.
fee TradeFee (optional) Trade Fee description.
side string Trade side: Sell or Buy.

TradeFee

Property Type Description
assetId string Asset ID
size decimal Fee size
package hft;

service PrivateService {
  rpc GetTradeUpdates (google.protobuf.Empty) returns (stream TradeUpdate);
}

message TradeUpdate {
    repeated Trade trades = 1;
}

message Trade {
    string id = 1;
    google.protobuf.Timestamp timestamp = 2;
    string assetPairId = 3;
    string orderId = 4;
    string role = 5;
    string price = 6;
    string baseVolume = 7;
    string quoteVolume = 8;
    string baseAssetId = 9;
    string quoteAssetId = 10;
    TradeFee fee = 11;
}

message TradeFee {
    string size = 1;
    string assetId = 2;
}

Error codes

Code Meaning
0 Success

General network errors (10xx)

Code Meaning Description
1001 RuntimeError Internal Server Error

Validation errors(11xx)

Code Meaning Description
1100 ItemNotFound resource not found (i.e. asset not found by provided ID)
1101 InvalidField invalid field in the request (i.e. Price must be > 0)

Logic errors(2xxx)

Code Meaning
2000 MeBadRequest
2001 MeLowBalance
2202 MeAlreadyProcessed
2003 MeDisabledAsset
2004 MeUnknownAsset
2005 MeNoLiquidity
2006 MeNotEnoughFunds
2007 MeDust
2008 MeReservedVolumeHigherThanBalance
2009 MeNotFound
2010 MeBalanceLowerThanReserved
2011 MeLeadToNegativeSpread
2012 MeTooSmallVolume
2013 MeInvalidFee
2014 MeInvalidPrice
2015 MeReplaced
2016 MeNotFoundPrevious
2017 MeDuplicate
2018 MeInvalidVolumeAccuracy
2019 MeInvalidPriceAccuracy
2020 MeInvalidVolume
2021 MeTooHighPriceDeviation
2022 MeInvalidOrderValue
2023 MeRuntime