NAV Navbar
json

REST API

BaseUrl: https://openapi.digifinex.com/swap/v2

Public endpoint

Private endpoint

account

trade

copy trading

Authentication

Making Requests

All private REST requests must contain the following headers:

Signature

The ACCESS-SIGN header is generated as follows:

Example: sign=CryptoJS.HmacSHA256(timestamp + 'GET' + '/swap/v2/positions?instrument_id=BTCUSDTPERP', ApiSecret).toString(Hex)
The timestamp value is the same as the ACCESS-TIMESTAMP header with millisecond as a string, e.g. 1657522488402.
The request method should be in UPPERCASE: e.g. GET and POST.
The requestPath is the path of requesting an endpoint. Example: /swap/v2/positions?instrument_id=BTCUSDTPERP
The body refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET requests).
Example: {"instrument_id":"BTCUSDTPERP","leverage":"20","side":"1"}
The SecretKey is generated when you create an APIKey. Example: ffd4e900015bdfaf5a72aa06f5612290df25c23a78

RateLimit

IP Limits

Account Limits

APIKey Limits

ErrorCode

code message description
0 success request success
400001 ParamMissing missing require param
400002 ParamInvalid param invalid
400003 InvalidIP unAuthentication ip
400004 InvalidSign access-sign miss matched
400005 PermissionDeny permission deny
400006 InvalidApiKey invalid api key
401001 OrderExist can not change leverage when exist no finish order
401002 OverMaxOpenLimit position open value over max limit
401003 NotEnoughMoney account balance not enough
401004 InstrumentNotTrading instrument trade is suspended
401005 InstrumentMaintain instrument under maintain
401006 InstrumentMinSizeLimit order size less than mini order size
401007 InvalidPricePrecision price precision invalid
401008 MarketTradingNotSupport current instrument deny market trade
401009 MarketNoOrder market order not support when opponent is empty
401010 PriceOverMaxBuyLimit order price over max buy price
401011 PriceBelowMinSellLimit order price less than min sell price
401012 NotEnoughClosePosition not enough position to close
401013 PriceOverLiquidationLimit order price inferior to liquidation price
401014 OrderCountOverLimit batch order/cancel count over limit (max 20)
401015 PositionNotIsolated can not do this when position mode is not isolated
401016 PositionExist can not do this when position exist
401017 PositionNotExist can not do this when position not exist
403001 FrequencyLimit request reach frequency limit
403002 RequestForbidden request forbidden (repeat requests after reach frequency limit)
404001 FollowExpertLocked expert is locked, can't open position
404002 FollowSettleLocked in the contract settlement, it does not support the initiation of
bringing orders
404003 FollowInstrumentNotExist the documentary contract variety is offline or does not exist
404004 FollowOrderChangeHasPosition existing positions, does not support modification of margin mode
or leverage
404005 FollowOrderChangeHasFollow existing orders, does not support modification of margin mode or leverage
404006 FollowOrderChangeHasOrder there is already a pending order, which does not support modifying the margin mode or leverage
404007 FollowOrderPriceOffsetOverLimit the price of the order deviates from the mark price a lot, for the sake of your account risk, please reduce the number of open positions
404008 FollowOrderStopEarnTriggerPriceLarge the take profit price must be greater than the order price
404009 FollowOrderStopEarnTriggerPriceLess the take profit price must be less than the order price
404010 FollowOrderStopLossTriggerPriceLess the stop loss price must be lower than the order price
404011 FollowOrderStopLossTriggerPriceLarge the stop loss price must be greater than the order price
404012 FollowErrorOrderClosed the order has been executed to close the position
404013 FollowOrderNotExist order does not exist
404014 FollowStopProfitExist take profit already exists
404015 FollowStopLossExist stop loss already exists
500001 SystemError system error
500002 SystemException system exception, pls retry

Public endpoint

Server Time

request URL: GET /swap/v2/public/time

response example

{
  "code":0,
  "data":1657528968992
}

response param

Parameters Types Description
code number error code
data number milliseconds since UNIX epoch

Api Weight

request URL: GET /swap/v2/public/api_weight

response example

{
  "code":0,
  "data":[
    {
      "path":"/swap/v2/api_weight",
      "weight":1
    },
    {
      "path":"/swap/v2/balance",
      "weight":1
    }
  ]
}

response param

Parameters Types Description
code number error code
- data object response data
path string route path
weight number route weight

Instruments

request URL: GET /swap/v2/public/instruments

request param

Parameters Required Type Description
type no number instrument type 1 simulate 2 real default real

response example

 {
  "code":0,
  "data": [
    {
      "instrument_id":"BTCUSDT2PERP",
      "type":"SIMULATE",
      "contract_type":"PERPETUAL",
      "base_currency":"BTC",
      "quote_currency":"USDT2",
      "clear_currency":"USDT2",
      "contract_value":"0.001",
      "contract_value_currency":"BTC",
      "is_inverse": false,
      "is_trading":true,
      "status":"ONLINE",
      "price_precision":4,
      "tick_size":"0.0001",
      "min_order_amount":1,
      "open_max_limits": [
        {
          "leverage":"20",
          "max_limit":"100000000"
        }
      ]},
    {
      "instrument_id":"EOSUSDT2PERP",
      "type":"SIMULATE",
      "contract_type":"PERPETUAL",
      "base_currency":"EOS",
      "quote_currency":"USDT",
      "clear_currency":"USDT",
      "contract_value":"0.001",
      "contract_value_currency":"EOS",
      "is_inverse": false,
      "is_trading":false,
      "status":"ONLINE",
      "price_precision":4,
      "tick_size":"0.0001",
      "min_order_amount":1,
      "open_max_limits":[]
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
type string instrument type: SIMULATE|REAL
contract_type string contract type: PERPETUAL
base_currency string base currency
quote_currency string quote currency
clear_currency string settlement currency
contract_value string contract value for each size
contract_value_currency string currency for contract value
is_inverse boolean is inverse contract
is_trading boolean trading status
status string contract status: ONLINE|OFFLINE|DELIVERY
price_precision number price precision
tick_size string mini price step
min_order_amount number mini order amount
- - open_max_limits object position max open value limit(position leverage bigger than leverage,position value must not more than limit)
leverage string leverage
max_limit string position max value

Instrument

request URL: GET /swap/v2/public/instrument

request param

Parameters Required Type Description
instrument_id yes string instrument id

response example

 {
  "code":0,
  "data": {
    "instrument_id":"BTCUSDT2PERP",
    "type":"SIMULATE",
    "contract_type":"PERPETUAL",
    "base_currency":"BTC",
    "quote_currency":"USDT2",
    "clear_currency":"USDT2",
    "contract_value":"0.001",
    "contract_value_currency":"BTC",
    "is_inverse": false,
    "is_trading":true,
    "status":"ONLINE",
    "price_precision":4,
    "tick_size":"0.0001",
    "min_order_amount":1,
    "open_max_limits": [
      {
        "leverage":"20",
        "max_limit":"100000000"
      }
    ]
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
type string instrument type: SIMULATE|REAL
contract_type string contract type: PERPETUAL
base_currency string base currency
quote_currency string quote currency
clear_currency string settlement currency
contract_value string contract value for each size
contract_value_currency string currency for contract value
is_inverse boolean is inverse contract
is_trading boolean trading status
status string contract status: ONLINE|OFFLINE|DELIVERY
price_precision number price precision
tick_size string mini price step
min_order_amount number mini order amount
- - open_max_limits object position max open value limit(position leverage bigger than leverage,position value must not more than limit)
leverage string leverage
max_limit string position max value

OrderBook

request URL: GET /swap/v2/public/depth

request param

Parameters Required Type Description
instrument_id yes string instrument id
limit no number request level: 1-100, default 20

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "timestamp":1657531507660,
    "asks":[
      ["20609.30",3855],
      ["20616.18",8565],
      ["20616.98",4597],
      ["20617.08",4659],
      ["20617.18",4519],
      ["20617.28",5195],
      ["20617.38",11139],
      ["20617.48",6117],
      ["20617.78",11416],
      ["20617.88",11322]
    ],
    "bids":[
      ["20588.60",5000],
      ["20582.32",4637],
      ["20582.22",4075],
      ["20582.02",4275],
      ["20581.82",4606],
      ["20581.72",3968],
      ["20581.62",4166],
      ["20581.52",4246],
      ["20581.42",4565],
      ["20581.22",3918]
    ]
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
timestamp number milliseconds since UNIX epoch
- - asks object asks book
0 string price
1 number amount
- - bids object bids book
0 string price
1 number amount

RecentTrades

request URL: GET /swap/v2/public/trades

request param

Parameters Required Type Description
instrument_id yes string instrument id
limit no number request level: 1-100, default 20

response example

{
  "code":0,
  "data":[
    {
      "instrument_id":"BTCUSDTPERP",
      "trade_id":"1546430170401869825",
      "direction":"1",
      "volume":"10000",
      "price":"20541.79",
      "trade_time":1657532658564
    },
    {
      "instrument_id":"BTCUSDTPERP",
      "trade_id":"1546430159257604097",
      "direction":"3",
      "volume":"967",
      "price":"20542.54",
      "trade_time":1657532655907
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
trade_id string trade id
direction string order direction 1:Open Long 2:Open Short 3:Close Long 4:Close Short
volume string trade volume
price string trade price
trade_time number milliseconds since UNIX epoch

Ticker

request URL: GET /swap/v2/public/ticker

request param

Parameters Required Type Description
instrument_id yes string instrument id

response example

{
  "code":0,
  "data": {
    "instrument_id":"BTCUSDTPERP",
    "index_price":"20529.49",
    "mark_price":"20533.91",
    "max_buy_price":"25661.54",
    "min_sell_price":"15396.92",
    "best_bid":"20523.73",
    "best_bid_size":"4000",
    "best_ask":"20544.37",
    "best_ask_size":"3080",
    "high_24h":"21351.41",
    "open_24h":"21308.4",
    "low_24h":"20373.31",
    "last":"20528.33",
    "last_qty":"10000",
    "volume_24h":"135526503",
    "price_change_percent":"-0.036608567513281134",
    "open_interest":"12344.55",
    "timestamp":1657533359744
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
index_price string index price
mark_price string mark price
max_buy_price string max buy price
min_sell_price string min sell price
best_bid string best bid price
best_bid_size string best bid volume
best_ask string best ask price
best_ask_size string best ask volume
high_24h string highest trade price since 24 hours ago
open_24h string 24 hours ago trade price
low_24h string lowest trade price since 24 hours ago
last string last trade price
last_qty string last trade volume
volume_24h string total trade volume since 24 hours ago
price_change_percent string price change percent from 24 hours ago to now
open_interest string open interest
timestamp number milliseconds since UNIX epoch

Tickers

request URL: GET /swap/v2/public/tickers

request param

Parameters Required Type Description
type no number instrument type 1 simulate 2 real default real

response example

{
  "code":0,
  "data": [
    {
      "instrument_id":"BTCUSDTPERP",
      "index_price":"20529.49",
      "mark_price":"20533.91",
      "max_buy_price":"25661.54",
      "min_sell_price":"15396.92",
      "best_bid":"20523.73",
      "best_bid_size":"4000",
      "best_ask":"20544.37",
      "best_ask_size":"3080",
      "high_24h":"21351.41",
      "open_24h":"21308.4",
      "low_24h":"20373.31",
      "last":"20528.33",
      "last_qty":"10000",
      "volume_24h":"135526503",
      "price_change_percent":"-0.036608567513281134",
      "open_interest":"-",
      "timestamp":1657533359744
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
index_price string index price
mark_price string mark price
max_buy_price string max buy price
min_sell_price string min sell price
best_bid string best bid price
best_bid_size string best bid volume
best_ask string best ask price
best_ask_size string best ask volume
high_24h string highest trade price since 24 hours ago
open_24h string 24 hours ago trade price
low_24h string lowest trade price since 24 hours ago
last string last trade price
last_qty string last trade volume
volume_24h string total trade volume since 24 hours ago
price_change_percent string price change percent from 24 hours ago to now
open_interest string ignore
timestamp number milliseconds since UNIX epoch

RecentCandle

request URL: GET /swap/v2/public/candles

request param

Parameters Required Type Description
instrument_id yes string instrument id
granularity yes string candle granularity: 1m 5m 15m 30m 1h 4h 12h 1d 1w
limit yes number return raws: 1-100, default 20

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "granularity":"15m",
    "candles":[
      [1657536300000,"20596.79","20597.39","20564.8","20590.31","559516","559.516"],
      [1657535400000,"20590.36","20598.41","20558.41","20593.17","1638892","1638.892"]
    ]
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
granularity string candle granularity: 1m 5m 15m 30m 1h 4h 12h 1d 1w
- - candles object candle list
0 number milliseconds since UNIX epoch (candle start)
1 string open price
2 string highest price
3 string lowest price
4 string close price
5 string trade volume
6 string token trade num

CurrentFundingRate

request URL: GET /swap/v2/public/funding_rate

request param

Parameters Required Type Description
instrument_id yes string instrument id

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "funding_rate":"-0.001",
    "funding_time":1657612800000,
    "next_funding_rate":"-0.001",
    "next_funding_time":1657641600000
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
funding_rate string current funding rate
funding_time number settlement time,milliseconds since UNIX epoch
next_funding_rate string forecasted funding rate for the next period
next_funding_time number funding time for the next period, milliseconds since UNIX epoch

CandleHistory

request URL: GET /swap/v2/public/candles_history

request param

Parameters Required Type Description
instrument_id yes string instrument id
granularity yes string candle granularity: 1m 5m 15m 30m 1h 4h 12h 1d 1w
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "granularity":"15m",
    "candles":[
      [1653994800000,"31660.34","31749.37","31587.91","31734.43","105048","105.048"],
      [1653995700000,"31736.57","31739.48","31603.44","31603.96","140370","140.37"]
    ]
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
granularity string candle granularity: 1m 5m 15m 30m 1h 4h 12h 1d 1w
- - candles object candle list
0 number milliseconds since UNIX epoch (candle start)
1 string open price
2 string highest price
3 string lowest price
4 string close price
5 string trade volume
6 string token trade num

FundingRateHistory

request URL: GET /swap/v2/public/funding_rate_history

request param

Parameters Required Type Description
instrument_id yes string instrument id
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "funding_rates":[
      {"rate":"0.0001","time":1598572800000},
      {"rate":"0.0001","time":1598601600000}
    ]
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
- - funding_rates object funding rate list
rate string funding rate
time number settlement time

Private Endpoint

Account The API endpoint of Account require authentication.

AccountBalance

request URL: GET /swap/v2/account/balance

request param

Parameters Required Type Description
type no number instrument type: 1 Simulate 2 Real
currency no string currency, currency has higher priority than type

response example

{
  "code":0,
  "data":[
    {
      "equity":"1298.9254006988704274",
      "currency":"BTC",
      "margin":"0",
      "cross_margin": "0",
      "isolate_margin": "0",
      "isolate_balance": "0",
      "frozen_margin":"0",
      "frozen_money":"0",
      "margin_ratio":"10000",
      "realized_pnl":"0.0514979253627392",
      "avail_balance":"1298.9254006988704274",
      "unrealized_pnl":"0",
      "isolate_unrealized_pnl":"0",
      "time_stamp":1639624873000
    },
    {
      "equity":"0.0099961852826424",
      "currency":"ETH",
      "margin":"0",
      "cross_margin": "0",
      "isolate_margin": "0",
      "isolate_balance": "0",
      "frozen_margin":"0",
      "frozen_money":"0",
      "margin_ratio":"10000",
      "realized_pnl":"0",
      "avail_balance":"0.0099961852826424",
      "unrealized_pnl":"0",
      "isolate_unrealized_pnl":"0",
      "time_stamp":1657505449431
    },
    {
      "equity":"9999837682.4619548530064563",
      "currency":"USDT",
      "margin":"56.9628552112676055",
      "cross_margin": "56.9628552112676055",
      "isolate_margin": "0",
      "isolate_balance": "0",
      "frozen_margin":"0",
      "frozen_money":"0",
      "margin_ratio":"2544691.382953222",
      "realized_pnl":"-11036.554614674757",
      "avail_balance":"9999837740.1759844750715308",
      "unrealized_pnl":"-114.67688483333268",
      "isolate_unrealized_pnl":"0",
      "time_stamp":1657595029446
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
equity string account equity(include unrealized profit and loss)
currency string currency
margin string margin occupied by position
cross_margin string cross margin occupied by position
isolate_margin string isolate margin occupied by position
isolate_balance string isolate_balance
frozen_margin string margin occupied by open orders
frozen_money string fee occupied by open orders
margin_ratio string margin ratio
realized_pnl string realized profit and loss
avail_balance string available balance
unrealized_pnl string unrealized profit and loss (cross+isolate)
isolate_unrealized_pnl string isolate unrealized profit and loss
time_stamp number milliseconds since UNIX epoch

Positions

request URL: GET /swap/v2/account/positions

request param

Parameters Required Type Description
type no number instrument type: 1 Simulate 2 Real
instrument_id no string instrument id, instrument id has higher priority than type

response example

{
  "code":0,
  "data":[
    {
      "instrument_id": "BTCUSDTPERP",
      "margin_mode":  "crossed",
      "posi_balance": "0",
      "avail_position":"197",
      "avg_cost":"20529.76",
      "last":"19941.77",
      "mark_price":"19941.78",
      "leverage":"71",
      "liquidation_price":"-51275900222.49557",
      "maint_margin_ratio":"0.01",
      "margin":"56.9628552112676055",
      "position":"197",
      "realized_pnl":"-15193763.760575533",
      "unrealized_pnl":"-114.03244858333346",
      "unrealized_pnl_rate":"-2.0018738204116064",
      "side":"long",
      "open_outstanding":"0",
      "risk_score":"0.2",
      "margin_ratio":"2544274.143023101",
      "timestamp":1657595569430
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
margin_mode string margin mode: "crossed" or "isolated"
posi_balance string valid only isolated margin mode
avail_position string position that can be closed
avg_cost string average open price
last string instrument latest trade price
mark_price string instrument mark price
leverage string leverage
liquidation_price string estimated liquidation price
maint_margin_ratio string maintenance margin ratio
margin string maintenance margin requirement
position string total position
realized_pnl string realized profit and loss
unrealized_pnl string unrealized profit and loss
unrealized_pnl_rate string unrealized profit and loss rate
side string position side: long | short
open_outstanding string close order not finish size
risk_score string risk score to be ADL (0-1)
margin_ratio string margin ratio
timestamp number milliseconds since UNIX epoch

PositionMode

request URL: POST /swap/v2/account/position_mode

can not do this operation when has position against to the mode want to adjust

request param

Parameters Required Type Description
instrument_id yes string instrument id
margin_mode yes string position mode: "crossed" or "isolated"

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "margin_mode":"isolated"
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
margin_mode string margin mode: "crossed" or "isolated"

PositionMargin

request URL: POST /swap/v2/account/position_margin

can not do this operation as crossed position mode

request param

Parameters Required Type Description
instrument_id yes string instrument id
side yes string position side: "long" or "short"
type yes number type 1 add, 2 reduce
amount yes string operate amount

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "side":"isolated",
    "type":1,
    "amount":"10.15"
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
side string position mode: "crossed" or "isolated"
type number type 1 add, 2 reduce
amount string operate amount

SetLeverage

request URL: POST /swap/v2/account/leverage

request param

Parameters Required Type Description
instrument_id yes string instrument id
leverage yes number leverage
margin_mode no string position mode: "crossed" or "isolated"
side no string position side: "long" or "short", valid only in isolated mode

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "leverage":30,
    "margin_mode": "isolated",
    "side": "long"
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
leverage number set leverage
margin_mode string position mode: "crossed" or "isolated"
side string position side: "long" or "short", valid only in isolated mode

TradingFee

request URL: GET /swap/v2/account/trading_fee_rate

request param

Parameters Required Type Description
instrument_id yes string instrument id

response example

{
  "code":0,
  "data":{
    "instrument_id":"BTCUSDTPERP",
    "taker_fee_rate":"0.00005",
    "maker_fee_rate":"0.00003"
  }
}

response param

Parameters Type Description
code number error code
- data object response data
instrument_id string instrument id
taker_fee_rate string taker fee rate
maker_fee_rate string maker fee rate

Bills

request URL: GET /swap/v2/account/finance_record

request param

Parameters Required Type Description
currency no string currency
finance_type no number finance type 1:transfer in 2:transfer out 3:open long 4:open short 5:close long 6:close short 9:ADL-close short 10:ADL-close long 12:force close long 13:force close short 15:funding rate 16:experience token
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":[
    {
      "currency":"USDT",
      "finance_type":3,
      "change":"-0.6187",
      "timestamp":1604919311873
    },
    {
      "currency":"USDT",
      "finance_type":15,
      "change":"-0.0337671088333333",
      "timestamp":1604972654439
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
currency string currency
finance_type number finance type 1:transfer in 2:transfer out 3:open long 4:open short 5:close long 6:close short 9:ADL-close short 10:ADL-close long 12:force close long 13:force close short 15:funding rate 16:experience token
change string change amount
timestamp number milliseconds since UNIX epoch

TransferRecord

request URL: GET /swap/v2/account/transfer_record

request param

Parameters Required Type Description
currency no string transfer currency
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":[
    {
      "transfer_id":5648,
      "type":2,
      "currency":"USDT",
      "amount":"3000",
      "timestamp":1606902218000
    },
    {
      "transfer_id":5898,
      "type":1,
      "currency":"USDT",
      "amount":"5",
      "timestamp":1608003262000
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
transfer_id number transfer id
type number transfer type: 1 transfer in 2 transfer out
currency string transfer currency
amount string transfer amount
timestamp number milliseconds since UNIX epoch

Trade The API endpoint of Trade require authentication. OrderPlace and CandleOrder should be subject to websocket order push

OrderPlace

request URL: POST /swap/v2/trade/order_place

request param

Parameters Required Type Description
instrument_id yes string instrument id
type yes number type: 1 open long 2 open short 3 close long 4 close short
order_type yes number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
size yes number order size
price options string order price, necessary if not market order
post_only no boolean is post-only order, default false

response example

{
  "code":0,
  "data":"1546741166173589504"
}

response param

Parameters Type Description
code number error code
data string order id

CancelOrder

request URL: POST /swap/v2/trade/cancel_order

request param

Parameters Required Type Description
instrument_id yes string instrument id
order_id yes string order ID

response example

 {
  "code":0,
  "data":"1546741166173589504"
}

response param

Parameters Type Description
code number error code
data string order id

BatchOrder

request URL: POST /swap/v2/trade/batch_order

request example

[
  {"instrument_id":"BTCUSDTPERP", "type": 1, "order_type": 0, "size": 10, "price": "19876.51", "post_only": true},
  {"instrument_id":"BTCUSDTPERP", "type": 1, "order_type": 0, "size": 10, "price": "19876.51", "post_only": true}
]

request param - array max count: 20

Parameters Required Type Description
instrument_id yes string instrument id
type yes number type: 1 open long 2 open short 3 close long 4 close short
order_type yes number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
size yes number order size
price options string order price, necessary if not market order
post_only no boolean is post-only order, default false

response example

{
  "code":0,
  "data":[
    "1546771720487047168",
    "1546771720487047169",
    "1546771720487047170"
  ]
}

response param

Parameters Type Description
code number error code
- data array response data
0 string order id

BatchCancel

request URL: POST /swap/v2/trade/batch_cancel_order

request example

[
  {"instrument_id":"BTCUSDTPERP", "order_id":"12312312312312"},
  {"instrument_id":"BTCUSDTPERP", "order_id":"22222222222222"}
]

request param - array max count: 20

Parameters Required Type Description
instrument_id yes string instrument id
order_id yes string order ID

response example

{
  "code":0,
  "data":[
    "1546771720487047168",
    "1546771720487047169",
    "1546771720487047170"
  ]
}

response param

Parameters Type Description
code number error code
- data array response data
0 string order id

OpenOrder

request URL: GET /swap/v2/trade/open_orders

request param

Parameters Required Type Description
instrument_id no string instrument id
type yes number type: 1 open long 2 open short 3 close long 4 close short
order_type yes number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
order_status no string order status: 0: open 1: part filled
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":[
    {
      "order_id":"1546775521365331968",
      "instrument_id":"ETHPERP",
      "margin_mode": "crossed",
      "contract_val":"1",
      "type":1,
      "order_type":0,
      "price":"1000",
      "size":"68",
      "filled_qty":"0",
      "price_avg":"0",
      "fee":"0",
      "state":0,
      "leverage":"20",
      "turnover":"0",
      "has_stop":0,
      "insert_time":1657614996653,
      "time_stamp":1657614996653
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
order_id string order id
instrument_id string instrument id
margin_mode string margin mode: crossed or isolated
contract_val string contract value of single size
type number type: 1 open long 2 open short 3 close long 4 close short
order_type number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
price string order price
size string order size
filled_qty string filled quantity
price_avg string average trade price
fee string trade fee
state number order status: 0: open 1: part filled
leverage string leverage
turnover string filled trade value
has_stop number has stop: 0 no 1 yes
insert_time number order create time, milliseconds since UNIX epoch
time_stamp number order last update time, milliseconds since UNIX epoch

OrderInfo

request URL: GET /swap/v2/trade/order_info

request param

Parameters Required Type Description
instrument_id no string instrumnent id
order_id yes string order id

response example

{
  "code":0,
  "data": {
    "order_id":"1546775521365331968",
    "instrument_id":"ETHPERP",
    "margin_mode": "crossed",
    "contract_val":"1",
    "type":1,
    "order_type":0,
    "price":"1000",
    "size":"68",
    "filled_qty":"0",
    "price_avg":"0",
    "fee":"0",
    "state":0,
    "leverage":"20",
    "turnover":"0",
    "has_stop":0,
    "insert_time":1657614996653,
    "time_stamp":1657614996653
  }
}

response param

Parameters Type Description
code number error code
- data object response data
order_id string order id
instrument_id string instrument id
margin_mode string margin mode: crossed or isolated
contract_val string contract value of single size
type number type: 1 open long 2 open short 3 close long 4 close short
order_type number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
price string order price
size string order size
filled_qty string filled quantity
price_avg string average trade price
fee string trade fee
state number order status: -1: canceled 0: open 1: part filled 2: filled
leverage string leverage
turnover string filled trade value
has_stop number has stop: 0 no 1 yes
insert_time number order create time, milliseconds since UNIX epoch
time_stamp number order last update time, milliseconds since UNIX epoch

HistoryOrder

request URL: GET /swap/v2/trade/history_orders

request param

Parameters Required Type Description
instrument_id no string instrument id
type no number type: 1 open long 2 open short 3 close long 4 close short
order_type no number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
order_status no string order status: -1: canceled 2: filled
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":[
    {
      "order_id":"1546775521365331968",
      "instrument_id":"ETHPERP",
      "margin_mode": "crossed",
      "contract_val":"1",
      "type":1,
      "order_type":0,
      "price":"1000",
      "size":"68",
      "filled_qty":"0",
      "price_avg":"0",
      "fee":"0",
      "state":-1,
      "leverage":"20",
      "turnover":"0",
      "has_stop":0,
      "insert_time":1657614996653,
      "time_stamp":1657615476234
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
order_id string order id
instrument_id string instrument id
margin_mode string margin mode: crossed or isolated
contract_val string contract value of single size
type number type: 1 open long 2 open short 3 close long 4 close short
order_type number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
price string order price
size string order size
filled_qty string filled quantity
price_avg string average trade price
fee string trade fee
state number order status: -1: canceled 2: filled
leverage string leverage
turnover string filled trade value
has_stop number has stop: 0 no 1 yes
insert_time number order create time, milliseconds since UNIX epoch
time_stamp number order last update time, milliseconds since UNIX epoch

HistoryTrade

request URL: GET /swap/v2/trade/history_trades

request param

Parameters Required Type Description
instrument_id no string instrument id
type no number type: 1 open long 2 open short 3 close long 4 close short
order_type no number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
order_id no string order id
start_timestamp no number query start milliseconds since UNIX epoch
end_timestamp no number query end milliseconds since UNIX epoch
limit no number query raws: 1-100, default 20

response example

{
  "code":0,
  "data":[
    {
      "trade_id":"1356141620419895298",
      "instrument_id":"BTCUSDTPERP",
      "margin_mode": "crossed",
      "order_id":"1356135807563337728",
      "type":1,
      "order_type":0,
      "price":"33603",
      "size":"10",
      "fee":"0.0168015",
      "close_profit":"0",
      "leverage":"100",
      "trade_type":0,
      "match_role":2,
      "trade_time":1612164332869
    }
  ]
}

response param

Parameters Type Description
code number error code
- data object response data
trade_id string trade id
instrument_id string instrument id
margin_mode string margin mode: crossed or isolated
order_id string order id
type number type: 1 open long 2 open short 3 close long 4 close short
order_type number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
price string trade price
size string trade size
fee string trade fee
close_profit string realized profit and loss
leverage string leverage
trade_type number trade type: 0 normal 1 force close 3 ADL
match_role number match role: 0=not distinction 1=taker 2=maker
trade_time number trade time, milliseconds since UNIX epoch

Copy Trading The API endpoint of Copy Trading require authentication.

ExpertSponsorOrder

request URL:

request param

Parameters Required Type Description
instrument_id yes string instrument id
margin_mode yes number position mode: 1 crossed 2 isolated
type yes number type: 1 open long 2 open short 3 close long 4 close
leverage yes number leverage
order_type yes number order type: 0: limit_price 1: IOC_opponent 2: IOC_Optimal_5 3: IOC_Optimal_10 13: IOC_Optimal_20 4: IOC_custom_price 6: GTC_opponent 7: GTC_Optimal_5 8: GTC_Optimal_10 14: GTC_Optimal_20 10: FOK_opponent 11: FOK_Optimal_5 12: FOK_Optimal_10 15: FOK_Optimal_20 9: FOK_custom_price
limit_price yes string order price, necessary if not market
order_num yes number order size
order_earn_trigger_price_type no number stop earn trigger price type: 1 index price 2 marker price 3 market price
order_loss_trigger_price_type no number stop loss trigger price type: 1 index price 2 marker price 3 market price
stop_earn_trigger_price no string stop earn trigger price
stop_loss_trigger_price no string stop loss trigger price type

response example

{
  "code":0,
  "data":{
    "res":1
  }
}

response param

Parameters Type Description
code number error code
- data object response data
res number result: 1 success 2 fail

CloseOrder

request URL:

request param

Parameters Required Type Description
open_order_id string order id

response example

{
  "code":0,
  "data":{
    "res":1
  }
}

response param

Parameters Type Description
code number error code
- data object response data
res number result: 1 success 2 fail

CancelCurrentOrder

request URL:

request param

Parameters Required Type Description
order_id string order id

response example

{
  "code":0,
  "data":{
    "res":1
  }
}

response param

Parameters Type Description
code number error code
- data object response data
res number result: 1 success 2 fail

UserCenterCurrent

request URL:

request param

Parameters Required Type Description
page no number page, default 1
size no number size,default 10
instrument_id no string instrument id
type yes number 1 Detailed 2 Summary

response example

{
  "code": 0,
  "data": {
    "res": 1,
    "list": [
      {
        "instrument_name": "BCHUSDT",
        "leverage": 20,
        "direction": 1,
        "open_price": 135.47617777777776,
        "open_time": 0,
        "open_fee": 0,
        "expert_name": "",
        "unrealized_profit": 1.6887999999999996,
        "unrealized_profit_rate": 0.013850733577104,
        "order_id": "",
        "volume_total_original": 180,
        "liquidate_price": 129.35561474334278,
        "market_price": 135.57,
        "is_closing": false,
        "stop_earn_trigger_price_type": 0,
        "stop_earn_trigger_price": "",
        "stop_loss_trigger_price_type": 0,
        "stop_loss_trigger_price": "",
        "margin_mode": 2,
        "margin_ratio": 0.05065745453353328,
        "posi_margin": 121.92856,
        "use_margin": 121.92856
      },
      {
        "instrument_name": "ETHUSDT",
        "leverage": 20,
        "direction": 1,
        "open_price": 1574.2400330812854,
        "open_time": 0,
        "open_fee": 0,
        "expert_name": "",
        "unrealized_profit": -1255.0017,
        "unrealized_profit_rate": -0.25116923297382,
        "order_id": "",
        "volume_total_original": 6348,
        "liquidate_price": 1510.7106736978849,
        "market_price": 1554.47,
        "is_closing": false,
        "stop_earn_trigger_price_type": 0,
        "stop_earn_trigger_price": "",
        "stop_loss_trigger_price_type": 0,
        "stop_loss_trigger_price": "",
        "margin_mode": 2,
        "margin_ratio": 0.03791772666746796,
        "posi_margin": 4996.637865,
        "use_margin": 4996.637865
      }
    ],
    "page": {
      "page_size": 10,
      "cur_page": 1,
      "total_page": 1,
      "count": 2
    }
  }
}

response param

Parameters Type Description
code number error code
- data object response data
- list object response list
- page object response page
res number 1 success 2 fail
page_size number page size
current_page number current page
total_page number total page
count number count
instrument_name string instrument name
leverage number leverage
direction number order direction 1:Open Long 2:Open Short
open_price number open price
open_time number open time
open_fee number open fee
expert_name number expert name
unrealized_profit number unrealized profit
unrealized_profit_rate number unrealized profit rate,did not multiply by 100%
order_id number order id
volume_total_original number opening quantity
liquidate_price number liquidate price
market_price number market price
is_closing number is closing:true,false
stop_earn_trigger_price_type number 1:index price 2:mark price 3:market price
stop_earn_trigger_price number stop earn trigger price
stop_loss_trigger_price_type number 1:index price 2:mark price 3:market price
stop_loss_trigger_price number stop loss trigger price
margin_mode number margin mode 1:crossed 2:isolated
margin_ratio number margin ratio
posi_margin number position margin
use_margin number use margin

UserCenterHistory

request URL:

request param

Parameters Required Type Description
page no number page, default 1
size no number size,default 10
instrument_id no string instrument id

response example

{
  "code": 0,
  "data": {
    "res": 1,
    "list": [
      {
        "instrument_name": "BTCUSDT",
        "leverage": 20,
        "direction": 1,
        "open_price": 16045.619,
        "open_time": 1669020058,
        "open_fee": 0.00080228095,
        "expert_name": "",
        "close_time": 1669202205,
        "close_price": 16590.117,
        "close_pnl": 0.5444980000000008,
        "status": 2,
        "close_fee": 0.00082950585,
        "profit": 0.5428662132000008,
        "order_id": "1594611819190685696",
        "close_volume_traded": 1,
        "margin_mode": 1
      },
      {
        "instrument_name": "BTCUSDT",
        "leverage": 80,
        "direction": 1,
        "open_price": 16771.19,
        "open_time": 1668592117,
        "open_fee": 0.001677119,
        "expert_name": "",
        "close_time": 1668592222,
        "close_price": 16735.22,
        "close_pnl": -0.0719399999999979,
        "status": 2,
        "close_fee": 0.001673522,
        "profit": -0.0752906409999979,
        "order_id": "1592816905331150848",
        "close_volume_traded": 2,
        "margin_mode": 1
      },
      {
        "instrument_name": "BTCUSDT",
        "leverage": 10,
        "direction": 1,
        "open_price": 16862.63,
        "open_time": 1668584328,
        "open_fee": 0.0042156575,
        "expert_name": "",
        "close_time": 1668589599,
        "close_price": 16753.61,
        "close_pnl": -0.5450999999999908,
        "status": 2,
        "close_fee": 0.0041884025,
        "profit": -0.5535040599999907,
        "order_id": "1592784234840330240",
        "close_volume_traded": 5,
        "margin_mode": 1
      }
    ],
    "page": {
      "page_size": 10,
      "cur_page": 1,
      "total_page": 1,
      "count": 3
    }
  }
}

response param

Parameters Type Description
code number error code
- data object response data
- list object response list
- page object response page
res number 1 success 2 fail
page_size number page size
current_page number current page
total_page number total page
count number count
instrument_name string instrument name
leverage number leverage
direction number order direction 1:open long 2:open short
open_price number open price
open_time number open time
open_fee number open fee
expert_name number expert name
close_time number close time
close_price number close price
close_pnl number closing profit and loss
status number 1:auto close 2:manual close 3:forced close 4:stop out close 5:stop loss close
close_fee number close_fee
profit number profit
order_id number order id
close_volume_traded number close volume traded(closed order has been executed quantity)
margin_mode number margin mode 1:crossed 2:isolated

ExpertCurrentOpenOrder

request URL:

request param

Parameters Required Type Description
page no number page, default 1
size no number size, default 10
instrument_id no string instrument id

response example

{
  "code": 0,
  "data": {
    "list": [
      {
        "instrument_name": "BCHUSDT",
        "leverage": 20,
        "direction": 1,
        "order_price": 0,
        "commission_amount": 27975.93552,
        "profit_rate": 180,
        "total_order": 2028,
        "status": 1,
        "order_price_type": 8,
        "order_time": 1673849380,
        "order_id": "1614867464376553472",
        "stop_earn_trigger_price_type": 0,
        "stop_earn_trigger_price": "",
        "stop_loss_trigger_price_type": 0,
        "stop_loss_trigger_price": "",
        "margin_mode": 2
      }
    ],
    "page": {
      "page_size": 10,
      "cur_page": 1,
      "total_page": 1,
      "count": 1
    }
  }
}

response param

Parameters Type Description
code number error code
- data object response data
- list object response list
- page object response page
page_size number page size
current_page number current page
total_page number total page
count number count
instrument_name string instrument name
leverage number leverage
direction number order direction 1:Open Long 2:Open Short
order_price number order price
commission_amount number commission amount
profit_rate number profit rate
total_order number total order
status number order status: -1: canceled 0: open 1: part filled 2: filled
order_price_type number order_price_type 0:limit 1:opponent_ioc 2:optimal_5_ioc 3:optimal_10_ioc 4:ioc 5:gtc 6:opponent_gtc 7:optimal_5_gtc 8:optimal_10_gtc 9:fok 10:opponent_fok 11:optimal_5_fok 12:optimal_10_fok',
order_time number order_time
order_id string order_id
stop_earn_trigger_price_type number 1:index price 2:mark price 3:market price
stop_earn_trigger_price string stop_earn_trigger_price
stop_loss_trigger_price_type number 1:index price 2:mark price 3:market price
stop_loss_trigger_price string stop_loss_trigger_price
margin_mode number margin mode 1:crossed 2:isolate

AddStopProfitOrderOrStopLossOrder

Request URL: - POST /swap/v2/follow/add_algo

Request param:

Parameters Required Type Description
order_id optional string order_id
profit_trigger_type optional number price type:1 index price 2 marker price 3 market price
profit_trigger_price optional string stop profit price
stop_trigger_type optional number type:1 index price 2 marker price 3 market price
stop_trigger_price optional string stop loss price

Response example

{
  "code":0,
  "data":{
      "result":1,
      "algos":["160497265443932323","1614526180466102272"]
    }
}

Response Description

Parameters Type Description
code number error code
- data object response data
result number 1 success 2 fail
algos []string stop loss and stop profit order_id

CancelStopLossOrStopProfitOrder

Request URL: - POST /swap/v2/follow/cancel_algo

Parameters:

Parameters Required Type Description
order_id optional string order_id
stop_profit optional number 1 cancel stop profit order 0 not cancel
stop_loss optional number 1 cancel stop loss order 0 not cancel

Response example

{
  "code":0,
  "data":{
      "result":1
    }
}

Response Description

Parameters Type Description
code number Error
- data object Response Param
result number 1 success 2 fail

AccountAvailableBalance

Request URL: - POST /swap/v2/follow/account_available

Request param:not required

Response param

{
  "code":0,
  "data":{
      "available":"878.98751223"
    }
}

Response Description

Parameters Type Description
code number error code
- data object response data
available string account available balance

PlanCommissionList

Request URL: - POST /swap/v2/follow/plan_task

Request param:

Parameters Required Type Description
page yes number page lte50
size yes number size

response example

{
    "code": 0,
    "data": {
        "list": [
            {
                "order_id": "1614526180466102272",
                "instrument_name": "BCHUSDT",
                "leverage": 20,
                "direction": 3,
                "order_time": 1673768236,
                "trigger_cond": 3,
                "trigger_price": 125,
                "com_type": 3,
                "order_price": 1,
                "com_num": 200,
                "status": 1,
                "margin_mode": 2
            },
            {
                "order_id": "1614526180466102272",
                "instrument_name": "BCHUSDT",
                "leverage": 20,
                "direction": 3,
                "order_time": 1673768046,
                "trigger_cond": 3,
                "trigger_price": 140,
                "com_type": 2,
                "order_price": 1,
                "com_num": 200,
                "status": 1,
                "margin_mode": 2
            }
        ],
        "page": {
            "page_size": 10,
            "cur_page": 1,
            "total_page": 1,
            "count": 2
        }
    }
}

response param

Parameters Type Description
code number error code
- data object response data
order_id string order_id
instrument_name string instrument_name
leverage number leverage
direction number direction 1:Open Multi-position 2:Open Short-position 3:Close Multi-position 4:Close Short-position
order_time number order update timestamp
trigger_cond number trigger condition 1 price-up 2 price-down
trigger_price number trigger price
com_type number strategy type 2 stop profit 3 stop loss
order_price number commissioning price 1 optimal10
com_num number commissioning num
status number status 1 to be validated 2 validated 3 canceled 4 fail 5 error
margin_mode number margin mode 1 cross 2 isolate