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:

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

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

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

New Contract API RateLimit Rules (for VAPI/VIP only)

Header name Description
x-ratelimit-remaining-groupName_symbol Remaining request ratelimit in the symbol group in this minute
x-ratelimit-capacity-groupName_symbol Total request capacity in the symbol group
x-ratelimit-retry-after-groupName_symbol Reset timeout in seconds for current ratelimited user in the symbol group
Group Name Capacity
Contract 5000/minute
Contract_SYMBOL 500/minute
CONTACT_ALL_SYM 500/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 unrealized PNL
/g-orders POST 1 Place new order
/g-orders/replace PUT 1 Amend order
/g-orders/cancel DELETE 1 Cancel order
/g-orders/all DELETE 3 Cancel All Orders
/g-orders DELETE 1 Bulk Cancel Orders
/g-orders/activeList GET 1 Query open orders by symbol
/g-orders/active GET 1 Query open order by orderID
/g-orders/create PUT 1 Place order
/g-accounts/accountPositions GET 1 Query Account Positions
/g-accounts/positions GET 25 Query Account Positions with unrealized PNL
/g-positions/assign POST 1 Assign Position Balance
/g-positions/leverage PUT 1 Set Leverage
/g-positions/riskLimit PUT 1 Set RiskLimit
/g-positions/switch-pos-mode-sync PUT 1 /g-positions/switch-pos-mode-sync
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

Java Sample Client

Python Sample Client

NodeJS Sample Client

C++ Market Data Sample Client

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

Query product information

Request

GET /public/products

Request/Response field explanation

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 server time

Request

GET /public/time

Response sample

{
    "code": 0,
    "msg": "",
    "data": {
        "serverTime": 1676172826345
    }
}

Common order fields

Order Type Description
Limit --
Market --
Stop --
StopLimit --
MarketIfTouched --
LimitIfTouched --
Order Status Description
Created order acked from order request, a transient state
Init Same as Created, order acked from order request, a transient state
Untriggered Conditional order waiting to be triggered
Triggered Conditional order being triggered
Deactivated untriggered conditonal order being removed
Rejected Order rejected
New Order placed into orderbook
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
tradeType Description
Trade --
Funding --
LiqTrade --
AdlTrade --
execStatus Description
Aborted --
MakerFill --
TakerFill --
Expired --
Canceled --
CreateRejected --
Trigger Description
OneWay can only hold one side position
Hedged can hold both side position
Trigger Description
Long Long position when pos mode is 'Hedged'
Short Short position when pos mode is 'Hedged'
Merged Merged position when pos mode is 'OneWay'
Description Code
REALIZED_PNL 1
TRANSFER 2
COMMISSION 3
BONUS 4
SUB_TO_PARENT_TRANSFER 5
PARENT_TO_SUB_TRANSFER 6
COPY_TRADE_TRANSFER 90
COPY_TRADE_SETTLEMENT 91
COPY_TRADE_REFUNDS 92
COPY_TRADE_PROFIT_SHARE 93
MARGIN_TRANSFER 213

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>&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 No Order ID, cannot be changed
origClOrdID No Original clOrderID
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

NOTE:
1) orderID and origClOrdID cannot both be empty.

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 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 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 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 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 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 /md/v1/ticker/24hr?symbol=<symbol>

the old url , v1/md/ticker/24hr?symbol= , will be removed later, which have the same response format as above url.

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 /md/v1/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 24 hours ticker for all symbols

you can use path below to get data for all symbols, which has reponse data with array list

  GET /md/v1/ticker/24hr/all

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

Query funding rate history

Request format

GET /api-data/public/data/funding-rate-history?symbol=<symbol>&start=<start>&end=<end>&limit=<limit>

Response sample

{
  "code": 0,
  "msg": "OK",
  "data": {
    "rows": [
      {
        "symbol": ".BTCFR8H",
        "fundingRate": "0.00007058",
        "fundingTime": 1680796800000,
        "intervalSeconds": 28800
      },
      {
        "symbol": ".BTCFR8H",
        "fundingRate": "0.00006672",
        "fundingTime": 1680825600000,
        "intervalSeconds": 28800
      }
    ]
  }
}
Field Type Required Description Possible Values
symbol String True funding rate symbol .BTCFR8H
start Long False start timestamp in ms of funding time (INCLUSIVE) 1679852520918
end Long False end timestamp in ms of funding time (INCLUSIVE) 1679852520918
limit Integer False default 100, max 100 100

Query funding fee history

Request format

GET /api-data/futures/funding-fees?symbol=<symbol>
Parameter Type Required Description Case
symbol String True the currency to query uBTCUSDT...
offset Integer False page starts from 0 default 0
limit Integer False page size default 20, max 200

Response sample

[
  {
    "createTime": 0,
    "currency": "string",
    "execFeeEv": 0,
    "execPriceEp": 0,
    "execQty": 0,
    "execValueEv": 0,
    "feeRateEr": 0,
    "fundingRateEr": 0,
    "side": "string",
    "symbol": "string"
  }
]

Query contract fee rate

Request format

GET /api-data/futures/fee-rate?settleCurrency=<settleCurrency>
Parameter Type Required Description Case
settleCurrency String True the settle currency to query USDT,USD,BTC,ETH, ...

NOTE: *RateEr (ratio scale) in response field are const 8

Response sample

{
  "symbolFeeRates": [
    {
      "takerFeeRateEr": 55000,
      "makerFeeRateEr": 6000,
      "symbol": "cETHUSD"
    }
  ]
}

Query Funds Detail

Request format

GET /api-data/futures/v2/tradeAccountDetail?currency=<currecny>&type=<type>&limit=<limit>&offset=<offset>&start=<start>&end=<end>&withCount=<withCount>
Parameter Type Required Description Case
currency String False the currency to query USDT,USD,BTC,ETH, ...
type Integer False Funds Biz Type REALIZED_PNL(1),TRANSFER(2), ...
start Integer False start time range, Epoch millis default 0
end Integer False end time range, Epoch millis default 0
offset Integer False offset to resultset, max 1000 default 0
limit Integer False limit of resultset default 20
withCount Integer False result with total count default false

Response sample

[
  {
    "typeDesc": "REALIZED_PNL",
    "amountRv": "-0.01010945",
    "balanceRv": "1464.64081733",
    "createTime": 1682035200000,
    "currency": "USDT"
  }
]

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


{
  "index_market24h": {
    "highEp": 10009,
    "lastEp": 10007,
    "lowEp": 10004, 
    "openEp": 10004,
    "symbol": ".USDT"
  },
  "timestamp": 1681496204104375396
}
{
  "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

Hedged Contract Rest API

Query product information

Request

GET /public/products

Place order (HTTP PUT, prefered)

Request format

PUT /g-orders/create?clOrdID=<clOrdID>&symbol=<symbol>&reduceOnly=<reduceOnly>&closeOnTrigger=<closeOnTrigger>&orderQtyRq=<orderQtyRq>&ordType=<ordType>&priceRp=<priceRp>&side=<side>&posSide=<posSide>&text=<text>&timeInForce=<timeInForce>&stopPxRp=<stopPxRp>&takeProfitRp=<takeProfitRp>&stopLossRp=<stopLossRp>&pegOffsetValueRp=<pegOffsetValueRp>&pegPriceType=<pegPriceType>&triggerType=<triggerType>&tpTrigger=<tpTrigger>&tpSlTs=<tpSlTs>&slTrigger=<slTrigger>

Response sample

{
  "code": 0,
  "data": {
    "actionTimeNs": 1580547265848034600,
    "bizError": 0,
    "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f",
    "closedPnlRv": "1271.9",
    "closedSizeRq": "0.01",
    "cumQtyRq": "0.01",
    "cumValueRv": "1271.9",
    "displayQtyRq": "0.01",
    "execInst": "ReduceOnly",
    "execStatus": "Init",
    "leavesQtyRq": "0.01",
    "leavesValueRv": "1271.9",
    "ordStatus": "Init",
    "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf",
    "orderQtyRq": "0.01",
    "orderType": "Limit",
    "pegOffsetValueRp": "1271.9",
    "pegPriceType": "LastPeg",
    "priceRp": "98970000",
    "reduceOnly": true,
    "side": "Sell",
    "stopDirection": "Rising",
    "stopPxRp": "1271.9",
    "symbol": "BTCUSDT",
    "timeInForce": "GoodTillCancel",
    "transactTimeNs": 0,
    "trigger": "ByMarkPrice"
  },
  "msg": "string"
}
Field Type Required Description Possible values
clOrdID String - client order id, max length is 40
symbol String Yes Which symbol to place order Trading symbols
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
orderQtyRq String - Order real quantity "1"
ordType String - Order type, default to Limit Market,Limit,Stop,StopLimit,MarketIfTouched,LimitIfTouched,
ProtectedMarket,MarketAsLimit,StopAsLimit,
MarketIfTouchedAsLimit,Bracket,BoTpLimit,BoSlLimit,BoSlMarket
priceRp String - Real price, required for limit order "1"
side String Yes Order direction, Buy or Sell Buy, Sell
posSide String Yes Position direction "Merged" for oneway mode ,
"Long" / "Short" for hedge mode
text String - Order comments
timeInForce String - Time in force. default to GoodTillCancel GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly
stopPxRp String - Trigger price of conditional order "1"
takeProfitRp String - trigger price of take-profit order attached to position opening "1"
tpPxRp String - limit price of take-profit order attached to position opening "1"
stopLossRp String - trigger price of stop-loss order attached to position opening "1"
slPxRp String - limit price of stop-loss order attached to position opening "1"
pegOffsetValueRp String - Trailing offset from current price. Negative value when position is long, positive when position is short "1"
pegPriceType String - Trailing order price type LastPeg, MidPricePeg, MarketPeg, PrimaryPeg, TrailingStopPeg, TrailingTakeProfitPeg
triggerType String - Trigger source ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit
tpTrigger String - Trigger source ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit
slTrigger String - Trigger source ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit

Place order (HTTP POST)

Request fields are the same as above place-order

Request format

POST /g-orders

body: json { "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f", "closeOnTrigger": true, "displayQtyRq": "0.01", "ordType": "Limit", "orderQtyRq": "0.01", "pegOffsetValueRp": "1271.9", "pegPriceType": "LastPeg", "posSide": "Long", "priceRp": "1271.9", "reduceOnly": true, "side": "Buy", "slTrigger": "ByMarkPrice", "stopLossRp": "1271.9", "stopPxRp": "1271.9", "symbol": "BTCUSDT", "takeProfitRp": "1271.9", "text": "string", "timeInForce": "GoodTillCancel", "tpTrigger": "ByMarkPrice", "triggerType": "ByMarkPrice" }

Response sample

{
  "code": 0,
  "data": {
    "actionTimeNs": 1580547265848034600,
    "bizError": 0,
    "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f",
    "closedPnlRv": "1271.9",
    "closedSizeRq": "0.01",
    "cumQtyRq": "0.01",
    "cumValueRv": "1271.9",
    "displayQtyRq": "0.01",
    "execInst": "ReduceOnly",
    "execStatus": "Init",
    "leavesQtyRq": "0.01",
    "leavesValueRv": "1271.9",
    "ordStatus": "Init",
    "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf",
    "orderQtyRq": "0.01",
    "orderType": "Limit",
    "pegOffsetValueRp": "1271.9",
    "pegPriceType": "LastPeg",
    "priceRq": "98970000",
    "reduceOnly": true,
    "side": "Sell",
    "stopDirection": "Rising",
    "stopPxRp": "1271.9",
    "symbol": "BTCUSDT",
    "timeInForce": "GoodTillCancel",
    "transactTimeNs": 0,
    "trigger": "ByMarkPrice"
  },
  "msg": "string"
}
Field Type Required Description Possible values
clOrdID String - client order id, max length is 40
symbol String Yes Which symbol to place order Trading symbols
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
orderQtyRq String - Order real quantity "1"
ordType String - Order type, default to Limit Market,Limit,Stop,StopLimit,MarketIfTouched,LimitIfTouched,
ProtectedMarket,MarketAsLimit,StopAsLimit,
MarketIfTouchedAsLimit,Bracket,BoTpLimit,BoSlLimit,BoSlMarket
priceRp String - Real price, required for limit order "1"
side String Yes Order direction, Buy or Sell Buy, Sell
posSide String Yes Position direction "Merged" for oneway mode ,
"Long" / "Short" for hedge mode
text String - Order comments
timeInForce String - Time in force. default to GoodTillCancel GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly
stopPxRp String - Trigger price of conditional order "1"
takeProfitRp String - trigger price of take-profit order attached to position opening "1"
tpPxRp String - limit price of take-profit order attached to position opening "1"
stopLossRp String - trigger price of stop-loss order attached to position opening "1"
slPxRp String - limit price of stop-loss order attached to position opening "1"
pegOffsetValueRp String - Trailing offset from current price. Negative value when position is long, positive when position is short "1"
pegPriceType String - Trailing order price type LastPeg, MidPricePeg, MarketPeg, PrimaryPeg, TrailingStopPeg, TrailingTakeProfitPeg
triggerType String - Trigger source ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit
tpTrigger String - Trigger source ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit
slTrigger String - Trigger source ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit

Amend order by orderID

Request format

PUT /g-orders/replace?symbol=<symbol>&orderID=<orderID>&origClOrdID=<origClOrdID>&price=<price>&priceRp=<priceRp>&orderQtyRq=<orderQtyRq>&stopPxRp=<stopPxRp>&takeProfitRp=<takeProfitRp>&stopLossRp=<stopLossRp>&pegOffsetValueRp=<pegOffsetValueRp>&pegPriceType=<pegPriceType>&triggerType=<triggerType>&posSide=<posSide>

Response sample

{
  "code": 0,
  "data": {
    "actionTimeNs": 0,
    "bizError": 0,
    "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f",
    "closedPnlRv": "1271.9",
    "closedSizeRq": "0.01",
    "cumQtyRq": "0.01",
    "cumValueRv": "1271.9",
    "displayQtyRq": "0.01",
    "execInst": "ReduceOnly",
    "execStatus": "Init",
    "leavesQtyRq": "0.01",
    "leavesValueRv": "1271.9",
    "ordStatus": "Init",
    "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf",
    "orderQtyRq": "0.01",
    "orderType": "Limit",
    "pegOffsetValueRp": "1271.9",
    "pegPriceType": "LastPeg",
    "priceRp": "1271.9",
    "reduceOnly": true,
    "side": "Sell",
    "stopDirection": "Rising",
    "stopPxRp": "1271.9",
    "symbol": "BTCUSDT",
    "timeInForce": "GoodTillCancel",
    "transactTimeNs": 0,
    "trigger": "ByMarkPrice",
    "takeProfitRp":"1271.9",
    "stopLossRp":"1271.9"
  },
  "msg": "string"
}
Field Required Description
symbol Yes order symbol, cannot be changed
orderID - order id, cannot be changed
origClOrdID - original clOrderID, cannot be changed
priceRp - new order price, real value
orderQtyRq - new orderQty, real value
stopPxRp - new stop price, real value
takeProfitRp - new stop profit price, real value
stopLossRp - new stop loss price, real value
pegOffsetValueRp - new trailing offset, real value
pegPriceType - new peg price type
triggerType - new triggerType
posSide Yes posSide to check, can not be changed

NOTE:
1) orderID and origClOrdID cannot both be empty.

Cancel Single Order by orderID

Request format

DELETE /g-orders/cancel?orderID=<orderID>&posSide=<posSide>&symbol=<symbol>

Response sample

{
  "code": 0,
  "data": {
    "actionTimeNs": 450000000,
    "bizError": 0,
    "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f",
    "closedPnlRv": "1271.9",
    "closedSizeRq": "0.01",
    "cumQtyRq": "0.01",
    "cumValueRv": "1271.9",
    "displayQtyRq": "0.01",
    "execInst": "ReduceOnly",
    "execStatus": "Init",
    "leavesQtyRq": "0.01",
    "leavesValueRv": "0.01",
    "ordStatus": "Init",
    "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf",
    "orderQtyRq": "0.01",
    "orderType": "Limit",
    "pegOffsetValueRp": "1271.9",
    "pegPriceType": "LastPeg",
    "priceRq": "0.01",
    "reduceOnly": true,
    "side": "Sell",
    "stopDirection": "Rising",
    "stopPxRp": "0.01",
    "symbol": "BTCUSDT",
    "timeInForce": "GoodTillCancel",
    "transactTimeNs": 450000000,
    "trigger": "ByMarkPrice"
  },
  "msg": "string"
}
Field Type Required Description
orderID String No order id, cannot be changed,
clOrdID String No clOrdID id, cannot be changed
symbol String Yes which symbol to cancel order
posSide String Yes position direction

NOTE:
1) orderID and clOrdID cannot both be empty.

Bulk Cancel Orders

Request format

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

Response sample

{
  "code": 0,
  "data": {
    "actionTimeNs": 450000000,
    "bizError": 0,
    "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f",
    "closedPnlRv": "1271.9",
    "closedSizeRq": "0.01",
    "cumQtyRq": "0.01",
    "cumValueRv": "1271.9",
    "displayQtyRq": "0.01",
    "execInst": "ReduceOnly",
    "execStatus": "Init",
    "leavesQtyRq": "0.01",
    "leavesValueRv": "1271.9",
    "ordStatus": "Init",
    "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf",
    "orderQtyRq": "0.01",
    "orderType": "Limit",
    "pegOffsetValueRp": "1271.9",
    "pegPriceType": "LastPeg",
    "priceRq": "0.01",
    "reduceOnly": true,
    "side": "string",
    "stopDirection": "Rising",
    "stopPxRp": "1271.9",
    "symbol": "BTCUSDT",
    "timeInForce": "GoodTillCancel",
    "transactTimeNs": 450000000,
    "trigger": "ByMarkPrice"
  },
  "msg": "string"
}
Field Type Required Description
orderID String No list of order ids to be cancelled
clOrdID String No list of clOrdIDs to be cancelled
symbol String Yes which symbol to cancel order
posSide String Yes position direction

NOTE:
1) orderID and clOrdID cannot both be empty.

Cancel All Orders

Request format

DELETE /g-orders/all?symbol=<symbol>&untriggered=<untriggered>&text=<text>

Response sample

{
  "code": 0,
  "data": 0,
  "msg": "string"
}
Field Type Required Description
symbol String - list of symbols to cancel all orders
untriggered boolean -
text String -

Query Account Positions

Request format

GET /g-accounts/accountPositions?currency=<currency>&symbol=<symbol>

Response sample

{
  "code": 0,
  "data": {
    "account": {
      "accountBalanceRv": "1271.9",
      "accountId": 123450001,
      "bonusBalanceRv": "1271.9",
      "currency": "BTC",
      "totalUsedBalanceRv": "1271.9",
      "userID": 12345
    },
    "positions": [
      {
        "accountID": 123450001,
        "assignedPosBalanceRv": "1271.9",
        "avgEntryPrice": "1271.9",
        "avgEntryPriceRp": "1271.9",
        "bankruptCommRv": "1271.9",
        "bankruptPriceRp": "1271.9",
        "buyValueToCostRr": "0.1",
        "cumClosedPnlRv": "1271.9",
        "cumFundingFeeRv": "1271.9",
        "cumTransactFeeRv": "1271.9",
        "curTermRealisedPnlRv": "1271.9",
        "currency": "BTC",
        "deleveragePercentileRr": "0.1",
        "estimatedOrdLossRv": "1271.9",
        "execSeq": 0,
        "initMarginReqRr": "0.1",
        "lastFundingTimeNs": 450000000,
        "lastTermEndTimeNs": 450000000,
        "leverageRr": "0",
        "liquidationPriceRp": "1271.9",
        "maintMarginReqRr": "0.1",
        "makerFeeRateRr": "0.1",
        "markPriceRp": "1271.9",
        "posCostRv": "1271.9",
        "posMode": "Hedged",
        "posSide": "Long",
        "positionMarginRv": "1271.9",
        "positionStatus": "Normal",
        "riskLimitRv": "0.1",
        "sellValueToCostRr": "0.1",
        "side": "Sell",
        "size": "0",
        "symbol": "BTC",
        "takerFeeRateRr": "0.1",
        "term": 0,
        "transactTimeNs": 450000000,
        "usedBalanceRv": "1271.9",
        "userID": 12345,
        "valueRv": "1271.9"
      }
    ]
  },
  "msg": "string"
}
Field Type Required Description
symbol String -
currency String Yes
Field Type Description
leverageRr Int when negative, cross margin; when positive, isolated margin

Query Account Positions with unrealized PNL

Request format

GET /g-accounts/positions?currency=<currency>

Response sample

{
  "code": 0,
  "msg": "",
  "data": {
    "account": {
      "userID": 4200013,
      "accountId": 42000130003,
      "currency": "USDT",
      "accountBalanceRv": "730.97309163",
      "totalUsedBalanceRv": "1.02037554",
      "bonusBalanceRv": "0"
    },
    "positions": [
      {
        "accountID": 42000130003,
        "symbol": "XEMUSDT",
        "currency": "USDT",
        "side": "Buy",
        "positionStatus": "Normal",
        "leverageRr": "-10",
        "initMarginReqRr": "0.1",
        "maintMarginReqRr": "0.01",
        "riskLimitRv": "200000",
        "sizeRq": "186",
        "valueRv": "9.951",
        "avgEntryPriceRp": "0.0535",
        "posCostRv": "1.00047354",
        "assignedPosBalanceRv": "1.086606978",
        "bankruptCommRv": "0.00001116",
        "bankruptPriceRp": "0.0001",
        "positionMarginRv": "730.97308047",
        "liquidationPriceRp": "0.0001",
        "deleveragePercentileRr": "0",
        "buyValueToCostRr": "0.10114",
        "sellValueToCostRr": "0.10126",
        "markPriceRp": "0.053036917",
        "markValueEv": 0,
        "unRealisedPosLossEv": 0,
        "estimatedOrdLossRv": "0",
        "usedBalanceRv": "1.086606978",
        "takeProfitEp": 0,
        "stopLossEp": 0,
        "cumClosedPnlRv": "0",
        "cumFundingFeeRv": "0",
        "cumTransactFeeRv": "0.0059706",
        "realisedPnlEv": 0,
        "unRealisedPnlRv": "-0.086133438",
        "cumRealisedPnlEv": 0,
        "term": 1,
        "lastTermEndTimeNs": 0,
        "lastFundingTimeNs": 0,
        "curTermRealisedPnlRv": "-0.0059706",
        "execSeq": 2260172450,
        "posSide": "Long",
        "posMode": "Hedged"
      },
      {
        "accountID": 42000130003,
        "symbol": "XEMUSDT",
        "currency": "USDT",
        "side": "None",
        "positionStatus": "Normal",
        "crossMargin": false,
        "leverageRr": "-10",
        "initMarginReqRr": "0.1",
        "maintMarginReqRr": "0.01",
        "riskLimitRv": "200000",
        "sizeRq": "0",
        "valueRv": "0",
        "avgEntryPriceRp": "0",
        "posCostRv": "0",
        "assignedPosBalanceRv": "0",
        "bankruptCommRv": "0",
        "bankruptPriceRp": "0",
        "positionMarginRv": "0",
        "liquidationPriceRp": "0",
        "deleveragePercentileRr": "0",
        "buyValueToCostRr": "0.10114",
        "sellValueToCostRr": "0.10126",
        "markPriceRp": "0.053036917",
        "markValueEv": 0,
        "unRealisedPosLossEv": 0,
        "estimatedOrdLossRv": "0",
        "usedBalanceRv": "0",
        "takeProfitEp": 0,
        "stopLossEp": 0,
        "cumClosedPnlRv": "0",
        "cumFundingFeeRv": "0",
        "cumTransactFeeRv": "0",
        "realisedPnlEv": 0,
        "unRealisedPnlRv": "0",
        "cumRealisedPnlEv": 0,
        "term": 1,
        "lastTermEndTimeNs": 0,
        "lastFundingTimeNs": 0,
        "curTermRealisedPnlRv": "0",
        "execSeq": 0,
        "posSide": "Short",
        "posMode": "Hedged"
      }
    ]
  }
}
Field Type Required Description
currency String Yes
Field Type Description
leverageRr Int when negative, cross margin; when positive, isolated margin

NOTE: Highly recommend calculating unRealisedPnlRv in client side with latest markPriceRp to avoid ratelimit penalty.

Switch Position Mode Synchronously

Request format

PUT /g-positions/switch-pos-mode-sync?symbol=<symbol>&targetPosMode=<targetPosMode>

Response sample

{
  "code": 0,
  "data": "string",
  "msg": "string"
}
Field Type Required Description Possible values
symbol String Yes symbol to switch position mode
targetPosMode String Yes the target position mode OneWay, Hedged

Set Leverage

Request format

PUT /g-positions/leverage?leverageRr=<leverage>&longLeverageRr=<longLeverageRr>&shortLeverageRr=<shortLeverageRr>&symbol=<symbol>

Response sample

{
  "code": 0,
  "data": "string",
  "msg": "string"
}
Field Type Required Description
symbol String Yes symbol to set leverage
leverageRr String - new leverage value, if leverageRr exists, the position side is merged.
longLeverageRr String - new long leverage value, if longLeverageRr exists, the position side is hedged.
both longLeverageRr and shortLeverageRr should exist.
shortLeverageRr String - new short leverage value, if shortLeverageRr exists, the position side is hedged.
both longLeverageRr and shortLeverageRr should exist.

Set RiskLimit

Risk Limit Modification Notice: For hedged contracts, the 'Set Position Risk Limit API' has been deprecated. It is no longer possible to manually set the 'Risk Limit'. Instead, simply adjust the leverage multiplier as required, and the 'Risk Limit' will be automatically adjusted.

New Risk Limit Configuration Explanation: A new attribute called leverageMargin has been added to the properties of symbol pairs. By locating the corresponding index_id within the leverageMargins node, one can find the associated 'Risk Limit' information. The configuration is as follows: json { "index_id": 1, "items": [ { "notionalValueRv": 50000, "maxLeverage": 20, "maintenanceMarginRateRr": "0.01", "maintenanceAmountRv": "0" }, { "notionalValueRv": 100000, "maxLeverage": 10, "maintenanceMarginRateRr": "0.06", "maintenanceAmountRv": "0" }, { "notionalValueRv": 200000, "maxLeverage": 5, "maintenanceMarginRateRr": "0.16", "maintenanceAmountRv": "0" }, { "notionalValueRv": 300000, "maxLeverage": 2, "maintenanceMarginRateRr": "0.46", "maintenanceAmountRv": "0" }, { "notionalValueRv": 500000, "maxLeverage": 1, "maintenanceMarginRateRr": "0.5", "maintenanceAmountRv": "0" } ] } For more information, please refer to the link: https://phemex.com/contract/leverage-margin

Assign Position Balance

Request format

POST /g-positions/assign?posBalanceRv=<posBalanceRv>&posSide=<posSide>&symbol=<symbol>

Response sample

{
  "code": 0,
  "data": "string",
  "msg": "string"
}
Field Type Required Description
symbol String Yes symbol to assign position balance
posSide String Yes position side to assign position balance
posBalanceRv String Yes the position balance value

Query open orders by symbol

Request format

GET /g-orders/activeList?symbol=<symbol>

Response sample * Full order { "code": 0, "msg": "", "data": { "rows": [ { "bizError": 0, "orderID": "c2621102-1cc0-4686-b520-9879311bcc26", "clOrdID": "", "symbol": "BTCUSDT", "side": "Sell", "actionTimeNs": 1678163665765381733, "transactTimeNs": 1678163665769528669, "orderType": "Limit", "priceRp": "22490.4", "orderQtyRq": "0.005", "displayQtyRq": "0.005", "timeInForce": "GoodTillCancel", "reduceOnly": false, "closedPnlRv": "0", "closedSizeRq": "0", "cumQtyRq": "0", "cumValueRv": "0", "leavesQtyRq": "0.005", "leavesValueRv": "112.452", "stopDirection": "UNSPECIFIED", "stopPxRp": "0", "trigger": "UNSPECIFIED", "pegOffsetValueRp": "0", "pegOffsetProportionRr": "0", "execStatus": "New", "pegPriceType": "UNSPECIFIED", "ordStatus": "New", "execInst": "CloseOnTrigger", "takeProfitRp": "0", "stopLossRp": "0" } ], "nextPageArg": "" } }

Field Type Description Possible values
symbol String which symbol to query Trading symbols

Query closed orders by symbol

Request format

GET /exchange/order/v2/orderList?symbol=<symbol>&currency=<currency>&ordStatus=<ordStatus>&ordType=<ordType>&start=<start>&end=<end>&offset=<offset>&limit=<limit>&withCount=<withCount>

Response sample

{
    "code": 0,
    "msg": "OK",
    "data": {
        "total": 1,
        "rows": [
            {
                "createdAt": 1666179379726,
                "symbol": "ETHUSDT",
                "orderQtyRq": "0.78",
                "side": 1,
                "priceRp": "1271.9",
                "execQtyRq": "0.78",
                "leavesQtyRq": "0",
                "execPriceRp": "1271.9",
                "orderValueRv": "992.082",
                "leavesValueRv": "0",
                "cumValueRv": "992.082",
                "stopDirection": 0,
                "stopPxRp": "0",
                "trigger": 0,
                "actionBy": 1,
                "execFeeRv": "0.0012719",
                "ordType": 2,
                "ordStatus": 7,
                "clOrdId": "2739dc9",
                "orderId": "2739dc90-41c6-449f-8774-0a62c8d8e320",
                "execStatus": 6,
                "bizError": 0,
                "totalPnlRv": null,
                "avgTransactPriceRp": null,
                "orderDetailsVos": null,
                "tradeType": 1
            }
        ]
    }
}
Field Type Required Description Possible values
symbol String No which symbol to query Trading symbols
currency String Yes which currency to query
ordStatus Integer No order status code list filter New(5), PartiallyFilled(6), Untriggered(1), Filled(7), Canceled(8)
ordType Integer No order type code list filter Market (1), Limit (2), Stop (3), StopLimit (4), MarketIfTouched (5), LimitIfTouched (6), ProtectedMarket (7), MarketAsLimit (8), StopAsLimit (9), MarketIfTouchedAsLimit (10), Bracket (11), BoTpLimit (12), BoSlLimit (13), BoSlMarket (14)
start Integer Yes start time range, Epoch millis，available only from the last 2 month
end Integer Yes end time range, Epoch millis
offset Integer Yes offset to resultset
limit Integer Yes limit of resultset, max 200
withCount boolean No if true, result info will contains count info. true,false

Response

Field Type Description Possible values
execStatus Integer exec status code Aborted(2), MakerFill(6), TakerFill(7), Expired(8), Canceled(11), CreateRejected(19)
tradeType Integer trade type code Trade(1), Funding(4), LiqTrade(6), AdlTrade(7)
side Integer side code Buy(1), Sell(2)
orderType Integer order type code Marketranslation missing: en.1, Limitranslation missing: en.2, Stop(3), StopLimitranslation missing: en.4, MarketIfTouched(5), LimitIfTouched(6)
ordStatus Integer order status code Created(0), Untriggered(1), Deactivated(2), Triggered(3), Rejected(4), New(5), PartiallyFilled(6), Filled(7), Canceled(8)
actionBy Integer action by code ByUser(1)
action Integer user code New(1), Cancel(2), Replace(3), CancelAll(4), LiqRequestranslation missing: en.11, SettleFundingFee(13)
trigger Integer trigger code UNSPECIFIED(0), ByMarkPrice(1), ByLastPrice(3)

Query closed positions

Request format

GET /api-data/g-futures/closedPosition?symbol=<symbol>&currency=<currency>

Response sample

{
    "code": 0,
    "msg": "OK",
    "data": {
        "total": 2,
        "rows": [
            {
                "symbol": "ETHUSDT",
                "currency": "USDT",
                "term": 0,
                "closedSizeRq": 1,
                "side": 1,
                "cumEntryValueRv": None,
                "closedPnlRv": "-0.2",
                "exchangeFeeRv": "0.007113",
                "fundingFeeRv": "0.78",
                "finished": "0",
                "openedTimeNs": 1694542394835,
                "updatedTimeNs": 1694542398837,
                "openPrice": "5.93900000",
                "closePrice": 2,
                "roi": "-0.01008799",
                "leverage": 6
            },
            {
                "symbol": "ETHUSDT",
                "currency": "USDT",
                "term": 0,
                "closedSizeRq": 20,
                "side": 1,
                "cumEntryValueRv": None,
                "closedPnlRv": "-55",
                "exchangeFeeRv": "0.7113",
                "fundingFeeRv": "3.52",
                "finished": "0",
                "openedTimeNs": 1693542394835,
                "updatedTimeNs": 1693542398837,
                "openPrice": "1998",
                "closePrice": "1888",
                "roi": "-0.28799",
                "leverage": 20
            }
        ]
    }
}
Field Type Required Description Possible values
symbol String No which symbol to query Trading symbols
currency String No which currency to query USDT...
offset Integer No offset to resultset
limit Integer No limit of resultset, max 200
withCount Boolean No if true, result info will contains count info. true, false

NOTE:
1) symbol and currency cannot both be empty.
2) user trade queries from database and its data is limited for the last 90 days.

Query user trade

Request format

GET /exchange/order/v2/tradingList?symbol=<symbol>&currency=<currency>&execType=<execType>&offset=<offset>&limit=<limit>&withCount=<withCount>

Response sample

{
    "code": 0,
    "msg": "OK",
    "data": {
        "total": 4,
        "rows": [
            {
                "createdAt": 1666226932259,
                "symbol": "ETHUSDT",
                "currency": "USDT",
                "action": 1,
                "tradeType": 1,
                "execQtyRq": "0.01",
                "execPriceRp": "1271.9",
                "side": 1,
                "orderQtyRq": "0.78",
                "priceRp": "1271.9",
                "execValueRv": "12.719",
                "feeRateRr": "0.0001",
                "execFeeRv": "0.0012719",
                "ordType": 2,
                "execId": "8718cae",
                "execStatus": 6,
                "posSide": 3,
                "ptFeeRv": 0,
                "ptPriceRp": 0
            },
            {
                "createdAt": 1666226903754,
                "symbol": "ETHUSDT",
                "currency": "USDT",
                "action": 1,
                "tradeType": 1,
                "execQtyRq": "0.07",
                "execPriceRp": "1271.9",
                "side": 1,
                "orderQtyRq": "0.07",
                "priceRp": "1271.9",
                "execValueRv": "89.033",
                "feeRateRr": "0.0001",
                "execFeeRv": "0.0089033",
                "ordType": 2,
                "execId": "8b8a8a0",
                "execStatus": 6,
                "posSide": 3,
                "ptFeeRv": 0,
                "ptPriceRp": 0
            }
        ]
    }
}
Field Type Required Description Possible values
symbol String No which symbol to query Trading symbols
currency String Yes which currency to query USDT...
execType Integer No trade type code list filter Trade(1),LiqTrade(6),AdlTrade(7)
offset Integer Yes offset to resultset
limit Integer Yes limit of resultset, max 200
withCount Boolean No if true, result info will contains count info. true,false

NOTE:
1) symbol and currency cannot both be empty.
2) user trade queries from database and its data is limited for the last 90 days.

TradeTypes Description
Trade Normal trades
Funding Funding on positions
AdlTrade Auto-delevearage trades
LiqTrade Liquidation trades
Field Type Description Possible values
execStatus Integer exec status code Aborted(2), MakerFill(6), TakerFill(7), Expired(8), Canceled(11), CreateRejected(19)
tradeType Integer trade type code Trade(1),LiqTrade(6),AdlTrade(7)
side Integer side code Buy(1),Sell(2)
orderType Integer order type code Market (1),Limit (2),Stop(3),StopLimit (4),MarketIfTouched (5),LimitIfTouched (6)
ordStatus Integer order status code Created(0),Untriggered(1),Deactivated(2),Triggered(3),Rejected(4),New(5),PartiallyFilled(6),Filled(7),Canceled(8)
actionBy Integer action by code ByUser(1)
trigger Integer trigger code UNSPECIFIED(0),ByMarkPrice(1),ByLastPrice(3)

Query Order Book

Request format


  GET /md/v2/orderbook?symbol=<symbol>

Response format

  {
    "error": null,
    "id": 0,
    "result": {
    "orderbook_p": {
      "asks": [
        [
          <priceRp>,
          <size>
        ],
        ...
        ...
        ...
      ],
      "bids": [
        [
          <priceRp>,
          <size>
        ],
        ...
        ...
        ...
      ],
    ]
    },
    "depth": 30,
    "sequence": <sequence>,
    "timestamp": <timestamp>,
    "symbol": "<symbol>",
    "type": "snapshot"
      }
  }
Field Type Description Possible values
symbol String Contract symbol name Trading symbols
Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds
priceRp String Real book level price
sizeRq String Real book level size
sequence Integer current message sequence
symbol String Contract symbol name Trading symbols 
  GET /md/v2/orderbook?symbol=BTCUSDT

  {
      "error": null,
      "id": 0,
      "result": {
          "depth": 30,
          "orderbook_p": {
              "asks": [
                  [
                      "20675.7",
                      "0.736"
                  ],
                  [
                      "20676.2",
                      "0.613"
                  ]
              ],
              "bids": [
                  [
                      "20672.4",
                      "0.818"
                  ],
                  [
                      "20672.2",
                      "0.614"
                  ]
              ]
          },
          "sequence": 77770771,
          "symbol": "BTCUSDT",
          "timestamp": 1666860123727907896,
          "type": "snapshot"
      }
  }

Query kline

NOTE: kline interfaces have rate limits rule, please check the Other group under api groups. Kline under generation beyond the latest interval is not included in the response.

Request format

  GET /exchange/public/md/v2/kline/last?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 which symbol to query Trading symbols
resolution Integer Yes Kline Interval MINUTE_1(60),MINUTE_5(300),MINUTE_15(900),MINUTE_30(1800),HOUR_1(3600),HOUR_4(14400),DAY_1(86400),WEEK_1(604800),MONTH_1(2592000),SEASON_1(7776000),YEAR_1(31104000)
limit Integer No records limit 5
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.

GET /exchange/public/md/v2/kline/list?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 2000
resolution Integer Yes kline interval the same as described above

Query Trade

Request format GET /md/v2/trade?symbol=<symbol>

Response format

  {
    "error": null,
    "id": 0,
    "result": {
    "sequence": <sequence>,
    "symbol": <symbol>,
    "trades_p": [
                    [
                        <timestamp>,
                        <Side>,
                        <PriceRp>,
                        <SizeRq>
                    ],
                    [
                        <timestamp>,
                        <Side>,
                        <PriceRp>,
                        <SizeRq>
                    ],
                    ...
                    ...
                    ...
                ],
    "type": "snapshot"
    }
  }
Field Type Description Possible values
symbol String Contract symbol name Trading symbols
Field Type Description Possible values
timestamp Integer Timestamp in nanoseconds
Side String Trade Side, Buy or Sell
priceRp String Real trade price
sizeRq String Real trade size
sequence Integer current message sequence
symbol String Contract symbol name Trading symbols 
  GET /md/v2/trade?symbol=BTCUSDT

  {
    "error": null,
    "id": 0,
    "result": {
        "sequence": 77766796,
        "symbol": "BTCUSDT",
        "trades_p": [
            [
                1666860389799499000,
                "Buy",
                "20702.1",
                "0.949"
            ],
            [
                1666860377636154600,
                "Sell",
                "20675.5",
                "0.785"
            ],
            ...
            ...
            ...
        ],
        "type": "snapshot"
    }
  }

Query 24 ticker

there are two differnent response format for 24 ticker

Request format 1 (v2 will be removed later, v3 is recommended) GET /md/v2/ticker/24hr?symbol=<symbol> GET /md/v2/ticker/24hr?symbol=<symbol>

Response sample

{
    "error": null,
    "id": 0,
    "result": {
        "closeRp": "1903.16",
        "fundingRateRr": "0.0001",
        "highRp": "1932.31",
        "indexPriceRp": "1903.62867093",
        "lowRp": "1854.52",
        "markPriceRp": "1903.16",
        "openInterestRv": "6880.97",
        "openRp": "1891.97",
        "predFundingRateRr": "0.0001",
        "symbol": "ETHUSDT",
        "timestamp": 1681349614932856300,
        "turnoverRv": "127962734.6031",
        "volumeRq": "67460.4"
    }
}
Field Type Required Description Possible values
symbol String Yes which symbol to query Trading symbols 
  GET /md/v2/ticker/24hr?symbol=BTCUSDT

Request format 2 (recommended) GET /md/v3/ticker/24hr?symbol=<symbol>

Response sample

{
    "error": null,
    "id": 0,
    "result": {
        "askRp": "1906.03",
        "bidRp": "1906",
        "fundingRateRr": "0.0001",
        "highRp": "1932.31",
        "indexRp": "1906.275",
        "lastRp": "1905.63",
        "lowRp": "1854.52",
        "markRp": "1905.733555189",
        "openInterestRv": "7115",
        "openRp": "1885.18",
        "predFundingRateRr": "0.0001",
        "symbol": "ETHUSDT",
        "timestamp": 1681350167054888200,
        "turnoverRv": "128200614.5585",
        "volumeRq": "67580.6"
    }
}

  GET /md/v3/ticker/24hr?symbol=BTCUSDT

Query 24 ticker for all symbols

also there are two differnent response format for 24 ticker with all ticker

you can use path below (v3 is recommended) to get data with array list

  GET /md/v2/ticker/24hr/all

  GET /md/v3/ticker/24hr/all

Query Orders History

Request format

GET /api-data/g-futures/orders?symbol=<symbol>

Response sample

[
    {
        "actionTimeNs": 1667562110213260743,
        "bizError": 0,
        "clOrdId": "cfffa744-712d-867a-e397-9888eec3f6d1",
        "closedPnlRv": "0",
        "closedSizeRq": "0",
        "cumQtyRq": "0.001",
        "cumValueRv": "20.5795",
        "displayQtyRq": "0.001",
        "leavesQtyRq": "0",
        "leavesValueRv": "0",
        "orderId": "743fc923-cb01-4261-88d1-b35dba2cdac0",
        "orderQtyRq": "0.001",
        "ordStatus": "Filled",
        "ordType": "Market",
        "priceRp": "21206.7",
        "reduceOnly": false,
        "side": "Buy",
        "stopDirection": "UNSPECIFIED",
        "stopLossRp": "0",
        "symbol": "BTCUSDT",
        "takeProfitRp": "0",
        "timeInForce": "ImmediateOrCancel",
        "transactTimeNs": 1667562110221077395
    }
]
Field Type Required Description Possible Values
symbol String False the symbol to query "BTCUSDT" ...
symbols String False the symbols to query "BTCUSDT, LINKUSDT" ...
currency String False the currency to query "USDT" ...
start Long False start time in millisecond default 2 days ago from the end
end Long 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

NOTE:
1) symbol and currency cannot both be empty.
2) When the symbol parameter is present, searching by symbol is prioritised.
3) If only the currency is provided, it retrieves all symbols under that currency.
4) Searching for specific symbols under a currency needs both symbols and currency parameter.

Query Orders By Ids

Request format

GET /api-data/g-futures/orders/by-order-id?symbol=<symbol>

Response sample

[
    {
        "orderId": "743fc923-cb01-4261-88d1-b35dba2cdac0",
        "clOrdId": "cfffa744-712d-867a-e397-9888eec3f6d1",
        "symbol": "BTCUSDT",
        "side": "Buy",
        "ordType": "Market",
        "actionTimeNs": 1667562110213260743,
        "priceRp": "21206.7",
        "orderQtyRq": "0.001",
        "displayQtyRq": "0.001",
        "timeInForce": "ImmediateOrCancel",
        "reduceOnly": false,
        "takeProfitRp": "0",
        "stopLossRp": "0",
        "closedPnlRv": "0",
        "closedSizeRq": "0",
        "cumQtyRq": "0.001",
        "cumValueRv": "20.5795",
        "leavesQtyRq": "0",
        "leavesValueRv": "0",
        "stopDirection": "UNSPECIFIED",
        "ordStatus": "Filled",
        "transactTimeNs": 1667562110221077395,
        "bizError": 0
    }
]
Field Type Required Description Possible Values
symbol String True the currency to query BTCUSDT ...
orderID String False order id orderID and clOrdID can not be both empty. If both IDs are given, it will return list of orders which match both orderID or clOrdID
clOrdID String False client order id refer to orderID

Query Trades History

Request format

GET /api-data/g-futures/trades?symbol=<symbol>

Response sample

[
    {
        "transactTimeNs": 1669407633926215067,
        "symbol": "BTCUSDT",
        "currency": "USDT",
        "action": "New",
        "posSide": "Short",
        "side": "Sell",
        "tradeType": "Trade",
        "execQtyRq": "0.001",
        "execPriceRp": "16600",
        "orderQtyRq": "0.001",
        "priceRp": "16600",
        "execValueRv": "16.6",
        "feeRateRr": "0.0001",
        "execFeeRv": "0.00166",
        "closedSizeRq": "0",
        "closedPnlRv": "0",
        "ordType": "LimitIfTouched",
        "execID": "5c3d96e1-8874-53b6-b6e5-9dcc4d28b4ab",
        "orderID": "fcdfeafa-ed68-45d4-b2bd-7bc27f2b2b0b",
        "clOrdID": "",                                
        "execStatus": "MakerFill",                                                  
    }
]
Field Type Required Description Possible Values
symbol String False the symbol to query "BTCUSDT" ...
symbols String False the symbols to query "BTCUSDT, LINKUSDT" ...
currency String False the currency to query "USDT" ...
start Long False start time in millisecond default 2 days ago from the end
end Long 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

NOTE:
1) symbol and currency cannot both be empty.
2) When the symbol parameter is present, searching by symbol is prioritised.
3) If only the currency is provided, it retrieves all symbols under that currency.
4) Searching for specific symbols under a currency needs both symbols and currency parameter.

Query funding rate history

Request format

GET /api-data/public/data/funding-rate-history?symbol=<symbol>&start=<start>&end=<end>&limit=<limit>

Response sample

{
  "code": 0,
  "msg": "OK",
  "data": {
    "rows": [
      {
        "symbol": ".ETHUSDTFR8H",
        "fundingRate": "0.0001",
        "fundingTime": 1680768000000,
        "intervalSeconds": 28800
      },
      {
        "symbol": ".ETHUSDTFR8H",
        "fundingRate": "0.0001",
        "fundingTime": 1680796800000,
        "intervalSeconds": 28800
      }
    ]
  }
}
Field Type Required Description Possible Values
symbol String True funding rate symbol .ETHUSDTFR8H
start Long False start timestamp in ms of funding time (INCLUSIVE) 1679852520918
end Long False end timestamp in ms of funding time (INCLUSIVE) 1679852520918
limit Integer False default 100, max 100 100

Query funding fee history

Request format

GET /api-data/g-futures/funding-fees?symbol=<symbol>
Parameter Type Required Description Case
symbol String True the currency to query BTCUSDT...
offset Integer False page starts from 0 default 0
limit Integer False page size default 20, max 200

Response sample

[
  {
    "symbol": "ETHUSDT",
    "currency": "USDT",
    "execQtyRq": "0.16",
    "side": "Buy",
    "execPriceRp": "1322.84500459",
    "execValueRv": "211.65520073",
    "fundingRateRr": "0.0001",
    "feeRateRr": "0.0001",
    "execFeeRv": "0.02116552",
    "createTime": 1671004800021
  }
]

Hedged Contract Websocket API

API Rate Limits

Heartbeat

Request format json { "id": 1234, "method": "server.ping", "params": [] }

Response sample

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

API User Authentication

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

Request format json { "method": "user.auth", "params": [ "API", "<token>", "<signature>", "<expiry>" ], "id": 1234 }

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

Response sample json { "error": null, "id": 1234, "result": { "status": "success" } }

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 for new Model

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

Request sample json { "id": 1234, "method": "orderbook_p.subscribe", "params": [ "BTCUSDT" ] } Response sample json { "error": null, "id": 1234, "result": { "status": "success" } }

OrderBook Message:

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

Response format ```javascript { "book": { "asks": [ [ , ], . . . ], "bids": [ [ , ], . . . ] }, "depth": , "sequence": , "timestamp": , "symbol": "", }


* Sample：

> Response sample
```json
{"depth":30,"orderbook_p":{"asks":[["20702.9","0.718"],["20703.9","0.524"],["20704.9","0"],["20720.8","0"]],"bids":[["20703.1","0"],["20701.3","0"],["20701.2","0"],["20700.5","1.622"],["20473.7","1.074"],["20441.3","0.904"]]},"sequence":77668172,"symbol":"BTCUSDT","timestamp":1666854171201355264,"type":"incremental"}

{"depth":30,"orderbook_p":{"asks":[],"bids":[["20700.5","0"],["20340.5","0.06"]]},"sequence":77668209,"symbol":"BTCUSDT","timestamp":1666854173705089711,"type":"incremental"}
Field Type Description Possible values
side String Price level side bid, ask
priceEp String Raw price
qty String Price level size
sequence Integer Latest message sequence
depth Integer Market depth 30
type String Message type snapshot, incremental

Unsubscribe OrderBook

It unsubscribes all orderbook related subscriptions.

Request format

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

Response format javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Subscribe Trade

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": 1234,
  "method": "trade_p.subscribe",
  "params": [
    "BTCUSDT"
  ]
}

Response sample

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

Trade Message Format：

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.

Response format javascript { "trades": [ [ <timestamp>, "<side>", "<price>", "<qty>" ], . . . ], "sequence": <sequence>, "symbol": "<symbol>", "type": "<type>" }

Response sample json { "sequence": 77702250, "symbol": "BTCUSDT", "trades_p": [ [ 1666856076819029800, "Sell", "20700.3", "0.649" ] ], "type": "incremental" } json { "sequence": 77663551, "symbol": "BTCUSDT", "trades_p": [ [ 1666856062351916300, "Sell", "20703.6", "0.669" ], [ 1666854025545354000, "Buy", "20699", "0.001" ] ], "type": "snapshot" }

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

Unsubscribe Trade

It unsubscribes all trade subscriptions or for a symbol.

Request format * unsubscribe all trade subsciptions javascript { "id": <id>, "method": "trade_p.unsubscribe", "params": [ ] } Request format * unsubscribe all trade subsciptions for a symbol javascript { "id": <id>, "method": "trade_p.unsubscribe", "params": [ "<symbol>" ] }

Response sample javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Subscribe Kline

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 format javascript { "id": <id>, "method": "kline_p.subscribe", "params": [ "<symbol>", "<interval>" ] }

Response format javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Request sample * subscribe 1-day kline json { "id": 1234, "method": "kline_p.subscribe", "params": [ "BTCUSDT", 86400 ] }

Response sample json { "error": null, "id": 1234, "result": { "status": "success" } }

Kline Message Format：

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.

Response format javascript { "kline": [ [ <timestamp>, "<interval>", <lastClose>, <open>, <high>, <low>, <close>, <volume>, <turnover>, ], . . . ], "sequence": <sequence>, "symbol": "<symbol>", "type": "<type>" }

Response sample json { "kline_p": [ [ 1666856340, 60, "20689.5", "20686.2", "20695.4", "20686.2", "20691.6", "2.742", "56731.5609" ], [ 1666856280, 60, "20700.1", "20712.7", "20712.7", "20689.1", "20689.5", "4.407", "91208.3065" ] ], "sequence": 77711279, "symbol": "BTCUSDT", "type": "snapshot" } json { "kline_p": [ [ 1666856520, 60, "20685", "20684.8", "20684.8", "20675.2", "20675.2", "3.547", "73353.8417" ] ], "priceScale": 0, "sequence": 77715046, "symbol": "BTCUSDT", "type": "incremental" }

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
lastClose String Unscaled last close price
open String Unscaled open price
high String Unscaled high price
low String Unscaled low price
close String Unscaled close price
volume String Trade voulme during the current kline interval
turnover String Unscaled turnover value
sequence Integer Latest message sequence
symbol String Contract symbol name
type String Message type snapshot, incremental

Unsubscribe Kline

It unsubscribes all kline subscriptions or for a symbol.

Request format * unsubscribe all Kline subscriptions javascript { "id": <id>, "method": "kline_p.unsubscribe", "params": [] } Request format * unsubscribe all Kline subscriptions of a symbol javascript { "id": <id>, "method": "kline_p.unsubscribe", "params": [ "<symbol>" ] }

Response sample javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Subscribe Account-Order-Position (AOP)

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.

Request format javascript { "id": <id>, "method": "aop_p.subscribe", "params": [] }

Response format javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Request sample json { "id": 1234, "method": "aop_p.subscribe", "params": [] } Response sample json { "error": null, "id": 1234, "result": { "status": "success" } }

Account-Order-Position (AOP) Message Sample:

Message sample: snapshot


{
  "index_market24h": {
    "highEp": 10009,
    "lastEp": 10007,
    "lowEp": 10004,
    "openEp": 10004,
    "symbol": ".USDT"
  },
  "timestamp": 1681496204104375396}
{
  "accounts_p":[
    {
      "accountBalanceRv":"1508.452588802237",
      "accountID":9328670003,
      "bonusBalanceRv":"0",
      "currency":"USDT",
      "totalUsedBalanceRv":"343.132599666883",
      "userID":932867
    }
  ],
  "orders_p":[
    {
      "accountID":9328670003,
      "action":"New",
      "actionBy":"ByUser",
      "actionTimeNs":1666858780876924611,
      "addedSeq":77751555,
      "apRp":"0",
      "bonusChangedAmountRv":"0",
      "bpRp":"0",
      "clOrdID":"c0327a7d-9064-62a9-28f6-2db9aaaa04e0",
      "closedPnlRv":"0",
      "closedSize":"0",
      "code":0,
      "cumFeeRv":"0",
      "cumQty":"0",
      "cumValueRv":"0",
      "curAccBalanceRv":"1508.489893982237",
      "curAssignedPosBalanceRv":"24.62786650928",
      "curBonusBalanceRv":"0",
      "curLeverageRr":"-10",
      "curPosSide":"Buy",
      "curPosSize":"0.043",
      "curPosTerm":1,
      "curPosValueRv":"894.0689",
      "curRiskLimitRv":"1000000",
      "currency":"USDT",
      "cxlRejReason":0,
      "displayQty":"0.003",
      "execFeeRv":"0",
      "execID":"00000000-0000-0000-0000-000000000000",
      "execPriceRp":"20723.7",
      "execQty":"0",
      "execSeq":77751555,
      "execStatus":"New",
      "execValueRv":"0",
      "feeRateRr":"0",
      "leavesQty":"0.003",
      "leavesValueRv":"63.4503",
      "message":"No error",
      "ordStatus":"New",
      "ordType":"Market",
      "orderID":"fa64c6f2-47a4-4929-aab4-b7fa9bbc4323",
      "orderQty":"0.003",
      "pegOffsetValueRp":"0",
      "posSide":"Long",
      "priceRp":"21150.1",
      "relatedPosTerm":1,
      "relatedReqNum":11,
      "side":"Buy",
      "slTrigger":"ByMarkPrice",
      "stopLossRp":"0",
      "stopPxRp":"0",
      "symbol":"BTCUSDT",
      "takeProfitRp":"0",
      "timeInForce":"ImmediateOrCancel",
      "tpTrigger":"ByLastPrice",
      "tradeType":"Amend",
      "transactTimeNs":1666858780881545305,
      "userID":932867
    }
  ],
  "positions_p": [
    {
      "accountID": 9328670003,
      "assignedPosBalanceRv": "0",
      "avgEntryPriceRp": "0",
      "bankruptCommRv": "0",
      "bankruptPriceRp": "0",
      "buyLeavesQty": "0",
      "buyLeavesValueRv": "0",
      "buyValueToCostRr": "0.10114",
      "createdAtNs": 0,
      "crossSharedBalanceRv": "266.079483950342",
      "cumClosedPnlRv": "-0.8092",
      "cumFundingFeeRv": "0.013573252307",
      "cumPtFeeRv": "0",
      "cumTransactFeeRv": "0.27247008",
      "curTermRealisedPnlRv": "-0.11368032",
      "currency": "USDT",
      "dataVer": 40,
      "deleveragePercentileRr": "0",
      "displayLeverageRr": "-10",
      "estimatedOrdLossRv": "0",
      "execSeq": 7659244869,
      "freeCostRv": "0",
      "freeQty": "0",
      "initMarginReqRr": "0.1",
      "lastFundingTime": 1699833600000000000,
      "lastTermEndTime": 1699545458473086582,
      "leverageRr": "-10",
      "liquidationPriceRp": "0",
      "maintMarginReqRr": "0.005",
      "makerFeeRateRr": "0.0001",
      "markPriceRp": "37214.088278684",
      "minPosCostRv": "0",
      "orderCostRv": "0",
      "posCostRv": "0",
      "posMode": "OneWay",
      "posSide": "Long",
      "positionMarginRv": "0",
      "positionStatus": "Normal",
      "riskLimitRv": "2000000",
      "sellLeavesQty": "0",
      "sellLeavesValueRv": "0",
      "sellValueToCostRr": "0.10126",
      "side": "None",
      "size": "0",
      "symbol": "BTCUSDT",
      "takerFeeRateRr": "0.0006",
      "term": 7,
      "transactTimeNs": 1699833600004313941,
      "unrealisedPnlRv": "0",
      "updatedAtNs": 0,
      "usedBalanceRv": "0",
      "userID": 932867,
      "valueRv": "0"
    }
  ],
  "sequence": 59553602,
  "timestamp": 1701414172164093977,
  "type": "snapshot",
  "version": 0
}

> Message sample: incremental

```json

{
  "accounts_p": [
    {
      "accountBalanceRv": "512.097102123158",
      "accountID": 9328670003,
      "bonusBalanceRv": "197.754035960875",
      "currency": "USDT",
      "status": 0,
      "totalUsedBalanceRv": "0.0074407494",
      "tradeLevel": 0,
      "userID": 932867
    }
  ],
  "orders_p": [
    {
      "accountID": 9328670003,
       "action": "New",
       "actionBy": "ByUser",
       "actionTimeNs": 1701414861467927198,
       "addedSeq": 7757755866,
       "bonusChangedAmountRv": "0",
       "clOrdID": "3811d9a0-96e4-2150-6f9a-686514cbb266",
       "cl_req_code": 0,
       "closedPnlRv": "0",
       "closedSize": "0",
       "code": 0,
       "cumFeeRv": "0",
       "cumPtFeeRv": "0",
       "cumQty": "0",
       "cumValueRv": "0",
       "curAccBalanceRv": "511.465393303158",
       "curAssignedPosBalanceRv": "2.04508414",
       "curBonusBalanceRv": "197.760331550875",
       "curLeverageRr": "-10",
       "curPosSide": "Buy",
       "curPosSize": "0.01",
       "curPosTerm": 3,
       "curPosValueRv": "20.341",
       "curRiskLimitRv": "1000000",
       "currency": "USDT",
       "cxlRejReason": 0,
       "displayQty": "0.01",
       "execFeeRv": "0",
       "execID": "00000000-0000-0000-0000-000000000000",
       "execInst": "CloseOnTrigger",
       "execPriceRp": "0",
       "execQty": "0",
       "execSeq": 7757755866,
       "execStatus": "New",
       "execValueRv": "0",
       "feeRateRr": "0",
       "leavesQty": "0.01",
       "leavesValueRv": "15.7389",
       "message": "No error",
       "ordStatus": "New",
       "ordType": "Market",
       "orderID": "2ce8a2ae-fda4-44d0-af70-bca632fd9869",
       "orderQty": "0.01",
       "pegOffsetProportionRr": "0",
       "pegOffsetValueRp": "0",
       "posSide": "Merged",
       "priceRp": "1573.89",
       "ptFeeRv": "0",
       "ptPriceRp": "0",
       "relatedPosTerm": 3,
       "relatedReqNum": 78,
       "side": "Sell",
       "slPxRp": "0",
       "slTimeInForce": "ImmediateOrCancel",
       "slTrigger": "ByMarkPrice",
       "stopLossRp": "0",
       "stopPxRp": "0",
       "symbol": "ETHUSDT",
       "takeProfitRp": "0",
       "timeInForce": "ImmediateOrCancel",
       "tpPxRp": "0",
       "tpTimeInForce": "ImmediateOrCancel",
       "tpTrigger": "ByLastPrice",
       "transactTimeNs": 1701414861472716784,
       "userID": 932867
    }
  ],
  "positions_p": [
    {
      "accountID": 9328670003,
      "assignedPosBalanceRv": "0",
      "avgEntryPriceRp": "0",
      "bankruptCommRv": "0",
      "bankruptPriceRp": "0",
      "buyLeavesQty": "0",
      "buyLeavesValueRv": "0",
      "buyValueToCostRr": "0.10114",
      "createdAtNs": 0,
      "crossSharedBalanceRv": "512.089661373758",
      "cumClosedPnlRv": "1.2114",
      "cumFundingFeeRv": "0.038701322568",
      "cumPtFeeRv": "0",
      "cumTransactFeeRv": "0.0668598",
      "curTermRealisedPnlRv": "0.613379890738",
      "currency": "USDT",
      "dataVer": 78,
      "deleveragePercentileRr": "0",
      "displayLeverageRr": "-10",
      "estimatedOrdLossRv": "0",
      "execSeq": 7757755866,
      "freeCostRv": "0",
      "freeQty": "0",
      "initMarginReqRr": "0.1",
      "lastFundingTime": 1701388800000000000,
      "lastTermEndTime": 1701414861472716784,
      "leverageRr": "-10",
      "liquidationPriceRp": "0",
      "maintMarginReqRr": "0.005",
      "makerFeeRateRr": "0.0001",
      "markPriceRp": "2100.851224773",
      "minPosCostRv": "0",
      "orderCostRv": "0",
      "posCostRv": "0",
      "posMode": "OneWay",
      "posSide": "Merged",
      "positionMarginRv": "0",
      "positionStatus": "Normal",
      "riskLimitRv": "1000000",
      "sellLeavesQty": "0",
      "sellLeavesValueRv": "0",
      "sellValueToCostRr": "0.10126",
      "side": "None",
      "size": "0",
      "symbol": "ETHUSDT",
      "takerFeeRateRr": "0.0006",
      "term": 4,
      "transactTimeNs": 1701414861472716784,
      "unrealisedPnlRv": "0",
      "updatedAtNs": 0,
      "usedBalanceRv": "0",
      "userID": 932867,
      "valueRv": "0"
    }
  ],
  "sequence": 59555555,
  "timestamp": 1701414861475827540,
  "type": "incremental",
  "version": 0
}
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

Unsubscribe Account-Order-Position (AOP)

Request format javascript { "id": <id>, "method": "aop_p.unsubscribe", "params": [] }

Response format javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Subscribe 24 Hours Ticker

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

Request format ```javascript * Subscribe single symbol { "id": , "method": "market24h_p.subscribe", "params": [] }

Response format javascript { "error": null, "id": <id>, "result": { "status": "success" } }

Request sample json { "method": "perp_market24h_pack_p.subscribe", "params": [], "id": 1234 }

Response sample json { "error": null, "id": 1234, "result": { "status": "success" } }

Hours Ticker Message Format：

Response format javascript { "data": [ [ <symbol>, <openRp>, <highRp>, <lowRp>, <lastRp>, <volumeRq>, <turnoverRv>, <openInterestRv>, <indexRp>, <markRp>, <fundingRateRr>, <predFundingRateRr> ] ], "fields": [ "symbol", "openRp", "highRp", "lowRp", "lastRp", "volumeRq", "turnoverRv", "openInterestRv", "indexRp", "markRp", "fundingRateRr", "predFundingRateRr" ], "method": "perp_market24h_pack_p.update", "timestamp": 1666862556850547000, "type": "snapshot" }

Response sample json { "data": [ [ "ETHUSDT", "1533.72", "1594.17", "1510.05", "1547.52", "545942.34", "848127644.5712", "0", "1548.31694379", "1548.44513153", "0.0001", "0.0001" ], [ "BTCUSDT", "20614.5", "21628.4", "19258.6", "20626.3", "8819.819", "182892627.4297", "0", "20641.8167574", "20643.52572781", "0.0001", "0.0001" ] ], "fields": [ "symbol", "openRp", "highRp", "lowRp", "lastRp", "volumeRq", "turnoverRv", "openInterestRv", "indexRp", "markRp", "fundingRateRr", "predFundingRateRr" ], "method": "perp_market24h_pack_p.update", "timestamp": 1666862556850547000, "type": "snapshot" }

Field Type Description Possible values
symbol String Contract symbol name Trading symbols
openRp String The unscaled open price in last 24 hours
highRp String The unscaled highest price in last 24 hours
lowRp String The unscaled lowest price in last 24 hours
lastRp String The unscaled close price in last 24 hours
volumeRq String Symbol trade volume in last 24 hours
turnoverRv String The unscaled turnover value in last 24 hours
openInterestRv String current open interest
indexRp String Unscaled index price
markRp String Unscaled mark price
fundingRateRr String Unscaled funding rate
predFundingRateRr String Unscaled predicated funding rate

Subscribe tick event for symbol price

symbol index symbol mark symbol pfr symbol funding rate symbol
BTCUSDT .BTCUSDT .MBTCUSDT .BTCUSDTFR .BTCUSDTFR8H
ETHUSDT .ETHUSDT .METHUSDT .ETHUSDTFR .ETHUSDTFR8H
XRPUSDT .XRPUSDT .MXRPUSDT .XRPUSDTFR .XRPUSDTFR8H
ADAUSDT .ADAUSDT .MADAUSDT .ADAUSDTFR .ADAUSDTFR8H

Request format * The symbol in params can be replace by any symbol. javascript { "method": "tick_p.subscribe", "params": [ <symbol> ], "id": <id> }

Response format javascript { "error": null, "id": <id>, "result": { "status": "success" } }

push event

Response format javascript { "tick": { "last": <price>, "symbol": <symbol> "timestamp": <timestamp_nano> } }

Response sample json {"tick_p":{"last":"20639.38692364","symbol":".BTCUSDT","timestamp":1666863393552000000}} json {"tick_p":{"last":"20639.15408363","symbol":".BTCUSDT","timestamp":1666863394538132741}}

Spot REST API

Endpoint security type

Query product information

Request

GET /public/products

Query server time

Request

GET /public/time

Response sample

{
    "code": 0,
    "msg": "",
    "data": {
        "serverTime": 1676172826345
    }
}

Price/Ratio/Value scales

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

NOTE:
1) ratioScale is always scaled 8.
2) priceScale follows the valueScale of quote-currency, and must follow quote-ticksize criteria.
e.g. priceScale of sBTCUSDT and sPEPEUSDT follow USDT-valueScale, i.e. 1e8; the scaled price of sBTCUSDT must be multiple times of quoteTickSizeEv=1e6.
3) qtySale follows the valueScale of base-currency, and must follow base-tickSize criteria.
e.g. qtyScale of sETHUSDT follows ETH-valueScale, i.e. 1e8; the scaled qty of sETHUSDT must be mulitple times of baseTickSizeEv=10000.

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>&priceEp=<priceEp>&baseQtyEV=<baseQtyEV>&quoteQtyEv=<quoteQtyEv>&stopPxEp=<stopPxEp>
Field Type Required Description
symbol Yes order symbol, cannot be changed
orderID - order id, cannot be changed
origClOrdID - origClOrdID , cannot be changed
priceRp - new order price, real value
orderQtyRq Yes new orderQty, real value
stopPxRp Yes new stop price, real value

orderID and origClOrdID can't both be empty

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

Parameter Type Required Description Case
currency String No the currency to query BTC, USDT...

NOTE: GET /spot/wallets queries the wallets of all currencies

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

{
  "code": 0,
  "msg": "OK",
  "data": {
    "rows":[{
      "id": 0,
      "currency": "string",
      "execId": "string",
      "amountEv": 0,
      "feeEv": 0,
      "side": "string",
      "action": "string",
      "balanceEv": 0,
      "bizCode": 0,
      "execSeq": 0,
      "transactTimeNs": 0,
      "text": "string",
      "createTime": 0,
    }]
  }
}
Field Type Required Description Possible Values
Currency String True the currency to query USDT,TRY,BRZ,USDC, ...

Query fee rate by quote currency

Request format

GET /api-data/spots/fee-rate?quoteCurrency=<quoteCurrency>

Response format

{
  "symbolFeeRates": [
    {
      "takerFeeRateEr": 80000,
      "makerFeeRateEr": 80000,
      "symbol": "sETHTRY"
    }
  ]
}
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 for all symbols

Request format

GET /md/spot/ticker/24hr/all

Response format

{
  "error": null,
  "id": 0,
  "result": [
    {
      "openEp": <open priceEp>,
      "highEp": <high priceEp>,
      "lowEp": <low priceEp>, 
      "indexEp": <index priceEp>,
      "lastEp": <last priceEp>,
      "bidEp": <bid priceEp>,
      "askEp": <ask priceEp>,
      "symbol": "<symbol>",
      "turnoverEv": <turnoverEv>,
      "volumeEv": <volumeEv>,
      "timestamp": <timestamp>
    }
  ]
}
Field Type Description Possible Value
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
index priceEp Integer The scaled index 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

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

Margin Trading API

Endpoint security type

Query product information

Request

GET /public/products

Price/Ratio/Value scales

Fields with post-fix "Rp", "Rr", "Rq" or "Rv" are real value.

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 /margin-trade/orders/create?symbol=<symbol>&trigger=<trigger>&clOrdID=<clOrdID>&priceRp=<priceRp>&baseQtyRq=<baseQtyRq>&quoteQtyRq=<quoteQtyRq>&stopPxRp=<stopPxRp>&text=<text>&side=<side>&qtyType=<qtyType>&ordType=<ordType>&timeInForce=<timeInForce>&execInst=<execInst>&autoBorrow=<autoBorrow>&borrowCurrency=<borrowCurrency>&borrowQtyRq=<borrowQtyRq>&autoPayback=<autoPayback>&paybackCurrency=<paybackCurrency>&paybackQtyRq=<paybackQtyRq>

Response format

{
  "code": 0,
  "msg": "",
  "data": {
    "orderID": "d1d09454-cabc-4a23-89a7-59d43363f16d",
    "clOrdID": "309bcd5c-9f6e-4a68-b775-4494542eb5cb",
    "priceRp": "0",
    "action": "New",
    "trigger": "UNSPECIFIED",
    "pegPriceType": "UNSPECIFIED",
    "stopDirection": "UNSPECIFIED",
    "bizError": 0,
    "symbol": "sBTCUSDT",
    "side": "Buy",
    "baseQtyRq": "0",
    "ordType": "Limit",
    "timeInForce": "GoodTillCancel",
    "ordStatus": "Created",
    "cumFeeRv": "0",
    "cumBaseQtyRq": "0",
    "cumQuoteQtyRq": "0",
    "leavesBaseQtyRq": "0",
    "leavesQuoteQtyRq": "0",
    "avgPriceRp": "0",
    "cumBaseAmountRv": "0",
    "cumQuoteAmountRv": "0",
    "quoteQtyRq": "0",
    "qtyType": "ByBase",
    "stopPxRp": "0",
    "pegOffsetValueRp": "0",
    "autoBorrow": false,
    "borrowCurrency": 1,
    "borrowQtyRq": "0",
    "autoPayback": false,
    "paybackCurrency": 1,
    "paybackPrincipalQtyRq": "0",
    "paybackInterestQtyRq": "0",
    "hourlyInterestRateRr": "0",
    "riskLevelRr": "0",
    "liqFeeRv": "0",
    "liqFeeRateRr": "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
quoteQtyRq String -- Required if qtyType = ByQuote
baseQtyRq String -- Required if qtyType = ByBase
priceRp String real price
stopPxRp String -- 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
autoBorrow Boolean No false
borrowCurrency String No BTC,USDT
borrowQtyRq String No
autoPayback Boolean No false
paybackCurrency String No BTC,USDT
paybackQtyRq String No

Cancel order

Request format

DELETE /margin-trade/orders?symbol=<symbol>&orderID=<orderID>
DELETE /margin-trade/orders?symbol=<symbol>&clOrdID=<clOrdID>

Cancel all order by symbol

Request format

DELETE /margin-trade/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 /margin-trade/orders/active?symbol=<symbol>&orderID=<orderID>
GET /margin-trade/orders/active?symbol=<symbol>&clOrDID=<clOrdID>

Query all open orders by symbol

Request format

GET /margin-trade/orders?symbol=<symbol>

Query margin orders details

Request format

GET /margin/orders?symbol=<symbol>&ordStatus=<ordStatus>&ordType=<ordType>&start=<start>&end=<end>&pageNum=<pageNum>&pageSize=<pageSize>
Parameter Type Required Description Case
symbol String NO spot symbol sBTCUSDT
ordStatus String NO Filled
ordType String NO Market
start Long NO start order index, default 0
end Long NO end order index, default 0
pageNum Long NO page number, default 0
pageSize Integer NO pageable size, default 20

Response Format

{
  "code": 0,
  "msg": "OK",
  "data": {
    "total": 1,
    "rows": [
      {
        "orderId": "f6256e4f-0f0f-40bd-b26e-2c3e5afd02f5",
        "clOrdId": "2337fc19-7db0-f0c7-6ff9-404234a78c3c",
        "stopPxRp": "0",
        "avgPriceRp": "24747.95059307",
        "qtyType": "ByBase",
        "leavesBaseQtyRq": "0",
        "leavesQuoteQtyRq": "0",
        "baseQtyRq": "0.349332",
        "feeCurrency": "USDT",
        "stopDirection": "UNSPECIFIED",
        "symbol": "sBTCUSDT",
        "side": "Sell",
        "quoteQtyRq": "0",
        "priceRp": "22211.84",
        "ordType": "Market",
        "timeInForce": "ImmediateOrCancel",
        "ordStatus": "Filled",
        "execStatus": "TakerFill",
        "createTimeNs": 1676893028372924849,
        "cumFeeRv": "8.64525109",
        "cumBaseValueRv": "0.349332",
        "cumQuoteValueRv": "8645.25107658",
        "detailVos": null
      }
    ]
  }
}

Query margin order trades details

Request format

GET /margin/orders/trades?symbol=<symbol>&execType=<execType>&start=<start>&end=<end>&pageNum=<pageNum>&pageSize=<pageSize>
Parameter Type Required Description Case
symbol String NO spot symbol sBTCUSDT
execType String NO Trade
start Long NO start order index, default 0
end Long NO end order index, default 0
pageNum Long NO page number, default 0
pageSize Integer NO pageable size, default 20

Response format

{
    "code": 0,
    "msg": "OK",
    "data": {
        "total": 1,
        "rows": [
            {
                "transactTimeNs": 1675181154118252379,
                "execType": "Amend",
                "qtyType": "ByQuote",
                "clOrdId": "6bbbf1d2-42a1-70ef-e272-168b524353b4",
                "orderId": "c111c403-ace7-43ec-a7a6-6c6ef012fdfe",
                "symbol": "sBTCUSDT",
                "side": "Buy",
                "priceRp": "25437.04",
                "baseQtyRq": "0",
                "quoteQtyRq": "2443.28",
                "action": "New",
                "execStatus": "TakerFill",
                "ordStatus": "PartiallyFilled",
                "ordType": "Market",
                "execInst": "None",
                "timeInForce": "ImmediateOrCancel",
                "stopDirection": "UNSPECIFIED",
                "stopPxRp": "0",
                "execId": "e7717c8a-5fd2-5360-a7e3-de5c29f24639",
                "execPriceRp": "23124.59",
                "execBaseQtyRq": "0.01126",
                "execQuoteQtyRq": "260.3828834",
                "leavesBaseQtyRq": "0",
                "leavesQuoteQtyRq": "2182.8971166",
                "execFeeRv": "0.00001126",
                "feeRateRr": "0.001",
                "baseCurrency": "BTC",
                "quoteCurrency": "USDT",
                "feeCurrency": "BTC"
            }
        ]
    }
}

Query margin borrow interest history

Request format

GET /margin/borrow/interests?currency=<currencyList>&start=<start>&end=<end>&pageNum=<pageNum>&pageSize=<pageSize>
Parameter Type Required Description Case
currency List NO currency list USDT,BTC
start Long NO default 0
end Long NO default 0
pageNum Long NO default 0
pageSize Integer NO default 20

Response format

{
    "code": 0,
    "msg": "OK",
    "data": {
        "total": 1,
        "rows": [
            {
                "borrowCurrency": "USDT",
                "interestCalcTime": 1678975566487,
                "interestCurrency": "USDT",
                "hourlyInterestRv": "0.00013254",
                "hourlyRateRr": "0.00000551",
                "annualRateRr": "0.0482676"
            }
        ]
    }
}

Query margin borrow history records

Request format

GET /margin/borrow?currency=<currency>&start=<start>&end=<end>&pageNum=<pageNum>&pageSize=<pageSize>
Parameter Type Required Description Case
Currency String NO USDT
start Long NO default 0
end Long NO default 0
pageNum Long NO default 0
pageSize Integer NO default 20

Response format

{
  "code": 0,
  "msg": "OK",
  "data": {
    "total": 1,
    "rows": [
      {
        "currency": "USDT",
        "borrowTime": 1677211672675,
        "amountRv": "94.05",
        "type": 1,
        "status": "Success"
      }
    ]
  }
}

Query margin payback history

Request format

GET /margin/payback?currency=<currency>&start=<start>&end=<end>&pageNum=<pageNum>&pageSize=<pageSize>
Parameter Type Required Description Case
currency String NO USDT
start Long NO default 0
end Long NO default 0
pageNum Long NO default 0
pageSize Integer NO default 20

Response format

{
    "code": 0,
    "msg": "OK",
    "data": {
        "total": 1,
        "rows": [
            {
                "currency": "USDT",
                "repayTime": 1678976978535,
                "principalAmountRv": "24.05469895",
                "interestAmountRv": "0.019881",
                "liqFeeRv": "0",
                "type": 1,
                "status": "Success"
            }
        ]
    }
}

Post margin borrow request

Request format

POST /margin/borrow?currency=<currency>&amountRv=<amountRv>
Parameter Type Required Description Case
currency String YES borrow currency USDT
amountRv String YES borrow amount real value 1000.12

Response format

{
  "code": 0,
  "msg": "OK",
  "data": {
    "maxBorrowAmountRq": "80000",
    "borrowedAmountRq": "40",
    "currency": "USDT"
  }
}

Post margin payback history

Request format

POST /margin/payback?currency=<currency>&amountRv=<amountRv>
Parameter Type Required Description Case
currency String YES payback currency USDT
amountRv String YES payback amount real value 1000.12

Response format

{
  "code": 0,
  "msg": "OK",
  "data": {
    "maxBorrowAmountRq": "80000",
    "borrowedAmountRq": "40",
    "currency": "USDT"
  }
}

Query wallets

Parameter Type Required Description Case
currency String No the currency to query BTC, USDT...

NOTE: GET /margin-trade/wallets queries the wallets of all currencies

Request format

GET /margin-trade/wallets?currency=<currency>

Response format

{
  "code": 0,
  "msg": "",
  "data": [
    {
      "currency": "BTC",
      "balanceRq": "0",
      "lockedTradingBalanceRq": "0",
      "lockedWithdrawRq": "0",
      "borrowedRq": "0",
      "cumInterestRq": "0",
      "lastUpdateTimeNs": 0
    }
  ]
}

Query order book the same as the spot api

Query full order book the same as the spot api

Query recent trades the same as the spot api

Query 24 hours ticker the same as the spot api

Margin Trading Websocket API

the same as above Spot Websocket API

Subscribe margin account and order

Request

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

Message sample: incremental json { "wallets_mao": [{ "balanceRv": "6300000054.015", "currency": "BTC", "lastUpdateTimeNs": 1587547210089640382, "lockedTradingBalanceRv": "2", "lockedWithdrawRv": "0", "borrowedRv": "12", "cumInterestRv": "0.5", "hourlyInterestRateRr": "0.0012", "maxAmountToBorrowRv": "100", "userID": 200076 }, { "balanceRv": "3518.025", "currency": "USDT", "lastUpdateTimeNs": 1587543489127498121, "lockedTradingBalanceRv": "0", "lockedWithdrawRv": "0", "borrowedRv": "12", "cumInterestRv": "0.5", "hourlyInterestRateRr": "0.0012", "maxAmountToBorrowRv": "100", "userID": 200076 }], "orders_mao": { "closed": [], "fills": [], "open": [{ "action": "New", "avgPriceRp": "0", "baseCurrency": "BTC", "baseQtyRq": "10000", "bizError": 0, "clOrdID": "0c1099e5-b900-5351-cf60-edb15ea2539c", "createTimeNs": 1587549529513521745, "cumBaseQtyRq": "0", "cumFeeRv": "0", "cumQuoteQtyRq": "0", "curBaseWalletQtyRq": "6300000.0540150", "curQuoteWalletQtyRq": "3518.0250", "cxlRejReason": 0, "feeCurrency": "BTC", "leavesBaseQtyRq": "1", "leavesQuoteQtyRq": "0", "ordStatus": "New", "ordType": "Limit", "orderID": "494a6cbb-32b3-4d6a-b9b7-196ea2506fb5", "pegOffsetValueRv": "0", "priceRp": "6665", "qtyType": "ByBase", "quoteCurrency": "USDT", "quoteQtyRq": "0", "side": "Sell", "stopPxRp": "0", "symbol": "sBTCUSDT", "timeInForce": "GoodTillCancel", "transactTimeNs": 1587549529518394235, "triggerTimeNs": 0, "userID": 200076 }] }, "sequence": 350, "timestamp": 1587549529519959388, "type": "incremental" }

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
side Integer True Direction 1 - futures to spot, 2 - spot to futures
bizType Integer True Business type 11 - futures to spot, 10 - spot to futures
status Integer True transfer status 0 - PENDING, 10 - DONE, 11 - FAILED

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 transfer history of spot accounts between main and sub

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
Field Type Description
status Integer PENDING(0), DONE(10), FAILED(11)

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 transfer history of contract accounts between main and sub

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
Field Type Description
bizCode Integer PARENT_TO_SUB_TRANSFER(3), SUB_TO_PARENT_TRANSFER(4)

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

New Transfer REST API (Universal Transfer REST API)

Transfer between wallets within an account

Request format

POST /wallets/account/transfer

{
  "fromAccType": "SPOT",
  "toAccType": "CONTRACT",
  "amountEv": 100000000,
  "amount": "1",
  "currency": "USDT"
}

Response format

{
  "code": 0,
  "msg": null,
  "data": {
    "amountEv": 10000000,
    "currency": "USDT",
    "status": 10,
    "bizCode": 10,
    "createTime": 1706601733000
  }
}
  1. During the transfer, the fromAccType and toAccType cannot be the same value.
  2. The amountEv is the scaled-up value of the original amount amount. Both values are required and are used to verify the correctness of the amount.
Field Type Required Description Possible Values
fromAccType String True Transfer out wallet type SPOT, CONTRACT, MARGIN, COPY_TRADE
toAccType String True Transfer in wallet type SPOT, CONTRACT, MARGIN, COPY_TRADE
amountEv Long True AmountEv to transfer 100000000
amount String True Origin amount to transfer 1
currency String True Currency to transfer BTC,ETH,USDT ...

Transfer between main and sub-accounts

  1. Under main account login, transfers between sub-accounts and the main account or between sub-accounts are supported
  2. When logged in under a non-main account: Only transfers from the current account to the main account are allowed

Request format

POST /wallets/account/main-sub-transfer

{
  "fromUid": 99900001,
  "fromAccType": "SPOT",
  "toUid": 99900002,
  "toAccType": "SPOT",
  "amountEv": 100000000,
  "amount": "1",
  "currency": "USDT"
}

Response format

{
  "code": 0,
  "msg": null,
  "data": {
    "amountEv": 10000000,
    "currency": "USDT",
    "status": 10,
    "bizCode": 3,
    "createTime": 1706601733000
  }
}
Field Type Required Description Possible Values
fromUid Long True Uid for transfer out
fromAccType String True Transfer out wallet type SPOT, CONTRACT, MARGIN
toUid Long True Uid for transfer in
toAccType String True Transfer in wallet type SPOT, CONTRACT, MARGIN
amountEv Long True AmountEv to transfer 100000000
amount String True Origin amount to transfer 1
currency String True Currency to transfer BTC,ETH,USDT ...

Query account wallet transfer history

Currently, only transfer records from the past 3 months is supported for queries.

GET /wallets/account/transfer

Supports multiple bizTypes parameters separated by ',' for example: bizTypes=3,4

Field Type Required Description Possible Values
currency String False The currency to query BTC,ETH ...
bizTypes Array False Business type for transfer 3: transfer to sub-accounts
4: transfer to main account
10: Spot transfer to Contract wallet
11: Contract transfer to Spot wallet
90: Copy trade transfer
213: Margin wallet transfer
start Long False Start time in millisecond Default to 3 months ago from the end
end Long False End time in millisecond Default to now
pageNum Integer False Page start from 0 Start from 1, default 1
pageSize Integer False Page size Default to 20, max 20

Response format

{
  "code": 0,
  "data": {
    "total": 1,
    "rows": [
      {
        "formUserId": 99900001,
        "toUserId": 99900001,
        "fromAccType": "SPOT",
        "toAccType": "CONTRACT",
        "currency": "USDT",
        "amountEv": 100000000,
        "amount": 1,
        "status": 10,
        "bizCode": 3,
        "requestKey": "13adf",
        "requestTime": 1706601733000
      }
    ]
  }
}

Deposit And Withdraw REST API

Endpoint Security Type

Price/Ratio/Value

Query deposit address information

Request Format

GET /phemex-deposit/wallets/api/depositAddress?currency=<currency>&chainName=<chainName>
Parameter Type Required Description Case
currency String YES coin name USDT
chainName String YES chain name ETH

Response Format

{
  "code": 0,
  "msg": "OK",
  "data": {
    "address": "44exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "tag": ""
  }
}
Field Type Description
address String deposit address
tag String chain address tag

Query deposit history records

Request format

GET /phemex-deposit/wallets/api/depositHist?currency=<currency>&offset=<offset>&limit=<limit>&withCount=<withCount>
Parameter Type Required Description Case
currency List NO batch coin name list ETH,BTC
offset String NO query rows offset ,default 0
limit Integer NO limit rows return, default 20
withCount Boolean NO return total rows or not True

Response Format

{
    "code": 0,
    "msg": "OK",
    "data": [
        {
            "accountType": 1,
            "address": "44exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "amountEv": 50000000,
            "chainCode": 1,
            "chainName": "BTC",
            "confirmations": 1,
            "confirmedHeight": null,
            "createdAt": 1670000000000,
            "currency": "BTC",
            "currencyCode": 1,
            "email": "abcdefg@gmail.com",
            "errorCode": null,
            "errMsg": null,
            "id": 1,
            "needConfirmHeight": null,
            "status": "Success",
            "transferStatus": null,
            "txHash": "567exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "type": "Deposit",
            "userId": 10000001
        }
    ]
}
Field Type Required Description Possible Values
depositTo String YES deposit account type SPOT, Contract
address String Yes deposit Address
amount Long Yes deposit Amount
chainCode Integer Yes
chainName String Yes
confirmations Long chain confirmed block
confirmedHeight Long chain block height
createdAt Long YES created time
currency String YES
currencyCode Integer YES
email String email Address
errorCode Integer
errMsg String
id String YES record unique id
needConfirmHeight Long chain confirmed total height
status String YES please refer to deposit status
txHash String
type Enum Yes Deposit Type Deposit & CompensateDeposit
userId Long Yes

Deposit status

Status Description
Success Succeed deposit to Phemex account
Rejected Possible deposit address not supported
SecurityChecking Risk control center is processing incoming withdraw request
SecurityCheckFailed Failure to pass Risk control center security rules
AmlCsApporve AML rule broken, Phemex support team manually approve
Confirmed Deposit confirmed
New Newly submitted deposit

Query deposit chain settings

Request format

GET /phemex-deposit/wallets/api/chainCfg?currency=<currency>
Parameter Type Required Description Case
currency String YES coin name ETH

Response Format

{
    "code": 0,
    "msg": "OK",
    "data": [
        {
            "currency": "TRX",
            "currencyCode": 11,
            "minAmountRv": "0",
            "confirmations": 1,
            "chainCode": 11,
            "chainName": "TRX",
            "status": "Active"
        }
    ]
}
Field Type Required Description Case
currency String YES coin name TRX
currencyCode Integer YES coin code 11
minAmountRv String minimal deposit amount
confirmations Long chain confirmation height
chainCode Integer YES chain code
chainName String YES chain name
status String YES chain status, Active Or Suspend

Query withdraw history records

Request format

GET /phemex-withdraw/wallets/api/withdrawHist?currency=<currency>&chainName=<chainNameList>&offset=<offset>&limit=<limit>&withCount=<withCount>
Parameter Type Required Description Case
currency List NO currency name list USDT, ETH
chainName List NO chain name list ETH,TRX
offset Long NO default 0
limit Integer NO default 20
withCount Boolean NO Total conditional rows found, default False True

Response Format

{
    "code": 0,
    "msg": "OK",
    "data": [
        {
            "id": 100,
            "address": "44exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "amountEv": 220000000,
            "chainCode": 11,
            "chainName": "TRX",
            "currency": "TRX",
            "currencyCode": 11,
            "email": "1234qwer@gmail.com",
            "expiredAt": 1657000000000,
            "feeEv": 100000000,
            "nickName": null,
            "phone": null,
            "rejectReason": "",
            "submitedAt": 1657000000000,
            "txHash": "44exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "userId": 100000001,
            "status": "Succeed"
        }
    ]
}
Field Type Required Description Possible Values
id Long YES unique identifier
address String YES chain address
amountEv Long YES received amount
chainCode Integer YES chain code
chainName String YES chain name
email String
expiredAt Long YES expired time
feeEv Long YES withdraw real fee
nickName String
phone String
rejectReason String
submitedAt Long YES
txHash String chain transfer hash key
userId Long YES
status String YES withdraw status please refer to withdraw status

Withdraw status

Status Description
Success Done
Rejected Possible withdraw address mismatch
Security Checking Risk control center is processing incoming withdraw request
Security check failed Failure to pass Risk control center security rules
Pending Review Risk rule exposure
Address Risk Dangerous address detected
Expired Withdraw request timeout,normally 30 minutes
Cancelled Manually cancelled by client
Pending Transfer Security checking rules passed, prepare to transfer assets to target address

Create withdraw request

Request Format

POST /phemex-withdraw/wallets/api/createWithdraw?currency=<currency>&address=<address>&amount=<amount>&addressTag=<addressTag>&chainName=<chainName>
Parameter Type Required Description Case
currency String YES currency name "ETH"
address String YES withdraw address "11xxxxxxxxxxxxxxxxxxxxx"
amount String YES withdraw amount "1.234"
addressTag String NO Address tag
chainName String YES chain Name "TRX"

Response Format

{
    "code": 0,
    "msg": "OK",
    "data": {
        "id": 10000001,
        "address": "44exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "amountRv": "100",
        "chainCode": 11,
        "chainName": "TRX",
        "currency": "USDT",
        "currencyCode": 3,
        "email": "abc@gmail.com",
        "expiredAt": 1670000000000,
        "feeRv": "1",
        "nickName": null,
        "phone": null,
        "rejectReason": "",
        "submitedAt": 1670000000000,
        "txHash": null,
        "userId": 10000001,
        "status": "Success"
    }
}
Field Type Required Description Possible Values
id Long YES withdraw request unique identifier
address String YES chain address
amountRv String YES receive amount
chainCode Integer YES chain code 4
chainName String YES chain name ETH
currency String YES coin name
currencyCode Integer YES coin code
email String user email address
expiredAt Timestamp YES withdraw request expired time
feeRv String YES withdraw fee
nickName String
phone String
rejectReason String
submitedAt Timestamp YES
txHash String chain transfer hash
userId Long YES
status String YES please refer to withdraw status

Cancel withdraw request

Request format

POST /phemex-withdraw/wallets/api/cancelWithdraw?id=<id>
Parameter Type Required Description Case
id Long YES withdraw request unique identifier 10001

Response Format

{
    "code": 0,
    "msg": "OK",
    "data": "OK"
}

Query withdraw chain settings

Request format

GET /phemex-withdraw/wallets/api/asset/info?currency=<currency>&amount=<amount>
Parameter Type Required Description Case
currency String NO coin name "ETH"
amount String NO withdraw amount with fee "0.1234"

Response format

{
  "code": 0,
  "msg": "ok",
  "data": {
    "currency": "USDT",
    "currencyCode": 3,
    "balanceRv": "100.000001",
    "confirmAmountRv": "0",
    "allAvailableBalanceRv": "1.000001",
    "chainInfos": [
      {
        "chainCode": 4,
        "chainName": "ETH",
        "minWithdrawAmountRv": "2",
        "minWithdrawAmountWithFeeRv": "6",
        "withdrawFeeRv": "4",
        "receiveAmountRv": "0"
      },
      {
        "chainCode": 11,
        "chainName": "TRX",
        "minWithdrawAmountRv": "2",
        "minWithdrawAmountWithFeeRv": "3",
        "withdrawFeeRv": "1",
        "receiveAmountRv": "0"
      }
    ]
  }
}
Field Type Required Description Possible Value
currency String YES coin name ETH
currencyCode Integer YES coin code 4
balanceRv String YES total balance
confirmAmountRv String apply for non kyc user only, lifetime remaining amount left
allAvailableBalanceRv String YES total balance minus locked trading balance, locked withdraw balance and frozen balance
chainCode Integer YES chain code
chainName String YES chain name
minWithdrawAmountRv String minimal withdraw amount
minWithdrawAmountWithFeeRv String minimal withdraw amount with fee
withdrawFeeRv String withdraw fee required for user input withdraw amount
receiveAmountRv String received withdraw amount for user input withdraw amount