NAV
protobuf json

Lykke trading API

Lykke high-frequency trading API.

This API allows Lykke clients to carry out automated trading on special sub-accounts. Also, the API allows you to get public data about the Lykke market, such as current prices, order books, and other parameters for 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-07-01 | The release of a new HFT API.

The new APIs now support the gRPC protocol. This protocol uses HTTP 2.0 standard, WebSocket, and ProtoBuf, helping to reduce latency, more efficient use of the CPU, and network resources on the client-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.

A new response format from the server, abstracted from the protocol. Allows you to work in a custom manner with the API regardless of the protocol. The contracts in the Rest API protocol have been updated as well. A new set of functions and models is being used, very similar to gRPC protocol. We have removed deprecated methods and created new methods. You can find them in Swagger UI.

Thanks to the gRCP protocol we added the ability to receive a market data stream from the server:

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

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

We have also optimized the API Keys management and increased the overall security.

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

Protocol description

Lykke HFT API allows users to use 2 kinds of protocol gRPC API and Rest API. Both kinds of APIs support the same methods with the same data format, but only gRPC API supports receiving streaming data from the platform.

gRPC API

The gRCP API utilizes 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 you can easily generate a client library in many programming languages. Also, the gRPC framework supports working with stream, which makes it easy to receive events 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: BloomRPC

API Endpoint:

Proto files

Rest API

The rest API uses the classic HTTP based framework that includes working with HTTP 1.1, and JSON. Rest API allows users to just call RPC methods without streaming data from the server.

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

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

API Endpoint:

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 Authorization: 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 problems with the non-strict precision "double" type.

In the Rest API contact, the decimal type is presented as 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 order book.
PartiallyMatched Order in order book and partially filled.
Matched Order is filled.
Pending An order is pending a trigger to be placed in the order book.
Cancelled Order is cancelled by user.
Replaced Order is replaced (canceled) by the user.
Rejected Order rejectd by the system.

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 Default 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 specific asset.

Request

gRPC: hft.PublicService.GetAsset

RestAPI: GET /api/assets/{assetId}

Query Parameters

Parameter Type Place 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 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 Description
assetPairId string query (Optional) Identificator of specific symbol. By default return all symbols.
depth uint query (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 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 Description
assetPairIds string query (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 Description
assetPairIds array of string query (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 Description
assetPairId string query (optional) Symbol unique identifier.
side string query (optional) Side of trade: buy or sell.
offset uint query (optional) Skip the specified number of elements.
take uint query (optional) Take the specified number of elements.
from TimeStamp query (optional) From timestamp.
to TimeStamp query (optional) To timestamp.

Query Parameters

Parameter Type Place 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.

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
    },
    {
      "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
    }]
}

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;
}

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 Description
assetPairId string query (optional) Symbol unique identifier.
offset uint query (optional) Skip the specified number of elements.
take uint query (optional) Take the specified number of elements.

Response

Asset 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;
}

Place a limit order

Place a limit order.

Request

gRPC: hft.PrivateService.PlaceLimitOrder

Rest API: POST /api/orders/limit

Request

Parameter Type Place 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 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 Description
assetPairId string body Symbol unique identifier.
cancelPreviousOrders bool body Cancel existing orders by AssetPair before placing new orders. Default: False.
cancelMode string body 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 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 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 Description
assetPairId string query (Optional) Symbol unique identifier (All asset pairs by default).
side string query (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 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 Description
assetPairIds array of string 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 Description
assetPairId string (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;
    }
}

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.

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;
}

Follow updates by orders

Get the flow of orders updates from your API account.

After subscribing you will receive a data stream. Packets in the data stream will come after any changes with the active order - placing, matching, canceling, etc.

Request

gRPC: hft.PublicService.GetOrderUpdates

Response

Array with order state:

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). 
package hft;

service PrivateService {
  rpc GetOrderUpdates (google.protobuf.Empty) returns (stream OrderUpdate);
}

message OrderUpdate {
    repeated Order orders = 1;
}

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;
}

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
protobuf json