Kronbase API guide | Kronbase technical support | Kronbase

  1. Speed limit is updated to 10 requests per 2 seconds :

1)GET/api/spot/v3/accounts/<currency>/ledger

2)GET/api/spot/v3/orders

3)GET/api/spot/v3/fills

4)GET/api/margin/v3/accounts/<instrument_id>/ledger

5)GET/api/margin/v3/orders

6)GET/api/margin/v3/fills

7)GET/api/futures/v3/orders/<instrument_id>

8)GET/api/futures/v3/fills

9)GET/api/swap/v3/orders/<instrument_id>

10)GET/api/swap/v3/fills

11)GET/api/option/v3/orders/<underlying>

12)GET/api/option/v3/fills/<underlying>;

2.futures added endpointPublic- Delivery/Settlement History

Endpoint:

GET/api/futures/v3/settlement/history

3.added «Testing environment services»

Before you start trading in Kronbase, you can have a simulative trading on our testnet to test the API interface related functions, and adjust your code trading logic.

Trading service available on testnet: futures and options contract.

Service to gradually available: spot trading, margin trading, and perpetual contracts.

The process of creating an APIKey on the testnet is same as on Kronbase.

The testnet domain:RestAPI url: kronbasehttps://testnet.kronbase.com

WebSocket: wss: //real.kronbase.com: 8443 / ws / v3? BrokerId = 184

Kronbase account can be used for logging on testnet. If you already have an kronbase account, you can log in directly. If you do not have one, please click here to sign up.

Start API simulative trading by the following steps:

Register an kronbase account—> Log in to the testnet—> Get testing asset—> Create a testnet APIkey—> Start a simulative trading on the testnet. Users can request all public interfaces for futures and options through the API, including basic contract information and market information. For detailed interface functions, please refer to the API documentation of Testnet.

  1. futures and swap ordering interface add market price function;

Endpoint:

POST /api/futures/v3/order

POST /api/swap/v3/order

5.Trigger type is added to orders for futures and swap.

Specific interface:

POST /api/futures/v3/order_algo

POST /api/swap/v3/order_algo

Added parameters:

Parameter Name

Parameter Type

Description

algo_type

String

1: Limit price 2: Market price;

1.Added «last_fill_id» for return parameters

Endpoint:

{«op»: «subscribe», «args»: [«spot/order:LTC-USDT»]}

Return Parameters
ParametersParameters TypesDescription
last_fill_idStringtrade ID,Transaction ID same as trade_id pushed by the trade channel



2.spot、futures、swap、option added «Public-Tick By Tick»

Endpoint:

{«op»: «subscribe», «args»: [«spot/depth_l2_tbt:BTC-USDT»]} {«op»: «subscribe», «args»: [«futures/depth_l2_tbt:BTC-USD-200327»]} {«op»: «subscribe», «args»: [«swap/depth_l2_tbt:BTC-USD-SWAP»]} {«op»: «subscribe», «args»: [«option/depth_l2_tbt:BTC-USD-200207-9500-C»]}

Return Parameters
ParametersParameters TypesDescription
asksList<String>Selling side
bidsList<String>Buying side
timestampStringSystem time stamp
instrument_idStringTrading pair
checksumStringchecksum



3.Added «trade_id» for return parameters

Endpoint:

GET /api/spot/v3/fills

{«op»: «subscribe», «args»: [«spot/trade:ETH-USDT»]}

Endpoint:

ParametersParameters TypesDescription
trade_idStringtrade_id



4.Added «mark_price» for endpoint

HTTP Requests

GET/api/margin/v3/instruments/<instrument_id>/mark_price

Rate Limit: 20 requests per 2 seconds
Example Request

GET/api/margin/v3/instruments/EOS-USDT/mark_price

Request Parameters
ParametersParameters TypesRequiredDescription
instrument_idStringYesTrading pair symbol
Return Parameters
ParametersParameters TypesDescription
instrument_idStringTrading pair symbol
mark_priceStringSpecify the margin price
timestamptimestampTimestamp
Return Sample
{
    "mark_price":"3.591",
    "instrument_id":"EOS-USDT",
    "timestamp":"2019-06-22T06:28:53.208Z"
}

5.The amount of the order book market depth data returning for the first time on the Public-Tick By Tick channel changed from all entries to 400 entries

6.Added ‘bi_quarter’ into the enumeration of alias

Endpoint:

GET/api/futures/v3/instruments

Return Parameters
ParametersParameters TypesDescription
aliasStringthis_week next_week quarter bi_quarter

 

  1. Added the interface to obtain the «current account transaction procedure level»
      Involved interface:
    

    GET /api/spot/v3/trade_fee,GET /api/futures/v3/trade_fee
  2. Add an interface for obtaining sub-account balance information
      Involved interface:
    

    GET /api/account/v3/sub-account
  3. Increase the interface to obtain the total assets of the account
       Involved interface:
    

    GET /api/account/v3/asset-valuation
  4. Coin Leverage The account information interface adds a maintenance margin rate field and a borrowing amount range field
       Involved interface:
    

    GET /api/margin/v3/accounts
    GET/api/margin/v3/accounts/
    {«op»: «subscribe», «args»: [«spot/margin_account:ETH-USDT»]}
  5. Increase in the leverage of coins and set the leverage multiple interface and query the leverage multiple interface
       Involved interface
    

    POST /api/margin/v3/accounts//leverage
    GET /api/margin/v3/accounts//leverage
  6. wsAPI currency account account channel new add liquidation price Field
       Involved interface:
    

    {«op»: «subscribe», «args»: [«spot/margin_account:ETH-USDT»]}
  7. The currency transaction details interface adds a currency field.
    The interfaces involved:
    GET /api/spot/v3/fills
  1. i / swap / v3 / trade_fee
    
  2. Last_fill_id is added to perpetual ws order

     Involved interface: {"op": "subscribe", "args": ["swap / order: BTC-USD-SWAP"]}
    
  3. RestAPI perpetual contract depth interface, increase merger depth query conditions

      Involved interface: GET / api / swap / v3 / instruments / <instrument_id> / depth
    
  4. In the instrumentid field of perpetual contracts, interfaces for order placing and cancellation, and position inquiry, input parameters support upper and lower case parameters.

  5. The information returned by the perpetual contract position interface adds an unrealized profit and loss field.

      Involved interface: GET / api / swap / v3 / <instrument_id> / position, GET / api / swap / v3 / position,
    
  1. Perpetual account information interface, increase the number of transferable fields The interfaces involved: GET / api / futures / v3 / accounts / {currency}, GET / api / futures / v3 / accounts,

The following updates are expected to launch in Sep.

Details as follows: (Note: This announcement only extends to API users, and V1 Open API does not support USDT-margined futures trading.)

  1. Updates:

Current: Our API cannot differentiate «coin-margined futures trading mode» and «USDT-margined futures trading mode» through parameters.

Endpoint: GET /api/futures/v3/accounts/ Example: GET /api/futures/v3/accounts/BTC

Updates: «currency» will be replaced with «underlying» in parameters. The parameters of coin-margined futures trading mode and USDT-margined futures trading mode are «BTC-USD» and «BTC-USDT» respectively.

Endpoint: GET /api/futures/v3/accounts/ Example of USDT-margined futures trading mode: GET /api/futures/v3/accounts/BTC-USDT Example of coin-margined futures trading mode: GET /api/futures/v3/accounts/BTC-USD

The existing request format remains compatible after the update. corresponds to (underlying index).

Example: GET /api/futures/v3/accounts/BTC = GET /api/futures/v3/accounts/BTC-USD

Note: «POST /api/futures/v3/accounts/margin_mode in setting account mode» in restAPI cannot be used interchangeably. Entering the corresponding underlying index is required while using this API.

  1. Involved Endpoint: restAPI

a. Information on futures accounts of a single currency: GET /api/futures/v3/accounts/

b. Enquiry about account statements: GET /api/futures/v3/accounts//ledger

c. Set the leverage level for futures contracts (cross-margin mode): POST/api/futures/v3/accounts//leverage

d. Obtain the leverage level for futures contracts: GET /api/futures/v3/accounts//leverage

e. Publicly obtain contract information: GET /api/futures/v3/instruments – – – – returning necessary strings with the respons

f. Set futures account mode: POST /api/futures/v3/accounts/margin_mode – – – – this API is incompatible

g. Obtain information on futures accounts of all currency: GET /api/futures/v3/accounts – – – – returning necessary strings with the response

  1. Involved Endpoint: WebSocketAPI

a. Public – channels for full contract data: futures/instruments – – – – necessary strings added to the return parameter

b. Individual – subscribe to account data channels: futures/account

Example of coin-margined futures trading mode: {"op": "subscribe", "args": ["futures/account:BTC"]}
Example of USDT-margined futures trading mode: {"op": "subscribe", "args": ["futures/account:BTC-USDT"]}

If you do not trade USDT-margined futures contracts, your program will remain unaffected, but new parameter fields will be added to the existing API response. Thank you for your understanding.

 

The following updates are expected to launch in Sep.

1.Disabled «id» for spot account data APIs

Details:

GET /api/spot/v3/accounts/ GET /api/spot/v3/accounts {«op»: «subscribe», «args»: [«spot/account:BTC»]}

Return parameter:

ParametersParameters TypesDescription
idStringaccount id

2.Added «forced-liquidation» for cross-margin return when obtaining all/single account data API in futures contracts.

Details:

GET /api/futures/v3/accounts/ GET /api/futures/v3/accounts/

Return parameter:

ParametersParameters TypesDescription
liqui_fee_rateStringliquidation fee

3.Added «holding volume» and «24-hour open price» in the Perpetual swap WebSocket ticker channel

Details:

{«op»: «subscribe», «args»: [«swap/ticker:BTC-USD-SWAP»]}

ParametersParameters TypesDescription
open_interestStringholding volume
open_24hString24-hour open price



4.Adjustment of Parameter Type of Leverage


4.1) restAPi: Perpetual Swap position API
«GET /api/swap/v3/position GET /api/swap/v3/position»


4.2) wsAPI: Channel of Perpetual Swap position
{«op»: «subscribe», «args»: [«swap/position:BTC-USD-SWAP»]}


4.3) rest: Perpetual Swap order list (Algo order)
«GET /api/swap/v3/order_algo»


Leverage levels return have been changed back to two decimal places from integers.
Past Leverage: «20»
Current leverage:»20.00″

5.Added «created_at» in Spot Trading WebSocket Platform
Details:
{«op»: «subscribe», «args»: [«spot/order:LTC-USDT»]}
Return Parameter:

ParametersParameters TypesDescription
created_atStringtime of order created

 

1.Added «withdraw_id» for request and return parameters

Endpoint:

GET /api/account/v3/withdrawal/history/<currency>

prarmeters:

ParametersParameters TypesRequiredDescription
withdraw_idStringNoWithdrawal ID

Transfer currency only, return all withdrawal record of this trading pair.

Return the specified withdrawal record after sending currency and withdraw_id

Return Parameters

ParametersParameters TypesDescription
withdraw_idStringWithdrawal ID

2.Request withdrawal record for all tokens. Added «withdraw_id» for return parameter.

Endpoint:

GET /api/account/v3/withdrawal/history

Return Parameters

ParametersParameters TypesDescription
withdraw_idStringWithdrawal ID

3.The parameter «order_id» of spot, futures and perpetual swap APIs for obtaining transaction details is now optional.

Endpoint:

GET /api/spot/v3/fillsGET /api/futures/v3/fillsGET /api/swap/v3/fills

prarmeters:

ParametersParameters TypesRequiredDescription
order_idStringNoOrder ID

4.For futures order placement, leverage request parameter (leverage) is now optional. The documentation is now unavailable.

Endpoint:

POST /api/futures/v3/order

POST /api/futures/v3/orders

prarmeters:

ParametersParameters TypesRequiredDescription
leverageStringNoleverage

5.Request parameter added «depth» for futures and perpetual swap depth API.

Endpoint:

GET /api/futures/v3/instruments/<instrument_id>/book

GET /api/swap/v3/instruments/<instrument_id>/depth

prarmeters:

ParametersParameters TypesRequiredDescription
depthStringNoAggregation of the order book. e.g . 0.1, 0.001

6.Obtain close details of futures through API

Endpoint:

GET /api/futures/v3/accounts//ledger

prarmeters:

ParametersParameters TypesRequiredDescription
typeStringNo20.Partially-closed Short 21.Partially-closed Long

7.Add «Realized profit of long/short positions» for futures single token holding API, all holding APIs, and WebSocket user holding channels.

Endpoint:

GET /api/futures/v3//position

GET /api/futures/v3/position

{«op»: «subscribe», «args»: [«futures/position:BTC-USD-170317»]}

Return Parameters

ParametersParameters TypesDescription
long_settled_pnlStringRealized profit of long positions
short_settled_pnlStringRealized profit of short positions

8.Add «Realized profit of positions» for swap single token holding API, all holding APIs, and WebSocket user holding channels.

Endpoint:

GET /api/swap/v3//position

GET /api/swap/v3/position

{«op»: «subscribe», «args»: [«swap/position:BTC-USD-SWAP»]}

Return Parameters

ParametersParameters TypesDescription
settled_pnlStringRealized profit of positions

9.API Adjustment of swap:

1) Restful: public-next perpetual swap settlement time capture endpoint

Endpoint:

GET /api/swap/v3/instruments/<instrument_id>/funding_time

Return Parameters

ParametersParameters TypesDescription
funding_rateStringcurrent funding rate
estimated_rateStringnext estimated funding rate
settlement_timeStringsettlement rate

2)WebSocket:public-funding rate channel(swap/funding_rate)

Return Parameters

ParametersParameters TypesDescription
estimated_rateStringnext estimated funding rate

3) The value of the current parameter funding_rate in V3 API will be changed from «funding rate» to «estimated funding rate»


10.Updates on V3 Open API for Spot/Margin Trading Transaction Fee («Fee»)


1)Obtain Transaction Details
«GET /api/margin/v3/fills» and «GET /api/spot/v3/fills»


2)Bills Details:
«GET /api/margin/v3/accounts//ledger» and «GET /api/spot/v3/accounts//ledger»


The rebate and transaction fee will be shown in fee parameters. Rebates will be displayed in positive numbers, and transaction fees will be displayed in negative numbers.

The following updates are scheduled to launch in June. Users please take necessary measures beforehand.

1、Pagination

Kronbase uses cursor pagination for some REST requests which return arrays.

Cursor pagination allows for fetching results before and after the current page of results and is well suited for realtime data. Endpoints like /trades, /fills, /orders, return the latest items by default. To retrieve more results subsequent requests should specify which direction to paginate based on the data previously returned.

before and after cursors are available via response headers OK-BEFORE and OK-AFTER. Your requests should use these cursor values when making requests for pages after the initial request.

EXAMPLE

GET /api/spot/v3/orders?before=2&limit=30

Parameters

Parameters Types

Required

Description

after

String

No

Request page before (older) this pagination id,the parameter are order_id, ledger_id or trade_id of the endpoint, etc.

before

String

No

Request page after (newer) this pagination id,the parameter are order_id, ledger_id or trade_id of the endpoint, etc.

limit

String

No

Number of results per request. Maximum 100. (default 100)

BEFORE AND AFTER CURSORS

The before cursor references the first item in a results page and the after cursor references the last item in a set of results.

The response will contain a OK-BEFORE header which will return the cursor id to use in your next request for the page before the current one. The page before is a newer page and not one that happened before in chronological time.

The response will also contain a OK-AFTER header which will return the cursor id to use in your next request for the page after this one. The page after is an older page and not one that happened after this one in chronological time.

Endpoint:

GET /api/futures/v3/accounts/<currency>/ledger

GET /api/futures/v3/orders/<instrument_id>

GET /api/futures/v3/fills

GET /api/futures/v3/instruments/<instrument_id>/trades

GET /api/spot/v3/orders_pending

GET /api/account/v3/ledger

GET /api/futures/v3/accounts/<currency>/ledger

GET /api/futures/v3/orders/<instrument_id>

GET /api/futures/v3/fills

GET /api/futures/v3/instruments/<instrument_id>/trades

GET /api/swap/v3/accounts/<instrument_id>/ledger

GET /api/swap/v3/orders/<instrument_id>

GET /api/swap/v3/fills

GET /api/swap/v3/instruments/<instrument_id>/trades

2、

When ‘from’ or ‘to’ is 0, sub account parameter is required.

When ‘from’ is 0, ‘to’ is only can be 6 (that is, the funding account of the sub-account can only be transferred to the funding account of the main account).

When ‘from’ or ‘to’ is 5, instrument_id is required.

«to» is specified to 1-9, and when «sub_account» is filled with a sub-account ID, user may transfer fund from the main account to the sub-account’s corresponding spot or derivative account directly.

Example Request

POST /api/account/v3/transfer

Request Parameters

Parameters

Parameters Types

Required

Description

currency

String

Yes

Token

amount

String

Yes

Transfer amount

from

String

Yes

the remitting account (0: sub account 1: spot 3: futures 4:C2C 5: margin 6: Funding Account 8:PiggyBank 9:swap)

to

String

Yes

the beneficiary account(0: sub account 1:spot 3: futures 4:C2C 5: margin 6: Funding Account 8:PiggyBank 9 :swap)

sub_account

String

No

sub account name

instrument_id

String

No

Margin trading pair transferred out, for supported pairs only

to_instrument_id

String

No

Margin trading pair transferred in, for supported pairs only

Return Parameters

Parameters

Parameters Types

Description

transfer_id

String

Transfer ID

currency

String

Token to be transferred

from

String

The remitting account

amount

String

Transfer amount

to

String

The beneficiary account

result

Boolean

Transfer result. An error code will be displayed if it failed.

The following updates are scheduled to launch in May. Users please take necessary measures beforehand.

1.Kronbase uses cursor pagination for all REST requests which return arrays. Cursor pagination allows for fetching results before and after the current page of results and is well suited for realtime data. Endpoints like /trades, /fills, /orders, return the latest items by default. To retrieve more results subsequent requests should specify which direction to paginate based on the data previously returned.

from and to cursors are available via response headers OK-FROM and OK-TO. Your requests should use these cursor values when making requests for pages after the initial request.

The from cursor references the first item in a results page and the after cursor references the last item in a set of results.

To request a page of records before the current one, use the before query parameter. Your initial request can omit this parameter to get the default first page.

Example

If the ID’s of the returned results are: 111, 112, 113, 114, 115, 116, 117, 118, 119, 120

Then they will be ordered in: 120, 119, 118, 117, 116, 115, 114, 113, 112, 111

The OK-FROM ID is now 120, and the OK-TO ID is now 111. If you want to access to updated data such as data after 120, then you will have to use the before parameters. For example: orders?before=120&limit=5 will return the 5 strings of data after 120, which is 125, 124, 123, 122, 121

prarmeters:

Parameters

Parameters Types

Required

Description

from

String

No

Request page before (newer) this pagination id,the parameter are order_id, ledger_id or trade_id of the endpoint, etc.

to

String

No

Request page after (older) this pagination id,the parameter are order_id, ledger_id or trade_id of the endpoint, etc.

limit

String

No

Number of results per request. Maximum 100. (default 100)

Endpoint:

GET /api/account/v3/ledger

GET /api/futures/v3/accounts/<currency>/ledger

GET /api/futures/v3/orders/<instrument_id>

GET /api/futures/v3/fills

GET /api/futures/v3/instruments/<instrument_id>/trades

GET /api/swap/v3/accounts/<instrument_id>/ledger

GET /api/swap/v3/orders/<instrument_id>

GET /api/swap/v3/fills

GET /api/swap/v3/instruments/<instrument_id>/trades

  1. Add a channel for pushing full contract:When new contract is live, full contract data will be pushed once;
  2. [Functionality Optimization] The return parameter of billing statement request API of perpetual swap will include «details», «currency», and «balance» (to show statement types)

| currency | String | Token, «btc» | | details | String | If the type is generated by transaction, the «order_id» and «instrument_id» will be included in details | | balance | String |balance: String of contracts of open and closed positions (positive for open positions; negative for closed positions; when type is fee, balance is 0) |

Market involved: Perpetual Swap

API involved – Rest API:

GET /api/swap/v3/accounts/<instrument_id>/ledger

  1. [Functionality Optimization] The return parameter of obtain order list and obtain order details of spot and margin trading will include average transaction price «price_avg»

| price_avg | String | Average price |

Markets involved: Token Trading, Spot Margin

API involved – Rest API:

GET /api/spot/v3/orders

GET /api/spot/v3/orders/<order_id>

GET /api/margin/v3/orders

GET /api/margin/v3/orders/<order_id>

  1. [Functionality Optimization] The request and return parameters of spot and margin trading, futures, and perpetual swap will include UserID «client_oid» parameter. «order_id» will be optional. Users can obtain all trading details of the current trading pair.

| client_oid | String | No | the order ID customized by yourself , The client_oid type should be comprised of alphabets + Strings or only alphabets within 1 – 32 characters, both uppercase and lowercase letters are supported | | order_id | String | No |Order ID. If order placement fails, this value will be -1. |

Markets involved: Spot, margin, futures, perpetual swap

API involved – Rest API:

GET /api/spot/v3/fills

GET /api/margin/v3/fills

GET /api/futures/v3/fills

GET /api/swap/v3/fills

  1. [Functionality Optimization] Bulk order placement API of spot trading, margin trading, futures, and perpetual swap
  2. a) For spot and margin trading bulk order placement return, the underscore «_» in trading pairs will be changed to hyphen «-» ; For example: «btc_usdt» will be changed to «btc-usdt».
  3. b) When spot and margin trading bulk order placement return shows «error_code 33017», or futures and perpetual swap bulk order placement return shows «error_code 32015», the http status code should return to «400»;
  4. c) When placing multiple orders and only some of the orders show insufficient balance error, http status code should also be «400».

Markets involved: Spot, margin, futures, perpetual swap

API involved – Rest API:

POST /api/spot/v3/batch_orders

POST /api/margin/v3/batch_orders

POST /api/futures/v3/batch_orders

POST /api/swap/v3/batch_orders

7.[Functionality Optimization] The billing statement API request parameter of spot trading, futures, and perpetual swap will include statement type «type»

Markets involved: Spot, futures, perpetual swap

API involved – Rest API:

GET /api/spot/v3/accounts/<currency>/ledger

GET /api/futures/v3/accounts/<currency>/ledger

GET /api/swap/v3/accounts/<instrument_id>/ledger

 

Updates:

Push

1)ok_sub_futureusd_positions Futures position data channel

a. Fixed-margin Mode Return Format Update:

Before Update: long and short directions, return 10x and 20x leverage open position information, push 0 if no data;

After Update: long and short directions, return n times and m times leverage open position information; push 0 if no data;

Old format before update:

[
    {
        "binary":0,
        "channel":"ok_sub_futureusd_positions",
        "data":{
            "symbol":"eos_usd",
            "user_id":7669455,
            "positions":[
                {
                    "lever_rate":10,
                    "avgprice":4.849,
                    "contract_id":201906280200053,
                    "hold_amount":1,
                    "contract_name":"EOS0628",
                    "costprice":4.849,
                    "forcedprice":4.44862378,
                    "bondfreez":0,
                    "eveningup":1,
                    "fixmargin":0.20622809,
                    "balance":0.20684677,
                    "position":1,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                },
                {
                    "lever_rate":10,
                    "avgprice":0,
                    "contract_id":201906280200053,
                    "hold_amount":0,
                    "contract_name":"EOS0628",
                    "costprice":0,
                    "forcedprice":0,
                    "bondfreez":0,
                    "eveningup":0,
                    "fixmargin":0,
                    "balance":0.20684677,
                    "position":2,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                },
                {
                    "lever_rate":20,
                    "avgprice":0,
                    "contract_id":201906280200053,
                    "hold_amount":0,
                    "contract_name":"EOS0628",
                    "costprice":0,
                    "forcedprice":0,
                    "bondfreez":0,
                    "eveningup":0,
                    "fixmargin":0,
                    "balance":0.20684677,
                    "position":1,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                },
                {
                    "lever_rate":20,
                    "avgprice":5.423,
                    "contract_id":201906280200053,
                    "hold_amount":0,
                    "contract_name":"EOS0628",
                    "costprice":5.423,
                    "forcedprice":0,
                    "bondfreez":0,
                    "eveningup":0,
                    "fixmargin":0,
                    "balance":0.20684677,
                    "position":2,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                }
            ]
        }
    }
]

New format after update:

[
    {
        "binary":0,
        "channel":"ok_sub_futureusd_positions",
        "data":{
    "symbol":"etc_usd",
    "user_id":36203808,
    "positions":[
        {
            "lever_rate":5,
            "avgprice":56.89655172,
            "contract_id":20170310446,
            "hold_amount":10,
            "contract_name":"ETC0310",
            "costprice":56.89655172,
            "forcedprice":52.5,
            "bondfreez":0,
            "eveningup":5,
            "fixmargin":0.17575758,
            "balance":0.2067697,
            "position":1,
            "longMaintainenceRatio":"0.015",
            "profitreal":-0.00070909,
            "position_id":2778972475169792
        },
        {
            "lever_rate":25,
            "avgprice":33,
            "contract_id":20170310446,
            "hold_amount":2,
            "contract_name":"ETC0310",
            "costprice":33,
            "forcedprice":34.2157,
            "bondfreez":0,
            "eveningup":1,
            "fixmargin":0.03030303,
            "balance":0.2067697,
            "shortMaintainenceRatio":"0.015",
            "position":2,
            "profitreal":-0.00070909,
            "position_id":2778972475169792
        }
    ]
}

b. New Return Parameters:

Fixed-margin Mode

|longMaintainenceRatio |String |Maintenance Margin Ratio for Long Position |

|shortMaintainenceRatio |String | Maintenance Margin Ratio for Short Position |

2)ok_sub_futureusd_userinfo Futures Account Information Channel

New Return Parameters:

Fixed-margin Mode

| bannerFrozen |String |Frozen |

Cross-margin Mode

|bannerFrozen |String |Frozen |

| maintainenceRatio |String |Maintenance Margin Ratio |

 

  1. Liquidation Mode Settings

You can choose the liquidation mode for futures trading. Please note that you would not be able to switch between the modes if you have any open position.

Speed Limit: 5 times / 2s

HTTP Request

POST /api/futures/v3/accounts/liqui_mode

Example Request

POST /api/futures/v3/accounts/liqui_mode{"currency":"btc","liqui_mode":"tier"}

Request Parameters
ParametersParameters TypesRequiredDescription
currencyStringYestoken
liqui_modestringYesLiquidation mode: tier (partial), legacy(full)
Return Parameters
ParametersParameters TypesDescription
liqui_modestringLiquidation mode: tier (partial), legacy(full)
currencyStringtoken
resultStringresult, Error message will be returned if the setting failed.
  1. Cross-margin Mode: Added API to get:

a.maintenance margin ratio

b.current liquidation mode

Fixed Margin Mode: Added API to get current liquidation mode.

Account information for all tokens (same for single token)

The processing time for getting futures account information of all tokens can be long. You are recommended to get the information separately by choosing one token at a time.

Speed Limit: 1 time /10s

HTTP Requests

GET /api/futures/v3/accounts

Example Request

GET /api/futures/v3/accounts

Return Parameters

Cross-margin Mode

ParametersParameters TypesDescription
maint_margin_ratioStringMaintenance Margin Ratio
liqui_modestringLiquidation mode: tier(partial), legacy(full)

Fixed Margin Mode

ParametersParameters TypesDescription
liqui_modestringLiquidation mode: tier(partial), legacy(full)
  1. Position Information

Cross-margin Mode: margin, profit, profit rate, unrealized profits and losses

Fixed Margin Mode: margin ratio, maintenance margin ratio, profit, unrealized profits and losses

Futures Position Information

The processing time for getting futures account information of all tokens can be long. You are recommended to get the information separately by choosing one token at a time.

Speed Limit: 5 times /2s

HTTP Requests

GET /api/futures/v3/position

Example Request

GET /api/futures/v3/position

Return Parameters

Cross-margin Mode

ParametersParameters TypesDescription
short_marginStringMargin for short positions
short_pnlStringProfit of short positions
short_pnl_ratioStringProfit rate of short positions
short_unrealised_pnlStringUnrealized profits and losses of short positions
long_marginStringMargin for long positions
long_pnlStringProfit of long positions
long_pnl_ratioStringProfit rate of long positions
long_unrealised_pnlStringUnrealized profits and losses of long positions

Fixed Margin Mode

ParametersParameters TypesDescription
short_margin_ratioStringMargin ratio of short positions
short_maint_margin_ratioStringMaintenance margin ratio of short positions
short_pnlStringProfit of short positions
short_unrealised_pnlStringUnrealized profits and losses of short positions
long_margin_ratioStringMargin ratio of long positions
long_maint_margin_ratioStringMaintenance margin ratio of long positions
long_pnlStringProfit of long positions
long_unrealised_pnlStringUnrealized profits and losses of long positions
  1. Leverage (1-100x; adjustable for open positions)

Set the leverage level for futures contracts

Set the leverage level for futures account. You will not be able to adjust the leverage level if you have any open orders.

Speed Limit: 5 times /2s

HTTP Requests

POST /api/futures/v3/accounts/<currency>/leverage

Example Request

POST /api/futures/v3/accounts/btc/leverage{"leverage":"10"}(cross-margin mode sample)

POST /api/futures/v3/accounts/btc/leverage{"instrument_id":"BTC-USD-180213","direction":"long","leverage":"10"}(fixed margin mode sample)

Request Parameters

Cross-margin Mode

ParametersParameters TypesRequiredDescription
leverageNumberYes1-100x
currencyStringYesToken. E.g. BTC

Fixed Margin Mode

ParametersParameters TypesRequiredDescription
currencyStringYesToken. E.g. BTC
instrument_idStringYesContract ID. E.g. BTC-USD-180213
directionStringYesSide (long or short)
leverageNumberYes1-100x

Error message:

32040: (error message:»EOS-USD-180213″) You have open positions or orders.

32060: Insufficient margin. Unable to adjust leverage.

WebSocket:

1.Account channel

Cross-margin Mode: Added API to get:

a.maintenance margin ratio

b.current liquidation mode

Fixed Margin Mode: Added API to get current liquidation mode.

Get the user’s account information (Login required)

Example:

{«op»: «subscribe», «args»:[«futures/account:EOS»]}

futures/account is channel name ,BTC is token

Response Parameters

ParametersParameters TypesDescription
maint_margin_ratioStringMaintenance Margin Ratio
liqui_modestringLiquidation Mode: tier(partial), legacy(full)
ParametersParameters TypesDescription
liqui_modestringLiquidation Mode: tier(partial), legacy(full)
  1. Position Information Channel

Cross-margin Mode: margin, profit, profit rate, unrealized profits and losses

Fixed Margin Mode: margin ratio, maintenance margin ratio, profit, unrealized profits and losses

send examples

{«op»: «subscribe», «args»:[«futures/position:EOS-USD-190628»]}

futures/position is channel name ,BTC-USD-170317 is instrument_id

response parameters:

Cross-margin Mode

ParametersParameters TypesDescription
short_marginStringMargin for short positions
short_pnlStringProfit of short positions
short_pnl_ratioStringProfit ratio of short positions
short_unrealised_pnlStringUnrealized profits and losses of short positions
long_marginStringMargin for long positions
long_pnlStringProfit of long positions
long_pnl_ratioStringProfit ratio of long positions
long_unrealised_pnlStringUnrealized profits and losses of long positions

Fixed Margin Mode

ParametersParameters TypesDescription
short_margin_ratioStringMargin ratio of short positions
short_maint_margin_ratioStringMaintenance margin ratio of short positions
short_pnlStringProfit of short positions
short_unrealised_pnlStringUnrealized profits and losses of short positions
long_margin_ratioStringMargin ratio of long positions
long_maint_margin_ratioStringMaintenance margin ratio of long positions
long_pnlStringProfit of long positions
long_unrealised_pnlStringUnrealized profits and losses of long positions

 

Updates:

Push

1)ok_sub_futureusd_positions Futures position data channel

a. Fixed-margin Mode Return Format Update:

Before Update: long and short directions, return 10x and 20x leverage open position information, push 0 if no data;

After Update: long and short directions, return n times and m times leverage open position information; push 0 if no data;

Old format before update:

[
    {
        "binary":0,
        "channel":"ok_sub_futureusd_positions",
        "data":{
            "symbol":"eos_usd",
            "user_id":7669455,
            "positions":[
                {
                    "lever_rate":10,
                    "avgprice":4.849,
                    "contract_id":201906280200053,
                    "hold_amount":1,
                    "contract_name":"EOS0628",
                    "costprice":4.849,
                    "forcedprice":4.44862378,
                    "bondfreez":0,
                    "eveningup":1,
                    "fixmargin":0.20622809,
                    "balance":0.20684677,
                    "position":1,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                },
                {
                    "lever_rate":10,
                    "avgprice":0,
                    "contract_id":201906280200053,
                    "hold_amount":0,
                    "contract_name":"EOS0628",
                    "costprice":0,
                    "forcedprice":0,
                    "bondfreez":0,
                    "eveningup":0,
                    "fixmargin":0,
                    "balance":0.20684677,
                    "position":2,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                },
                {
                    "lever_rate":20,
                    "avgprice":0,
                    "contract_id":201906280200053,
                    "hold_amount":0,
                    "contract_name":"EOS0628",
                    "costprice":0,
                    "forcedprice":0,
                    "bondfreez":0,
                    "eveningup":0,
                    "fixmargin":0,
                    "balance":0.20684677,
                    "position":1,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                },
                {
                    "lever_rate":20,
                    "avgprice":5.423,
                    "contract_id":201906280200053,
                    "hold_amount":0,
                    "contract_name":"EOS0628",
                    "costprice":5.423,
                    "forcedprice":0,
                    "bondfreez":0,
                    "eveningup":0,
                    "fixmargin":0,
                    "balance":0.20684677,
                    "position":2,
                    "profitreal":-0.00061868,
                    "position_id":2517385395344384
                }
            ]
        }
    }
]

New format after update:

[
    {
        "binary":0,
        "channel":"ok_sub_futureusd_positions",
        "data":{
    "symbol":"etc_usd",
    "user_id":36203808,
    "positions":[
        {
            "lever_rate":5,
            "avgprice":56.89655172,
            "contract_id":20170310446,
            "hold_amount":10,
            "contract_name":"ETC0310",
            "costprice":56.89655172,
            "forcedprice":52.5,
            "bondfreez":0,
            "eveningup":5,
            "fixmargin":0.17575758,
            "balance":0.2067697,
            "position":1,
            "longMaintainenceRatio":"0.015",
            "profitreal":-0.00070909,
            "position_id":2778972475169792
        },
        {
            "lever_rate":25,
            "avgprice":33,
            "contract_id":20170310446,
            "hold_amount":2,
            "contract_name":"ETC0310",
            "costprice":33,
            "forcedprice":34.2157,
            "bondfreez":0,
            "eveningup":1,
            "fixmargin":0.03030303,
            "balance":0.2067697,
            "shortMaintainenceRatio":"0.015",
            "position":2,
            "profitreal":-0.00070909,
            "position_id":2778972475169792
        }
    ]
}

b. New Return Parameters:

Fixed-margin Mode

|longMaintainenceRatio |String |Maintenance Margin Ratio for Long Position |

|shortMaintainenceRatio |String | Maintenance Margin Ratio for Short Position |

2)ok_sub_futureusd_userinfo Futures Account Information Channel

New Return Parameters:

Fixed-margin Mode

| bannerFrozen |String |Frozen |

Cross-margin Mode

|bannerFrozen |String |Frozen |

| maintainenceRatio |String |Maintenance Margin Ratio |

Arrow-up