NAV
API Reference

Overview

Welcome to the Phemex API documentation. We offer REST and Websocket APIs to interact with our systems.

General API information

REST API Standards

HTTP return codes

REST request header

Every HTTP Rest Request must have the following Headers:

REST response format

Response general format

{
  "code": <code>,
  "msg": <msg>,
  "data": <data>
}
Field Description
code 0 means success, non-zero means error
msg when code is non-zero, it gives short error description
data operation dependant

Rate limits

IP ratelimits

Currently Phemex restrict every IP 5,000 request in 5 minutes window. If exceeded this IP capacity, the user would be blocked in the following 5 minutes.

REST API ratelimit rules

Header name Description
x-ratelimit-remaining-groupName Remaining request permits in this minute
x-ratelimit-capacity-groupName Request ratelimit capacity
x-ratelimit-retry-after-groupName Reset timeout in seconds for current ratelimited user
Group Name Capacity
Contract 500/minute
SpotOrder 500/minute
Others 100/minute

API groups

Path Method Weight Description
/orders POST 1 Place new order
/orders/replace PUT 1 Amend order
/orders/cancel DELETE 1 Cancel order
/orders/all DELETE 3 Cancel all order by symbol
/orders DELETE 1 cancel orders
/orders/activeList GET 1 Query open orders by symbol
/orders/active GET 1 Query open order by orderID
/accounts/accountPositions GET 1 Query account & position by currency
/accounts/positions GET 25 Query positions with un-realized-pnl
Path Method Weight Description
/spot/orders POST 1 Place spot order
/spot/orders PUT 1 Amend spot order
/spot/orders DELETE 2 Cancel spot order
/spot/orders/all DELETE 2 Cancel spot orders by symbol
/spot/orders/active GET 1 Query open spot order
/spot/orders GET 1 Query all open spot orders by symbol
Path Method Weight Description
/exchange/public/md/kline GET 10 kline query

Contact us

CCXT integration

Code samples

Error codes

CxlRejReason field

Code Reason Description
100 CE_NO_ENOUGH_QTY Qty is not enough
101 CE_WILLCROSS Passive order rejected due to price may cross
116 CE_NO_ENOUGH_BASE_QTY Base-qty is not enough in spot-trading
117 CE_NO_ENOUGH_QUOTE_QTY Quote-qty is not enough in spot-trading

BizError field

Code Message Description
19999 REQUEST_IS_DUPLICATED Duplicated request ID
10001 OM_DUPLICATE_ORDERID Duplicated order ID
10002 OM_ORDER_NOT_FOUND Cannot find order ID
10003 OM_ORDER_PENDING_CANCEL Cannot cancel while order is already in pending cancel status
10004 OM_ORDER_PENDING_REPLACE Cannot cancel while order is already in pending cancel status
10005 OM_ORDER_PENDING Cannot cancel while order is already in pending cancel status
11001 TE_NO_ENOUGH_AVAILABLE_BALANCE Insufficient available balance
11002 TE_INVALID_RISK_LIMIT Invalid risk limit value
11003 TE_NO_ENOUGH_BALANCE_FOR_NEW_RISK_LIMIT Insufficient available balance
11004 TE_INVALID_LEVERAGE Invalid input or new leverage is over maximum allowed leverage
11005 TE_NO_ENOUGH_BALANCE_FOR_NEW_LEVERAGE Insufficient available balance
11006 TE_CANNOT_CHANGE_POSITION_MARGIN_WITHOUT_POSITION Position size is zero. Cannot change margin
11007 TE_CANNOT_CHANGE_POSITION_MARGIN_FOR_CROSS_MARGIN Cannot change margin under CrossMargin
11008 TE_CANNOT_REMOVE_POSITION_MARGIN_MORE_THAN_ADDED Exceeds the maximum removable Margin
11009 TE_CANNOT_REMOVE_POSITION_MARGIN_DUE_TO_UNREALIZED_PNL Exceeds the maximum removable Margin
11010 TE_CANNOT_ADD_POSITION_MARGIN_DUE_TO_NO_ENOUGH_AVAILABLE_BALANCE Insufficient available balance
11011 TE_REDUCE_ONLY_ABORT Cannot accept reduce only order
11012 TE_REPLACE_TO_INVALID_QTY Order quantity Error
11013 TE_CONDITIONAL_NO_POSITION Position size is zero. Cannot determine conditional order's quantity
11014 TE_CONDITIONAL_CLOSE_POSITION_WRONG_SIDE Close position conditional order has the same side
11015 TE_CONDITIONAL_TRIGGERED_OR_CANCELED
11016 TE_ADL_NOT_TRADING_REQUESTED_ACCOUNT Request is routed to the wrong trading engine
11017 TE_ADL_CANNOT_FIND_POSITION Cannot find requested position on current account
11018 TE_NO_NEED_TO_SETTLE_FUNDING The current account does not need to pay a funding fee
11019 TE_FUNDING_ALREADY_SETTLED The current account already pays the funding fee
11020 TE_CANNOT_TRANSFER_OUT_DUE_TO_BONUS Withdraw to wallet needs to remove all remaining bonus. However if bonus is used by position or order cost, withdraw fails.
11021 TE_INVALID_BONOUS_AMOUNT Invalid bonus amount
11022 TE_REJECT_DUE_TO_BANNED Account is banned
11023 TE_REJECT_DUE_TO_IN_PROCESS_OF_LIQ Account is in the process of liquidation
11024 TE_REJECT_DUE_TO_IN_PROCESS_OF_ADL Account is in the process of auto-deleverage
11025 TE_ROUTE_ERROR = 11025 Request is routed to the wrong trading engine
11026 TE_UID_ACCOUNT_MISMATCH
11027 TE_SYMBOL_INVALID Invalid number ID or name
11028 TE_CURRENCY_INVALID Invalid currency ID or name
11029 TE_ACTION_INVALID Unrecognized request type
11030 TE_ACTION_BY_INVALID
11031 TE_SO_NUM_EXCEEDS Number of total conditional orders exceeds the max limit
11032 TE_AO_NUM_EXCEEDS Number of total active orders exceeds the max limit
11033 TE_ORDER_ID_DUPLICATE Details:Duplicated order ID
11034 TE_SIDE_INVALID Details:Invalid side
11035 TE_ORD_TYPE_INVALID Details:Invalid OrderType
11036 TE_TIME_IN_FORCE_INVALID Details:Invalid TimeInForce
11037 TE_EXEC_INST_INVALID Details:Invalid ExecType
11038 TE_TRIGGER_INVALID Details:Invalid trigger type
11039 TE_STOP_DIRECTION_INVALID Details:Invalid stop direction type
11040 TE_NO_MARK_PRICE Cannot get valid mark price to create conditional order
11041 TE_NO_INDEX_PRICE Cannot get valid index price to create conditional order
11042 TE_NO_LAST_PRICE Cannot get valid last market price to create conditional order
11043 TE_RISING_TRIGGER_DIRECTLY Conditional order would be triggered immediately
11044 TE_FALLING_TRIGGER_DIRECTLY Conditional order would be triggered immediately
11045 TE_TRIGGER_PRICE_TOO_LARGE Conditional order trigger price is too high
11046 TE_TRIGGER_PRICE_TOO_SMALL Conditional order trigger price is too low
11047 TE_BUY_TP_SHOULD_GT_BASE TakeProfit BUY conditional order trigger price needs to be greater than reference price
11048 TE_BUY_SL_SHOULD_LT_BASE StopLoss BUY condition order price needs to be less than the reference price
11049 TE_BUY_SL_SHOULD_GT_LIQ StopLoss BUY condition order price needs to be greater than liquidation price or it will not trigger
11050 TE_SELL_TP_SHOULD_LT_BASE TakeProfit SELL conditional order trigger price needs to be less than reference price
11051 TE_SELL_SL_SHOULD_LT_LIQ StopLoss SELL condition order price needs to be less than liquidation price or it will not trigger
11052 TE_SELL_SL_SHOULD_GT_BASE StopLoss SELL condition order price needs to be greater than the reference price
11053 TE_PRICE_TOO_LARGE Order price is too large
11054 TE_PRICE_WORSE_THAN_BANKRUPT Order price cannot be more aggressive than bankrupt price if this order has instruction to close a position
11055 TE_PRICE_TOO_SMALL Order price is too low
11056 TE_QTY_TOO_LARGE Order quantity is too large
11057 TE_QTY_NOT_MATCH_REDUCE_ONLY Does not allow ReduceOnly order without position
11058 TE_QTY_TOO_SMALL Order quantity is too small
11059 TE_TP_SL_QTY_NOT_MATCH_POS Position size is zero. Cannot accept any TakeProfit or StopLoss order
11060 TE_SIDE_NOT_CLOSE_POS TakeProfit or StopLoss order has wrong side. Cannot close position
11061 TE_ORD_ALREADY_PENDING_CANCEL Repeated cancel request
11062 TE_ORD_ALREADY_CANCELED Order is already canceled
11063 TE_ORD_STATUS_CANNOT_CANCEL Order is not able to be canceled under current status
11064 TE_ORD_ALREADY_PENDING_REPLACE Replace request is rejected because order is already in pending replace status
11065 TE_ORD_REPLACE_NOT_MODIFIED Replace request does not modify any parameters of the order
11066 TE_ORD_STATUS_CANNOT_REPLACE Order is not able to be replaced under current status
11067 TE_CANNOT_REPLACE_PRICE Market conditional order cannot change price
11068 TE_CANNOT_REPLACE_QTY Condtional order for closing position cannot change order quantity, since the order quantity is determined by position size already
11069 TE_ACCOUNT_NOT_IN_RANGE The account ID in the request is not valid or is not in the range of the current process
11070 TE_SYMBOL_NOT_IN_RANGE The symbol is invalid
11071 TE_ORD_STATUS_CANNOT_TRIGGER
11072 TE_TKFR_NOT_IN_RANGE The fee value is not valid
11073 TE_MKFR_NOT_IN_RANGE The fee value is not valid
11074 TE_CANNOT_ATTACH_TP_SL Order request cannot contain TP/SL parameters when the account already has positions
11075 TE_TP_TOO_LARGE TakeProfit price is too large
11076 TE_TP_TOO_SMALL TakeProfit price is too small
11077 TE_TP_TRIGGER_INVALID Invalid trigger type
11078 TE_SL_TOO_LARGE StopLoss price is too large
11079 TE_SL_TOO_SMALL StopLoss price is too small
11080 TE_SL_TRIGGER_INVALID Invalid trigger type
11081 TE_RISK_LIMIT_EXCEEDS Total potential position breaches current risk limit
11082 TE_CANNOT_COVER_ESTIMATE_ORDER_LOSS The remaining balance cannot cover the potential unrealized PnL for this new order
11083 TE_TAKE_PROFIT_ORDER_DUPLICATED TakeProfit order already exists
11084 TE_STOP_LOSS_ORDER_DUPLICATED StopLoss order already exists
11085 TE_CL_ORD_ID_DUPLICATE ClOrdId is duplicated
11086 TE_PEG_PRICE_TYPE_INVALID PegPriceType is invalid
11087 TE_BUY_TS_SHOULD_LT_BASE The trailing order's StopPrice should be less than the current last price
11088 TE_BUY_TS_SHOULD_GT_LIQ The traling order's StopPrice should be greater than the current liquidation price
11089 TE_SELL_TS_SHOULD_LT_LIQ The traling order's StopPrice should be greater than the current last price
11090 TE_SELL_TS_SHOULD_GT_BASE The traling order's StopPrice should be less than the current liquidation price
11091 TE_BUY_REVERT_VALUE_SHOULD_LT_ZERO The PegOffset should be less than zero
11092 TE_SELL_REVERT_VALUE_SHOULD_GT_ZERO The PegOffset should be greater than zero
11093 TE_BUY_TTP_SHOULD_ACTIVATE_ABOVE_BASE The activation price should be greater than the current last price
11094 TE_SELL_TTP_SHOULD_ACTIVATE_BELOW_BASE The activation price should be less than the current last price
11095 TE_TRAILING_ORDER_DUPLICATED A trailing order exists already
11096 TE_CLOSE_ORDER_CANNOT_ATTACH_TP_SL An order to close position cannot have trailing instruction
11097 TE_CANNOT_FIND_WALLET_OF_THIS_CURRENCY This crypto is not supported
11098 TE_WALLET_INVALID_ACTION Invalid action on wallet
11099 TE_WALLET_VID_UNMATCHED Wallet operation request has a wrong wallet vid
11100 TE_WALLET_INSUFFICIENT_BALANCE Wallet has insufficient balance
11101 TE_WALLET_INSUFFICIENT_LOCKED_BALANCE Locked balance in wallet is not enough for unlock/withdraw request
11102 TE_WALLET_INVALID_DEPOSIT_AMOUNT Deposit amount must be greater than zero
11103 TE_WALLET_INVALID_WITHDRAW_AMOUNT Withdraw amount must be less than zero
11104 TE_WALLET_REACHED_MAX_AMOUNT Deposit makes wallet exceed max amount allowed
11105 TE_PLACE_ORDER_INSUFFICIENT_BASE_BALANCE Insufficient funds in base wallet
11106 TE_PLACE_ORDER_INSUFFICIENT_QUOTE_BALANCE Insufficient funds in quote wallet
11107 TE_CANNOT_CONNECT_TO_REQUEST_SEQ TradingEngine failed to connect with CrossEngine
11108 TE_CANNOT_REPLACE_OR_CANCEL_MARKET_ORDER Cannot replace/amend market order
11109 TE_CANNOT_REPLACE_OR_CANCEL_IOC_ORDER Cannot replace/amend ImmediateOrCancel order
11110 TE_CANNOT_REPLACE_OR_CANCEL_FOK_ORDER Cannot replace/amend FillOrKill order
11111 TE_MISSING_ORDER_ID OrderId is missing
11112 TE_QTY_TYPE_INVALID QtyType is invalid
11113 TE_USER_ID_INVALID UserId is invalid
11114 TE_ORDER_VALUE_TOO_LARGE Order value is too large
11115 TE_ORDER_VALUE_TOO_SMALL Order value is too small
11116 TE_BO_NUM_EXCEEDS The total count of brakcet orders should equal or less than 5
11117 TE_BO_CANNOT_HAVE_BO_WITH_DIFF_SIDE All bracket orders should have the same Side.
11118 TE_BO_TP_PRICE_INVALID Bracker order take profit price is invalid
11119 TE_BO_SL_PRICE_INVALID Bracker order stop loss price is invalid
11120 TE_BO_SL_TRIGGER_PRICE_INVALID Bracker order stop loss trigger price is invalid
11121 TE_BO_CANNOT_REPLACE Cannot replace bracket order.
11122 TE_BO_BOTP_STATUS_INVALID Bracket take profit order status is invalid
11123 TE_BO_CANNOT_PLACE_BOTP_OR_BOSL_ORDER Cannot place bracket take profit order
11124 TE_BO_CANNOT_REPLACE_BOTP_OR_BOSL_ORDER Cannot place bracket stop loss order
11125 TE_BO_CANNOT_CANCEL_BOTP_OR_BOSL_ORDER Cannot cancel bracket sl/tp order
11126 TE_BO_DONOT_SUPPORT_API Doesn't support bracket order via API
11128 TE_BO_INVALID_EXECINST ExecInst value is invalid
11129 TE_BO_MUST_BE_SAME_SIDE_AS_POS Bracket order should have the same side as position's side
11130 TE_BO_WRONG_SL_TRIGGER_TYPE Bracket stop loss order trigger type is invalid
11131 TE_BO_WRONG_TP_TRIGGER_TYPE Bracket take profit order trigger type is invalid
11132 TE_BO_ABORT_BOSL_DUE_BOTP_CREATE_FAILED Cancel bracket stop loss order due failed to create take profit order.
11133 TE_BO_ABORT_BOSL_DUE_BOPO_CANCELED Cancel bracket stop loss order due main order canceled.
11134 TE_BO_ABORT_BOTP_DUE_BOPO_CANCELED Cancel bracket take profit order due main order canceled.

Contract REST API

Endpoint security type

Signature example 1: HTTP GET request

Singature example 2: HTTP GET request with multiple query string

Signature example 3: HTTP POST request

Request/Response field explaination

Leverage

Cross margin mode

Isolated margin mode

Price/Ratio/Value scales

Fields with post-fix "Ep", "Er" or "Ev" have been scaled based on symbol setting.

Query product information

Request

GET /public/products

Common order fields

Order Type Description
Limit --
Market --
Stop --
StopLimit --
MarketIfTouched --
LimitIfTouched --
Order Status Description
Untriggered Conditional order waiting to be triggered
Triggered Conditional order being triggered
Rejected Order rejected
New Order placed in cross engine
PartiallyFilled Order partially filled
Filled Order fully filled
Canceled Order canceled
TimeInForce Description
GoodTillCancel --
PostOnly --
ImmediateOrCancel --
FillOrKill --
Execution Instruction Description
ReduceOnly reduce position size, never increase position size
CloseOnTrigger close the position
Trigger Description
ByMarkPrice trigger by mark price
ByLastPrice trigger by last price

More order fields explained

Field Description
bizError 0 means processing normally, and non-zero values mean wrong state. code in response is equal to bizError if response contains only one order
cumQty cumulative filled order quantity
cumValueEv scaled cumulative filled order value
leavesQty leaves order quantity
leavesValueEv scaled leaves order value

Place order (HTTP PUT, prefered)

Request format

PUT /orders/create?clOrdID=<clOrdID>&symbol=<symbol>&reduceOnly=<reduceOnly>&closeOnTrigger=<closeOnTrigger>&orderQty=<orderQty>&displayQty=<displayQty>&ordType=<ordType>&priceEp=<priceEp>&side=<side>&text=<text>&timeInForce=<timeInForce>&stopPxEp=<stopPxEp>&takeProfitEp=<takeProfitEp>&stopLossEp=<stopLossEp>&pegOffsetValueEp=<pegOffsetValueEp>&pegPriceType=<pegPriceType>&trailingStopEp=<trailingStopEp>&triggerType=<triggerType>&tpTrigger=<tpTrigger>&tpSlTs=<tpSlTs>&slTrigger=<slTrigger>

Response sample

{
  "code": 0,
  "msg": "",
  "data": {
    "bizError": 0,
    "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf",
    "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f",
    "symbol": "BTCUSD",
    "side": "Sell",
    "actionTimeNs": 1580547265848034600,
    "transactTimeNs": 0,
    "orderType": null,
    "priceEp": 98970000,
    "price": 9897,
    "orderQty": 1,
    "displayQty": 1,
    "timeInForce": null,
    "reduceOnly": false,
    "stopPxEp": 0,
    "closedPnlEv": 0,
    "closedPnl": 0,
    "closedSize": 0,
    "cumQty": 0,
    "cumValueEv": 0,
    "cumValue": 0,
    "leavesQty": 1,
    "leavesValueEv": 10104,
    "leavesValue": 0.00010104,
    "stopPx": 0,
    "stopDirection": "UNSPECIFIED",
    "ordStatus": "Created"
  }
}
Field Type Required Description Possible values
symbol String Yes Which symbol to place order
clOrdID String Yes client order id, max length is 40
side Enum Yes Order direction, Buy or Sell Buy, Sell
orderQty Integer Yes Order quantity
priceEp Integer - Scaled price, required for limit order
ordType Enum - default to Limit Market, Limit, Stop, StopLimit, MarketIfTouched, LimitIfTouched
stopPxEp Integer - Trigger price for stop orders
timeInForce Enum - Time in force. default to GoodTillCancel GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly
reduceOnly Boolean - whether reduce position side only. Enable this flag, i.e. reduceOnly=true, position side won't change true, false
closeOnTrigger Boolean - implicitly reduceOnly, plus cancel other orders in the same direction(side) when necessary true, false
triggerType Enum - Trigger source, whether trigger by mark price, index price or last price ByMarkPrice, ByLastPrice
takeProfitEp Integer - Scaled take profit price
stopLossEp Integer - Scaled stop loss price
slTrigger Enum - Trigger source, by mark-price or last-price ByMarkPrice, ByLastPrice
tpTrigger Enum - Trigger source, by mark-price or last-price ByMarkPrice, ByLastPrice
pegOffsetValueEp Integer - Trailing offset from current price. Negative value when position is long, positive when position is short
pegPriceType Enum - Trailing order price type TrailingStopPeg, TrailingTakeProfitPeg

Place order (HTTP POST)

Request example

POST /orders
{
  "actionBy": "FromOrderPlacement",
  "symbol": "BTCUSD",
  "clOrdID": "uuid-1573058952273",
  "side": "Sell",
  "priceEp": 93185000,
  "orderQty": 7,
  "ordType": "Limit",
  "reduceOnly": false,
  "triggerType": "UNSPECIFIED",
  "pegPriceType": "UNSPECIFIED",
  "timeInForce": "GoodTillCancel",
  "takeProfitEp": 0,
  "stopLossEp": 0,
  "pegOffsetValueEp": 0,
  "pegPriceType": "UNSPECIFIED"
}

More order type examples

Order Type Side Parameter requirements Trigger condition
Stop/StopLimit Sell stopPxEp < last-price/mark-price last/mark-price <= stopPxEp
Stop/StopLimit Buy stopPxEp > last-price/mark-price last/mark-price >= stopPxEp
MarketIfTouched/LimitIfTouched Sell stopPxEp > last-price/mark-price last/mark-price >= stopPxEp
MarketIfTouched/LimitIfTouched Buy stopPxEp < last-price/mark-price last/mark-price <= stopPxEp

Buy stop limit order: triggered order is placed as limit order (assume current last-price is 30k)

{
  "clOrdID": "stop-loss-order-then-limit",
  "symbol": "BTCUSD",
  "side": "Sell",
  "ordType": "StopLimit",
  "triggerType": "ByMarkPrice",
  "stopPxEp": 299550000,
  "priceEp": 299650000,
  "orderQty": 10000
}

Buy stop market order: triggered order is placed as market order (assume current last-price is 30k)

{
  "clOrdID": "stop-loss-order-then-market",
  "symbol": "BTCUSD",
  "side": "Buy",
  "ordType": "Stop",
  "triggerType": "ByMarkPrice",
  "stopPxEp": 333550000,
  "priceEp": 0,
  "orderQty": 10000
}
Field Type Description Possible values
triggerType String The trigger price type ByMarkPrice, ByLastPrice
stopPxEp Integer The order trigger price. It should be less than the last price if ordType= Stop/StopLimit/LimitIfTouched/MarketIfTouched and side = Sell, and greater than the last price if side = Buy.
priceEp Integer The order price after triggered. Required if ordType = StopLimit/LimitIfTouched.

Take-profit sell limit order: triggered order is placed as limit order (Assume current last-price is 30k)

{
  "clOrdID": "take-profit-order-then-limit",
  "symbol": "BTCUSD",
  "side": "Sell",
  "ordType": "LimitIfTouched",
  "triggerType": "ByMarkPrice",
  "stopPxEp": 333550000,
  "priceEp": 334550000,
  "orderQty": 10000
}

Take-profit buy market order: triggered order is placed as market order (assume current last-price is 30k)

{
  "clOrdID": "take-profit-order-then-market",
  "symbol": "BTCUSD",
  "side": "Buy",
  "ordType": "MarketIfTouched",
  "triggerType": "ByLastPrice",
  "stopPxEp": 299550000,
  "priceEp": 0,
  "orderQty": 10000
}

Place order with stop-loss and take-profit

{
  "clOrdID": "order-with-take-profit-stop-loss",
  "symbol": "BTCUSD",
  "side": "Buy",
  "priceEp": 300000000,
  "orderQty": 1000,
  "ordType": "Limit",
  "takeProfitEp": 3111100000,
  "tpTrigger": "ByLastPrice",
  "stopLossEp": 299990000,
  "slTrigger": "ByMarkPrice"
}

Trailing stop order: (assume current position is long, current last-price is 32k)

{
  "symbol": "BTCUSD",
  "side": "Sell",
  "ordType": "Stop",
  "orderQty": 0,
  "priceEp": 0,
  "triggerType": "ByLastPrice",
  "stopPxEp": 315000000,
  "timeInForce": "ImmediateOrCancel",
  "closeOnTrigger": true,
  "pegPriceType": "TrailingStopPeg",
  "pegOffsetValueEp": -10000000,
  "clOrdID": "cl-order-id"
}

Trailing stop order with activiation price

{
  "symbol": "BTCUSD",
  "side": "Sell",
  "ordType": "Stop",
  "orderQty": 0,
  "priceEp": 0,
  "triggerType": "ByLastPrice",
  "stopPxEp": 340000000,
  "timeInForce": "ImmediateOrCancel",
  "closeOnTrigger": true,
  "pegPriceType": "TrailingTakeProfitPeg",
  "pegOffsetValueEp": -10000000,
  "clOrdID": "cl-order-id"
}
Field Type Description Possible values
triggerType String The trigger price type ByMarkPrice, ByLastPrice
stopPxEp Integer The order trigger price. It should be less than last-price if hold long position and vice versa.
pegOffsetValueEp Integer The offset price. It means to set offset price by an offset from the optimal price, and the sign is opposite to position side. e.g. Long Position => negative sign. Short Position => positive sign;

Amend order by order ID

Request format

PUT
/orders/replace?symbol=<symbol>&orderID=<orderID>&origClOrdID=<origClOrdID>&clOrdID=<clOrdID>&price=<price>&priceEp=<priceEp>&orderQty=<orderQty>&stopPx=<stopPx>&stopPxEp=<stopPxEp>&takeProfit=<takeProfit>&takeProfitEp=<takeProfitEp>&stopLoss=<stopLoss>&stopLossEp=<stopLossEp>&pegOffsetValueEp=<pegOffsetValueEp>&pegPriceType=<pegPriceType>
Field Required Description
symbol Yes Order symbol, cannot be changed
orderID Yes Order ID, cannot be changed
origClOrdID No Original clOrderID
clOrdID No New clOrdID
price No New order price
priceEp No New order price with scale
orderQty No New orderQty
stopPx No New stop price
stopPxEp No New stop price with scale
takeProfit No New stop profit price
takeProfitEp No New stop profit price with scale
stopLoss No New stop loss price
stopLossEp No New stop loss price with scale
pegOffsetValueEp No New trailing offset
pegPriceType No New peg price type

Cancel order by order ID or client order ID

Request format

DELETE /orders/cancel?symbol=<symbol>&orderID=<orderID>
DELETE /orders/cancel?symbol=<symbol>&clOrdID=<clOrdID>

Request sample

{
  "code": 0,
  "msg": "",
  "data": {
    "bizError": 0,
    "orderID": "2585817b-85df-4dea-8507-5db1920b9954",
    "clOrdID": "4b19fd1e-a1a7-2986-d02a-0288ad5137d4",
    "symbol": "BTCUSD",
    "side": "Buy",
    "actionTimeNs": 1580533179846642700,
    "transactTimeNs": 1580532966633276200,
    "orderType": null,
    "priceEp": 80040000,
    "price": 8004,
    "orderQty": 1,
    "displayQty": 1,
    "timeInForce": null,
    "reduceOnly": false,
    "stopPxEp": 0,
    "closedPnlEv": 0,
    "closedPnl": 0,
    "closedSize": 0,
    "cumQty": 0,
    "cumValueEv": 0,
    "cumValue": 0,
    "leavesQty": 1,
    "leavesValueEv": 12493,
    "leavesValue": 0.00012493,
    "stopPx": 0,
    "stopDirection": "UNSPECIFIED",
    "ordStatus": "New"
  }
}

Bulk cancel orders

Request format

DELETE /orders?symbol=<symbol>&orderID=<orderID1>,<orderID2>,<orderID3>

Cancel all orders

Request format

DELETE /orders/all?symbol=<symbol>&untriggered=<untriggered>&text=<text>
Field Type Required Description Possible values
symbol String Yes Which Symbol to cancel
untriggered Boolean No Default to false, default cancel non-conditional order; if intending to cancel conditional order, set this to true true,false
text Comments No Comments of this operation, limited to 40 characters

Query trading account and positions

Request format

GET /accounts/accountPositions?currency=<currency>

Response sample

{
  "code": 0,
  "msg": "",
  "data": {
    "account": {
      "accountId": 0,
      "currency": "BTC",
      "accountBalanceEv": 0,
      "totalUsedBalanceEv": 0
    },
    "positions": [
      {
        "accountID": 0,
        "symbol": "BTCUSD",
        "currency": "BTC",
        "side": "None",
        "positionStatus": "Normal",
        "crossMargin": false,
        "leverageEr": 0,
        "leverage": 0,
        "initMarginReqEr": 0,
        "initMarginReq": 0.01,
        "maintMarginReqEr": 500000,
        "maintMarginReq": 0.005,
        "riskLimitEv": 10000000000,
        "riskLimit": 100,
        "size": 0,
        "value": 0,
        "valueEv": 0,
        "avgEntryPriceEp": 0,
        "avgEntryPrice": 0,
        "posCostEv": 0,
        "posCost": 0,
        "assignedPosBalanceEv": 0,
        "assignedPosBalance": 0,
        "bankruptCommEv": 0,
        "bankruptComm": 0,
        "bankruptPriceEp": 0,
        "bankruptPrice": 0,
        "positionMarginEv": 0,
        "positionMargin": 0,
        "liquidationPriceEp": 0,
        "liquidationPrice": 0,
        "deleveragePercentileEr": 0,
        "deleveragePercentile": 0,
        "buyValueToCostEr": 1150750,
        "buyValueToCost": 0.0115075,
        "sellValueToCostEr": 1149250,
        "sellValueToCost": 0.0114925,
        "markPriceEp": 93169002,
        "markPrice": 9316.9002,
        "markValueEv": 0,
        "markValue": null,
        "estimatedOrdLossEv": 0,
        "estimatedOrdLoss": 0,
        "usedBalanceEv": 0,
        "usedBalance": 0,
        "takeProfitEp": 0,
        "takeProfit": null,
        "stopLossEp": 0,
        "stopLoss": null,
        "realisedPnlEv": 0,
        "realisedPnl": null,
        "cumRealisedPnlEv": 0,
        "cumRealisedPnl": null
      }
    ]
  }
}
Field Type Description Possible values
currency String trading account's settle currency. Use to identify trading account. BTC, USD, ETH
Inverse long contract: unRealizedPnl = (posSize * contractSize) / avgEntryPrice - (posSize * contractSize) / markPrice
Inverse short contract: unRealizedPnl =  (posSize *contractSize) / markPrice - (posSize * contractSize) / avgEntryPrice
Linear long contract:  unRealizedPnl = (posSize * contractSize) * markPrice - (posSize * contractSize) * avgEntryPrice
Linear short contract:  unRealizedPnl = (posSize * contractSize) * avgEntryPrice - (posSize * contractSize) * markPrice

posSize is a signed vaule. contractSize is a fixed value.

Query trading account and positions with realtime unPnL

Request format

GET /accounts/positions?currency=<currency>

Response sample

{
  "code": 0,
  "msg": "",
  "data": {
    "account": {
      "accountId": 111100001,
      "currency": "BTC",
      "accountBalanceEv": 879599942377,
      "totalUsedBalanceEv": 285,
      "bonusBalanceEv": 0
    },
    "positions": [
      {
        "accountID": 111100001,
        "symbol": "BTCUSD",
        "currency": "BTC",
        "side": "Buy",
        "positionStatus": "Normal",
        "crossMargin": false,
        "leverageEr": 0,
        "initMarginReqEr": 1000000,
        "maintMarginReqEr": 500000,
        "riskLimitEv": 10000000000,
        "size": 5,
        "valueEv": 26435,
        "avgEntryPriceEp": 189143181,
        "posCostEv": 285,
        "assignedPosBalanceEv": 285,
        "bankruptCommEv": 750000,
        "bankruptPriceEp": 5000,
        "positionMarginEv": 879599192377,
        "liquidationPriceEp": 5000,
        "deleveragePercentileEr": 0,
        "buyValueToCostEr": 1150750,
        "sellValueToCostEr": 1149250,
        "markPriceEp": 238287555,
        "markValueEv": 0,
        "unRealisedPosLossEv": 0,
        "estimatedOrdLossEv": 0,
        "usedBalanceEv": 285,
        "takeProfitEp": 0,
        "stopLossEp": 0,
        "cumClosedPnlEv": -8913353,
        "cumFundingFeeEv": 123996,
        "cumTransactFeeEv": 940245,
        "realisedPnlEv": 0,
        "unRealisedPnlEv": 5452,
        "cumRealisedPnlEv": 0
      }
    ]
  }
}

The API return latest position unrealized pnl with considerable cost, thus its ratelimit weight is very high.

Set leverage

Request format

PUT /positions/leverage?symbol=<symbol>&leverage=<leverage>&leverageEr=<leverageEr>
Field Type Description Possible values
symbol String Which postion needs to change
leverage Integer Unscaled leverage
leverageEr Integer Ratio scaled leverage, leverage wins when both leverage and leverageEr provided

Set position risklimit

Request format

PUT /positions/riskLimit?symbol=<symbol>&riskLimit=<riskLimit>&riskLimitEv=<riskLimitEv>
Field Type Description Possible values
symbol String Which postion needs to change
riskLimit Integer Unscaled value, reference BTC/USD value scale
riskLimitEv Integer Value scaled risklimit, riskLimitEv wins when both riskLimit and riskLimitEv provided

Assign position balance in isolated marign mode

Request format

POST /positions/assign?symbol=<symbol>&posBalance=<posBalance>&posBalanceEv=<posBalanceEv>
Field Type Description Possible values
symbol String Which symbol needs to change
posBalance Integer Unscaled raw value
posBalanceEv Integer The scaled value for position balance, posBalanceEv wins when both posBalance and posBalanceEv provided

Query open orders by symbol

Request format

GET /orders/activeList?symbol=<symbol>

Response sample

{
  "code": 0,
  "msg": "",
  "data": {
    "rows": [
      {
        "bizError": 0,
        "orderID": "9cb95282-7840-42d6-9768-ab8901385a67",
        "clOrdID": "7eaa9987-928c-652e-cc6a-82fc35641706",
        "symbol": "BTCUSD",
        "side": "Buy",
        "actionTimeNs": 1580533011677666800,
        "transactTimeNs": 1580533011677666800,
        "orderType": null,
        "priceEp": 84000000,
        "price": 8400,
        "orderQty": 1,
        "displayQty": 1,
        "timeInForce": null,
        "reduceOnly": false,
        "stopPxEp": 0,
        "closedPnlEv": 0,
        "closedPnl": 0,
        "closedSize": 0,
        "cumQty": 0,
        "cumValueEv": 0,
        "cumValue": 0,
        "leavesQty": 0,
        "leavesValueEv": 0,
        "leavesValue": 0,
        "stopPx": 0,
        "stopDirection": "Falling",
        "ordStatus": "Untriggered"
      },
      {
        "bizError": 0,
        "orderID": "93397a06-e76d-4e3b-babc-dff2696786aa",
        "clOrdID": "71c2ab5d-eb6f-0d5c-a7c4-50fd5d40cc50",
        "symbol": "BTCUSD",
        "side": "Sell",
        "actionTimeNs": 1580532983785506600,
        "transactTimeNs": 1580532983786370300,
        "orderType": null,
        "priceEp": 99040000,
        "price": 9904,
        "orderQty": 1,
        "displayQty": 1,
        "timeInForce": null,
        "reduceOnly": false,
        "stopPxEp": 0,
        "closedPnlEv": 0,
        "closedPnl": 0,
        "closedSize": 0,
        "cumQty": 0,
        "cumValueEv": 0,
        "cumValue": 0,
        "leavesQty": 1,
        "leavesValueEv": 10096,
        "leavesValue": 0.00010096,
        "stopPx": 0,
        "stopDirection": "UNSPECIFIED",
        "ordStatus": "New"
      }
    ]
  }
}
Field Type Description Possible values
symbol String which symbol needs to query

Query closed orders by symbol

Request format

GET /exchange/order/list?symbol=<symbol>&start=<start>&end=<end>&offset=<offset>&limit=<limit>&ordStatus=<ordStatus>&withCount=<withCount>

Response sample

{
  "code": 0,
  "msg": "OK",
  "data": {
    "total": 39,
    "rows": [
      {
        "orderID": "7d5a39d6-ff14-4428-b9e1-1fcf1800d6ac",
        "clOrdID": "e422be37-074c-403d-aac8-ad94827f60c1",
        "symbol": "BTCUSD",
        "side": "Sell",
        "orderType": "Limit",
        "actionTimeNs": 1577523473419470300,
        "priceEp": 75720000,
        "price": null,
        "orderQty": 12,
        "displayQty": 0,
        "timeInForce": "GoodTillCancel",
        "reduceOnly": false,
        "takeProfitEp": 0,
        "takeProfit": null,
        "stopLossEp": 0,
        "closedPnlEv": 0,
        "closedPnl": null,
        "closedSize": 0,
        "cumQty": 0,
        "cumValueEv": 0,
        "cumValue": null,
        "leavesQty": 0,
        "leavesValueEv": 0,
        "leavesValue": null,
        "stopLoss": null,
        "stopDirection": "UNSPECIFIED",
        "ordStatus": "Canceled",
        "transactTimeNs": 1577523473425416400
      },
      {
        "orderID": "b63bc982-be3a-45e0-8974-43d6375fb626",
        "clOrdID": "uuid-1577463487504",
        "symbol": "BTCUSD",
        "side": "Sell",
        "orderType": "Limit",
        "actionTimeNs": 1577963507348468200,
        "priceEp": 71500000,
        "price": null,
        "orderQty": 700,
        "displayQty": 700,
        "timeInForce": "GoodTillCancel",
        "reduceOnly": false,
        "takeProfitEp": 0,
        "takeProfit": null,
        "stopLossEp": 0,
        "closedPnlEv": 0,
        "closedPnl": null,
        "closedSize": 0,
        "cumQty": 700,
        "cumValueEv": 9790209,
        "cumValue": null,
        "leavesQty": 0,
        "leavesValueEv": 0,
        "leavesValue": null,
        "stopLoss": null,
        "stopDirection": "UNSPECIFIED",
        "ordStatus": "Filled",
        "transactTimeNs": 1578026629824704800
      }
    ]
  }
}
Field Type Description Possible values
symbol String which symbol needs to query
start Integer start time range, Epoch millis,available only from the last 2 month
end Integer end time range, Epoch millis
offset Integer offset to resultset
limit Integer limit of resultset, max 200
ordStatus String order status list filter New, PartiallyFilled, Untriggered, Filled, Canceled

Query user order by order ID or client order ID

Request format

Query user order history from database. Data is limited for the last 2 months.

GET /exchange/order?symbol=<symbol>&orderID=<orderID1,orderID2>
GET /exchange/order?symbol=<symbol>&clOrdID=<clOrdID1,clOrdID2>

Response sample

{
  "code": 0,
  "msg": "OK",
  "data": [
    {
      "orderID": "7d5a39d6-ff14-4428-b9e1-1fcf1800d6ac",
      "clOrdID": "e422be37-074c-403d-aac8-ad94827f60c1",
      "symbol": "BTCUSD",
      "side": "Sell",
      "orderType": "Limit",
      "actionTimeNs": 1577523473419470300,
      "priceEp": 75720000,
      "price": null,
      "orderQty": 12,
      "displayQty": 0,
      "timeInForce": "GoodTillCancel",
      "reduceOnly": false,
      "takeProfitEp": 0,
      "takeProfit": null,
      "stopLossEp": 0,
      "closedPnlEv": 0,
      "closedPnl": null,
      "closedSize": 0,
      "cumQty": 0,
      "cumValueEv": 0,
      "cumValue": null,
      "leavesQty": 0,
      "leavesValueEv": 0,
      "leavesValue": null,
      "stopLoss": null,
      "stopDirection": "UNSPECIFIED",
      "ordStatus": "Canceled",
      "transactTimeNs": 1577523473425416400
    },
    {
      "orderID": "b63bc982-be3a-45e0-8974-43d6375fb626",
      "clOrdID": "uuid-1577463487504",
      "symbol": "BTCUSD",
      "side": "Sell",
      "orderType": "Limit",
      "actionTimeNs": 1577963507348468200,
      "priceEp": 71500000,
      "price": null,
      "orderQty": 700,
      "displayQty": 700,
      "timeInForce": "GoodTillCancel",
      "reduceOnly": false,
      "takeProfitEp": 0,
      "takeProfit": null,
      "stopLossEp": 0,
      "closedPnlEv": 0,
      "closedPnl": null,
      "closedSize": 0,
      "cumQty": 700,
      "cumValueEv": 9790209,
      "cumValue": null,
      "leavesQty": 0,
      "leavesValueEv": 0,
      "leavesValue": null,
      "stopLoss": null,
      "stopDirection": "UNSPECIFIED",
      "ordStatus": "Filled",
      "transactTimeNs": 1578026629824704800
    }
  ]
}

Query user trade

Request format

GET /exchange/order/trade?symbol=<symbol>&start=<start>&end=<end>&limit=<limit>&offset=<offset>&withCount=<withCount>

Response sample

{
  "code": 0,
  "msg": "OK",
  "data": {
    "total": 79,
    "rows": [
      {
        "transactTimeNs": 1578026629824704800,
        "symbol": "BTCUSD",
        "currency": "BTC",
        "action": "Replace",
        "side": "Sell",
        "tradeType": "Trade",
        "execQty": 700,
        "execPriceEp": 71500000,
        "orderQty": 700,
        "priceEp": 71500000,
        "execValueEv": 9790209,
        "feeRateEr": -25000,
        "execFeeEv": -2447,
        "ordType": "Limit",
        "execID": "b01671a1-5ddc-5def-b80a-5311522fd4bf",
        "orderID": "b63bc982-be3a-45e0-8974-43d6375fb626",
        "clOrdID": "uuid-1577463487504",
        "execStatus": "MakerFill"
      },
      {
        "transactTimeNs": 1578009600000000000,
        "symbol": "BTCUSD",
        "currency": "BTC",
        "action": "SettleFundingFee",
        "side": "Buy",
        "tradeType": "Funding",
        "execQty": 700,
        "execPriceEp": 69473435,
        "orderQty": 0,
        "priceEp": 0,
        "execValueEv": 10075793,
        "feeRateEr": 4747,
        "execFeeEv": 479,
        "ordType": "UNSPECIFIED",
        "execID": "381fbe21-a116-472d-a547-9e2368dcc194",
        "orderID": "00000000-0000-0000-0000-000000000000",
        "clOrdID": "SettlingFunding",
        "execStatus": "Init"
      }
    ]
  }
}

Field Type Required Description Possible Values
symbol String Yes Trading symbol BTCUSD, ETHUSD ...
tradeType String No Trade type of execution order Trade,Funding,AdlTrade,LiqTrade
start Integer No Epoch time in milli-seconds of range start. available only from the last 2 month --
end Integer No Epoch time in milli-seconds of range end --
limit Integer No The expected count of returned data-set. Default to 50. Max to 200 --
offset Integer No Offset of total dataset in a range --
withCount Boolean No A flag to tell if the count of total result set is required --
TradeTypes Description
Trade Normal trades
Funding Funding on positions
AdlTrade Auto-delevearage trades
LiqTrade Liquidation trades

Query order book

Request format

GET /md/orderbook?symbol=<symbol>

Response format

{
  "error": null,
  "id": 0,
  "result": {
    "book": {
      "asks": [
        [
          <priceEp>,
          <size>
        ],
        .
        .
        .
      ],
      "bids": [
        [
          <priceEp>,
          <size>
        ],
        .
        .
        .
      ],
    ]
    },
    "depth": 30,
    "sequence": <sequence>,
    "timestamp": <timestamp>,
    "symbol": "<symbol>",
    "type": "snapshot"
  }
}
Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds
priceEp Integer Scaled book level price
size Integer Scaled book level size
sequence Integer current message sequence
symbol String Contract symbol name

Request sample

GET /md/orderbook?symbol=BTCUSD

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "book": {
      "asks": [
        [
          87705000,
          1000000
        ],
        [
          87710000,
          200000
        ]
      ],
      "bids": [
        [
          87700000,
          2000000
        ],
        [
          87695000,
          200000
        ]
      ]
    },
    "depth": 30,
    "sequence": 455476965,
    "timestamp": 1583555482434235628,
    "symbol": "BTCUSD",
    "type": "snapshot"
  }
}

Query full order book

Request format

GET /md/fullbook?symbol=<symbol>

Request sample

GET /md/fullbook?symbol=BTCUSD

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "book": {
      "asks": [
        [
          87705000,
          1000000
        ],
        [
          87710000,
          200000
        ]
      ],
      "bids": [
        [
          87700000,
          2000000
        ],
        [
          87695000,
          200000
        ]
      ]
    },
    "depth": 0,
    "sequence": 455476965,
    "timestamp": 1583555482434235628,
    "symbol": "BTCUSD",
    "type": "snapshot"
  }
}

Query kline

Request format

GET /exchange/public/md/v2/kline?symbol=<symbol>&resolution=<resolution>&limit=<limit>

Response format

{
  "code": 0,
  "msg": "OK",
  "data": {
    "total": -1,
    "rows": [[<timestamp>, <interval>, <last_close>, <open>, <high>, <low>, <close>, <volume>, <turnover>], [...]]
  }
}
Field Type Required Description Possible Values
symbol String Yes symbol name BTCUSD,ETHUSD,uBTCUSD,cETHUSD,XRPUSD...
resolution Integer Yes kline interval described as below
limit Integer No limit of result described as below
Resolution Description
60 MINUTE_1
300 MINUTE_5
900 MINUTE_15
1800 MINUTE_30
3600 HOUR_1
14400 HOUR_4
86400 DAY_1
604800 WEEK_1
2592000 MONTH_1
7776000 SEASON_1
31104000 YEAR_1
Limit Description
5 limit 5
10 limit 10
50 limit 50
100 limit 100
500 limit 500
1000 limit 1000

NOTE for backward compatibility reason, phemex also provides kline query with from/to, however, this interface is NOT recommended.

Request format

GET /exchange/public/md/kline?symbol=<symbol>&to=<to>&from=<from>&resolution=<resolution>

Field Type Required Description Possible Values
symbol String Yes symbol name BTCUSD,ETHUSD,uBTCUSD,cETHUSD,XRPUSD...
from Integer Yes start time in seconds value aligned in resolution boundary
to Integer Yes end time in seconds value aligned in resolution boundary; Number of k-lines return between [from, to) should be less than 1000
resolution Integer Yes kline interval the same as described above

Query recent trades

Request format

GET /md/trade?symbol=<symbol>
Field Type Description Possible values
symbol String Contract symbol name

Response format

{
  "error": null,
  "id": 0,
  "result": {
    "type": "snapshot",
    "sequence": <sequence>,
    "symbol": "<symbol>",
    "trades": [
      [
        <timestamp>,
        "<side>",
        <priceEp>,
        <size>
      ],
      .
      .
      .
    ]
  }
}

Request sample

GET /md/trade?symbol=BTCUSD

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "sequence": 15934323,
    "symbol": "BTCUSD",
    "trades": [
      [
        1579164056368538508,
        "Sell",
        86960000,
        121
      ],
      [
        1579164055036820552,
        "Sell",
        86960000,
        58
      ]
    ],
    "type": "snapshot"
  }
}
Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds
side String Trade side string Buy, Sell
priceEp Integer Scaled trade price
size Integer Scaled trade size
sequence Integer Current message sequence
symbol String Contract symbol name

Query 24 hours ticker

Request format

GET v1/md/ticker/24hr?symbol=<symbol>
Field Type Description Possible values
symbol String Contract symbol name

Response format

{
  "error": null,
  "id": 0,
  "result": {
      "askEp": <best ask priceEp>,
      "bidEp": <best bid priceEp>,
      "fundingRateEr": <funding rateEr>,
      "highEp": <high priceEp>,
      "indexEp": <index priceEp>,
      "lastEp": <last priceEp>,
      "lowEp": <low priceEp>,
      "markEp": <mark priceEp>,
      "openEp": <open priceEp>,
      "openInterest": <open interest>,
      "predFundingRateEr": <predicated funding rateEr>,
      "symbol": <symbol>,
      "timestamp": <timestamp>,
      "turnoverEv": <turnoverEv>,
      "volume": <volume>
  }
}

Request sample

GET v1/md/ticker/24hr?symbol=BTCUSD

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "close": 87425000,
    "fundingRate": 10000,
    "high": 92080000,
    "indexPrice": 87450676,
    "low": 87130000,
    "markPrice": 87453092,
    "open": 90710000,
    "openInterest": 7821141,
    "predFundingRate": 7609,
    "symbol": "BTCUSD",
    "timestamp": 1583646442444219017,
    "turnover": 1399362834123,
    "volume": 125287131
  }
}
Field Type Description Possible values
open priceEp Integer The scaled open price in last 24 hours
high priceEp Integer The scaled highest price in last 24 hours
low priceEp Integer The scaled lowest price in last 24 hours
close priceEp Integer The scaled close price in last 24 hours
index priceEp Integer Scaled index price
mark priceEp Integer Scaled mark price
open interest Integer current open interest
funding rateEr Integer Scaled funding rate
predicated funding rateEr Integer Scaled predicated funding rate
timestamp Integer Timestamp in nanoseconds
symbol String Contract symbol name
turnoverEv Integer The scaled turnover value in last 24 hours
volume Integer Symbol trade volume in last 24 hours

Query history trades by symbol

Request format

GET /exchange/public/nomics/trades?market=<symbol>&since=<since>
Field Type Description Possible values
market String the market of symbol
since String Last id of response field, 0-0-0 is from the very initial trade default 0-0-0
start Integer Epoch time in milli-seconds of range start
end Integer Epoch time in milli-seconds of range end

Response format

{
  "code": 0,
  "data": [
    {
      "id": "<id>",
      "amount_quote": "<amount>",
      "price": "<price>",
      "side": "<side>",
      "timestamp": "<timestamp>",
      "type": "<type>"
    }
  ],
  "msg": "<msg>"
}

Response sample

{
  "code": 0,
  "msg": "OK",
  "data": [
  {
    "id": "1183-3-2",
    "timestamp": "2019-11-24T08:32:17.046Z",
    "price": "7211.00000000",
    "amount_quote": "1",
    "side": "sell",
    "type": "limit"
  },
  {
    "id": "1184-2-1",
    "timestamp": "2019-11-24T08:32:17.047Z",
    "price": "7211.00000000",
    "amount_quote": "1",
    "side": "buy",
    "type": "limit"
  }]
}

Contract Websocket API

Heartbeat

Request

{
  "id": 0,
  "method": "server.ping",
  "params": []
}

Response

{
  "error": null,
  "id": 0,
  "result": "pong"
}

User authentication

Request format

{
  "method": "user.auth",
  "params": [
    "API",
    "<token>",
    "<signature>",
    <expiry>
  ],
  "id": 0
}

Request sample

{
  "method": "user.auth",
  "params": [
    "API",
    "806066b0-f02b-4d3e-b444-76ec718e1023",
    "8c939f7a6e6716ab7c4240384e07c81840dacd371cdcf5051bb6b7084897470e",
    1570091232
  ],
  "id": 0
}

Public channels like trade/orderbook/kline are published publicly without user authentication. While for private channels like account/position/order data, the client should send user.auth message to Data Gateway to authenticate the session.

Field Type Description Possible values
type String Token type API
token String API Key
signature String Signature generated by a funtion as HMacSha256(API Key + expiry) with API Secret
expiry Integer A future time after which request will be rejected, in epoch second. Maximum expiry is request time plus 2 minutes

Subscribe orderBook

Request format

{
  "id": <id>,
  "method": "orderbook.subscribe",
  "params": [
    "<symbol>"
  ]
}

Subscribe orderbook update messages with depth = 30 and interval = 20ms.

On each successful subscription, DataGW will immediately send the current Order Book (with default depth=30) snapshot to client and all later order book updates will be published.

Request sample:

{
  "id": 0,
  "method": "orderbook.subscribe",
  "params": [
    "BTCUSD"
  ]
}

Subscribe full orderBook

Request format

{
  "id": <id>,
  "method": "orderbook.subscribe",
  "params": [
    "<symbol>",
    true
  ]
}

Subscribe orderbook update messages with full depth and interval = 100ms.

On each successful subscription, DataGW will immediately send the current full Order Book snapshot to client and all later order book updates will be published.

Request sample:

{
  "id": 0,
  "method": "orderbook.subscribe",
  "params": [
    "BTCUSD",
    true
  ]
}

OrderBook message

Message format:

{
  "book": {
    "asks": [
      [
        <priceEp>,
        <qty>
      ],
      .
      .
      .
    ],
    "bids": [
      [
        <priceEp>,
        <qty>
      ],
      .
      .
      .
    ]
  },
  "depth": <depth>,
  "sequence": <sequence>,
  "timestamp": <timestamp>,
  "symbol": "<symbol>",

DataGW publishes order book message with types: incremental, snapshot. Snapshot messages are published with 60-second interval for client self-verification.

Field Type Description Possible values
side String Price level side bid, ask
priceEp Integer Scaled price
qty Integer Price level size. Non-zero qty indicates price level insertion or updation, and qty 0 indicates price level deletion.
sequence Integer Latest message sequence
depth Integer Market depth 30 by default, 0 denotes fullbook
type String Message type snapshot, incremental

Message sample: snapshot

{
  "book": {
    "asks": [
      [
        86765000,
        19609
      ],
      [
        86770000,
        7402
      ]
    ],
    "bids": [
      [
        86760000,
        18995
      ],
      [
        86755000,
        6451
      ]
    ]
  },
  "depth": 30,
  "sequence": 1191904,
  "symbol": "BTCUSD",
  "type": "snapshot"
}

Message sample: incremental update

{
  "book": {
    "asks": [
      [
        86775000,
        4621
      ]
    ],
    "bids": []
  },
  "depth": 30,
  "sequence": 1191905,
  "symbol": "BTCUSD",
  "type": "incremental"
}

Unsubscribe orderBook

Request sample

{
  "id": 0,
  "method": "orderbook.unsubscribe",
  "params": []
}

It unsubscribes all orderbook related subscriptions.

Subscribe trade

Request format

{
  "id": <id>,
  "method": "trade.subscribe",
  "params": [
    "<symbol>"
  ]
}

On each successful subscription, DataGW will send the 200 history trades immediately for the subscribed symbol and all the later trades will be published.

Request sample

{
  "id": 0,
  "method": "trade.subscribe",
  "params": [
    "BTCUSD"
  ]
}

Trade message

Message format

{
  "trades": [
    [
      <timestamp>,
      "<side>",
      <priceEp>,
      <qty>
    ],
    .
    .
    .
  ],
  "sequence": <sequence>,
  "symbol": "<symbol>",
  "type": "<type>"
}

DataGW publishes trade message with types: incremental, snapshot. Incremental messages are published with 20ms interval. And snapshot messages are published on connection initial setup for client recovery.

Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds for each trade
side String Execution taker side bid, ask
priceEp Integer Scaled execution price
qty Integer Execution size
sequence Integer Latest message sequence
symbol String Contract symbol name
type String Message type snapshot, incremental

Message sample: snapshot

{
  "sequence": 1167852,
  "symbol": "BTCUSD",
  "trades": [
    [
      1573716998128563500,
      "Buy",
      86735000,
      56
    ],
    [
      1573716995033683000,
      "Buy",
      86735000,
      52
    ],
    [
      1573716991485286000,
      "Buy",
      86735000,
      51
    ],
    [
      1573716988636291300,
      "Buy",
      86735000,
      12
    ]
  ],
  "type": "snapshot"
}

Message sample: snapshot

{
  "sequence": 1188273,
  "symbol": "BTCUSD",
  "trades": [
    [
      1573717116484024300,
      "Buy",
      86730000,
      21
    ]
  ],
  "type": "incremental"
}

Unsubscribe trade

Request format: unsubscribe all trade subsciptions

{
  "id": <id>,
  "method": "trade.unsubscribe",
  "params": [
  ]
}

Request format: unsubscribe all trade subsciptions for a symbol

{
  "id": <id>,
  "method": "trade.unsubscribe",
  "params": [
    "<symbol>"
  ]
}

It unsubscribes all trade subscriptions or for a single symbol.

Subscribe kline

Request format

{
  "id": <id>,
  "method": "kline.subscribe",
  "params": [
    "<symbol>",
    "<interval>"
  ]
}

On each successful subscription, DataGW will send the 1000 history klines immediately for the subscribed symbol and all the later kline update will be published in real-time.

Request sample: subscribe 1-day kline

{
  "id": 0,
  "method": "kline.subscribe",
  "params": [
    "BTCUSD",
    86400
  ]
}

Kline message

Message format

{
  "kline": [
    [
      <timestamp>,
      "<interval>",
      <lastCloseEp>,
      <openEp>,
      <highEp>,
      <lowEp>,
      <closeEp>,
      <volume>,
      <turnoverEv>,
    ],
    .
    .
    .
  ],
  "sequence": <sequence>,
  "symbol": "<symbol>",
  "type": "<type>"
}

Message sample: snapshot

{
  "kline": [
    [
      1590019200,
      86400,
      95165000,
      95160000,
      95160000,
      95160000,
      95160000,
      164,
      1723413
    ],
    [
      1589932800,
      86400,
      97840000,
      97840000,
      98480000,
      92990000,
      95165000,
      246294692,
      2562249857942
    ],
    [
      1589846400,
      86400,
      97335000,
      97335000,
      99090000,
      94490000,
      97840000,
      212484260,
      2194232158593
    ]
  ],
  "sequence": 1118993873,
  "symbol": "BTCUSD",
  "type": "snapshot"
}

Message sample: snapshot

{
  "kline": [
    [
      1590019200,
      86400,
      95165000,
      95160000,
      95750000,
      92585000,
      93655000,
      84414679,
      892414738605
    ]
  ],
  "sequence": 1122006398,
  "symbol": "BTCUSD",
  "type": "incremental"
}

DataGW publishes kline message with types: incremental, snapshot. Incremental messages are published with 20ms interval. And snapshot messages are published on connection initial setup for client recovery.

Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds for each trade
interval Integer Kline interval type 60, 300, 900, 1800, 3600, 14400, 86400, 604800, 2592000, 7776000, 31104000
lastCloseEp Integer Scaled last close price
openEp Integer Scaled open price
highEp Integer Scaled high price
lowEp Integer Scaled low price
closeEp Integer Scaled close price
volume Integer Trade voulme during the current kline interval
turnoverEv Integer Scaled turnover value
sequence Integer Latest message sequence
symbol String Contract symbol name
type String Message type snapshot, incremental

Unsubscribe kline

Request format: unsubscribe all kline subscriptions

{
  "id": <id>,
  "method": "kline.unsubscribe",
  "params": []
}

Request format: unsubscribe all kline subscriptions of a symbol

{
  "id": <id>,
  "method": "kline.unsubscribe",
  "params": [
    "<symbol>"
  ]
}

It unsubscribes all kline subscriptions or for a single symbol.

Subscribe account-order-position (AOP)

Request format

{
  "id": <id>,
  "method": "aop.subscribe",
  "params": []
}

AOP subscription requires the session been authorized successfully. DataGW extracts the user information from the given token and sends AOP messages back to client accordingly. 0 or more latest account snapshot messages will be sent to client immediately on subscription, and incremental messages will be sent for later updates. Each account snapshot contains a trading account information, holding positions, and open / max 100 closed / max 100 filled order event message history.

Account-order-position (AOP) message

Message format

{
  "accounts": [
    {
      "accountID": 604630001,
      "currency": "BTC",
      .
      .
      .
    }
  ],
  "orders": [
    {
      "accountID": 604630001,
      .
      .
      .
    }
  ],
  "positions": [
    {
      "accountID": 604630001,
      .
      .
      .
    }
  ],
  "sequence":1,
  "timestamp":<timestamp>,
  "type":"<type>"
}

Field Type Description Possible values
timestamp Integer Transaction timestamp in nanoseconds
sequence Integer Latest message sequence
symbol String Contract symbol name
type String Message type snapshot, incremental

Message sample: snapshot

{
  "accounts": [
    {
      "accountBalanceEv": 100000024,
      "accountID": 675340001,
      "bonusBalanceEv": 0,
      "currency": "BTC",
      "totalUsedBalanceEv": 1222,
      "userID": 67534
    }
  ],
  "orders": [
    {
      "accountID": 675340001,
      "action": "New",
      "actionBy": "ByUser",
      "actionTimeNs": 1573711481897337000,
      "addedSeq": 1110523,
      "bonusChangedAmountEv": 0,
      "clOrdID": "uuid-1573711480091",
      "closedPnlEv": 0,
      "closedSize": 0,
      "code": 0,
      "cumQty": 2,
      "cumValueEv": 23018,
      "curAccBalanceEv": 100000005,
      "curAssignedPosBalanceEv": 0,
      "curBonusBalanceEv": 0,
      "curLeverageEr": 0,
      "curPosSide": "Buy",
      "curPosSize": 2,
      "curPosTerm": 1,
      "curPosValueEv": 23018,
      "curRiskLimitEv": 10000000000,
      "currency": "BTC",
      "cxlRejReason": 0,
      "displayQty": 2,
      "execFeeEv": -5,
      "execID": "92301512-7a79-5138-b582-ac185223727d",
      "execPriceEp": 86885000,
      "execQty": 2,
      "execSeq": 1131034,
      "execStatus": "MakerFill",
      "execValueEv": 23018,
      "feeRateEr": -25000,
      "lastLiquidityInd": "AddedLiquidity",
      "leavesQty": 0,
      "leavesValueEv": 0,
      "message": "No error",
      "ordStatus": "Filled",
      "ordType": "Limit",
      "orderID": "e9a45803-0af8-41b7-9c63-9b7c417715d9",
      "orderQty": 2,
      "pegOffsetValueEp": 0,
      "priceEp": 86885000,
      "relatedPosTerm": 1,
      "relatedReqNum": 2,
      "side": "Buy",
      "stopLossEp": 0,
      "stopPxEp": 0,
      "symbol": "BTCUSD",
      "takeProfitEp": 0,
      "timeInForce": "GoodTillCancel",
      "tradeType": "Trade",
      "transactTimeNs": 1573712555309040400,
      "userID": 67534
    },
    {
      "accountID": 675340001,
      "action": "New",
      "actionBy": "ByUser",
      "actionTimeNs": 1573711490507067000,
      "addedSeq": 1110980,
      "bonusChangedAmountEv": 0,
      "clOrdID": "uuid-1573711488668",
      "closedPnlEv": 0,
      "closedSize": 0,
      "code": 0,
      "cumQty": 3,
      "cumValueEv": 34530,
      "curAccBalanceEv": 100000013,
      "curAssignedPosBalanceEv": 0,
      "curBonusBalanceEv": 0,
      "curLeverageEr": 0,
      "curPosSide": "Buy",
      "curPosSize": 5,
      "curPosTerm": 1,
      "curPosValueEv": 57548,
      "curRiskLimitEv": 10000000000,
      "currency": "BTC",
      "cxlRejReason": 0,
      "displayQty": 3,
      "execFeeEv": -8,
      "execID": "80899855-5b95-55aa-b84e-8d1052f19886",
      "execPriceEp": 86880000,
      "execQty": 3,
      "execSeq": 1131408,
      "execStatus": "MakerFill",
      "execValueEv": 34530,
      "feeRateEr": -25000,
      "lastLiquidityInd": "AddedLiquidity",
      "leavesQty": 0,
      "leavesValueEv": 0,
      "message": "No error",
      "ordStatus": "Filled",
      "ordType": "Limit",
      "orderID": "7e03cd6b-e45e-48d9-8937-8c6628e7a79d",
      "orderQty": 3,
      "pegOffsetValueEp": 0,
      "priceEp": 86880000,
      "relatedPosTerm": 1,
      "relatedReqNum": 3,
      "side": "Buy",
      "stopLossEp": 0,
      "stopPxEp": 0,
      "symbol": "BTCUSD",
      "takeProfitEp": 0,
      "timeInForce": "GoodTillCancel",
      "tradeType": "Trade",
      "transactTimeNs": 1573712559100655600,
      "userID": 67534
    },
    {
      "accountID": 675340001,
      "action": "New",
      "actionBy": "ByUser",
      "actionTimeNs": 1573711499282604000,
      "addedSeq": 1111025,
      "bonusChangedAmountEv": 0,
      "clOrdID": "uuid-1573711497265",
      "closedPnlEv": 0,
      "closedSize": 0,
      "code": 0,
      "cumQty": 4,
      "cumValueEv": 46048,
      "curAccBalanceEv": 100000024,
      "curAssignedPosBalanceEv": 0,
      "curBonusBalanceEv": 0,
      "curLeverageEr": 0,
      "curPosSide": "Buy",
      "curPosSize": 9,
      "curPosTerm": 1,
      "curPosValueEv": 103596,
      "curRiskLimitEv": 10000000000,
      "currency": "BTC",
      "cxlRejReason": 0,
      "displayQty": 4,
      "execFeeEv": -11,
      "execID": "0be06645-90b8-5abe-8eb0-dca8e852f82f",
      "execPriceEp": 86865000,
      "execQty": 4,
      "execSeq": 1132422,
      "execStatus": "MakerFill",
      "execValueEv": 46048,
      "feeRateEr": -25000,
      "lastLiquidityInd": "AddedLiquidity",
      "leavesQty": 0,
      "leavesValueEv": 0,
      "message": "No error",
      "ordStatus": "Filled",
      "ordType": "Limit",
      "orderID": "66753807-9204-443d-acf9-946d15d5bedb",
      "orderQty": 4,
      "pegOffsetValueEp": 0,
      "priceEp": 86865000,
      "relatedPosTerm": 1,
      "relatedReqNum": 4,
      "side": "Buy",
      "stopLossEp": 0,
      "stopPxEp": 0,
      "symbol": "BTCUSD",
      "takeProfitEp": 0,
      "timeInForce": "GoodTillCancel",
      "tradeType": "Trade",
      "transactTimeNs": 1573712618104628700,
      "userID": 67534
    }
  ],
  "positions": [
    {
      "accountID": 675340001,
      "assignedPosBalanceEv": 0,
      "avgEntryPriceEp": 86875941,
      "bankruptCommEv": 75022,
      "bankruptPriceEp": 90000,
      "buyLeavesQty": 0,
      "buyLeavesValueEv": 0,
      "buyValueToCostEr": 1150750,
      "createdAtNs": 0,
      "crossSharedBalanceEv": 99998802,
      "cumClosedPnlEv": 0,
      "cumFundingFeeEv": 0,
      "cumTransactFeeEv": -24,
      "currency": "BTC",
      "dataVer": 4,
      "deleveragePercentileEr": 0,
      "displayLeverageEr": 1000000,
      "estimatedOrdLossEv": 0,
      "execSeq": 1132422,
      "freeCostEv": 0,
      "freeQty": -9,
      "initMarginReqEr": 1000000,
      "lastFundingTime": 1573703858883133200,
      "lastTermEndTime": 0,
      "leverageEr": 0,
      "liquidationPriceEp": 90000,
      "maintMarginReqEr": 500000,
      "makerFeeRateEr": 0,
      "markPriceEp": 86786292,
      "orderCostEv": 0,
      "posCostEv": 1115,
      "positionMarginEv": 99925002,
      "positionStatus": "Normal",
      "riskLimitEv": 10000000000,
      "sellLeavesQty": 0,
      "sellLeavesValueEv": 0,
      "sellValueToCostEr": 1149250,
      "side": "Buy",
      "size": 9,
      "symbol": "BTCUSD",
      "takerFeeRateEr": 0,
      "term": 1,
      "transactTimeNs": 1573712618104628700,
      "unrealisedPnlEv": -107,
      "updatedAtNs": 0,
      "usedBalanceEv": 1222,
      "userID": 67534,
      "valueEv": 103596
    }
  ],
  "sequence": 1310812,
  "timestamp": 1573716998131004000,
  "type": "snapshot"
}

Message sample: incremental

{
  "accounts": [
    {
      "accountBalanceEv": 99999989,
      "accountID": 675340001,
      "bonusBalanceEv": 0,
      "currency": "BTC",
      "totalUsedBalanceEv": 1803,
      "userID": 67534
    }
  ],
  "orders": [
    {
      "accountID": 675340001,
      "action": "New",
      "actionBy": "ByUser",
      "actionTimeNs": 1573717286765750000,
      "addedSeq": 1192303,
      "bonusChangedAmountEv": 0,
      "clOrdID": "uuid-1573717284329",
      "closedPnlEv": 0,
      "closedSize": 0,
      "code": 0,
      "cumQty": 0,
      "cumValueEv": 0,
      "curAccBalanceEv": 100000024,
      "curAssignedPosBalanceEv": 0,
      "curBonusBalanceEv": 0,
      "curLeverageEr": 0,
      "curPosSide": "Buy",
      "curPosSize": 9,
      "curPosTerm": 1,
      "curPosValueEv": 103596,
      "curRiskLimitEv": 10000000000,
      "currency": "BTC",
      "cxlRejReason": 0,
      "displayQty": 4,
      "execFeeEv": 0,
      "execID": "00000000-0000-0000-0000-000000000000",
      "execPriceEp": 0,
      "execQty": 0,
      "execSeq": 1192303,
      "execStatus": "New",
      "execValueEv": 0,
      "feeRateEr": 0,
      "leavesQty": 4,
      "leavesValueEv": 46098,
      "message": "No error",
      "ordStatus": "New",
      "ordType": "Limit",
      "orderID": "e329ae87-ce80-439d-b0cf-ad65272ed44c",
      "orderQty": 4,
      "pegOffsetValueEp": 0,
      "priceEp": 86770000,
      "relatedPosTerm": 1,
      "relatedReqNum": 5,
      "side": "Buy",
      "stopLossEp": 0,
      "stopPxEp": 0,
      "symbol": "BTCUSD",
      "takeProfitEp": 0,
      "timeInForce": "GoodTillCancel",
      "transactTimeNs": 1573717286765896400,
      "userID": 67534
    },
    {
      "accountID": 675340001,
      "action": "New",
      "actionBy": "ByUser",
      "actionTimeNs": 1573717286765750000,
      "addedSeq": 1192303,
      "bonusChangedAmountEv": 0,
      "clOrdID": "uuid-1573717284329",
      "closedPnlEv": 0,
      "closedSize": 0,
      "code": 0,
      "cumQty": 4,
      "cumValueEv": 46098,
      "curAccBalanceEv": 99999989,
      "curAssignedPosBalanceEv": 0,
      "curBonusBalanceEv": 0,
      "curLeverageEr": 0,
      "curPosSide": "Buy",
      "curPosSize": 13,
      "curPosTerm": 1,
      "curPosValueEv": 149694,
      "curRiskLimitEv": 10000000000,
      "currency": "BTC",
      "cxlRejReason": 0,
      "displayQty": 4,
      "execFeeEv": 35,
      "execID": "8d1848a2-5faf-52dd-be71-9fecbc8926be",
      "execPriceEp": 86770000,
      "execQty": 4,
      "execSeq": 1192303,
      "execStatus": "TakerFill",
      "execValueEv": 46098,
      "feeRateEr": 75000,
      "lastLiquidityInd": "RemovedLiquidity",
      "leavesQty": 0,
      "leavesValueEv": 0,
      "message": "No error",
      "ordStatus": "Filled",
      "ordType": "Limit",
      "orderID": "e329ae87-ce80-439d-b0cf-ad65272ed44c",
      "orderQty": 4,
      "pegOffsetValueEp": 0,
      "priceEp": 86770000,
      "relatedPosTerm": 1,
      "relatedReqNum": 5,
      "side": "Buy",
      "stopLossEp": 0,
      "stopPxEp": 0,
      "symbol": "BTCUSD",
      "takeProfitEp": 0,
      "timeInForce": "GoodTillCancel",
      "tradeType": "Trade",
      "transactTimeNs": 1573717286765896400,
      "userID": 67534
    }
  ],
  "positions": [
    {
      "accountID": 675340001,
      "assignedPosBalanceEv": 0,
      "avgEntryPriceEp": 86843828,
      "bankruptCommEv": 75056,
      "bankruptPriceEp": 130000,
      "buyLeavesQty": 0,
      "buyLeavesValueEv": 0,
      "buyValueToCostEr": 1150750,
      "createdAtNs": 0,
      "crossSharedBalanceEv": 99998186,
      "cumClosedPnlEv": 0,
      "cumFundingFeeEv": 0,
      "cumTransactFeeEv": 11,
      "currency": "BTC",
      "dataVer": 5,
      "deleveragePercentileEr": 0,
      "displayLeverageEr": 1000000,
      "estimatedOrdLossEv": 0,
      "execSeq": 1192303,
      "freeCostEv": 0,
      "freeQty": -13,
      "initMarginReqEr": 1000000,
      "lastFundingTime": 1573703858883133200,
      "lastTermEndTime": 0,
      "leverageEr": 0,
      "liquidationPriceEp": 130000,
      "maintMarginReqEr": 500000,
      "makerFeeRateEr": 0,
      "markPriceEp": 86732335,
      "orderCostEv": 0,
      "posCostEv": 1611,
      "positionMarginEv": 99924933,
      "positionStatus": "Normal",
      "riskLimitEv": 10000000000,
      "sellLeavesQty": 0,
      "sellLeavesValueEv": 0,
      "sellValueToCostEr": 1149250,
      "side": "Buy",
      "size": 13,
      "symbol": "BTCUSD",
      "takerFeeRateEr": 0,
      "term": 1,
      "transactTimeNs": 1573717286765896400,
      "unrealisedPnlEv": -192,
      "updatedAtNs": 0,
      "usedBalanceEv": 1803,
      "userID": 67534,
      "valueEv": 149694
    }
  ],
  "sequence": 1315725,
  "timestamp": 1573717286767188200,
  "type": "incremental"
}

Unsubscribe account-order-position (AOP)

Request format

{
  "id": <id>,
  "method": "aop.unsubscribe",
  "params": []
}

It unsubscribes all account-order-positions.

Subscribe 24 hours ticker

Reuqest sample

{
  "method": "market24h.subscribe",
  "params": [],
  "id": 0
}

24-Hours ticker message

Message format

{
  "market24h": {
    "open": <open priceEp>,
    "high": <high priceEp>,
    "low": <low priceEp>,
    "close": <close priceEp>,
    "indexPrice": <index priceEp>,
    "markPrice": <mark priceEp>,
    "openInterest": <open interest>,
    "fundingRate": <funding rateEr>,
    "predFundingRate": <predicated funding rateEr>,
    "symbol": "<symbol>",
    "turnover": <turnoverEv>,
    "volume": <volume>
  },
  "timestamp": <timestamp>
}

Message sample

{
  "market24h": {
    "close": 87425000,
    "fundingRate": 10000,
    "high": 92080000,
    "indexPrice": 87450676,
    "low": 87130000,
    "markPrice": 87453092,
    "open": 90710000,
    "openInterest": 7821141,
    "predFundingRate": 7609,
    "symbol": "BTCUSD",
    "timestamp": 1583646442444219017,
    "turnover": 1399362834123,
    "volume": 125287131
  },
  "timestamp": 1576490244024818000
}

On each successful subscription, DataGW will publish 24-hour ticker metrics for all symbols every 1 second.

Field Type Description Possible values
open priceEp Integer The scaled open price in last 24 hours
high priceEp Integer The scaled highest price in last 24 hours
low priceEp Integer The scaled lowest price in last 24 hours
close priceEp Integer The scaled close price in last 24 hours
index priceEp Integer Scaled index price
mark priceEp Integer Scaled mark price
open interest Integer current open interest
funding rateEr Integer Scaled funding rate
predicated funding rateEr Integer Scaled predicated funding rate
timestamp Integer Timestamp in nanoseconds
symbol String Contract symbol name
turnoverEv Integer The scaled turnover value in last 24 hours
volume Integer Symbol trade volume in last 24 hours

Subscribe price tick

Request sample: subscribe a single symbol.

{
  "method": "tick.subscribe",
  "params": [
    ".BTC"
  ],
  "id": 1580631267153
}

Tick message

Message format

{
  "tick": {
    "last": <priceEp>,
    "scale": <scale>,
    "symbol": <symbol>
    "timestamp": <timestamp_in_nano>
  }
}

Message sample

{
  "tick": {
    "last": 93385362,
    "scale": 4,
    "symbol": ".BTC",
    "timestamp": 1580635719408000000
  }
}
Field Type Description Possible values
priceEp Integer The scaled open price in last 24 hours
scale Integer The price scale factor, e.g. 4 denotes price scaled with factor 1e4. 4,6,8
symbol String Symbol

Spot REST API

Endpoint security type

Query product information

Request

GET /public/products

Price/Ratio/Value scales

Fields with post-fix "Ep", "Er" or "Ev" have been scaled based on symbol setting.

Common order fields

Order type Description
Limit --
Market --
Stop --
StopLimit --
MarketIfTouched --
LimitIfTouched --
MarketAsLimit --
StopAsLimit --
MarketIfTouchedAsLimit --
Order status Description
Untriggered Conditional order waiting to be triggered
Triggered Conditional order being triggered
Rejected Order rejected
New Order placed in cross engine
PartiallyFilled Order partially filled
Filled Order fully filled
Canceled Order canceled
TimeInForce Description
GoodTillCancel --
PostOnly --
ImmediateOrCancel --
FillOrKill --
Trigger Description
ByLastPrice Trigger by last price

Place order (HTTP PUT, prefered)

Request format

PUT /spot/orders/create?symbol=<symbol>&trigger=<trigger>&clOrdID=<clOrdID>&priceEp=<priceEp>&baseQtyEv=<baseQtyEv>&quoteQtyEv=<quoteQtyEv>&stopPxEp=<stopPxEp>&text=<text>&side=<side>&qtyType=<qtyType>&ordType=<ordType>&timeInForce=<timeInForce>&execInst=<execInst>

Response format

{
  "code": 0,
  "msg": "",
  "data": {
    "orderID": "d1d09454-cabc-4a23-89a7-59d43363f16d",
    "clOrdID": "309bcd5c-9f6e-4a68-b775-4494542eb5cb",
    "priceEp": 0,
    "action": "New",
    "trigger": "UNSPECIFIED",
    "pegPriceType": "UNSPECIFIED",
    "stopDirection": "UNSPECIFIED",
    "bizError": 0,
    "symbol": "sBTCUSDT",
    "side": "Buy",
    "baseQtyEv": 0,
    "ordType": "Limit",
    "timeInForce": "GoodTillCancel",
    "ordStatus": "Created",
    "cumFeeEv": 0,
    "cumBaseQtyEv": 0,
    "cumQuoteQtyEv": 0,
    "leavesBaseQtyEv": 0,
    "leavesQuoteQtyEv": 0,
    "avgPriceEp": 0,
    "cumBaseAmountEv": 0,
    "cumQuoteAmountEv": 0,
    "quoteQtyEv": 0,
    "qtyType": "ByBase",
    "stopPxEp": 0,
    "pegOffsetValueEp": 0
  }
}
Field Type Required Description Possible values
symbol String Yes
side Enum Yes Sell, Buy
qtyType Enum Yes Set order quantity by base or quote currency ByBase, ByQuote
quoteQtyEv Integer -- Required if qtyType = ByQuote
baseQtyEv Integer -- Required if qtyType = ByBase
priceEp Integer Scaled price
stopPxEp Integer -- used in conditionalorder
trigger Enum -- Required in conditional order ByLastPrice
timeInForce Enum No Default GoodTillCancel GoodTillCancel, PostOnly,ImmediateOrCancel,FillOrKill
ordType Enum No Default to Limit Market, Limit, Stop, StopLimit, MarketIfTouched, LimitIfTouched

Place order (HTTP POST)

Request format

POST /spot/orders
{
  "symbol": "sBTCUSDT",
  "clOrdID": "",
  "side": "Buy/Sell",
  "qtyType": "ByBase/ByQuote",
  "quoteQtyEv": 0,
  "baseQtyEv": 0,
  "priceEp": 0,
  "stopPxEp": 0,
  "trigger": "UNSPECIFIED",
  "ordType": "Limit",
  "timeInForce": "GoodTillCancel"
}

Amend order

Request format

PUT /spot/orders?symbol=<symbol>&orderID=<orderID>&origClOrdID=<origClOrdID>&clOrdID=<clOrdID>&priceEp=<priceEp>&baseQtyEV=<baseQtyEV>&quoteQtyEv=<quoteQtyEv>&stopPxEp=<stopPxEp> 

Cancel order

Request format

DELETE /spot/orders?symbol=<symbol>&orderID=<orderID>
DELETE /spot/orders?symbol=<symbol>&clOrdID=<clOrdID>

Cancel all order by symbol

Request format

DELETE /spot/orders/all?symbol=<symbol>&untriggered=<untriggered>
Field Type Required Description
symbol Enum Yes The symbol to cancel
untriggered Boolean No set false to cancel non-conditiaonal order, true to conditional order

Query open order by order ID or client order ID

Request format

GET /spot/orders/active?symbol=<symbol>&orderID=<orderID>
GET /spot/orders/active?symbol=<symbol>&clOrDID=<clOrdID>

Query all open orders by symbol

Request format

GET /spot/orders?symbol=<symbol>

Query wallets

Query spot wallet by currency.

Request format

GET /spot/wallets?currency=<currency>

Response format

{
  "code": 0,
  "msg": "",
  "data": [
    {
      "currency": "BTC",
      "balanceEv": 0,
      "lockedTradingBalanceEv": 0,
      "lockedWithdrawEv": 0,
      "lastUpdateTimeNs": 0
    }
  ]
}

Query orders by order ID or client order ID

Request format

GET /api-data/spots/orders/by-order-id?symbol=<symbol>&oderId=<orderID>&clOrdID=<clOrdID>
Field Type Required Description Possible Values
symbol String True the trade symbol to query sBTCUSDT ...
orderID String False Order id Either orderID or clOrdID is required.
clOrdID String False Client order id Refer to orderID

Response format

[
  {
    "avgPriceEp": 0,
    "avgTransactPriceEp": 0,
    "baseQtyEv": "string",
    "createTimeNs": 0,
    "cumBaseValueEv": 0,
    "cumFeeEv": 0,
    "cumQuoteValueEv": 0,
    "execStatus": "string",
    "feeCurrency": "string",
    "leavesBaseQtyEv": 0,
    "leavesQuoteQtyEv": 0,
    "ordStatus": "string",
    "ordType": "string",
    "orderID": "string",
    "priceEp": 0,
    "qtyType": "string",
    "quoteQtyEv": 0,
    "side": "string",
    "stopDirection": "string",
    "stopPxEp": 0,
    "symbol": "string",
    "timeInForce": "string"
  }
]

Query order history

Request format

GET /api-data/spots/orders?symbol=<symbol>

Response format

[
  {
    "avgPriceEp": 0,
    "avgTransactPriceEp": 0,
    "baseQtyEv": "string",
    "createTimeNs": 0,
    "cumBaseValueEv": 0,
    "cumFeeEv": 0,
    "cumQuoteValueEv": 0,
    "execStatus": "string",
    "feeCurrency": "string",
    "leavesBaseQtyEv": 0,
    "leavesQuoteQtyEv": 0,
    "ordStatus": "string",
    "ordType": "string",
    "orderID": "string",
    "priceEp": 0,
    "qtyType": "string",
    "quoteQtyEv": 0,
    "side": "string",
    "stopDirection": "string",
    "stopPxEp": 0,
    "symbol": "string",
    "timeInForce": "string"
  }
]
Field Type Required Description Possible Values
symbol String True The trade symbol to query sBTCUSDT ...
start Integer False Start time in millisecond Default to 2 days before the end time
end Integer False End time in millisecond Default to now
offset Integer False Page start from 0 Start from 0, default 0
limit Integer False Page size Default to 20, max 200

Query trade history

Request format

GET /api-data/spots/trades?symbol=<symbol>

Response format

[
  {
    "action": "string",
    "baseCurrency": "string",
    "baseQtyEv": 0,
    "clOrdID": "string",
    "execBaseQtyEv": 0,
    "execFeeEv": 0,
    "execId": "string",
    "execInst": "string",
    "execPriceEp": 0,
    "execQuoteQtyEv": 0,
    "execStatus": "string",
    "feeCurrency": "string",
    "feeRateEr": 0,
    "leavesBaseQtyEv": 0,
    "leavesQuoteQtyEv": 0,
    "ordStatus": "string",
    "ordType": "string",
    "orderID": "string",
    "priceEP": 0,
    "qtyType": "string",
    "quoteCurrency": "string",
    "quoteQtyEv": 0,
    "side": "string",
    "stopDirection": "string",
    "stopPxEp": 0,
    "symbol": "string",
    "timeInForce": "string",
    "tradeType": "string",
    "transactTimeNs": 0
  }
]
Field Type Required Description Possible Values
symbol String True The currency to query sBTCUSDT ...
start Integer False Start time in millisecond Default to 2 days before the end time
end Integer False End time in millisecond Default to now
offset Integer False Page start from 0 Start from 0, default 0
limit Integer False Page size Default 20, max 200

Query PnL

Request format

GET /api-data/spots/pnls

Response format

[
  {
    "collectTime": 0,
    "cumPnlEv": 0,
    "dailyPnlEv": 0,
    "userId": 0
  }
]
Field Type Required Description Possible Values
start Integer False Start time in millisecond Default to 2 days before the end time
end Integer False End time in millisecond Default to now

Query chain information

Request format

GET /exchange/public/cfg/chain-settings?currency=<currency>

Query deposit address by currency

Request format

GET /exchange/wallets/v2/depositAddress?currency=<currency>&chainName=<chainName>

Response format

{
  "address": "1Cdxxxxxxxxxxxxxx",
  "tag": null
}
Field Type Required Description Possible Values
currency String True the currency to query BTC,ETH, USDT ...
chainName String True the chain for this currency BTC, ETH, EOS

Query recent deposit history

Request format

GET /exchange/wallets/depositList?currency=<currency>&offset=<offset>&limit=<limit>

Response format

{
  "address": "1xxxxxxxxxxxxxxxxxx",
  "amountEv": 1000000,
  "confirmations": 1,
  "createdAt": 1574685871000,
  "currency": "BTC",
  "currencyCode": 1,
  "status": "Success",
  "txHash": "9e84xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "Deposit"
}
Field Type Required Description Possible Values
currency String True the currency to query BTC,ETH, ...

Query recent withdraw history

Request format

GET /exchange/wallets/withdrawList?currency=<currency>&offset=<offset>&limit=<limit>

Response format

{
  "address": "1Lxxxxxxxxxxx",
  "amountEv": 200000,
  "currency": "BTC",
  "currencyCode": 1,
  "expiredTime": 0,
  "feeEv": 50000,
  "rejectReason": null,
  "status": "Succeed",
  "txHash": "44exxxxxxxxxxxxxxxxxxxxxx",
  "withdrawStatus": ""
}
Field Type Required Description Possible Values
currency String True the currency to query BTC,ETH, ...

Query funds history

Request format

GET /api-data/spots/funds?currency=<currency>

Response format

[
  {
    "action": "string",
    "amountEv": 0,
    "balanceEv": 0,
    "bizCode": 0,
    "createTime": 0,
    "currency": "string",
    "execId": "string",
    "execSeq": 0,
    "feeEv": 0,
    "id": 0,
    "side": "string",
    "text": "string",
    "transactTimeNs": 0
  }
]
Field Type Required Description Possible Values
currency String True the currency to query BTC,ETH, USDT ...
start Integer False start time in millisecond default 2 days ago from the end
end Integer False end time in millisecond default now
offset Integer False page start from 0 start from 0, default 0
limit Integer False page size default 20, max 200

Query order book

Request format

GET /md/orderbook?symbol=<symbol>

Response format

{
  "error": null,
  "id": 0,
  "result": {
    "book": {
      "asks": [
        [
          <priceEp>,
          <size>
        ],
        ...
        ...
        ...
      ],
      "bids": [
        [
          <priceEp>,
          <size>
        ],
        ...
        ...
        ...
      ],
    ]
    },
    "depth": 30,
    "sequence": <sequence>,
    "timestamp": <timestamp>,
    "symbol": "<symbol>",
    "type": "snapshot"
  }
}
Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds
priceEp Integer Scaled book level price
size Integer Scaled book level size
sequence Integer current message sequence
symbol String Spot symbol name

Request sample

GET /md/orderbook?symbol=sBTCUSDT

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "book": {
      "asks": [
        [
          877050000000,
          1000000
        ],
        [
          877100000000,
          200000
        ]
      ],
      "bids": [
        [
          877000000000,
          2000000
        ],
        [
          876950000000,
          200000
        ]
      ]
    },
    "depth": 30,
    "sequence": 455476965,
    "timestamp": 1583555482434235628,
    "symbol": "sBTCUSDT",
    "type": "snapshot"
  }
}

Query full order book

Request format

GET /md/fullbook?symbol=<symbol>

Request sample

GET /md/orderbook?symbol=sBTCUSDT

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "book": {
      "asks": [
        [
          877050000000,
          1000000
        ],
        [
          877100000000,
          200000
        ]
      ],
      "bids": [
        [
          877000000000,
          2000000
        ],
        [
          876950000000,
          200000
        ]
      ]
    },
    "depth": 0,
    "sequence": 455476965,
    "timestamp": 1583555482434235628,
    "symbol": "sBTCUSDT",
    "type": "snapshot"
  }
}

Query recent trades

Request format

GET /md/trade?symbol=<symbol>

Response format

{
  "error": null,
  "id": 0,
  "result": {
    "type": "snapshot",
    "sequence": <sequence>,
    "symbol": "<symbol>",
    "trades": [
      [
        <timestamp>,
        "<side>",
        <priceEp>,
        <size>
      ],
      ...
      ...
      ...
    ]
  }
}

Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds
side String Trade side string Buy, Sell
priceEp Integer Scaled trade price
size Integer Scaled trade size
sequence Integer Current message sequence
symbol String Spot symbol name

Request sample

GET /md/trade?symbol=sBTCUSDT

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "sequence": 15934323,
    "symbol": "sBTCUSDT",
    "trades": [
      [
        1579164056368538508,
        "Sell",
        869600000000,
        1210000
      ],
      [
        1579164055036820552,
        "Sell",
        869600000000,
        580000
      ]
    ],
    "type": "snapshot"
  }
}

Query 24 hours ticker

Request format

GET /md/spot/ticker/24hr?symbol=<symbol>

Response format

{
  "error": null,
  "id": 0,
  "result": {
    "openEp": <open priceEp>,
    "highEp": <high priceEp>,
    "lowEp": <low priceEp>,
    "lastEp": <last priceEp>,
    "bidEp": <bid priceEp>,
    "askEp": <ask priceEp>,
    "symbol": "<symbol>",
    "turnoverEv": <turnoverEv>,
    "volumeEv": <volumeEv>,
    "timestamp": <timestamp>
  }
}
Field Type Description Possible values
open priceEp Integer The scaled open price in last 24 hours
high priceEp Integer The scaled highest price in last 24 hours
low priceEp Integer The scaled lowest price in last 24 hours
last priceEp Integer The scaled last price
bid priceEp Integer Scaled bid price
ask priceEp Integer Scaled ask price
timestamp Integer Timestamp in nanoseconds
symbol String symbol name Trading symbols
turnoverEv Integer The scaled turnover value in last 24 hours
volumeEv Integer The scaled trade volume in last 24 hours

Request sample

GET /md/spot/ticker/24hr?symbol=sBTCUSDT

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "askEp": 892100000000,
    "bidEp": 891835000000,
    "highEp": 898264000000,
    "lastEp": 892486000000,
    "lowEp": 870656000000,
    "openEp": 896261000000,
    "symbol": "sBTCUSDT",
    "timestamp": 1590571240030003249,
    "turnoverEv": 104718804814499,
    "volumeEv": 11841148100
  }
}

Spot Websocket API

Heartbeat

Request

{
  "id": 0,
  "method": "server.ping",
  "params": []
}

Response

{
  "error": null,
  "id": 0,
  "result": "pong"
}

User authentication

Request format

{
  "method": "user.auth",
  "params": [
    "API",
    "<token>",
    "<signature>",
    <expiry>
  ],
  "id": 0
}

Request sample

{
  "method": "user.auth",
  "params": [
    "API",
    "806066b0-f02b-4d3e-b444-76ec718e1023",
    "8c939f7a6e6716ab7c4240384e07c81840dacd371cdcf5051bb6b7084897470e",
    1570091232
  ],
  "id": 0
}

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "status": "success"
  }
}

Public channels like trade/orderbook/kline are published publicly without user authentication. While for private channels like account/position/order data, the client should send user.auth message to Data Gateway to authenticate the session.

Field Type Description Possible values
type String Token type API
token String API Key
signature String Signature generated by a funtion as HMacSha256(API Key + expiry) with API Secret
expiry Integer A future time after which request will be rejected, in epoch second. Maximum expiry is request time plus 2 minutes

Subscribe orderBook

Request format

{
  "id": <id>,
  "method": "orderbook.subscribe",
  "params": [
    "<symbol>"
  ]
}

Subscribe orderbook update messages with depth = 30 and interval = 20ms.

On each successful subscription, DataGW will immediately send the current Order Book (with default depth=30) snapshot to client and all later order book updates will be published.

Request sample:

{
  "id": 0,
  "method": "orderbook.subscribe",
  "params": [
    "sBTCUSDT"
  ]
}

Subscribe full orderBook

Request format

{
  "id": <id>,
  "method": "orderbook.subscribe",
  "params": [
    "<symbol>",
    true
  ]
}

Subscribe orderbook update messages with full depth and interval = 100ms.

On each successful subscription, DataGW will immediately send the current full Order Book snapshot to client and all later order book updates will be published.

Request sample:

{
  "id": 0,
  "method": "orderbook.subscribe",
  "params": [
    "sBTCUSDT",
    true
  ]
}

OrderBook message

Message format:

{
  "book": {
    "asks": [
      [
        <priceEp>,
        <qty>
      ],
      .
      .
      .
    ],
    "bids": [
      [
        <priceEp>,
        <qty>
      ],
      .
      .
      .
    ]
  },
  "depth": <depth>,
  "sequence": <sequence>,
  "timestamp": <timestamp>,
  "symbol": "<symbol>",

DataGW publishes order book message with types: incremental, snapshot. Snapshot messages are published with 60-second interval for client self-verification.

Field Type Description Possible values
side String Price level side bid, ask
priceEp Integer Scaled price
qty Integer Price level size. Non-zero qty indicates price level insertion or updation, and qty 0 indicates price level deletion.
sequence Integer Latest message sequence
depth Integer Market depth 30 by default, 0 denotes fullbook
type String Message type snapshot, incremental

Message sample: snapshot

{
  "book": {
    "asks": [
      [
        892697000000,
        1781800
      ],
      [
        892708000000,
        7543500
      ]
    ],
    "bids": [
      [
        892376000000,
        6866500
      ],
      [
        892354000000,
        14209000
      ]
    ]
  },
  "depth": 30,
  "sequence": 677996311,
  "symbol": "sBTCUSDT",
  "timestamp": 1590570810187571000,
  "type": "snapshot"
}

Message sample: incremental update

{
  "book": {
    "asks": [],
    "bids": [
      [
        892387000000,
        4792900
      ],
      [
        892226000000,
        0
      ]
    ]
  },
  "depth": 30,
  "sequence": 677996941,
  "symbol": "sBTCUSDT",
  "timestamp": 1590570811244189000,
  "type": "incremental"
}

Unsubscribe orderBook

Request sample

{
  "id": 0,
  "method": "orderbook.unsubscribe",
  "params": []
}

Response sample

{
  "error": null,
  "id": 0,
  "result": {
    "status": "success"
  }
}

It unsubscribes all orderbook related subscriptions.

Subscribe trade

Request format

{
  "id": <id>,
  "method": "trade.subscribe",
  "params": [
    "<symbol>"
  ]
}

On each successful subscription, DataGW will send the 200 history trades immediately for the subscribed symbol and all the later trades will be published.

Request sample

{
  "id": 0,
  "method": "trade.subscribe",
  "params": [
    "sBTCUSDT"
  ]
}

Trade message

Message format

{
  "trades": [
    [
      <timestamp>,
      "<side>",
      <priceEp>,
      <qty>
    ],
    .
    .
    .
  ],
  "sequence": <sequence>,
  "symbol": "<symbol>",
  "type": "<type>"
}

DataGW publishes trade message with types: incremental, snapshot. Incremental messages are published with 20ms interval. And snapshot messages are published on connection initial setup for client recovery.

Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds for each trade
side String Execution taker side bid, ask
priceEp Integer Scaled execution price
qty Integer Execution size
sequence Integer Latest message sequence
symbol String Spot symbol name
type String Message type snapshot, incremental

Message sample: snapshot

{
  "sequence": 1167852,
  "symbol": "sBTCUSDT",
  "trades": [
    [
      1573716998128563500,
      "Buy",
      867350000000,
      560000
    ],
    [
      1573716995033683000,
      "Buy",
      867350000000,
      520000
    ],
    [
      1573716991485286000,
      "Buy",
      867350000000,
      510000
    ],
    [
      1573716988636291300,
      "Buy",
      867350000000,
      120000
    ]
  ],
  "type": "snapshot"
}

Message sample: snapshot

{
  "sequence": 1188273,
  "symbol": "sBTCUSDT",
  "trades": [
    [
      1573717116484024300,
      "Buy",
      86730000000,
      210000
    ]
  ],
  "type": "incremental"
}

Unsubscribe trade

Request format: unsubscribe all trade subsciptions

{
  "id": <id>,
  "method": "trade.unsubscribe",
  "params": [
  ]
}

Request format: unsubscribe all trade subsciptions for a symbol

{
  "id": <id>,
  "method": "trade.unsubscribe",
  "params": [
    "<symbol>"
  ]
}

It unsubscribes all trade subscriptions or for a single symbol.

Subscribe kline

Request format

{
  "id": <id>,
  "method": "kline.subscribe",
  "params": [
    "<symbol>",
    "<interval>"
  ]
}

On each successful subscription, DataGW will send the 1000 history klines immediately for the subscribed symbol and all the later kline update will be published in real-time.

Request sample: subscribe 1-day kline

{
  "id": 0,
  "method": "kline.subscribe",
  "params": [
    "sBTCUSDT",
    86400
  ]
}

Kline message

Message format

{
  "kline": [
    [
      <timestamp>,
      "<interval>",
      <lastCloseEp>,
      <openEp>,
      <highEp>,
      <lowEp>,
      <closeEp>,
      <volumeEv>,
      <turnoverEv>,
    ],
    .
    .
    .
  ],
  "sequence": <sequence>,
  "symbol": "<symbol>",
  "type": "<type>"
}

Message sample: snapshot

{
  "kline": [
    [
      1590019200,
      86400,
      952057000000,
      952000000000,
      955587000000,
      947835000000,
      954446000000,
      1162621600,
      11095452729869
    ],
    [
      1589932800,
      86400,
      977566000000,
      978261000000,
      984257000000,
      935452000000,
      952057000000,
      11785486656,
      113659374080189
    ],
    [
      1589846400,
      86400,
      972343000000,
      972351000000,
      989607000000,
      949106000000,
      977566000000,
      11337554900,
      109928494593609
    ]
  ],
  "sequence": 380876982,
  "symbol": "sBTCUSDT",
  "type": "snapshot"
}

Message sample: snapshot

{
  "kline": [
    [
      1590019200,
      86400,
      952057000000,
      952000000000,
      955587000000,
      928440000000,
      941597000000,
      4231329700,
      40057408967508
    ]
  ],
  "sequence": 396865028,
  "symbol": "sBTCUSDT",
  "type": "incremental"
}

DataGW publishes kline message with types: incremental, snapshot. Incremental messages are published with 20ms interval. And snapshot messages are published on connection initial setup for client recovery.

Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds for each trade
interval Integer Kline interval type 60, 300, 900, 1800, 3600, 14400, 86400, 604800, 2592000, 7776000, 31104000
lastCloseEp Integer Scaled last close price
openEp Integer Scaled open price
highEp Integer Scaled high price
lowEp Integer Scaled low price
closeEp Integer Scaled close price
volumeEv Integer Scaled trade voulme during the current kline interval
turnoverEv Integer Scaled turnover value
sequence Integer Latest message sequence
symbol String Spot symbol name
type String Message type snapshot, incremental

Unsubscribe kline

Request format: unsubscribe all kline subscriptions

{
  "id": <id>,
  "method": "kline.unsubscribe",
  "params": []
}

Request format: unsubscribe all kline subscriptions of a symbol

{
  "id": <id>,
  "method": "kline.unsubscribe",
  "params": [
    "<symbol>"
  ]
}

It unsubscribes all kline subscriptions or for a single symbol.

Subscribe wallet-order

Request

{
  "id": 0,
  "method": "wo.subscribe",
  "params": []
}

WO subscription requires the session been authorized successfully. DataGW extracts the user information from the given token and sends WO messages back to client accordingly. 0 or more latest WO snapshot messages will be sent to client immediately on subscription, and incremental messages will be sent for later updates. Each account snapshot contains a users' wallets and open / max 100 closed / max 100 filled order event message history.

Wallet-Order message

Message format

{
  "wallets": [{"userID":60463,...}, ...],
  "orders": [{"userID":60463, ...}],
  "sequence": <sequence>,
  "timestamp": <timestamp>,
  "type": "<type>"
}
Field Type Description Possible values
timestamp Integer Transaction timestamp in nanoseconds
sequence Integer Latest message sequence
type String Message type snapshot, incremental

Message sample: snapshot

{
  "orders": {
    "closed": [
      {
        "action": "New",
        "avgPriceEp": 0,
        "baseCurrency": "BTC",
        "baseQtyEv": 10000,
        "bizError": 0,
        "clOrdID": "123456",
        "createTimeNs": 1587463924959744800,
        "cumBaseQtyEv": 10000,
        "cumFeeEv": 0,
        "cumQuoteQtyEv": 66900000,
        "curBaseWalletQtyEv": 899990000,
        "curQuoteWalletQtyEv": 66900000,
        "cxlRejReason": 0,
        "feeCurrency": "BTC",
        "leavesBaseQtyEv": 0,
        "leavesQuoteQtyEv": 0,
        "ordStatus": "Filled",
        "ordType": "Limit",
        "orderID": "35217ade-3c6b-48c7-a280-8a1edb88013e",
        "pegOffsetValueEp": 0,
        "priceEp": 68000000,
        "qtyType": "ByBase",
        "quoteCurrency": "USDT",
        "quoteQtyEv": 66900000,
        "side": "Sell",
        "stopPxEp": 0,
        "symbol": "sBTCUSDT",
        "timeInForce": "GoodTillCancel",
        "transactTimeNs": 1587463924964876800,
        "triggerTimeNs": 0,
        "userID": 200076
      }
    ],
    "fills": [
      {
        "avgPriceEp": 0,
        "baseCurrency": "BTC",
        "baseQtyEv": 10000,
        "clOrdID": "123456",
        "execBaseQtyEv": 10000,
        "execFeeEv": 0,
        "execID": "8135ebe3-f767-577b-b70d-1a839d5178e0",
        "execPriceEp": 669000000000,
        "execQuoteQtyEv": 66900000,
        "feeCurrency": "BTC",
        "lastLiquidityInd": "RemovedLiquidity",
        "ordType": "Limit",
        "orderID": "35217ade-3c6b-48c7-a280-8a1edb88013e",
        "priceEp": 68000000,
        "qtyType": "ByBase",
        "quoteCurrency": "USDT",
        "quoteQtyEv": 66900000,
        "side": "Sell",
        "symbol": "sBTCUSDT",
        "transactTimeNs": 1587463924964876800,
        "userID": 200076
      }
    ],
    "open": [
      {
        "action": "New",
        "avgPriceEp": 0,
        "baseCurrency": "BTC",
        "baseQtyEv": 100000000,
        "bizError": 0,
        "clOrdID": "31f793f4-163d-aa3f-5994-0e1164719ba2",
        "createTimeNs": 1587547657438536000,
        "cumBaseQtyEv": 0,
        "cumFeeEv": 0,
        "cumQuoteQtyEv": 0,
        "curBaseWalletQtyEv": 630000005401500000,
        "curQuoteWalletQtyEv": 351802500000,
        "cxlRejReason": 0,
        "feeCurrency": "BTC",
        "leavesBaseQtyEv": 100000000,
        "leavesQuoteQtyEv": 0,
        "ordStatus": "New",
        "ordType": "Limit",
        "orderID": "b98b25c5-6aa4-4158-b9e5-477e37bd46d8",
        "pegOffsetValueEp": 0,
        "priceEp": 666500000000,
        "qtyType": "ByBase",
        "quoteCurrency": "USDT",
        "quoteQtyEv": 0,
        "side": "Sell",
        "stopPxEp": 0,
        "symbol": "sBTCUSDT",
        "timeInForce": "GoodTillCancel",
        "transactTimeNs": 1587547657442753000,
        "triggerTimeNs": 0,
        "userID": 200076
      }
    ]
  },
  "sequence": 349,
  "timestamp": 1587549121318737700,
  "type": "snapshot",
  "wallets": [
    {
      "balanceEv": 0,
      "currency": "LTC",
      "lastUpdateTimeNs": 1587481897840503600,
      "lockedTradingBalanceEv": 0,
      "lockedWithdrawEv": 0,
      "userID": 200076
    },
    {
      "balanceEv": 351802500000,
      "currency": "USDT",
      "lastUpdateTimeNs": 1587543489127498200,
      "lockedTradingBalanceEv": 0,
      "lockedWithdrawEv": 0,
      "userID": 200076
    },
    {
      "balanceEv": 630000005401500000,
      "currency": "BTC",
      "lastUpdateTimeNs": 1587547210089640400,
      "lockedTradingBalanceEv": 100000000,
      "lockedWithdrawEv": 0,
      "userID": 200076
    }
  ]
}

Message sample: incremental

{
  "orders": {
    "closed": [],
    "fills": [],
    "open": [
      {
        "action": "New",
        "avgPriceEp": 0,
        "baseCurrency": "BTC",
        "baseQtyEv": 100000000,
        "bizError": 0,
        "clOrdID": "0c1099e5-b900-5351-cf60-edb15ea2539c",
        "createTimeNs": 1587549529513521700,
        "cumBaseQtyEv": 0,
        "cumFeeEv": 0,
        "cumQuoteQtyEv": 0,
        "curBaseWalletQtyEv": 630000005401500000,
        "curQuoteWalletQtyEv": 351802500000,
        "cxlRejReason": 0,
        "feeCurrency": "BTC",
        "leavesBaseQtyEv": 100000000,
        "leavesQuoteQtyEv": 0,
        "ordStatus": "New",
        "ordType": "Limit",
        "orderID": "494a6cbb-32b3-4d6a-b9b7-196ea2506fb5",
        "pegOffsetValueEp": 0,
        "priceEp": 666500000000,
        "qtyType": "ByBase",
        "quoteCurrency": "USDT",
        "quoteQtyEv": 0,
        "side": "Sell",
        "stopPxEp": 0,
        "symbol": "sBTCUSDT",
        "timeInForce": "GoodTillCancel",
        "transactTimeNs": 1587549529518394000,
        "triggerTimeNs": 0,
        "userID": 200076
      }
    ]
  },
  "sequence": 350,
  "timestamp": 1587549529519959300,
  "type": "incremental",
  "wallets": [
    {
      "balanceEv": 630000005401500000,
      "currency": "BTC",
      "lastUpdateTimeNs": 1587547210089640400,
      "lockedTradingBalanceEv": 200000000,
      "lockedWithdrawEv": 0,
      "userID": 200076
    },
    {
      "balanceEv": 351802500000,
      "currency": "USDT",
      "lastUpdateTimeNs": 1587543489127498200,
      "lockedTradingBalanceEv": 0,
      "lockedWithdrawEv": 0,
      "userID": 200076
    }
  ]
}

Unsubscribe wallet-order

Request

{
  "id": 0,
  "method": "wo.unsubscribe",
  "params": []
}

Subscribe spot 24-hours ticker

Reuqest sample

{
  "method": "spot_market24h.subscribe",
  "params": [],
  "id": 0
}

Spot 24-hours ticker message

Message format

{
  "spot_market24h": {
    "openEp": <open priceEp>,
    "highEp": <high priceEp>,
    "lowEp": <low priceEp>,
    "lastEp": <last priceEp>,
    "bidEp": <bid priceEp>,
    "askEp": <ask priceEp>,
    "symbol": "<symbol>",
    "turnoverEv": <turnoverEv>,
    "volumeEv": <volumeEv>
  },
  "timestamp": <timestamp>
}

Message sample

{
  "spot_market24h": {
    "askEp": 892100000000,
    "bidEp": 891835000000,
    "highEp": 898264000000,
    "lastEp": 892486000000,
    "lowEp": 870656000000,
    "openEp": 896261000000,
    "symbol": "sBTCUSDT",
    "timestamp": 1590571240030003249,
    "turnoverEv": 104718804814499,
    "volumeEv": 11841148100
  },
  "timestamp": 1576490244024818000
}

On each successful subscription, DataGW will publish 24-hour ticker metrics for all symbols every 1 second.

Field Type Description Possible values
open priceEp Integer The scaled open price in last 24 hours
high priceEp Integer The scaled highest price in last 24 hours
low priceEp Integer The scaled lowest price in last 24 hours
last priceEp Integer The scaled last price
bid priceEp Integer Scaled bid price
ask priceEp Integer Scaled ask price
timestamp Integer Timestamp in nanoseconds
symbol String Spot Symbol name
turnoverEv Integer The scaled turnover value in last 24 hours
volumeEv Integer The scaled trade volume in last 24 hours

Subscribe investment account

Request sample

{
  "id": 0,
  "method": "wm.subscribe",
  "params": []
}

On subscription to investment account then you will get your investment information of each currency type.

Investment account message

Message format

{
  "investments":[
    {
      "currency": <currency>,
      "balanceEv": <balanceEv>,
      "userId": <userId>,
      "demandPendingInterestBalanceEv": <demandPendingInterestBalanceEv>,
      "demandInterestedBalanceEv": <demandInterestedBalanceEv>,
      "timedDepositBalanceEv": <timedDepositBalanceEv>,
      "currentTimeMillis": <currentTimeMillis>
  ]
}

Message sample

{
  "investments":[
    {
      "currency":"USDT",
      "balanceEv":21797700000,
      "userId":1234,
      "demandPendingInterestBalanceEv":0,
      "demandInterestedBalanceEv":0,
      "timedDepositBalanceEv":20000000000,
      "currentTimeMillis":1653972360161
    },
    {
      "currency":"BTC",
      "balanceEv":0,
      "userId":1234,
      "demandPendingInterestBalanceEv":0,
      "demandInterestedBalanceEv":0,
      "timedDepositBalanceEv":0,
      "currentTimeMillis":1653972360166
    }
  ]
}
Field Type Description Possible values
currency String Invested currency BTC,ETH
balanceEv Integer Invested amount 0
userId Integer User id
demandPendingInterestBalanceEv Integer Pending interest for flexible product 0
demandInterestedBalanceEv Integer Paid interest for flexible product 0
timedDepositBalanceEv Integer Amount for fixed product 20000000000
currentTimeMillis Integer Time in milliseconds 165397230166

Transfer REST API

Transfer between spot and futures

Request format

POST /assets/transfer
{
  "amountEv": 0,
  "currency": "string",
  "moveOp": 0
}

Response format

{
  "amountEv": 0,
  "currency": "string",
  "linkKey": "string",
  "side": 0,
  "status": 0,
  "userId": 0
}
Field Type Required Description Possible Values
amountEv Long True AmountEv to transfer 100000 ...
moveOp Integer True Direction 1 - futures to spot, 2 - spot to futures
currency String True Currency to transfer BTC, ETH, USD ...

Query transfer history

Request format

GET /assets/transfer?currency=<currency>

Response format

[
  {
    "amountEv": 0,
    "bizType": 0,
    "createTime": 0,
    "currency": "string",
    "linkKey": "string",
    "side": 0,
    "status": 0,
    "userId": 0
  }
]
Field Type Required Description Possible Values
currency String True The currency to query BTC,ETH ...
start Long False Start time in millisecond Default to 2 days ago from the end
end Long False End time in millisecond Default to now
offset Integer False Page start from 0 Start from 0, default 0
limit Integer False Page size Default to 20, max 200

Spot sub to main transfer (for sub-account only)

Request format

POST /assets/spots/sub-accounts/transfer
{
  "amountEv": 0,
  "currency": "string",
  "requestKey": "string"
}

Response format

{
  "amountEv": 0,
  "currency": "string",
  "fromUserId": 0,
  "requestKey": "string",
  "toUserId": 0
}
Field Type Required Description Possible Values
amountEv Long True AmountEv to transfer 100000 ...
currency String True Currency to transfer BTC, ETH, USD ...
requestKey String False Unique request key Unique request Key, system will generate if its empty

Query spot sub to main transfer

Request format

GET /assets/spots/sub-accounts/transfer?currency=<currency>

Response format

[
  {
    "amountEv": 0,
    "createAt": 0,
    "currency": "string",
    "fromUserId": 0,
    "id": 0,
    "requestKey": "string",
    "status": 0,
    "toUserId": 0
  }
]
Field Type Required Description Possible Values
currency String True The currency to query BTC,ETH ...
start Long False Start time in millisecond Default to 2 days ago from the end
end Long False End time in millisecond Default to now
offset Integer False Page start from 0 Start from 0, default 0
limit Integer False Page size Default to 20, max 200

Futures sub to main transfer (for sub-account only)

Request format

POST /assets/futures/sub-accounts/transfer
{
  "amountEv": 0,
  "currency": "string",
  "requestKey": "string"
}

Response format

{
  "amountEv": 0,
  "bizCode": 0,
  "currency": "string",
  "fromUserId": 0,
  "requestKey": "string",
  "toUserId": 0
}
Field Type Required Description Possible Values
amountEv Long True AmountEv to transfer 100000 ...
currency String True Currency to transfer BTC, ETH, USD ...
requestKey String False Unique request key Unique request Key, system will generate if its empty

Query futures sub to main transfer

Request format

GET /assets/futures/sub-accounts/transfer?currency=<currency>

Response format

[
  {
    "fromUserId": 0,
    "toUserId": 0,
    "currency": "string",
    "amountEv": 0,
    "bizCode": 0,
    "requestKey": "string",
    "createAt": 0
  }
]
Field Type Required Description Possible Values
currency String True The currency to query BTC,ETH ...
start Long False Start time in millisecond Default to 2 days ago from the end
end Long False End time in millisecond Default to now
offset Integer False Page start from 0 Start from 0, default 0
limit Integer False Page size Default to 20, max 200

Universal transfer (main account only) - transfer between sub to main, main to sub or sub to sub

Request format

POST /assets/universal-transfer
{
  "amountEv": 0,
  "bizType": "string",
  "currency": "string",
  "fromUserId": 0,
  "toUserId": 0
}

Response format

{
  "requestKey"
}
Field Type Required Description Possible Values
fromUserId Long True From user id Will set as main account if not given or 0
toUserId Long True To user id Will set as main account if not given or 0
currency String True The currency to query BTC,ETH ...
amountEv Long True AmountEv to transfer 100000 ...
bizType String True Transfer for which biz type SPOT, PERPETUAL
requestKey String False Unique request key Unique request Key, system will generate if its empty

Convert REST API

RFQ quote

Request format

GET /assets/quote

Response format

{
  "code": "string",
  "quoteArgs": {
    "expireAt": 0,
    "origin": 0,
    "price": "string",
    "proceeds": "string",
    "quoteAt": 0,
    "requestAt": 0,
    "ttlMs": 0
  }
}
Field Type Required Description Possible Values
fromCurrency String True From currency BTC,USD ...
toCurrency String True To currency BTC,USD ...
fromAmountEv Long True AmountEv to transfer 100000 ...

Convert

Request format

POST /assets/convert
{
  "code": "string",
  "fromAmountEv": 0,
  "fromCurrency": "string",
  "toCurrency": "string"
}

Response format

{
  "fromAmountEv": 0,
  "fromCurrency": "string",
  "linkKey": "string",
  "moveOp": 0,
  "status": 0,
  "toAmountEv": 0,
  "toCurrency": "string"
}
Field Type Required Description Possible Values
toCurrency String True To currency BTC,USD ...
fromCurrency String True From currency BTC,USD ...
fromAmountEv Long False AmountEv to convert 100000 ...
code String True Encrypted convert args xxxxxxxx ...

Query convert history

Request format

GET /assets/convert

Response format

[
  {
    "conversionRate": 0,
    "createTime": 0,
    "errorCode": 0,
    "fromAmountEv": 0,
    "fromCurrency": "string",
    "linkKey": "string",
    "status": 0,
    "toAmountEv": 0,
    "toCurrency": "string"
  }
]
Field Type Required Description Possible Values
fromCurrency String False From currency BTC,USD ...
toCurrency String False To currency BTC,USD ...
startTime Long False Start time in millisecond Default to 2 days ago from the end time
endTime Long False End time in millisecond Default to now
offset Integer False Page start from 0 Start from 0, default 0
limit Integer False Page size Default to 20, max 200