├── README.md ├── Generic-API-Info.en.md ├── TradingErrorCode.md ├── Public-Transfer-API-en.md ├── Public-Spot-API-en.md └── Public-Hedged-Perpetual-API.md /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Phemex API Reference 3 | * CCXT is our authorized SDK provider and you may access the Phemex API through CCXT. For more information, please visit: https://ccxt.trade. 4 | 5 | ## Phemex Public API Reference 6 | * Public Contract Rest and WebSocket API reference (English): https://github.com/phemex/phemex-api-docs/blob/master/Public-Contract-API-en.md 7 | * Public Spot Rest and WebSocket API reference (English): https://github.com/phemex/phemex-api-docs/blob/master/Public-Spot-API-en.md 8 | * Sample: https://github.com/phemex/java-client 9 | 10 | ## Asset Transfer API 11 | * Asset Transfer API: https://github.com/phemex/phemex-api-docs/blob/master/Public-Transfer-API-en.md 12 | -------------------------------------------------------------------------------- /Generic-API-Info.en.md: -------------------------------------------------------------------------------- 1 | ## Table of Contents 2 | 3 | * [Rate Limits](#ratelimit) 4 | * [IP RateLimit](#ipratelimit) 5 | * [API RateLimit Rules](#apiratelimitrule) 6 | * [API Groups](#apigroup) 7 | * [New Contract API RateLimit Rules](#newcontractapiratelimitrule) 8 | 9 | 10 | 11 | ## Rate Limits 12 | 13 | * In order to prevent API abuse, Phemex applies `API RateLimit` and `IP Ratelimit` on all requests. 14 | 15 | * Rest API has a request capacity in one-minute window on user basis. 16 | 17 | * IP has request capacity in 5-minute window. 18 | 19 | * Ratelimit of API is ***independant*** of that in WEB/APP, so if one gets rate limited in API, one can still place/cancel 20 | orders via WEB or APP. 21 | 22 | 23 | 24 | ### IP Ratelimit 25 | 26 | Currently Phemex restrict every IP 5,000 requests in 5-minute window. 27 | 28 | If the rate limit has been breached, user request would be blocked in the following 5 minutes. 29 | 30 | 31 | 32 | ### API RateLimit Rules 33 | 34 | * All Phemex APIs are divided into 3 groups, `contract`, `spotOrder` and `others`. 35 | * All APIs in the same group share the same total group capacity. 36 | * Every API consume its own corresponding weight. 37 | * If the ratelimit is violated, http status 429 will be returned, together with a reset time in seconds 38 | header `x-ratelimit-retry-after-` 39 | 40 | * Ratelimit headers 41 | Below headers are returned with API response. Postfix `-` is empty if the group is others 42 | 43 | | Header name | Description | 44 | |--------------|-------------| 45 | | x-ratelimit-remaining-*groupName* | Remaining request permits in this minute | 46 | | x-ratelimit-capacity-*groupName* | Request ratelimit capacity | 47 | | x-ratelimit-retry-after-*groupName* | Reset timeout in seconds for current ratelimited user | 48 | 49 | * Group capacity 50 | 51 | | Group Name | Capacity | 52 | |------------|---------| 53 | | Contract | 500/minute | 54 | | SpotOrder | 500/minute | 55 | | Others | 100/minute | 56 | 57 | 58 | 59 | ### Api Groups 60 | 61 | 62 | * Contract group 63 | 64 | Contract group is for contract trading, it contains following api. 65 | 66 | | Path | Method | Weight | Description | 67 | |------|--------|--------|-------------| 68 | | /orders | POST | 1 | Place new order | 69 | | /orders/replace | PUT | 1 | Amend order | 70 | | /orders/cancel | DELETE | 1 | Cancel order | 71 | | /orders/all | DELETE | 3 | Cancel all order by symbol | 72 | | /orders | DELETE | 1 | cancel orders | 73 | | /orders/activeList | GET | 1 | Query open orders by symbol | 74 | | /orders/active | GET | 1 | Query open order by orderID | 75 | | /accounts/accountPositions | GET | 1 | Query account & position by currency | 76 | | /accounts/positions | GET | 25 | Query positions with un-realized-pnl | 77 | 78 | * SpotOrder group 79 | 80 | 81 | SpotOrder group is for spot trading, which contains following api. 82 | 83 | | Path | Method | Weight | Description | 84 | |------|--------|--------|-------------| 85 | | /spot/orders | POST | 1 | Place spot order | 86 | | /spot/orders | PUT | 1 | Amend spot order | 87 | | /spot/orders | DELETE | 2 | Cancel spot order | 88 | | /spot/orders/all | DELETE | 2 | Cancel spot orders by symbol | 89 | | /spot/orders/active | GET | 1 | Query open spot order | 90 | | /spot/orders | GET | 1 | Query all open spot orders by symbol | 91 | 92 | * Others 93 | 94 | 95 | 96 | APIs which is not in contract or spotOrder group are categorized into other group. 97 | 98 | As the number of interfaces in Other group may grow over time, the list below is not exhausted, the items in the 99 | table highlight interfaces that has weight other than 1, or interfaces that Phemex deems important. 100 | 101 | | Path | Method | Weight | Description | 102 | |------|--------|--------|--------------| 103 | | /exchange/public/md/kline | GET | 10 | kline query | 104 | 105 | 106 | 107 | 108 | ### New Contract API RateLimit Rules (for VAPI/VIP only) 109 | 110 | * Contract API currently employs new rate-limit rules based on symbols, according to Phemex internal configuration of uid individually. 111 | * Under the new throttling rules, Contract API consumes both contract group capacity (5000/minute) and symbol group capacity (500/minute) at the same time, but the each capacity of different symbols are independent from one another. 112 | * Contract API that may involve all symbols like 'cancel all' consumes request capacity under a special group named 'CONTACT_ALL_SYM'. 113 | 114 | * Ratelimit headers added in the symbol dimension. 115 | 116 | | Header name | Description | 117 | |-------------------------------------------------|---------------------------------------------------------------------------| 118 | | x-ratelimit-remaining-*groupName_symbol* | Remaining request ratelimit in the symbol group in this minute | 119 | | x-ratelimit-capacity-*groupName_symbol* | Total request capacity in the symbol group | 120 | | x-ratelimit-retry-after-*groupName_symbol* | Reset timeout in seconds for current ratelimited user in the symbol group | 121 | 122 | * Special Contract Group Capacity 123 | 124 | | Group Name | Capacity | 125 | |-----------------|-------------| 126 | | Contract | 5000/minute | 127 | | Contract_SYMBOL | 500/minute | 128 | | CONTACT_ALL_SYM | 500/minute | 129 | 130 | 131 | -------------------------------------------------------------------------------- /TradingErrorCode.md: -------------------------------------------------------------------------------- 1 | ## BizError Field 2 | 3 | | code | Message | Description | 4 | |---------|-------------|-----------------| 5 | | 19999 | REQUEST_IS_DUPLICATED | Details: Duplicated request ID | 6 | | 10001 | OM_DUPLICATE_ORDERID | Details: Duplicated order ID | 7 | | 10002 | OM_ORDER_NOT_FOUND | Details: Cannot find order ID | 8 | | 10003 | OM_ORDER_PENDING_CANCEL | Details: Cannot cancel while order is already in pending cancel status | 9 | | 10004 | OM_ORDER_PENDING_REPLACE | Details: Cannot cancel while order is already in pending cancel status | 10 | | 10005 | OM_ORDER_PENDING | Details: Cannot cancel while order is already in pending cancel status | 11 | | 11001 | TE_NO_ENOUGH_AVAILABLE_BALANCE | Details: Insufficient available balance | 12 | | 11002 | TE_INVALID_RISK_LIMIT | Details: Invalid risk limit value | 13 | | 11003 | TE_NO_ENOUGH_BALANCE_FOR_NEW_RISK_LIMIT | Details: Insufficient available balance | 14 | | 11004 | TE_INVALID_LEVERAGE | Details: invalid input or new leverage is over maximum allowed leverage | 15 | | 11005 | TE_NO_ENOUGH_BALANCE_FOR_NEW_LEVERAGE | Details: Insufficient available balance | 16 | | 11006 | TE_CANNOT_CHANGE_POSITION_MARGIN_WITHOUT_POSITION | Details: Position size is zero. Cannot change margin | 17 | | 11007 | TE_CANNOT_CHANGE_POSITION_MARGIN_FOR_CROSS_MARGIN | Details: Cannot change margin under CrossMargin | 18 | | 11008 | TE_CANNOT_REMOVE_POSITION_MARGIN_MORE_THAN_ADDED | Details: exceeds the maximum removable Margin | 19 | | 11009 | TE_CANNOT_REMOVE_POSITION_MARGIN_DUE_TO_UNREALIZED_PNL | Details: exceeds the maximum removable Margin | 20 | | 11010 | TE_CANNOT_ADD_POSITION_MARGIN_DUE_TO_NO_ENOUGH_AVAILABLE_BALANCE | Details: Insufficient available balance | 21 | | 11011 | TE_REDUCE_ONLY_ABORT | Details: Cannot accept reduce only order | 22 | | 11012 | TE_REPLACE_TO_INVALID_QTY | Details: Order quantity Error | 23 | | 11013 | TE_CONDITIONAL_NO_POSITION | Details: Position size is zero. Cannot determine conditional order's quantity | 24 | | 11014 | TE_CONDITIONAL_CLOSE_POSITION_WRONG_SIDE | Details: Close position conditional order has the same side | 25 | | 11015 | TE_CONDITIONAL_TRIGGERED_OR_CANCELED | | 26 | | 11016 | TE_ADL_NOT_TRADING_REQUESTED_ACCOUNT | Details: Request is routed to the wrong trading engine | 27 | | 11017 | TE_ADL_CANNOT_FIND_POSITION | Details: Cannot find requested position on current account | 28 | | 11018 | TE_NO_NEED_TO_SETTLE_FUNDING | Details: The current account does not need to pay a funding fee | 29 | | 11019 | TE_FUNDING_ALREADY_SETTLED | Details: The current account already pays the funding fee | 30 | | 11020 | TE_CANNOT_TRANSFER_OUT_DUE_TO_BONUS = 11020; | Details: Withdraw to wallet needs to remove all remaining bonus. However if bonus is used by position or order cost, withdraw fails. | 31 | | 11021 | TE_INVALID_BONOUS_AMOUNT = 11021; // Grpc command cannot be negative number | Details: Invalid bonus amount | 32 | | 11022 | TE_REJECT_DUE_TO_BANNED = 11022; | Details: Account is banned | 33 | | 11023 | TE_REJECT_DUE_TO_IN_PROCESS_OF_LIQ = 11023; | Details: Account is in the process of liquidation | 34 | | 11024 | TE_REJECT_DUE_TO_IN_PROCESS_OF_ADL = 11024; | Details: Account is in the process of auto-deleverage | 35 | | 11025 | TE_ROUTE_ERROR = 11025; | Details: Request is routed to the wrong trading engine | 36 | | 11026 | TE_UID_ACCOUNT_MISMATCH = 11026; | | 37 | | 11027 | TE_SYMBOL_INVALID = 11027; | Details: Invalid number ID or name | 38 | | 11028 | TE_CURRENCY_INVALID = 11028; | Details: Invalid currency ID or name | 39 | | 11029 | TE_ACTION_INVALID = 11029; | Details: Unrecognized request type | 40 | | 11030 | TE_ACTION_BY_INVALID = 11030; | | 41 | | 11031 | TE_SO_NUM_EXCEEDS = 11031; | Details: Number of total conditional orders exceeds the max limit | 42 | | 11032 | TE_AO_NUM_EXCEEDS = 11032; | Details: Number of total active orders exceeds the max limit | 43 | | 11033 | TE_ORDER_ID_DUPLICATE = 11033; | Details:Duplicated order ID | 44 | | 11034 | TE_SIDE_INVALID = 11034; | Details:Invalid side | 45 | | 11035 | TE_ORD_TYPE_INVALID = 11035; | Details:Invalid OrderType | 46 | | 11036 | TE_TIME_IN_FORCE_INVALID = 11036; | Details:Invalid TimeInForce | 47 | | 11037 | TE_EXEC_INST_INVALID = 11037; | Details:Invalid ExecType | 48 | | 11038 | TE_TRIGGER_INVALID = 11038; | Details:Invalid trigger type | 49 | | 11039 | TE_STOP_DIRECTION_INVALID = 11039; | Details:Invalid stop direction type | 50 | | 11040 | TE_NO_MARK_PRICE = 11040; | Details: Cannot get valid mark price to create conditional order | 51 | | 11041 | TE_NO_INDEX_PRICE = 11041; | Details: Cannot get valid index price to create conditional order | 52 | | 11042 | TE_NO_LAST_PRICE = 11042; | Details: Cannot get valid last market price to create conditional order | 53 | | 11043 | TE_RISING_TRIGGER_DIRECTLY = 11043; | Details: Conditional order would be triggered immediately | 54 | | 11044 | TE_FALLING_TRIGGER_DIRECTLY = 11044; | Details: Conditional order would be triggered immediately | 55 | | 11045 | TE_TRIGGER_PRICE_TOO_LARGE = 11045; | Details: Conditional order trigger price is too high | 56 | | 11046 | TE_TRIGGER_PRICE_TOO_SMALL = 11046; | Details: Conditional order trigger price is too low | 57 | | 11047 | TE_BUY_TP_SHOULD_GT_BASE = 11047; | Details: TakeProfit BUY conditional order trigger price needs to be greater than reference price | 58 | | 11048 | TE_BUY_SL_SHOULD_LT_BASE = 11048; | Details: StopLoss BUY condition order price needs to be less than the reference price | 59 | | 11049 | TE_BUY_SL_SHOULD_GT_LIQ = 11049; | Details: StopLoss BUY condition order price needs to be greater than liquidation price or it will not trigger | 60 | | 11050 | TE_SELL_TP_SHOULD_LT_BASE = 11050; | Details: TakeProfit SELL conditional order trigger price needs to be less than reference price | 61 | | 11051 | TE_SELL_SL_SHOULD_LT_LIQ = 11051; | Details: StopLoss SELL condition order price needs to be less than liquidation price or it will not trigger | 62 | | 11052 | TE_SELL_SL_SHOULD_GT_BASE = 11052; | Details: StopLoss SELL condition order price needs to be greater than the reference price | 63 | | 11053 | TE_PRICE_TOO_LARGE = 11053; | Details: Order price is too large | 64 | | 11054 | TE_PRICE_WORSE_THAN_BANKRUPT = 11054; | Details: Order price cannot be more aggressive than bankrupt price if this order has instruction to close a position | 65 | | 11055 | TE_PRICE_TOO_SMALL = 11055; | Details: Order price is too low | 66 | | 11056 | TE_QTY_TOO_LARGE = 11056; | Details: Order quantity is too large | 67 | | 11057 | TE_QTY_NOT_MATCH_REDUCE_ONLY = 11057; | Details: Does not allow ReduceOnly order without position | 68 | | 11058 | TE_QTY_TOO_SMALL = 11058; | Details: Order quantity is too small | 69 | | 11059 | TE_TP_SL_QTY_NOT_MATCH_POS = 11059; | Details: Position size is zero. Cannot accept any TakeProfit or StopLoss order | 70 | | 11060 | TE_SIDE_NOT_CLOSE_POS = 11060; | Details: TakeProfit or StopLoss order has wrong side. Cannot close position | 71 | | 11061 | TE_ORD_ALREADY_PENDING_CANCEL = 11061; | Details: Repeated cancel request | 72 | | 11062 | TE_ORD_ALREADY_CANCELED = 11062; | Details: Order is already canceled | 73 | | 11063 | TE_ORD_STATUS_CANNOT_CANCEL = 11063; | Details: Order is not able to be canceled under current status | 74 | | 11064 | TE_ORD_ALREADY_PENDING_REPLACE = 11064; | Details: Replace request is rejected because order is already in pending replace status | 75 | | 11065 | TE_ORD_REPLACE_NOT_MODIFIED = 11065; | Details: Replace request does not modify any parameters of the order | 76 | | 11066 | TE_ORD_STATUS_CANNOT_REPLACE = 11066; | Details: Order is not able to be replaced under current status | 77 | | 11067 | TE_CANNOT_REPLACE_PRICE = 11067; | Details: Market conditional order cannot change price | 78 | | 11068 | TE_CANNOT_REPLACE_QTY = 11068; | Details: Condtional order for closing position cannot change order quantity, since the order quantity is determined by position size already | 79 | | 11069 | TE_ACCOUNT_NOT_IN_RANGE = 11069; | Details: The account ID in the request is not valid or is not in the range of the current process | 80 | | 11070 | TE_SYMBOL_NOT_IN_RANGE = 11070; | Details: The symbol is invalid | 81 | | 11071 | TE_ORD_STATUS_CANNOT_TRIGGER = 11071; | | 82 | | 11072 | TE_TKFR_NOT_IN_RANGE = 11072; | Details: The fee value is not valid | 83 | | 11073 | TE_MKFR_NOT_IN_RANGE = 11073; | Details: The fee value is not valid | 84 | | 11074 | TE_CANNOT_ATTACH_TP_SL = 11074; | Details: Order request cannot contain TP/SL parameters when the account already has positions | 85 | | 11075 | TE_TP_TOO_LARGE = 11075; | Details: TakeProfit price is too large | 86 | | 11076 | TE_TP_TOO_SMALL = 11076; | Details: TakeProfit price is too small | 87 | | 11077 | TE_TP_TRIGGER_INVALID = 11077; | Details: Invalid trigger type | 88 | | 11078 | TE_SL_TOO_LARGE = 11078; | Details: StopLoss price is too large | 89 | | 11079 | TE_SL_TOO_SMALL = 11079; | Details: StopLoss price is too small | 90 | | 11080 | TE_SL_TRIGGER_INVALID = 11080; | Details: Invalid trigger type | 91 | | 11081 | TE_RISK_LIMIT_EXCEEDS = 11081; | Details: Total potential position breaches current risk limit | 92 | | 11082 | TE_CANNOT_COVER_ESTIMATE_ORDER_LOSS = 11082; | Details: The remaining balance cannot cover the potential unrealized PnL for this new order | 93 | | 11083 | TE_TAKE_PROFIT_ORDER_DUPLICATED = 11083; | Details: TakeProfit order already exists | 94 | | 11084 | TE_STOP_LOSS_ORDER_DUPLICATED = 11084; | Details: StopLoss order already exists | 95 | | 11085 | TE_CL_ORD_ID_DUPLICATE | Details: ClOrdId is duplicated | 96 | | 11086 | TE_PEG_PRICE_TYPE_INVALID | Details: PegPriceType is invalid | 97 | | 11087 | TE_BUY_TS_SHOULD_LT_BASE | Details: The trailing order's StopPrice should be less than the current last price | 98 | | 11088 | TE_BUY_TS_SHOULD_GT_LIQ | Details: The traling order's StopPrice should be greater than the current liquidation price | 99 | | 11089 | TE_SELL_TS_SHOULD_LT_LIQ | Details: The traling order's StopPrice should be greater than the current last price | 100 | | 11090 | TE_SELL_TS_SHOULD_GT_BASE | Details: The traling order's StopPrice should be less than the current liquidation price | 101 | | 11091 | TE_BUY_REVERT_VALUE_SHOULD_LT_ZERO | Details: The PegOffset should be less than zero | 102 | | 11092 | TE_SELL_REVERT_VALUE_SHOULD_GT_ZERO | Details: The PegOffset should be greater than zero | 103 | | 11093 | TE_BUY_TTP_SHOULD_ACTIVATE_ABOVE_BASE | Details: The activation price should be greater than the current last price | 104 | | 11094 | TE_SELL_TTP_SHOULD_ACTIVATE_BELOW_BASE | Details: The activation price should be less than the current last price | 105 | | 11095 | TE_TRAILING_ORDER_DUPLICATED | Details: A trailing order exists already | 106 | | 11096 | TE_CLOSE_ORDER_CANNOT_ATTACH_TP_SL | Details: An order to close position cannot have trailing instruction | 107 | | 11097 | TE_CANNOT_FIND_WALLET_OF_THIS_CURRENCY | Details: This crypto is not supported | 108 | | 11098 | TE_WALLET_INVALID_ACTION | Details: Invalid action on wallet | 109 | | 11099 | TE_WALLET_VID_UNMATCHED | Details: Wallet operation request has a wrong wallet vid | 110 | | 11100 | TE_WALLET_INSUFFICIENT_BALANCE | Details: Wallet has insufficient balance | 111 | | 11101 | TE_WALLET_INSUFFICIENT_LOCKED_BALANCE | Details: Locked balance in wallet is not enough for unlock/withdraw request | 112 | | 11102 | TE_WALLET_INVALID_DEPOSIT_AMOUNT | Details: Deposit amount must be greater than zero | 113 | | 11103 | TE_WALLET_INVALID_WITHDRAW_AMOUNT | Details: Withdraw amount must be less than zero | 114 | | 11104 | TE_WALLET_REACHED_MAX_AMOUNT | Details: Deposit makes wallet exceed max amount allowed | 115 | | 11105 | TE_PLACE_ORDER_INSUFFICIENT_BASE_BALANCE | Details: Insufficient funds in base wallet | 116 | | 11106 | TE_PLACE_ORDER_INSUFFICIENT_QUOTE_BALANCE | Details: Insufficient funds in quote wallet | 117 | | 11107 | TE_CANNOT_CONNECT_TO_REQUEST_SEQ | Details: TradingEngine failed to connect with CrossEngine | 118 | | 11108 | TE_CANNOT_REPLACE_OR_CANCEL_MARKET_ORDER | Details: Cannot replace/amend market order | 119 | | 11109 | TE_CANNOT_REPLACE_OR_CANCEL_IOC_ORDER | Details: Cannot replace/amend ImmediateOrCancel order | 120 | | 11110 | TE_CANNOT_REPLACE_OR_CANCEL_FOK_ORDER | Details: Cannot replace/amend FillOrKill order | 121 | | 11111 | TE_MISSING_ORDER_ID | Details: OrderId is missing | 122 | | 11112 | TE_QTY_TYPE_INVALID | Details: QtyType is invalid | 123 | | 11113 | TE_USER_ID_INVALID | Details: UserId is invalid | 124 | | 11114 | TE_ORDER_VALUE_TOO_LARGE | Details: Order value is too large | 125 | | 11115 | TE_ORDER_VALUE_TOO_SMALL | Details: Order value is too small | 126 | | 11116 | TE_BO_NUM_EXCEEDS| Details: the total count of brakcet orders should equal or less than 5 | 127 | | 11117 | TE_BO_CANNOT_HAVE_BO_WITH_DIFF_SIDE| Details: all bracket orders should have the same Side.| 128 | | 11118 | TE_BO_TP_PRICE_INVALID| Details: bracker order take profit price is invalid| 129 | | 11119 | TE_BO_SL_PRICE_INVALID| Details: bracker order stop loss price is invalid| 130 | | 11120 | TE_BO_SL_TRIGGER_PRICE_INVALID| Details: bracker order stop loss trigger price is invalid| 131 | | 11121 | TE_BO_CANNOT_REPLACE| Details: cannot replace bracket order.| 132 | | 11122 | TE_BO_BOTP_STATUS_INVALID| Details: bracket take profit order status is invalid | 133 | | 11123 | TE_BO_CANNOT_PLACE_BOTP_OR_BOSL_ORDER| Details: cannot place bracket take profit order | 134 | | 11124 | TE_BO_CANNOT_REPLACE_BOTP_OR_BOSL_ORDER| Details: cannot place bracket stop loss order| 135 | | 11125 | TE_BO_CANNOT_CANCEL_BOTP_OR_BOSL_ORDER| Details: cannot cancel bracket sl/tp order| 136 | | 11126 | TE_BO_DONOT_SUPPORT_API| Details: doesn't support bracket order via API| 137 | | 11128 | TE_BO_INVALID_EXECINST| Details: ExecInst value is invalid| 138 | | 11129 | TE_BO_MUST_BE_SAME_SIDE_AS_POS| Details: bracket order should have the same side as position's side| 139 | | 11130 | TE_BO_WRONG_SL_TRIGGER_TYPE| Details: bracket stop loss order trigger type is invalid| 140 | | 11131 | TE_BO_WRONG_TP_TRIGGER_TYPE| Details: bracket take profit order trigger type is invalid| 141 | | 11132 | TE_BO_ABORT_BOSL_DUE_BOTP_CREATE_FAILED| Details: cancel bracket stop loss order due failed to create take profit order.| 142 | | 11133 | TE_BO_ABORT_BOSL_DUE_BOPO_CANCELED| Details: cancel bracket stop loss order due main order canceled.| 143 | | 11134 | TE_BO_ABORT_BOTP_DUE_BOPO_CANCELED| Details: cancel bracket take profit order due main order canceled.| 144 | 145 | ## CxlRejReason Field 146 | 147 | | code | Reason | Description | 148 | |-----|---------|-------------| 149 | | 100 | CE_NO_ENOUGH_QTY | Details: qty is not enough | 150 | | 101 | CE_WILLCROSS | Details: passive order rejected due to price may cross | 151 | | 116 | CE_NO_ENOUGH_BASE_QTY | Details: base-qty is not enough in spot-trading | 152 | | 117 | CE_NO_ENOUGH_QUOTE_QTY | Details: quote-qty is not enough in spot-trading | 153 | -------------------------------------------------------------------------------- /Public-Transfer-API-en.md: -------------------------------------------------------------------------------- 1 | ## Table of Contents 2 | 3 | * [Phemex Public API](#publicapi) 4 | * [General Public API Information](#general) 5 | * [REST API Standards](#restapi) 6 | * [HTTP Restful Response](#restresponse) 7 | * [HTTP Return Codes](#httpreturncodes) 8 | * [HTTP Restful Response Format](#responseformat) 9 | * [Restful Response Error Codes](#errorcode) 10 | * [HTTP REST Request Header](#httprestheader) 11 | * [API Rate Limits](#apiratelimits) 12 | * [Endpoint security type](#securitytype) 13 | * [Signature Example 1: HTTP GET Request](#signatureexample1) 14 | * [Singature Example 2: HTTP GET Request with multiple query string](#signatureexample2) 15 | * [Signature Example 3: HTTP POST Request](#signatureexample3) 16 | * [Request/Response field explained](#fieldexplained) 17 | * [Spot currency and Symbol](#spotCurrencySym) 18 | * [Common constants](#commconsts) 19 | * [REST API List](#restapilist) 20 | * [Transfer Api List](#transferApiList) 21 | * [Transfer Between Spot and Futures](#assetsTransfer) 22 | * [Query Transfer History](#assetsTransferQuery) 23 | * [Spot Sub To Main Transfer](#spotSubToMainTransfer) 24 | * [Query Spot Sub To Main Transfer](#spotSubToMainTransferQuery) 25 | * [Futures Sub To Main Transfer](#futuresSubToMainTransfer) 26 | * [Query Futures Sub To Main Transfer](#futuresSubToMainTransferQuery) 27 | * [Universal Transfer](#universalTransfer) 28 | * [Convert Api List](#convertApiList) 29 | * [RFQ Quote](#rfqQuote) 30 | * [Convert](#convert) 31 | * [Query Convert History](#convertQuery) 32 | 33 | 34 | 35 | # Phemex Public API 36 | 37 | 38 | 39 | ## General Public API Information 40 | 41 | * Phemex provides HTTP Rest API for client to operate Orders, all endpoints return a JSON object. 42 | * The default Rest API base endpoint is: **https://api.phemex.com**. The High rate limit Rest API base endpoint 43 | is: **https://vapi.phemex.com**. Or for the testnet is: **https://testnet-api.phemex.com** 44 | * Phemex provides WebSocket API for client to receive market data, order and position updates. 45 | * The WebSocket API url is: **wss://phemex.com/ws**. The High rate limit WebSocket API url is: **wss: 46 | //vapi.phemex.com/ws**. Or for the testnet is: **wss://testnet.phemex.com/ws** 47 | 48 | 49 | 50 | # REST API Standards 51 | 52 | 53 | 54 | ## Restful API Response 55 | 56 | 57 | 58 | ### HTTP Return Codes 59 | 60 | * HTTP `401` return code is used when unauthenticated 61 | * HTTP `403` return code is used when lack of priviledge. 62 | * HTTP `429` return code is used when breaking a request rate limit. 63 | * HTTP `5XX` return codes are used for Phemex internal errors. Note: This doesn't means the operation failed, the 64 | execution status is **UNKNOWN** and could be Succeed. 65 | 66 | 67 | 68 | ### Rest Response format 69 | 70 | * All restful API except ***starting*** with `/md` shares same response format. 71 | 72 | ```json 73 | { 74 | "code": , 75 | "msg": , 76 | "data": 77 | } 78 | ``` 79 | 80 | | Field | Description | 81 | |-------|------| 82 | | code | 0 means `success`, non-zero means `error`| 83 | | msg | when code is non-zero, it gives short error description | 84 | | data | operation dependant | 85 | 86 | 87 | 88 | ### Error codes 89 | 90 | [Trading Error Codes](TradingErrorCode.md) 91 | 92 | ## HTTP REST Request Header 93 | 94 | Every HTTP Rest Request must have the following Headers: 95 | 96 | * x-phemex-access-token : This is ***API-KEY*** (id field) from Phemex site. 97 | * x-phemex-request-expiry : This describes the Unix ***EPoch SECONDS*** to expire the request, normally it should be ( 98 | Now() + 1 minute) 99 | * x-phemex-request-signature : This is HMAC SHA256 signature of the http request. Secret is ***API Secret***, its 100 | formula is : HMacSha256( URL Path + QueryString + Expiry + body ) 101 | 102 | Optional Headers: 103 | 104 | * x-phemex-request-tracing: a unique string to trace http-request, less than 40 bytes. This header is a must in 105 | resolving latency issues. 106 | 107 | 108 | 109 | ## API Rate Limits 110 | 111 | * [Order spamming limitations](https://phemex.com/user-guides/order-spamming-limitations) 112 | * RateLimit group of contract trading api is ***SPOTORDER***. 113 | * RateLimit Explained [phemex ratelimite docs](/Generic-API-Info.en.md) 114 | * Contract trading api response carries following headers. 115 | 116 | ``` 117 | X-RateLimit-Remaining-SPOTORDER, # Remaining request permits in this minute 118 | X-RateLimit-Capacity-SPOTORDER, # Request ratelimit capacity 119 | X-RateLimit-Retry-After-SPOTORDER, # Reset timeout in seconds for current ratelimited user 120 | ``` 121 | 122 | 123 | 124 | ## Endpoint security type 125 | 126 | * Each API call must be signed and pass to server in HTTP header `x-phemex-request-signature`. 127 | * Endpoints use `HMAC SHA256` signatures. The `HMAC SHA256 signature` is a keyed `HMAC SHA256` operation. Use 128 | your `apiSecret` as the key and the string `URL Path + QueryString + Expiry + body )` as the value for the HMAC 129 | operation. 130 | * `apiSecret` = `Base64::urlDecode(API Secret)` 131 | * The `signature` is **case sensitive**. 132 | 133 | 134 | 135 | ### Signature Example 1: HTTP GET Request 136 | 137 | * API REST Request URL: https://api.phemex.com/spot/wallets?currency=BTC 138 | * Request Path: /spot/wallets 139 | * Request Query: currency=BTC 140 | * Request Body: 141 | * Request Expiry: 1587552406 142 | * Signature: HMacSha256( /spot/wallets + currency=BTC + 1587552406 ) 143 | 144 | 145 | 146 | ### Singature Example 2: HTTP GET Request with multiple query string 147 | 148 | * API REST Request 149 | URL: https://api.phemex.com/spot/orders/active?symbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc 150 | * Request Path: /spot/orders/active 151 | * Request Query: symbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc 152 | * Request Body: 153 | * Request Expire: 1587552407 154 | * Signature: HMacSha256(/spot/orders/active + symbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc + 155 | 1587552407) 156 | * signed string is `/spot/orders/activesymbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc1587552407` 157 | 158 | 159 | 160 | ### Signature Example 3: HTTP POST Request 161 | 162 | * API REST Request URL: https://api.phemex.com/spot/orders 163 | * Request Path: /spot/orders 164 | * Request Query: 165 | * Request Body: 166 | ```json 167 | {"symbol":"sBTCUSDT","clOrdID":"ece0187f-7e02-44b5-a778-404125f124fa","side":"Buy","qtyType":"ByBase","quoteQtyEv":"0","baseQtyEv":"100000","priceEp":"700000000","stopPxEp":"0","execInst":"","ordType":"Limit","timeInForce":"","text":""} 168 | ``` 169 | * Request Expiry: 1587552407 170 | * signed string is 171 | ``` 172 | /spot/orders1587552407{"symbol":"sBTCUSDT","clOrdID":"ece0187f-7e02-44b5-a778-404125f124fa","side":"Buy","qtyType":"ByBase","quoteQtyEv":"0","baseQtyEv":"100000","priceEp":"700000000","stopPxEp":"0","execInst":"","ordType":"Limit","timeInForce":"","text":""} 173 | ``` 174 | 175 | ## Request/response field explained 176 | 177 | 178 | 179 | 180 | 181 | ### Spot Currency and Symbols 182 | 183 | * Spot Currency and its scale factor 184 | 185 | | currency | value scale factor | min value | max value | need addr arg | 186 | |--------|---------------|------------|------------|------------| 187 | |BTC|8|1|5e+18|0| 188 | |USDT|8|1|5e+18|0| 189 | |ETH|8|1|5e+18|0| 190 | |XRP|8|1|5e+18|1| 191 | |LINK|8|1|5e+18|0| 192 | |XTZ|8|1|5e+18|0| 193 | |LTC|8|1|5e+18|0| 194 | |ADA|8|1|5e+18|0| 195 | |TRX|8|1|5e+18|0| 196 | |ONT|8|1|5e+18|0| 197 | |BCH|8|1|5e+18|0| 198 | |NEO|8|1|5e+18|0| 199 | |EOS|8|1|5e+18|1| 200 | |COMP|8|1|5e+18|0| 201 | |LEND|8|1|5e+18|0| 202 | |YFI|8|1|5e+18|0| 203 | |DOT|8|1|5e+18|0| 204 | |UNI|8|1|5e+18|0| 205 | |AAVE|8|1|5e+18|0| 206 | |DOGE|8|1|5e+18|0| 207 | |BAT|8|1|5e+18|0| 208 | |CHZ|8|1|5e+18|0| 209 | |MANA|8|1|5e+18|0| 210 | |ENJ|8|1|5e+18|0| 211 | |SUSHI|8|1|5e+18|0| 212 | |SNX|8|1|5e+18|0| 213 | |GRT|8|1|5e+18|0| 214 | |MKR|8|1|5e+18|0| 215 | |ALGO|8|1|5e+18|0| 216 | |VET|8|1|5e+18|0| 217 | |ZEC|8|1|5e+18|0| 218 | |FIL|8|1|5e+18|0| 219 | |KSM|8|1|5e+18|0| 220 | |XMR|8|1|5e+18|0| 221 | |QTUM|8|1|5e+18|0| 222 | |XLM|8|1|5e+18|1| 223 | |ATOM|8|1|5e+18|1| 224 | |LUNA|8|1|5e+18|1| 225 | |SOL|8|1|5e+18|0| 226 | |AXS|8|1|5e+18|0| 227 | |MATIC|8|1|5e+18|0| 228 | |SHIB|2|1|5e+18|0| 229 | |FTM|8|1|5e+18|0| 230 | |DYDX|8|1|5e+18|0| 231 | 232 | 233 | 234 | * Spot symbol and its scale factor 235 | 236 | All spot symbols use the same price and ratio scale factors (price scale facor(Ep) = 8, ratio scale factor(Er) = 8). 237 | 238 | | symbol| type | price scale factor | ratio scale factor | baseTickSize| baseTickSizeEv| quoteTickSize| quoteTickSizeEv| baseQtyPrecision| quoteQtyPrecision| pricePrecision| minOrderValue| minOrderValueEv| maxBaseOrderSize| maxBaseOrderSizeEv| maxOrderValue| maxOrderValueEv| defaultTakerFee| defaultTakerFeeEr| defaultMakerFee| defaultMakerFeeEr| 239 | |---------|---------|---------|---------|-------------|-----------|-----------------|------------|------------|-------------|------|--------|-------|------|--------|-------|------|------|-------|-------|--------| 240 | |sBTCUSDT|Spot|8|8|0.000001 BTC|100|0.01 USDT|1000000|6|2|2|10 USDT|1000000000|1000 BTC|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 241 | |sETHUSDT|Spot|8|8|0.00001 ETH|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|10000 ETH|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 242 | |sXRPUSDT|Spot|8|8|0.1 XRP|10000000|0.00001 USDT|1000|1|2|5|10 USDT|1000000000|5000000 XRP|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 243 | |sLINKUSDT|Spot|8|8|0.01 LINK|1000000|0.0001 USDT|10000|2|2|4|10 USDT|1000000000|5000000 LINK|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 244 | |sXTZUSDT|Spot|8|8|0.01 XTZ|1000000|0.0001 USDT|10000|2|2|4|10 USDT|1000000000|2000000 XTZ|200000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 245 | |sLTCUSDT|Spot|8|8|0.00001 LTC|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|100000 LTC|10000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 246 | |sADAUSDT|Spot|8|8|0.1 ADA|10000000|0.00005 USDT|5000|1|2|5|10 USDT|1000000000|5000000 ADA|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 247 | |sTRXUSDT|Spot|8|8|0.1 TRX|10000000|0.00005 USDT|5000|1|2|5|10 USDT|1000000000|5000000 TRX|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 248 | |sONTUSDT|Spot|8|8|0.1 ONT|10000000|0.0005 USDT|50000|1|2|4|10 USDT|1000000000|5000000 ONT|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 249 | |sBCHUSDT|Spot|8|8|0.00001 BCH|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|10000 BCH|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 250 | |sNEOUSDT|Spot|8|8|0.001 NEO|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|5000000 NEO|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 251 | |sEOSUSDT|Spot|8|8|0.01 EOS|1000000|0.0001 USDT|10000|2|2|4|10 USDT|1000000000|5000000 EOS|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 252 | |sDOGEUSDT|Spot|8|8|1 DOGE|100000000|0.000001 USDT|100|0|2|6|10 USDT|1000000000|5000000 DOGE|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 253 | |sBATUSDT|Spot|8|8|0.01 BAT|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|300000 BAT|30000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 254 | |sCHZUSDT|Spot|8|8|0.01 CHZ|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|700000 CHZ|70000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 255 | |sMANAUSDT|Spot|8|8|0.01 MANA|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|400000 MANA|40000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 256 | |sENJUSDT|Spot|8|8|0.01 ENJ|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|200000 ENJ|20000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 257 | |sSUSHIUSDT|Spot|8|8|0.001 SUSHI|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|40000 SUSHI|4000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 258 | |sSNXUSDT|Spot|8|8|0.001 SNX|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|30000 SNX|3000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 259 | |sGRTUSDT|Spot|8|8|0.01 GRT|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|200000 GRT|20000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 260 | |sUNIUSDT|Spot|8|8|0.001 UNI|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|15000 UNI|1500000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 261 | |sAAVEUSDT|Spot|8|8|0.0001 AAVE|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1000 AAVE|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 262 | |sYFIUSDT|Spot|8|8|0.00001 YFI|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|10 YFI|1000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 263 | |sCOMPUSDT|Spot|8|8|0.0001 COMP|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1000 COMP|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 264 | |sMKRUSDT|Spot|8|8|0.00001 MKR|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|100 MKR|10000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 265 | |sDOTUSDT|Spot|8|8|0.001 DOT|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|10000 DOT|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 266 | |sALGOUSDT|Spot|8|8|0.01 ALGO|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|300000 ALGO|30000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 267 | |sVETUSDT|Spot|8|8|0.1 VET|10000000|0.000001 USDT|100|1|2|6|10 USDT|1000000000|2000000 VET|200000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 268 | |sZECUSDT|Spot|8|8|0.0001 ZEC|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|2000 ZEC|200000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 269 | |sFILUSDT|Spot|8|8|0.0001 FIL|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|3000 FIL|300000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 270 | |sKSMUSDT|Spot|8|8|0.0001 KSM|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1000 KSM|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 271 | |sXMRUSDT|Spot|8|8|0.0001 XMR|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1500 XMR|150000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 272 | |sQTUMUSDT|Spot|8|8|0.001 QTUM|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|30000 QTUM|3000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 273 | |sXLMUSDT|Spot|8|8|0.01 XLM|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|1000000 XLM|100000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 274 | |sATOMUSDT|Spot|8|8|0.001 ATOM|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|20000 ATOM|2000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 275 | |sLUNAUSDT|Spot|8|8|0.001 LUNA|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|40000 LUNA|4000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 276 | |sSOLUSDT|Spot|8|8|0.001 SOL|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|10000 SOL|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 277 | |sAXSUSDT|Spot|8|8|0.001 AXS|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|10000 AXS|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 278 | |sMATICUSDT|Spot|8|8|0.01 MATIC|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|300000 MATIC|30000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 279 | |sSHIBUSDT|Spot|8|8|1 SHIB|100|0.00000001 USDT|1|0|2|8|10 USDT|1000000000|5000000000 SHIB|500000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 280 | |sFTMUSDT|Spot|8|8|0.01 FTM|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|200000 FTM|20000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 281 | |sDYDXUSDT|Spot|8|8|0.001 DYDX|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|30000 DYDX|3000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 282 | 283 | 284 | 285 | ### Common constants 286 | 287 | * order type 288 | 289 | | order type | description | 290 | |-----------|-------------| 291 | | Limit | -- | 292 | | Market | -- | 293 | | Stop | -- | 294 | | StopLimit | -- | 295 | | MarketIfTouched | -- | 296 | | LimitIfTouched | -- | 297 | | MarketAsLimit | -- | 298 | | StopAsLimit | -- | 299 | | MarketIfTouchedAsLimit | -- | 300 | 301 | * order Status 302 | 303 | | order status | description | 304 | |------------|-------------| 305 | | Untriggered | Conditional order waiting to be triggered | 306 | | Triggered | Conditional order being triggered| 307 | | Rejected | Order rejected | 308 | | New | Order placed in cross engine | 309 | | PartiallyFilled | Order partially filled | 310 | | Filled | Order fully filled | 311 | | Canceled | Order canceled | 312 | 313 | * TimeInForce 314 | 315 | | timeInForce | description | 316 | |------------|-------------| 317 | | GoodTillCancel | -- | 318 | | PostOnly | -- | 319 | | ImmediateOrCancel | -- | 320 | | FillOrKill | -- | 321 | 322 | * Trigger source 323 | 324 | | trigger | description | 325 | |------------|-------------| 326 | | ByLastPrice | trigger by last price | 327 | 328 | * Transfer Status 329 | 330 | | Transfer Status | Description | 331 | |-----------------|---------------------------------| 332 | | 3 | Rejected | 333 | | 6 | Got error and wait for recovery | 334 | | 10 | Success | 335 | | 11 | Failed | 336 | | others | Under processing | 337 | 338 | 339 | 340 | ## REST API List 341 | 342 | 343 | 344 | ### Transfer API List 345 | 346 | 347 | 348 | #### Transfer Between Spot and Futures 349 | 350 | * Http Request 351 | 352 | ``` 353 | POST /assets/transfer 354 | ``` 355 | 356 | | Field | Type | Required | Description | Possible Values | 357 | |----------|---------|-----------|-----------------------|--------------------------------------------| 358 | | amountEv | Long | True | amountEv to transfer | 100000 ... | 359 | | moveOp | Integer | True | direction | 1 - futures to spot, 2 - spot to futures | 360 | | currency | String | True | currency to transfer | BTC, ETH, USD ... | 361 | 362 | * Request 363 | 364 | ```json 365 | { 366 | "amountEv": 0, 367 | "currency": "string", 368 | "moveOp": 0 369 | } 370 | ``` 371 | 372 | * Response 373 | 374 | ```json 375 | { 376 | "amountEv": 0, 377 | "currency": "string", 378 | "linkKey": "string", 379 | "side": 0, 380 | "status": 0, 381 | "userId": 0 382 | } 383 | ``` 384 | 385 | 386 | 387 | #### Query Transfer History 388 | 389 | * Http Request 390 | 391 | ``` 392 | GET /assets/transfer?currency=BTC 393 | ``` 394 | 395 | | Field | Type | Required | Description | Possible Values | 396 | |----------|---------|----------|---------------------------|--------------------------------------------| 397 | | currency | String | True | the currency to query | BTC,ETH ... | 398 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 399 | | end | Long | False | end time in millisecond | default now | 400 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 401 | | limit | Integer | False | page size | default 20, max 200 | 402 | | side | Integer | True | direction | 1 - futures to spot, 2 - spot to futures | 403 | | bizType | Integer | True | business type | 11 - futures to spot, 10 - spot to futures | 404 | 405 | * Response 406 | 407 | ```json 408 | [ 409 | { 410 | "amountEv": 0, 411 | "bizType": 0, 412 | "createTime": 0, 413 | "currency": "string", 414 | "linkKey": "string", 415 | "side": 0, 416 | "status": 0, 417 | "userId": 0 418 | } 419 | ] 420 | ``` 421 | 422 | 423 | 424 | #### Spot Sub To Main Transfer (for sub-account only) 425 | 426 | * Http Request 427 | 428 | ``` 429 | POST /assets/spots/sub-accounts/transfer 430 | ``` 431 | 432 | | Field | Type | Required | Description | Possible Values | 433 | |------------|---------|----------|----------------------|-------------------------------------------------------| 434 | | amountEv | Long | True | amountEv to transfer | 100000 ... | 435 | | currency | String | True | currency to transfer | BTC, ETH, USD ... | 436 | | requestKey | String | False | unique request key | Unique request Key, system will generate if its empty | 437 | 438 | * Request 439 | 440 | ```json 441 | { 442 | "amountEv": 0, 443 | "currency": "string", 444 | "requestKey": "string" 445 | } 446 | ``` 447 | 448 | * Response 449 | 450 | ```json 451 | { 452 | "amountEv": 0, 453 | "currency": "string", 454 | "fromUserId": 0, 455 | "requestKey": "string", 456 | "toUserId": 0 457 | } 458 | ``` 459 | 460 | 461 | 462 | #### Query Spot Sub To Main Transfer 463 | 464 | * Http Request 465 | 466 | ``` 467 | GET /assets/spots/sub-accounts/transfer?currency=BTC 468 | ``` 469 | 470 | | Field | Type | Required | Description | Possible Values | 471 | |----------|---------|----------|---------------------------|---------------------------------| 472 | | currency | String | True | the currency to query | BTC,ETH ... | 473 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 474 | | end | Long | False | end time in millisecond | default now | 475 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 476 | | limit | Integer | False | page size | default 20, max 200 | 477 | 478 | * Response 479 | 480 | ```json 481 | [ 482 | { 483 | "amountEv": 0, 484 | "createAt": 0, 485 | "currency": "string", 486 | "fromUserId": 0, 487 | "id": 0, 488 | "requestKey": "string", 489 | "status": 0, 490 | "toUserId": 0 491 | } 492 | ] 493 | ``` 494 | 495 | 496 | 497 | #### Futures Sub To Main Transfer (for sub-account only) 498 | 499 | * Http Request 500 | 501 | ``` 502 | POST /assets/futures/sub-accounts/transfer 503 | ``` 504 | 505 | | Field | Type | Required | Description | Possible Values | 506 | |------------|---------|----------|----------------------|-------------------------------------------------------| 507 | | amountEv | Long | True | amountEv to transfer | 100000 ... | 508 | | currency | String | True | currency to transfer | BTC, ETH, USD ... | 509 | | requestKey | String | False | unique request key | Unique request Key, system will generate if its empty | 510 | 511 | * Request 512 | 513 | ```json 514 | { 515 | "amountEv": 0, 516 | "currency": "string", 517 | "requestKey": "string" 518 | } 519 | ``` 520 | 521 | * Response 522 | 523 | ```json 524 | { 525 | "amountEv": 0, 526 | "bizCode": 0, 527 | "currency": "string", 528 | "fromUserId": 0, 529 | "requestKey": "string", 530 | "toUserId": 0 531 | } 532 | ``` 533 | 534 | 535 | 536 | #### Query Futures Sub To Main Transfer 537 | 538 | * Http Request 539 | 540 | ``` 541 | GET /assets/futures/sub-accounts/transfer?currency=BTC 542 | ``` 543 | 544 | | Field | Type | Required | Description | Possible Values | 545 | |----------|---------|----------|---------------------------|---------------------------------| 546 | | currency | String | True | the currency to query | BTC,ETH ... | 547 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 548 | | end | Long | False | end time in millisecond | default now | 549 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 550 | | limit | Integer | False | page size | default 20, max 200 | 551 | 552 | * Response 553 | 554 | ```json 555 | [ 556 | { 557 | "fromUserId": 0, 558 | "toUserId": 0, 559 | "currency": "string", 560 | "amountEv": 0, 561 | "bizCode": 0, 562 | "requestKey": "string", 563 | "createAt": 0 564 | } 565 | ] 566 | ``` 567 | 568 | 569 | 570 | #### Universal Transfer(Main account only) - Transfer between sub to main, main to sub or sub to sub 571 | 572 | * Http Request 573 | 574 | ``` 575 | POST /assets/universal-transfer 576 | ``` 577 | 578 | | Field | Type | Required | Description | Possible Values | 579 | |-------------|---------|----------|-----------------------------|-------------------------------------------------------| 580 | | fromUserId | Long | True | from user id | Will set as main account if not given or 0 | 581 | | toUserId | Long | True | to user id | Will set as main account if not given or 0 | 582 | | amountEv | Long | True | amountEv to transfer | 100000 ... | 583 | | bizType | String | True | transfer for which biz type | SPOT, PERPETUAL | 584 | | requestKey | String | False | unique request key | Unique request Key, system will generate if its empty | 585 | 586 | * Request 587 | 588 | ```json 589 | { 590 | "amountEv": 0, 591 | "bizType": "string", 592 | "currency": "string", 593 | "fromUserId": 0, 594 | "toUserId": 0 595 | } 596 | ``` 597 | 598 | * Response 599 | 600 | ```json 601 | { 602 | "requestKey" 603 | } 604 | ``` 605 | 606 | 607 | 608 | ### Convert API List 609 | 610 | 611 | 612 | #### RFQ Quote 613 | 614 | * Http Request 615 | 616 | ``` 617 | GET /assets/quote 618 | ``` 619 | 620 | | Field | Type | Required | Description | Possible Values | 621 | |--------------|--------|----------|----------------------|-----------------| 622 | | fromCurrency | String | True | from currency | BTC,USD ... | 623 | | toCurrency | String | True | to currency | BTC,USD ... | 624 | | fromAmountEv | Long | True | amountEv to transfer | 100000 ... | 625 | 626 | * Response 627 | 628 | ```json 629 | { 630 | "code": "string", 631 | "quoteArgs": { 632 | "expireAt": 0, 633 | "origin": 0, 634 | "price": "string", 635 | "proceeds": "string", 636 | "quoteAt": 0, 637 | "requestAt": 0, 638 | "ttlMs": 0 639 | } 640 | } 641 | ``` 642 | 643 | 644 | 645 | #### Convert 646 | 647 | * Http Request 648 | 649 | ``` 650 | POST /assets/convert 651 | ``` 652 | 653 | | Field | Type | Required | Description | Possible Values | 654 | |--------------|--------|----------|------------------------|-----------------| 655 | | toCurrency | String | True | to currency | BTC,USD ... | 656 | | fromCurrency | String | True | from currency | BTC,USD ... | 657 | | fromAmountEv | Long | False | amountEv to convert | 100000 ... | 658 | | code | String | True | encrypted convert args | xxxxxxxx ... | 659 | 660 | * Request 661 | 662 | ```json 663 | { 664 | "code": "string", 665 | "fromAmountEv": 0, 666 | "fromCurrency": "string", 667 | "toCurrency": "string" 668 | } 669 | ``` 670 | 671 | * Response 672 | 673 | ```json 674 | { 675 | "fromAmountEv": 0, 676 | "fromCurrency": "string", 677 | "linkKey": "string", 678 | "moveOp": 0, 679 | "status": 0, 680 | "toAmountEv": 0, 681 | "toCurrency": "string" 682 | } 683 | ``` 684 | 685 | 686 | 687 | #### Query Convert History 688 | 689 | * Http Request 690 | 691 | ``` 692 | GET /assets/convert 693 | ``` 694 | 695 | | Field | Type | Required | Description | Possible Values | 696 | |--------------|----------|----------|---------------------------|--------------------------------------| 697 | | fromCurrency | String | False | from currency | BTC,USD ... | 698 | | toCurrency | String | False | to currency | BTC,USD ... | 699 | | startTime | Long | False | start time in millisecond | default 2 days ago from the end time | 700 | | endTime | Long | False | end time in millisecond | default now | 701 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 702 | | limit | Integer | False | page size | default 20, max 200 | 703 | 704 | * Response 705 | 706 | ```json 707 | [ 708 | { 709 | "conversionRate": 0, 710 | "createTime": 0, 711 | "errorCode": 0, 712 | "fromAmountEv": 0, 713 | "fromCurrency": "string", 714 | "linkKey": "string", 715 | "status": 0, 716 | "toAmountEv": 0, 717 | "toCurrency": "string" 718 | } 719 | ] 720 | ``` 721 | -------------------------------------------------------------------------------- /Public-Spot-API-en.md: -------------------------------------------------------------------------------- 1 | ## Table of Contents 2 | 3 | * [Phemex Public API](#publicapi) 4 | * [General Public API Information](#general) 5 | * [REST API Standards](#restapi) 6 | * [HTTP Restful Response](#restresponse) 7 | * [HTTP Return Codes](#httpreturncodes) 8 | * [HTTP Restful Response Format](#responseformat) 9 | * [Restful Response Error Codes](#errorcode) 10 | * [HTTP REST Request Header](#httprestheader) 11 | * [API Rate Limits](#apiratelimits) 12 | * [Endpoint security type](#securitytype) 13 | * [Signature Example 1: HTTP GET Request](#signatureexample1) 14 | * [Singature Example 2: HTTP GET Request with multiple query string](#signatureexample2) 15 | * [Signature Example 3: HTTP POST Request](#signatureexample3) 16 | * [Request/Response field explained](#fieldexplained) 17 | * [Spot currency and Symbol](#spotCurrencySym) 18 | * [Common constants](#commconsts) 19 | * [REST API List](#restapilist) 20 | * [Market API List](#marketapilist) 21 | * [Query Product Information](#queryproductinfo) 22 | * [Market Data API List ](#mdapilist) 23 | * [Query Order Book](#queryorderbook) 24 | * [Query Recent Trades](#querytrades) 25 | * [Query 24 Hours Ticker](#query24hrsticker) 26 | * [Spot Trading Api List](#spotTradingApi) 27 | * [Place Order With PUT method, *Preferred*](#spotPutPlaceOrder) 28 | * [Place Order](#spotPlaceOrder) 29 | * [Amend Order](#spotAmendOrder) 30 | * [Cancel Order](#spotCancelOrder) 31 | * [Cancel All Order by Symbol](#spotCancelAll) 32 | * [Query Open Order by clOrdID or orderID](#spotQueryOpenOrder) 33 | * [List all Open Orders by Symbol](#spotListAllOpenOrder) 34 | * [Query Wallets](#spotQueryWallet) 35 | * [Query Closed orders, *Deprecated*](#spotQueryClosedOrder) 36 | * [Query history trades, *Deprecated*](#spotQueryHistTrade) 37 | * [Spot Asset Api List](#spotAssetAPIList) 38 | * [Query Deposit address](#depositAddr) 39 | * [Query Deposit history](#depositHist) 40 | * [Query withdraw history](#withdrawHist) 41 | * [Spot Data Api List](#spotDataAPIList) 42 | * [Query Funds History](#spotDataFundsHist) 43 | * [Query Orders History](#spotDataOrdersHist) 44 | * [Query Orders By Ids](#spotDataOrdersByIds) 45 | * [Query PNLs](#spotDataPnls) 46 | * [Query Trades](#spotDataTradesHist) 47 | * [Query Trades By Ids](#spotDataTradesByIds) 48 | 49 | * [Websocket API Standards](#wsapi) 50 | * [Session Management](#sessionmanagement) 51 | * [API Rate Limits](#wsapiratelimits) 52 | * [WebSocket API List](#wsapilist) 53 | * [Heartbeat](#heartbeat) 54 | * [API User Authentication](#apiuserauth) 55 | * [Subscribe OrderBook](#booksub) 56 | * [Subscribe Full OrderBook](#booksub2) 57 | * [Unsubscribe OrderBook](#bookunsub) 58 | * [Subscribe Trade](#tradesub) 59 | * [Unsubscribe Trade](#tradeunsub) 60 | * [Subscribe Kline](#klinesub) 61 | * [Unsubscribe Kline](#klinesub) 62 | * [Subscribe Wallet-Order](#wosub) 63 | * [Unsubscribe Wallet-Order](#wounsub) 64 | * [Subscribe 24 Hours Ticker](#tickersub) 65 | * [All Spot trading currencies](#currencyinfo) 66 | * [All Spot trading products](#productinfo) 67 | * [Subscribe Investment Account](#investmentaccount) 68 | 69 | 70 | 71 | # Phemex Public API 72 | 73 | 74 | 75 | ## General Public API Information 76 | 77 | * Phemex provides HTTP Rest API for client to operate Orders, all endpoints return a JSON object. 78 | * The default Rest API base endpoint is: **https://api.phemex.com**. The High rate limit Rest API base endpoint 79 | is: **https://vapi.phemex.com**. Or for the testnet is: **https://testnet-api.phemex.com** 80 | * Phemex provides WebSocket API for client to receive market data, order and position updates. 81 | * The WebSocket API url is: **wss://phemex.com/ws**. The High rate limit WebSocket API url is: **wss: 82 | //vapi.phemex.com/ws**. Or for the testnet is: **wss://testnet.phemex.com/ws** 83 | 84 | 85 | 86 | # REST API Standards 87 | 88 | 89 | 90 | ## Restful API Response 91 | 92 | 93 | 94 | ### HTTP Return Codes 95 | 96 | * HTTP `401` return code is used when unauthenticated 97 | * HTTP `403` return code is used when lack of priviledge. 98 | * HTTP `429` return code is used when breaking a request rate limit. 99 | * HTTP `5XX` return codes are used for Phemex internal errors. Note: This doesn't means the operation failed, the 100 | execution status is **UNKNOWN** and could be Succeed. 101 | 102 | 103 | 104 | ### Rest Response format 105 | 106 | * All restful API except ***starting*** with `/md` shares same response format. 107 | 108 | ```javascript 109 | { 110 | "code": , 111 | "msg": , 112 | "data": 113 | } 114 | ``` 115 | 116 | | Field | Description | 117 | |-------|------| 118 | | code | 0 means `success`, non-zero means `error`| 119 | | msg | when code is non-zero, it gives short error description | 120 | | data | operation dependant | 121 | 122 | 123 | 124 | ### Error codes 125 | 126 | [Trading Error Codes](TradingErrorCode.md) 127 | 128 | ## HTTP REST Request Header 129 | 130 | Every HTTP Rest Request must have the following Headers: 131 | 132 | * x-phemex-access-token : This is ***API-KEY*** (id field) from Phemex site. 133 | * x-phemex-request-expiry : This describes the Unix ***EPoch SECONDS*** to expire the request, normally it should be ( 134 | Now() + 1 minute) 135 | * x-phemex-request-signature : This is HMAC SHA256 signature of the http request. Secret is ***API Secret***, its 136 | formula is : HMacSha256( URL Path + QueryString + Expiry + body ) 137 | 138 | Optional Headers: 139 | 140 | * x-phemex-request-tracing: a unique string to trace http-request, less than 40 bytes. This header is a must in 141 | resolving latency issues. 142 | 143 | 144 | 145 | ## API Rate Limits 146 | 147 | * [Order spamming limitations](https://phemex.com/user-guides/order-spamming-limitations) 148 | * RateLimit group of contract trading api is ***SPOTORDER***. 149 | * RateLimit Explained [phemex ratelimite docs](/Generic-API-Info.en.md) 150 | * Contract trading api response carries following headers. 151 | 152 | ``` 153 | X-RateLimit-Remaining-SPOTORDER, # Remaining request permits in this minute 154 | X-RateLimit-Capacity-SPOTORDER, # Request ratelimit capacity 155 | X-RateLimit-Retry-After-SPOTORDER, # Reset timeout in seconds for current ratelimited user 156 | ``` 157 | 158 | 159 | 160 | ## Endpoint security type 161 | 162 | * Each API call must be signed and pass to server in HTTP header `x-phemex-request-signature`. 163 | * Endpoints use `HMAC SHA256` signatures. The `HMAC SHA256 signature` is a keyed `HMAC SHA256` operation. Use 164 | your `apiSecret` as the key and the string `URL Path + QueryString + Expiry + body )` as the value for the HMAC 165 | operation. 166 | * `apiSecret` = `Base64::urlDecode(API Secret)` 167 | * The `signature` is **case sensitive**. 168 | 169 | 170 | 171 | ### Signature Example 1: HTTP GET Request 172 | 173 | * API REST Request URL: https://api.phemex.com/spot/wallets?currency=BTC 174 | * Request Path: /spot/wallets 175 | * Request Query: currency=BTC 176 | * Request Body: 177 | * Request Expiry: 1587552406 178 | * Signature: HMacSha256( /spot/wallets + currency=BTC + 1587552406 ) 179 | 180 | 181 | 182 | ### Singature Example 2: HTTP GET Request with multiple query string 183 | 184 | * API REST Request 185 | URL: https://api.phemex.com/spot/orders/active?symbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc 186 | * Request Path: /spot/orders/active 187 | * Request Query: symbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc 188 | * Request Body: 189 | * Request Expire: 1587552407 190 | * Signature: HMacSha256(/spot/orders/active + symbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc + 191 | 1587552407) 192 | * signed string is `/spot/orders/activesymbol=sBTCUSDT&orderID=bc2b8ff1-a73b-4673-aa5b-fda632285fcc1587552407` 193 | 194 | 195 | 196 | ### Signature Example 3: HTTP POST Request 197 | 198 | * API REST Request URL: https://api.phemex.com/spot/orders 199 | * Request Path: /spot/orders 200 | * Request Query: 201 | * Request Body: 202 | ```json 203 | {"symbol":"sBTCUSDT","clOrdID":"ece0187f-7e02-44b5-a778-404125f124fa","side":"Buy","qtyType":"ByBase","quoteQtyEv":"0","baseQtyEv":"100000","priceEp":"700000000","stopPxEp":"0","execInst":"","ordType":"Limit","timeInForce":"","text":""} 204 | ``` 205 | * Request Expiry: 1587552407 206 | * signed string is 207 | ``` 208 | /spot/orders1587552407{"symbol":"sBTCUSDT","clOrdID":"ece0187f-7e02-44b5-a778-404125f124fa","side":"Buy","qtyType":"ByBase","quoteQtyEv":"0","baseQtyEv":"100000","priceEp":"700000000","stopPxEp":"0","execInst":"","ordType":"Limit","timeInForce":"","text":""} 209 | ``` 210 | 211 | ## Request/response field explained 212 | 213 | 214 | 215 | 216 | 217 | ### Spot Currency and Symbols 218 | 219 | * Spot Currency and its scale factor 220 | See [all spot trading currencies](#currencyinfo) for details. 221 | 222 | 223 | 224 | * Spot symbol and its scale factor 225 | 226 | All spot symbols use the same price and ratio scale factors (price scale facor(Ep) = 8, ratio scale factor(Er) = 8). 227 | 228 | See [all spot trading products](#productinfo) for details. 229 | 230 | 231 | 232 | ### Common constants 233 | 234 | * order type 235 | 236 | | order type | description | 237 | |-----------|-------------| 238 | | Limit | -- | 239 | | Market | -- | 240 | | Stop | -- | 241 | | StopLimit | -- | 242 | | MarketIfTouched | -- | 243 | | LimitIfTouched | -- | 244 | | MarketAsLimit | -- | 245 | | StopAsLimit | -- | 246 | | MarketIfTouchedAsLimit | -- | 247 | 248 | * order Status 249 | 250 | | order status | description | 251 | |------------|-------------| 252 | | Untriggered | Conditional order waiting to be triggered | 253 | | Triggered | Conditional order being triggered| 254 | | Rejected | Order rejected | 255 | | New | Order placed in cross engine | 256 | | PartiallyFilled | Order partially filled | 257 | | Filled | Order fully filled | 258 | | Canceled | Order canceled | 259 | 260 | * TimeInForce 261 | 262 | | timeInForce | description | 263 | |------------|-------------| 264 | | GoodTillCancel | -- | 265 | | PostOnly | -- | 266 | | ImmediateOrCancel | -- | 267 | | FillOrKill | -- | 268 | 269 | * Trigger source 270 | 271 | | trigger | description | 272 | |------------|-------------| 273 | | ByLastPrice | trigger by last price | 274 | 275 | 276 | 277 | ## REST API List 278 | 279 | 280 | 281 | ### Market API List 282 | 283 | 284 | 285 | #### Query Product Information 286 | 287 | * Request： 288 | 289 | ``` 290 | GET /public/products 291 | ``` 292 | 293 | 294 | 295 | ### Market Data API List 296 | 297 | 298 | 299 | #### Query Order Book 300 | 301 | * Request： 302 | 303 | ``` 304 | GET /md/orderbook?symbol= 305 | ``` 306 | 307 | | Field | Type | Description | Possible values | 308 | |-------------|--------|--------------------------------------------|--------------| 309 | | symbol | String | symbol name | [Trading symbols](#productinfo) | 310 | 311 | * Response: 312 | 313 | ```javascript 314 | { 315 | "error": null, 316 | "id": 0, 317 | "result": { 318 | "book": { 319 | "asks": [ 320 | [ 321 | , 322 | 323 | ], 324 | ... 325 | ... 326 | ... 327 | ], 328 | "bids": [ 329 | [ 330 | , 331 | 332 | ], 333 | ... 334 | ... 335 | ... 336 | ], 337 | ] 338 | }, 339 | "depth": 30, 340 | "sequence": , 341 | "timestamp": , 342 | "symbol": "", 343 | "type": "snapshot" 344 | } 345 | } 346 | ``` 347 | 348 | | Field | Type | Description | Possible values | 349 | |-------------|--------|--------------------------------------------|--------------| 350 | | timestamp | Integer| Timestamp in nanoseconds | | 351 | | priceEp | Integer| Scaled book level price | | 352 | | size | Integer| Scaled book level size | | 353 | | sequence | Integer| current message sequence | | 354 | | symbol | String | Spot symbol name | [Trading symbols](#productinfo) | 355 | 356 | * Sample： 357 | 358 | ``` 359 | GET /md/orderbook?symbol=sBTCUSDT 360 | ``` 361 | 362 | ```json 363 | { 364 | "error": null, 365 | "id": 0, 366 | "result": { 367 | "book": { 368 | "asks": [ 369 | [ 370 | 877050000000, 371 | 1000000 372 | ], 373 | [ 374 | 877100000000, 375 | 200000 376 | ] 377 | ], 378 | "bids": [ 379 | [ 380 | 877000000000, 381 | 2000000 382 | ], 383 | [ 384 | 876950000000, 385 | 200000 386 | ] 387 | ] 388 | }, 389 | "depth": 30, 390 | "sequence": 455476965, 391 | "timestamp": 1583555482434235628, 392 | "symbol": "sBTCUSDT", 393 | "type": "snapshot" 394 | } 395 | } 396 | ``` 397 | 398 | 399 | 400 | #### Query Recent Trades 401 | 402 | * Request： 403 | 404 | ``` 405 | GET /md/trade?symbol= 406 | ``` 407 | 408 | | Field | Type | Description | Possible values | 409 | |-------------|--------|--------------------------------------------|--------------| 410 | | symbol | String | symbol name | [Trading symbols](#productinfo) | 411 | 412 | * Response: 413 | 414 | ```javascript 415 | { 416 | "error": null, 417 | "id": 0, 418 | "result": { 419 | "type": "snapshot", 420 | "sequence": , 421 | "symbol": "", 422 | "trades": [ 423 | [ 424 | , 425 | "", 426 | , 427 | 428 | ], 429 | ... 430 | ... 431 | ... 432 | ] 433 | } 434 | } 435 | 436 | ``` 437 | 438 | | Field | Type | Description | Possible values | 439 | |-------------|--------|--------------------------------------------|--------------| 440 | | timestamp | Integer| Timestamp in nanoseconds | | 441 | | side | String | Trade side string | Buy, Sell | 442 | | priceEp | Integer| Scaled trade price | | 443 | | size | Integer| Scaled trade size | | 444 | | sequence | Integer| Current message sequence | | 445 | | symbol | String | Spot symbol name | [Trading symbols](#productinfo) | 446 | 447 | * Sample： 448 | 449 | ``` 450 | GET /md/trade?symbol=sBTCUSDT 451 | ``` 452 | 453 | ```json 454 | { 455 | "error": null, 456 | "id": 0, 457 | "result": { 458 | "sequence": 15934323, 459 | "symbol": "sBTCUSDT", 460 | "trades": [ 461 | [ 462 | 1579164056368538508, 463 | "Sell", 464 | 869600000000, 465 | 1210000 466 | ], 467 | [ 468 | 1579164055036820552, 469 | "Sell", 470 | 869600000000, 471 | 580000 472 | ] 473 | ], 474 | "type": "snapshot" 475 | } 476 | } 477 | 478 | ``` 479 | 480 | 481 | 482 | #### Query 24 Hours Ticker 483 | 484 | * Request： 485 | 486 | ``` 487 | GET /md/spot/ticker/24hr?symbol= 488 | ``` 489 | 490 | | Field | Type | Description | Possible values | 491 | |-------------|--------|--------------------------------------------|--------------| 492 | | symbol | String | symbol name | [Trading symbols](#productinfo) | 493 | 494 | * Response: 495 | 496 | ```javascript 497 | { 498 | "error": null, 499 | "id": 0, 500 | "result": { 501 | "openEp": , 502 | "highEp": , 503 | "lowEp": , 504 | "lastEp": , 505 | "bidEp": , 506 | "askEp": , 507 | "symbol": "", 508 | "turnoverEv": , 509 | "volumeEv": , 510 | "timestamp": 511 | } 512 | } 513 | ``` 514 | 515 | | Field | Type | Description | Possible values | 516 | |---------------|--------|--------------------------------------------|--------------| 517 | | open priceEp | Integer| The scaled open price in last 24 hours | | 518 | | high priceEp | Integer| The scaled highest price in last 24 hours | | 519 | | low priceEp | Integer| The scaled lowest price in last 24 hours | | 520 | | last priceEp | Integer| The scaled last price | | 521 | | bid priceEp | Integer| Scaled bid price | | 522 | | ask priceEp | Integer| Scaled ask price | | 523 | | timestamp | Integer| Timestamp in nanoseconds | | 524 | | symbol | String | symbol name | [Trading symbols](#productinfo) | 525 | | turnoverEv | Integer| The scaled turnover value in last 24 hours | | 526 | | volumeEv | Integer| The scaled trade volume in last 24 hours | | 527 | 528 | * Sample： 529 | 530 | ``` 531 | GET /md/spot/ticker/24hr?symbol=sBTCUSDT 532 | ``` 533 | 534 | ```json 535 | { 536 | "error": null, 537 | "id": 0, 538 | "result": { 539 | "askEp": 892100000000, 540 | "bidEp": 891835000000, 541 | "highEp": 898264000000, 542 | "lastEp": 892486000000, 543 | "lowEp": 870656000000, 544 | "openEp": 896261000000, 545 | "symbol": "sBTCUSDT", 546 | "timestamp": 1590571240030003249, 547 | "turnoverEv": 104718804814499, 548 | "volumeEv": 11841148100 549 | } 550 | } 551 | ``` 552 | 553 | 554 | 555 | ### Market Data API List 556 | 557 | 558 | 559 | #### Query Order Book 560 | 561 | * Request： 562 | 563 | ``` 564 | GET /v1/md/orderbook?symbol= 565 | ``` 566 | 567 | | Field | Type | Description | Possible values | 568 | |-------------|--------|--------------------------------------------|--------------| 569 | | symbol | String | Spot symbol name | [Trading symbols](#productinfo) | 570 | 571 | * Response: 572 | 573 | ```javascript 574 | { 575 | "error": null, 576 | "id": 0, 577 | "result": { 578 | "book": { 579 | "asks": [ 580 | [ 581 | , 582 | 583 | ], 584 | ... 585 | ... 586 | ... 587 | ], 588 | "bids": [ 589 | [ 590 | , 591 | 592 | ], 593 | ... 594 | ... 595 | ... 596 | ], 597 | ] 598 | }, 599 | "depth": 30, 600 | "sequence": , 601 | "symbol": "", 602 | "timestamp": "", 603 | "type": "snapshot" 604 | } 605 | } 606 | ``` 607 | 608 | | Field | Type | Description | Possible values | 609 | |-------------|--------|--------------------------------------------|--------------| 610 | | timestamp | Integer| Timestamp in nanoseconds | | 611 | | priceEp | Integer| Scaled book level price | | 612 | | size | Integer| Scaled book level size | | 613 | | sequence | Integer| current message sequence | | 614 | | symbol | String | Spot symbol name | [Trading symbols](#productinfo) | 615 | 616 | * Sample： 617 | 618 | ``` 619 | GET /v1/md/orderbook?symbol=sBTCUSDT 620 | ``` 621 | 622 | ```json 623 | { 624 | "error": null, 625 | "id": 0, 626 | "result": { 627 | "book": { 628 | "asks": [ 629 | [ 630 | 87705000000, 631 | 1000000 632 | ], 633 | [ 634 | 87710000000, 635 | 200000 636 | ] 637 | ], 638 | "bids": [ 639 | [ 640 | 877000000000, 641 | 2000000 642 | ], 643 | [ 644 | 876950000000, 645 | 200000 646 | ] 647 | ] 648 | }, 649 | "depth": 30, 650 | "sequence": 455476965, 651 | "symbol": "sBTCUSDT", 652 | "timestamp": 1583552267253988998, 653 | "type": "snapshot" 654 | } 655 | } 656 | ``` 657 | 658 | 659 | 660 | ### Spot Trading Api List 661 | 662 | 663 | 664 | * Http Request: 665 | 666 | ``` 667 | PUT /spot/orders/create?symbol=&trigger=&clOrdID=&priceEp=&baseQtyEv="eQtyEv=&stopPxEp=&text=&side=&qtyType=&ordType=&timeInForce=&execInst= 668 | ``` 669 | 670 | | Field | Type | Required | Description | Possible values | 671 | |---------- |--------|----------|---------------------------|-----------------| 672 | | symbol | String | Yes | | [Spot Trading symbols](#spotSymList) | 673 | | side | Enum | Yes | | Sell, Buy | 674 | | qtyType | Enum | Yes | default ByBase | ByBase, ByQuote| 675 | | quoteQtyEv | Number | -- | Required when qtyType = ByQuote| | 676 | | baseQtyEv | Number | -- | | Required when qtyType = ByBase | 677 | | priceEp | Number | | | Scaled price | 678 | | stopPxEp | Number | -- | used in conditional order | | 679 | | trigger | Enum | -- | Required in conditional order | ByLastPrice | 680 | | timeInForce | Enum | No | Default GoodTillCancel | GoodTillCancel, PostOnly,ImmediateOrCancel,FillOrKill | 681 | | ordType | Enum | No | Default to Limit |Market, Limit, Stop, StopLimit, MarketIfTouched, LimitIfTouched| 682 | 683 | * Http Response 684 | 685 | ```javascript 686 | { 687 | "code": 0, 688 | "msg": "", 689 | "data": { 690 | "orderID": "d1d09454-cabc-4a23-89a7-59d43363f16d", 691 | "clOrdID": "309bcd5c-9f6e-4a68-b775-4494542eb5cb", 692 | "priceEp": 0, 693 | "action": "New", 694 | "trigger": "UNSPECIFIED", 695 | "pegPriceType": "UNSPECIFIED", 696 | "stopDirection": "UNSPECIFIED", 697 | "bizError": 0, 698 | "symbol": "sBTCUSDT", 699 | "side": "Buy", 700 | "baseQtyEv": 0, 701 | "ordType": "Limit", 702 | "timeInForce": "GoodTillCancel", 703 | "ordStatus": "Created", 704 | "cumFeeEv": 0, 705 | "cumBaseQtyEv": 0, 706 | "cumQuoteQtyEv": 0, 707 | "leavesBaseQtyEv": 0, 708 | "leavesQuoteQtyEv": 0, 709 | "avgPriceEp": 0, 710 | "cumBaseAmountEv": 0, 711 | "cumQuoteAmountEv": 0, 712 | "quoteQtyEv": 0, 713 | "qtyType": "ByBase", 714 | "stopPxEp": 0, 715 | "pegOffsetValueEp": 0 716 | } 717 | } 718 | ``` 719 | 720 | 721 | 722 | #### Place order 723 | 724 | * Http Request: 725 | 726 | ``` 727 | POST /spot/orders 728 | ``` 729 | 730 | ```json 731 | { 732 | "symbol": "sBTCUSDT", 733 | "clOrdID": "", 734 | "side": "Buy/Sell", 735 | "qtyType": "ByBase/ByQuote", 736 | "quoteQtyEv": 0, 737 | "baseQtyEv": 0, 738 | "priceEp": 0, 739 | "stopPxEp": 0, 740 | "trigger": "UNSPECIFIED", 741 | "ordType": "Limit", 742 | "timeInForce": "GoodTillCancel" 743 | } 744 | ``` 745 | 746 | * Fields are the same as [above place-order](#spotPutPlaceOrder) 747 | 748 | 749 | 750 | #### Amend Order 751 | 752 | * Http Request 753 | 754 | ``` 755 | PUT /spot/orders?symbol=&orderID=&origClOrdID=&clOrdID=&priceEp=&baseQtyEV="eQtyEv=&stopPxEp= 756 | ``` 757 | 758 | * Http Response 759 | 760 | * amended order 761 | 762 | 763 | 764 | #### Cancel Order 765 | 766 | ``` 767 | DELETE /spot/orders?symbol=&orderID= 768 | DELETE /spot/orders?symbol=&clOrdID= 769 | ``` 770 | 771 | * Http Response 772 | * Canceled order 773 | 774 | 775 | 776 | #### Cancel all order by symbol 777 | 778 | ``` 779 | DELETE /spot/orders/all?symbol=&untriggered= 780 | ``` 781 | 782 | | Field | Type | Required | Description | 783 | |---------|--------|-------|-------------| 784 | | symbol | Enum | Yes | The symbol to cancel | 785 | | untriggered | Boolean | No | set false to cancel non-conditiaonal order, true to conditional order | 786 | 787 | * Http Response 788 | * Total orders canceled 789 | 790 | 791 | 792 | #### Query Open order by clOrdID or orderID 793 | 794 | * Http Request 795 | 796 | ``` 797 | GET /spot/orders/active?symbol=&orderID= 798 | GET /spot/orders/active?symbol=&clOrDID= 799 | ``` 800 | 801 | * Http Response 802 | 803 | * Order object 804 | 805 | 806 | 807 | #### Query all open orders by symbol 808 | 809 | * Http Request 810 | 811 | ``` 812 | GET /spot/orders?symbol= 813 | ``` 814 | 815 | * Http Response 816 | * List of orders 817 | 818 | 819 | 820 | #### Query wallets 821 | 822 | * Query spot wallet by currency 823 | 824 | * Http Request 825 | 826 | ``` 827 | GET /spot/wallets?currency= 828 | ``` 829 | 830 | * Http Response 831 | 832 | ```json 833 | { 834 | "code": 0, 835 | "msg": "", 836 | "data": [ 837 | { 838 | "currency": "BTC", 839 | "balanceEv": 0, 840 | "lockedTradingBalanceEv": 0, 841 | "lockedWithdrawEv": 0, 842 | "lastUpdateTimeNs": 0 843 | } 844 | ] 845 | } 846 | ``` 847 | 848 | 849 | 850 | #### Query spot closed orders 851 | 852 | * Query closed orders by symbol 853 | 854 | **NOTE:** deprecated, recommend [Query Orders by IDs](#spotDataOrdersByIds) 855 | 856 | * Http Request 857 | 858 | ``` 859 | GET /exchange/spot/order?symbol=&ordStatus=ordType=&start=&end=&limit=&offset= 860 | ``` 861 | 862 | | Field | Type | Required | Description | Possible Values | 863 | |-----------|------|----------|-------------|------------------| 864 | | symbol | String | Yes | symbol to query | [Trading symbols](#productinfo) | 865 | | ordStatus | enum | No | order status filter |[common constants for order status](#commconsts) | 866 | | ordType | enum | No | order type filter |[common constants for order type](#commconsts) | 867 | | start | integer | No | Epoch millisecond, start of time range | within 3 month | 868 | | end | integer | No | Epoch millisecond, end of time range | within 3 months | 869 | 870 | * Http Response 871 | 872 | * return a list of spot order model. 873 | 874 | ```json 875 | { 876 | "code": 0, 877 | "msg": "OK", 878 | "data": { 879 | "total": 2, 880 | "rows": [ 881 | { 882 | "orderID": "string", 883 | "stopPxEp": 0, 884 | "avgPriceEp": 0, 885 | "qtyType": "", 886 | "leavesBaseQtyEv": 0, 887 | "leavesQuoteQtyEv": 0, 888 | "baseQtyEv": "0", 889 | "feeCurrency": "string", 890 | "stopDirection": "UNSPECIFIED", 891 | "symbol": "string", 892 | "side": "enum", 893 | "quoteQtyEv": 0, 894 | "priceEp": 0, 895 | "ordType": "enum", 896 | "timeInForce": "enum", 897 | "ordStatus": "enum", 898 | "execStatus": "enum", 899 | "createTimeNs": 0, 900 | "cumFeeEv": 0, 901 | "cumBaseValueEv": 0, 902 | "cumQuoteValueEv": 0 903 | } 904 | ] 905 | } 906 | } 907 | ``` 908 | 909 | * Sample Response 910 | 911 | ```json 912 | { 913 | "code": 0, 914 | "msg": "OK", 915 | "data": { 916 | "total": 2, 917 | "rows": [ 918 | { 919 | "orderID": "b2b7018d-f02f-4c59-b4cf-051b9c2d2e83", 920 | "stopPxEp": 0, 921 | "avgPriceEp": 970056000000, 922 | "qtyType": "ByQuote", 923 | "leavesBaseQtyEv": 0, 924 | "leavesQuoteQtyEv": 0, 925 | "baseQtyEv": "0", 926 | "feeCurrency": "1", 927 | "stopDirection": "UNSPECIFIED", 928 | "symbol": "sBTCUSDT", 929 | "side": "Buy", 930 | "quoteQtyEv": 1000000000, 931 | "priceEp": 970056000000, 932 | "ordType": "Limit", 933 | "timeInForce": "GoodTillCancel", 934 | "ordStatus": "Filled", 935 | "execStatus": "MakerFill", 936 | "createTimeNs": 1589449348601287000, 937 | "cumFeeEv": 0, 938 | "cumBaseValueEv": 103000, 939 | "cumQuoteValueEv": 999157680 940 | } 941 | ] 942 | } 943 | } 944 | ``` 945 | 946 | 947 | 948 | #### Query spot history trades 949 | 950 | * Query spot history trades by symbol 951 | 952 | **NOTE:** Deprecated, recommend [Query Trades](#spotDataTradesHist) 953 | 954 | * Http Request 955 | 956 | ``` 957 | GET /exchange/spot/order/trades?symbol=&start=&end=&limit=&offset= 958 | ``` 959 | 960 | | Field | Type | Required | Description | Possible values | 961 | |-------|------|----------|-------------|-----------------| 962 | | symbol | string | Yes | symbol to query | [spot symbol list](#spotSymList) | 963 | | start | integer | No | Epoch millisecond, start of time range | | 964 | | end | integer | No | Epoch millisecond, end of time range | | 965 | 966 | * Http Response 967 | 968 | ```json 969 | { 970 | "code": 0, 971 | "msg": "OK", 972 | "data": { 973 | "total": 1, 974 | "rows": [ 975 | { 976 | "qtyType": "ByQuote/ByBase", 977 | "transactTimeNs": 0, 978 | "clOrdID": "string" 979 | "orderID": "string", 980 | "symbol": "string", 981 | "side": "enum", 982 | "priceEP": 0, 983 | "baseQtyEv": 0, 984 | "quoteQtyEv": 0, 985 | "action": "enum", 986 | "execStatus": "enum", 987 | "ordStatus": "enum", 988 | "ordType": "enum", 989 | "execInst": "enum", 990 | "timeInForce": "enum", 991 | "stopDirection": "enum", 992 | "tradeType": "enum", 993 | "stopPxEp": 0, 994 | "execId": "0", 995 | "execPriceEp": 0, 996 | "execBaseQtyEv": 0, 997 | "execQuoteQtyEv": 0, 998 | "leavesBaseQtyEv": 0, 999 | "leavesQuoteQtyEv": 0, 1000 | "execFeeEv": 0, 1001 | "feeRateEr": 0 1002 | } 1003 | ] 1004 | } 1005 | } 1006 | ``` 1007 | 1008 | * Sample Response 1009 | 1010 | ```json 1011 | { 1012 | "code": 0, 1013 | "msg": "OK", 1014 | "data": { 1015 | "total": 1, 1016 | "rows": [ 1017 | { 1018 | "qtyType": "ByQuote", 1019 | "transactTimeNs": 1589450974800550100, 1020 | "clOrdID": "8ba59d40-df25-d4b0-14cf-0703f44e9690", 1021 | "orderID": "b2b7018d-f02f-4c59-b4cf-051b9c2d2e83", 1022 | "symbol": "sBTCUSDT", 1023 | "side": "Buy", 1024 | "priceEP": 970056000000, 1025 | "baseQtyEv": 0, 1026 | "quoteQtyEv": 1000000000, 1027 | "action": "New", 1028 | "execStatus": "MakerFill", 1029 | "ordStatus": "Filled", 1030 | "ordType": "Limit", 1031 | "execInst": "None", 1032 | "timeInForce": "GoodTillCancel", 1033 | "stopDirection": "UNSPECIFIED", 1034 | "tradeType": "Trade", 1035 | "stopPxEp": 0, 1036 | "execId": "c6bd8979-07ba-5946-b07e-f8b65135dbb1", 1037 | "execPriceEp": 970056000000, 1038 | "execBaseQtyEv": 103000, 1039 | "execQuoteQtyEv": 999157680, 1040 | "leavesBaseQtyEv": 0, 1041 | "leavesQuoteQtyEv": 0, 1042 | "execFeeEv": 0, 1043 | "feeRateEr": 0 1044 | } 1045 | ] 1046 | } 1047 | } 1048 | ``` 1049 | 1050 | 1051 | 1052 | # Spot Asset API 1053 | 1054 | 1055 | 1056 | #### Query deposit address by currency 1057 | 1058 | * Http Request 1059 | 1060 | ``` 1061 | GET /exchange/wallets/v2/depositAddress?currency=&chainName= 1062 | ``` 1063 | 1064 | | Field | Type | Required | Description| Possible Values | 1065 | |----------|--------|-----------|------------|-----------------| 1066 | | currency | String | True | the currency to query | BTC,ETH, USDT ... | 1067 | | chainName| String | True | the chain for this currency | BTC, ETH, EOS | 1068 | 1069 | * chainName is provided by below currency settings interface. 1070 | 1071 | ``` 1072 | GET /exchange/public/cfg/chain-settings?currency= 1073 | ``` 1074 | 1075 | * Response 1076 | 1077 | ```json 1078 | { 1079 | "address": "1Cdxxxxxxxxxxxxxx", 1080 | "tag": null 1081 | } 1082 | ``` 1083 | 1084 | 1085 | 1086 | #### Query recent deposit history within 3 months 1087 | 1088 | * Http Request 1089 | 1090 | ``` 1091 | GET /exchange/wallets/depositList?currency=&offset=&limit= 1092 | ``` 1093 | 1094 | | Field | Type | Required | Description| Possible Values | 1095 | |----------|--------|-----------|------------|-----------------| 1096 | | currency | String | True | the currency to query | BTC,ETH, ... | 1097 | 1098 | * Response 1099 | 1100 | ```json 1101 | { 1102 | "address": "1xxxxxxxxxxxxxxxxxx", 1103 | "amountEv": 1000000, 1104 | "confirmations": 1, 1105 | "createdAt": 1574685871000, 1106 | "currency": "BTC", 1107 | "currencyCode": 1, 1108 | "status": "Success", 1109 | "txHash": "9e84xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 1110 | "type": "Deposit" 1111 | } 1112 | ``` 1113 | 1114 | 1115 | 1116 | #### Query recent withdraw history within 3 months 1117 | 1118 | * Http Request 1119 | 1120 | ``` 1121 | GET /exchange/wallets/withdrawList?currency=&offset=&limit= 1122 | ``` 1123 | 1124 | * Response 1125 | 1126 | ```json 1127 | { 1128 | "address": "1Lxxxxxxxxxxx", 1129 | "amountEv": 200000, 1130 | "currency": "BTC", 1131 | "currencyCode": 1, 1132 | "expiredTime": 0, 1133 | "feeEv": 50000, 1134 | "rejectReason": null, 1135 | "status": "Succeed", 1136 | "txHash": "44exxxxxxxxxxxxxxxxxxxxxx", 1137 | "withdrawStatus": "" 1138 | } 1139 | ``` 1140 | 1141 | 1142 | 1143 | ### Spot Data Api List 1144 | 1145 | 1146 | 1147 | #### Query Funds History 1148 | 1149 | * Http Request 1150 | 1151 | ``` 1152 | GET /api-data/spots/funds?currency= 1153 | ``` 1154 | 1155 | | Field | Type | Required | Description | Possible Values | 1156 | |----------|----------------|----------|---------------------------|---------------------------------| 1157 | | currency | String | True | the currency to query | BTC,ETH, USDT ... | 1158 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 1159 | | end | Long | False | end time in millisecond | default now | 1160 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1161 | | limit | Integer | False | page size | default 20, max 200 | 1162 | 1163 | * Response 1164 | 1165 | ```json 1166 | [ 1167 | { 1168 | "action": "string", 1169 | "amountEv": 0, 1170 | "balanceEv": 0, 1171 | "bizCode": 0, 1172 | "createTime": 0, 1173 | "currency": "string", 1174 | "execId": "string", 1175 | "execSeq": 0, 1176 | "feeEv": 0, 1177 | "id": 0, 1178 | "side": "string", 1179 | "text": "string", 1180 | "transactTimeNs": 0 1181 | } 1182 | ] 1183 | ``` 1184 | 1185 | 1186 | 1187 | #### Query Orders History 1188 | 1189 | * Http Request 1190 | 1191 | ``` 1192 | GET /api-data/spots/orders?symbol= 1193 | ``` 1194 | 1195 | | Field | Type | Required | Description | Possible Values | 1196 | |-----------|---------|----------|---------------------------|---------------------------------| 1197 | | symbol | String | True | the currency to query | sBTCUSDT ... | 1198 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 1199 | | end | Long | False | end time in millisecond | default now | 1200 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1201 | | limit | Integer | False | page size | default 20, max 200 | 1202 | 1203 | * Response 1204 | 1205 | ```json 1206 | [ 1207 | { 1208 | "avgPriceEp": 0, 1209 | "avgTransactPriceEp": 0, 1210 | "baseQtyEv": "string", 1211 | "createTimeNs": 0, 1212 | "cumBaseValueEv": 0, 1213 | "cumFeeEv": 0, 1214 | "cumQuoteValueEv": 0, 1215 | "execStatus": "string", 1216 | "feeCurrency": "string", 1217 | "leavesBaseQtyEv": 0, 1218 | "leavesQuoteQtyEv": 0, 1219 | "ordStatus": "string", 1220 | "ordType": "string", 1221 | "orderID": "string", 1222 | "priceEp": 0, 1223 | "qtyType": "string", 1224 | "quoteQtyEv": 0, 1225 | "side": "string", 1226 | "stopDirection": "string", 1227 | "stopPxEp": 0, 1228 | "symbol": "string", 1229 | "timeInForce": "string" 1230 | } 1231 | ] 1232 | ``` 1233 | 1234 | 1235 | 1236 | #### Query Orders By Ids 1237 | 1238 | * Http Request 1239 | 1240 | ``` 1241 | GET /api-data/spots/orders/by-order-id?symbol=&oderId=&clOrdID= 1242 | ``` 1243 | 1244 | | Field | Type | Required | Description | Possible Values | 1245 | |----------|--------|----------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------| 1246 | | symbol | String | True | the currency to query | sBTCUSDT ... | 1247 | | orderID | String | False | order id | orderID and clOrdID can not be both empty. If both IDs are given, it will return orderID if there is any, otherwise will try to find clOrdID | 1248 | | clOrdID | String | False | client order id | refer to orderID | 1249 | 1250 | * Response 1251 | 1252 | ```json 1253 | [ 1254 | { 1255 | "avgPriceEp": 0, 1256 | "avgTransactPriceEp": 0, 1257 | "baseQtyEv": "string", 1258 | "createTimeNs": 0, 1259 | "cumBaseValueEv": 0, 1260 | "cumFeeEv": 0, 1261 | "cumQuoteValueEv": 0, 1262 | "execStatus": "string", 1263 | "feeCurrency": "string", 1264 | "leavesBaseQtyEv": 0, 1265 | "leavesQuoteQtyEv": 0, 1266 | "ordStatus": "string", 1267 | "ordType": "string", 1268 | "orderID": "string", 1269 | "priceEp": 0, 1270 | "qtyType": "string", 1271 | "quoteQtyEv": 0, 1272 | "side": "string", 1273 | "stopDirection": "string", 1274 | "stopPxEp": 0, 1275 | "symbol": "string", 1276 | "timeInForce": "string" 1277 | } 1278 | ] 1279 | ``` 1280 | 1281 | 1282 | 1283 | #### Query PNLs 1284 | 1285 | * Http Request 1286 | 1287 | ``` 1288 | GET /api-data/spots/pnls 1289 | ``` 1290 | 1291 | | Field | Type | Required | Description | Possible Values | 1292 | |----------|--------|----------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------| 1293 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 1294 | | end | Long | False | end time in millisecond | default now | 1295 | 1296 | * Response 1297 | 1298 | ```json 1299 | [ 1300 | { 1301 | "collectTime": 0, 1302 | "cumPnlEv": 0, 1303 | "dailyPnlEv": 0, 1304 | "userId": 0 1305 | } 1306 | ] 1307 | ``` 1308 | 1309 | 1310 | 1311 | #### Query Trades History 1312 | 1313 | * Http Request 1314 | 1315 | ``` 1316 | GET /api-data/spots/trades?symbol= 1317 | ``` 1318 | 1319 | | Field | Type | Required | Description | Possible Values | 1320 | |-----------|---------|----------|---------------------------|---------------------------------| 1321 | | symbol | String | True | the currency to query | sBTCUSDT ... | 1322 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 1323 | | end | Long | False | end time in millisecond | default now | 1324 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1325 | | limit | Integer | False | page size | default 20, max 200 | 1326 | 1327 | * Response 1328 | 1329 | ```json 1330 | [ 1331 | { 1332 | "action": "string", 1333 | "baseCurrency": "string", 1334 | "baseQtyEv": 0, 1335 | "clOrdID": "string", 1336 | "execBaseQtyEv": 0, 1337 | "execFeeEv": 0, 1338 | "execId": "string", 1339 | "execInst": "string", 1340 | "execPriceEp": 0, 1341 | "execQuoteQtyEv": 0, 1342 | "execStatus": "string", 1343 | "feeCurrency": "string", 1344 | "feeRateEr": 0, 1345 | "leavesBaseQtyEv": 0, 1346 | "leavesQuoteQtyEv": 0, 1347 | "ordStatus": "string", 1348 | "ordType": "string", 1349 | "orderID": "string", 1350 | "priceEP": 0, 1351 | "qtyType": "string", 1352 | "quoteCurrency": "string", 1353 | "quoteQtyEv": 0, 1354 | "side": "string", 1355 | "stopDirection": "string", 1356 | "stopPxEp": 0, 1357 | "symbol": "string", 1358 | "timeInForce": "string", 1359 | "tradeType": "string", 1360 | "transactTimeNs": 0 1361 | } 1362 | ] 1363 | ``` 1364 | 1365 | 1366 | 1367 | #### Query Orders By Ids 1368 | 1369 | * Http Request 1370 | 1371 | ``` 1372 | GET /api-data/spots/trades/by-order-id?symbol=&oderId=&clOrdID= 1373 | ``` 1374 | 1375 | | Field | Type | Required | Description | Possible Values | 1376 | |----------|--------|----------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------| 1377 | | symbol | String | True | the currency to query | sBTCUSDT ... | 1378 | | orderID | String | False | order id | orderID and clOrdID can not be both empty. If both IDs are given, it will return orderID if there is any, otherwise will try to find clOrdID | 1379 | | clOrdID | String | False | client order id | refer to orderID | 1380 | 1381 | * Response 1382 | 1383 | ```json 1384 | [ 1385 | { 1386 | "action": "string", 1387 | "baseCurrency": "string", 1388 | "baseQtyEv": 0, 1389 | "clOrdID": "string", 1390 | "execBaseQtyEv": 0, 1391 | "execFeeEv": 0, 1392 | "execId": "string", 1393 | "execInst": "string", 1394 | "execPriceEp": 0, 1395 | "execQuoteQtyEv": 0, 1396 | "execStatus": "string", 1397 | "feeCurrency": "string", 1398 | "feeRateEr": 0, 1399 | "leavesBaseQtyEv": 0, 1400 | "leavesQuoteQtyEv": 0, 1401 | "ordStatus": "string", 1402 | "ordType": "string", 1403 | "orderID": "string", 1404 | "priceEP": 0, 1405 | "qtyType": "string", 1406 | "quoteCurrency": "string", 1407 | "quoteQtyEv": 0, 1408 | "side": "string", 1409 | "stopDirection": "string", 1410 | "stopPxEp": 0, 1411 | "symbol": "string", 1412 | "timeInForce": "string", 1413 | "tradeType": "string", 1414 | "transactTimeNs": 0 1415 | } 1416 | ] 1417 | ``` 1418 | 1419 | 1420 | 1421 | # Websocket API Standards 1422 | 1423 | 1424 | 1425 | ## Session Management 1426 | 1427 | * Each client is required to actively send heartbeat (ping) message to Phemex data gateway ('DataGW' in short) with 1428 | interval less than 30 seconds, otherwise DataGW will drop the connection. If a client sends a ping message, DataGW 1429 | will reply with a pong message. 1430 | * Clients can use WS built-in ping message or the application level ping message to DataGW as heartbeat. The heartbeat 1431 | interval is recommended to be set as *5 seconds*, and actively reconnect to DataGW if don't receive messages in *3 1432 | heartbeat intervals*. 1433 | 1434 | 1435 | 1436 | ## API Rate Limits 1437 | 1438 | * Each Client has concurrent connection limit to *5* in maximum. 1439 | * Each connection has subscription limit to *20* in maximum. 1440 | * Each connection has throttle limit to *20* request/s. 1441 | 1442 | 1443 | 1444 | ## WebSocket API List 1445 | 1446 | 1447 | 1448 | ### Heartbeat 1449 | 1450 | * Request： 1451 | 1452 | ```javascript 1453 | { 1454 | "id": , 1455 | "method": "server.ping", 1456 | "params": [] 1457 | } 1458 | ``` 1459 | 1460 | * Response: 1461 | 1462 | ```javascript 1463 | { 1464 | "error": null, 1465 | "id": , 1466 | "result": "pong" 1467 | } 1468 | ``` 1469 | 1470 | * Sample： 1471 | 1472 | ```javascript 1473 | > { 1474 | "id": 1234, 1475 | "method": "server.ping", 1476 | "params": [] 1477 | } 1478 | 1479 | < { 1480 | "error": null, 1481 | "id": 1234, 1482 | "result": "pong" 1483 | } 1484 | ``` 1485 | 1486 | 1487 | 1488 | ### API User Authentication 1489 | 1490 | Market trade/orderbook are published publicly without user authentication. 1491 | While for client private account/position/order data, the client should send user.auth message to Data Gateway to 1492 | authenticate the session. 1493 | 1494 | * Request 1495 | 1496 | ```javascript 1497 | { 1498 | "method": "user.auth", 1499 | "params": [ 1500 | "API", 1501 | "", 1502 | "", 1503 | 1504 | ], 1505 | "id": 1234 1506 | } 1507 | ``` 1508 | 1509 | | Field | Type | Description | Possible values | 1510 | |-------------|--------|------------------|-----------------| 1511 | | type | String | Token type | API | 1512 | | token | String | API Key | | 1513 | | signature | String | Signature generated by a funtion as HMacSha256(API Key + expiry) with ***API Secret*** || 1514 | | expiry | Integer| A future time after which request will be rejected, in epoch ***second***. Maximum expiry is request time plus 2 minutes || 1515 | 1516 | * Sample: 1517 | 1518 | ```javascript 1519 | > { 1520 | "method": "user.auth", 1521 | "params": [ 1522 | "API", 1523 | "806066b0-f02b-4d3e-b444-76ec718e1023", 1524 | "8c939f7a6e6716ab7c4240384e07c81840dacd371cdcf5051bb6b7084897470e", 1525 | 1570091232 1526 | ], 1527 | "id": 1234 1528 | } 1529 | 1530 | < { 1531 | "error": null, 1532 | "id": 1234, 1533 | "result": { 1534 | "status": "success" 1535 | } 1536 | } 1537 | ``` 1538 | 1539 | 1540 | 1541 | ### Subscribe OrderBook 1542 | 1543 | On each successful subscription, DataGW will immediately send the current Order Book snapshot to client and all later 1544 | order book updates will be published. 1545 | Incremental messages are published with **depth=30 and 20ms interval**. 1546 | 1547 | * Request 1548 | 1549 | ```javascript 1550 | { 1551 | "id": , 1552 | "method": "orderbook.subscribe", 1553 | "params": [ 1554 | "" 1555 | ] 1556 | } 1557 | ``` 1558 | 1559 | * Response 1560 | 1561 | ```javascript 1562 | { 1563 | "error": null, 1564 | "id": , 1565 | "result": { 1566 | "status": "success" 1567 | } 1568 | } 1569 | ``` 1570 | 1571 | * Sample： 1572 | 1573 | ```javascript 1574 | > { 1575 | "id": 1234, 1576 | "method": "orderbook.subscribe", 1577 | "params": [ 1578 | "sBTCUSDT" 1579 | ] 1580 | } 1581 | 1582 | < { 1583 | "error": null, 1584 | "id": 1234, 1585 | "result": { 1586 | "status": "success" 1587 | } 1588 | } 1589 | ``` 1590 | 1591 | 1592 | 1593 | ### Subscribe Full OrderBook 1594 | 1595 | On each successful subscription, DataGW will immediately send the current Order Book snapshot to client and all later 1596 | order book updates will be published. 1597 | Incremental messages are published with **full depth and 100ms interval**. 1598 | 1599 | * Request 1600 | 1601 | ```javascript 1602 | { 1603 | "id": , 1604 | "method": "orderbook.subscribe", 1605 | "params": [ 1606 | "", 1607 | true 1608 | ] 1609 | } 1610 | ``` 1611 | 1612 | * Response 1613 | 1614 | ```javascript 1615 | { 1616 | "error": null, 1617 | "id": , 1618 | "result": { 1619 | "status": "success" 1620 | } 1621 | } 1622 | ``` 1623 | 1624 | * Sample： 1625 | 1626 | ```javascript 1627 | > { 1628 | "id": 1234, 1629 | "method": "orderbook.subscribe", 1630 | "params": [ 1631 | "sBTCUSDT", 1632 | true 1633 | ] 1634 | } 1635 | 1636 | < { 1637 | "error": null, 1638 | "id": 1234, 1639 | "result": { 1640 | "status": "success" 1641 | } 1642 | } 1643 | ``` 1644 | 1645 | #### OrderBook Message: 1646 | 1647 | DataGW publishes order book message with types: incremental, snapshot. And snapshot messages are published with 60-second interval for client self-verification. 1648 | 1649 | * Message Format： 1650 | 1651 | ```javascript 1652 | { 1653 | "book": { 1654 | "asks": [ 1655 | [ 1656 | , 1657 | 1658 | ], 1659 | . 1660 | . 1661 | . 1662 | ], 1663 | "bids": [ 1664 | [ 1665 | , 1666 | 1667 | ], 1668 | . 1669 | . 1670 | . 1671 | ] 1672 | }, 1673 | "depth": , 1674 | "sequence": , 1675 | "timestamp": , 1676 | "symbol": "" 1677 | } 1678 | ``` 1679 | 1680 | | Field | Type | Description | Possible values | 1681 | |-------------|--------|------------------|-----------------| 1682 | | side | String | Price level side | bid, ask | 1683 | | priceEp | Integer| Scaled price | | 1684 | | qty | Integer| Price level size. Non-zero qty indicates price level insertion or updation, and qty 0 indicates price level deletion. | | 1685 | | sequence | Integer| Latest message sequence | | 1686 | | depth | Integer| Market depth | 30 | 1687 | | type | String | Message type | snapshot, incremental | 1688 | 1689 | * Sample： 1690 | 1691 | ```javascript 1692 | < {"book":{"asks":[[892697000000,1781800],[892708000000,7543500],[892718000000,6552500],[892720000000,4714100],[892728000000,8431000],[892735000000,11644800],[892756000000,5909600],[892790000000,9053100],[892798000000,3336400],[892819000000,1689500],[892828000000,1616700],[892855000000,6484000],[892869000000,6873200],[892872000000,1919900],[892875000000,2373200],[892942000000,1875300],[892944000000,3117500],[892962000000,1353500],[892965000000,2589800],[892966000000,11169800],[892973000000,7829700],[892977000000,2697200],[892978000000,2110700],[892985000000,12563700],[892988000000,5374100],[893023000000,3816000],[893031000000,5852700],[893035000000,4990900],[893061000000,3479500],[893083000000,327900]],"bids":[[892376000000,6866500],[892354000000,14209000],[892353000000,5287200],[892348000000,6417800],[892340000000,8074400],[892334000000,3991900],[892303000000,4558000],[892295000000,10154700],[892280000000,16214500],[892277000000,11425300],[892270000000,39156500],[892268000000,13821100],[892260000000,32157500],[892257000000,5466100],[892252000000,11468700],[892241000000,13940300],[892226000000,33832300],[892220000000,3000000],[892171000000,4320400],[892165000000,4454000],[892152000000,5336400],[892144000000,4539200],[892134000000,7472200],[892127000000,5352700],[892087000000,10264400],[892082000000,4908000],[892038000000,1485500],[892031000000,4089200],[892030000000,4895500],[892014000000,3846600]]},"depth":30,"sequence":677996311,"symbol":"sBTCUSDT","timestamp":1590570810187570850,"type":"snapshot"} 1693 | < {"book":{"asks":[[892696000000,1669700],[892697000000,10455500],[892728000000,0],[892735000000,0],[892748000000,1550900],[892790000000,0],[892819000000,19087900],[892860000000,17152500],[892882000000,11546100],[892893000000,10986500],[892973000000,0],[892985000000,0],[893004000000,8306500],[893061000000,0],[893065000000,5446400],[893073000000,0],[893083000000,0],[893073000000,0],[893083000000,0]],"bids":[]},"depth":30,"sequence":677996548,"symbol":"sBTCUSDT","timestamp":1590570810819505422,"type":"incremental"} 1694 | < {"book":{"asks":[],"bids":[[892387000000,4792900],[892354000000,3170700],[892226000000,0],[892187000000,14425000],[892171000000,6366500],[892165000000,0],[892135000000,11511400],[892134000000,0],[892127000000,0],[892090000000,5446000],[892079000000,4687800],[892041000000,8590200],[892030000000,0],[892014000000,0]]},"depth":30,"sequence":677996941,"symbol":"sBTCUSDT","timestamp":1590570811244188841,"type":"incremental"} 1695 | ``` 1696 | 1697 | 1698 | 1699 | ### Unsubscribe OrderBook 1700 | 1701 | It unsubscribes all orderbook related subscriptions. 1702 | 1703 | * Request 1704 | 1705 | ```javascript 1706 | { 1707 | "id": , 1708 | "method": "orderbook.unsubscribe", 1709 | "params": [] 1710 | } 1711 | ``` 1712 | 1713 | * Response: 1714 | 1715 | ```javascript 1716 | { 1717 | "error": null, 1718 | "id": , 1719 | "result": { 1720 | "status": "success" 1721 | } 1722 | } 1723 | ``` 1724 | 1725 | 1726 | 1727 | ### Subscribe Trade 1728 | 1729 | On each successful subscription, DataGW will send the 200 history trades immediately for the subscribed symbol and all 1730 | the later trades will be published. 1731 | 1732 | * Request 1733 | 1734 | ```javascript 1735 | { 1736 | "id": , 1737 | "method": "trade.subscribe", 1738 | "params": [ 1739 | "" 1740 | ] 1741 | } 1742 | ``` 1743 | 1744 | * Response: 1745 | 1746 | ```javascript 1747 | { 1748 | "error": null, 1749 | "id": , 1750 | "result": { 1751 | "status": "success" 1752 | } 1753 | } 1754 | ``` 1755 | 1756 | * Sample: 1757 | 1758 | ```javascript 1759 | > { 1760 | "id": 1234, 1761 | "method": "trade.subscribe", 1762 | "params": [ 1763 | "sBTCUSDT" 1764 | ] 1765 | } 1766 | 1767 | < { 1768 | "error": null, 1769 | "id": 1234, 1770 | "result": { 1771 | "status": "success" 1772 | } 1773 | } 1774 | ``` 1775 | 1776 | #### Trade Message Format： 1777 | 1778 | DataGW publishes trade message with types: incremental, snapshot. Incremental messages are published with 20ms interval. 1779 | And snapshot messages are published on connection initial setup for client recovery. 1780 | 1781 | ```javascript 1782 | { 1783 | "trades": [ 1784 | [ 1785 | , 1786 | "", 1787 | , 1788 | 1789 | ], 1790 | . 1791 | . 1792 | . 1793 | ], 1794 | "sequence": , 1795 | "symbol": "", 1796 | "type": "" 1797 | } 1798 | ``` 1799 | 1800 | | Field | Type | Description | Possible values | 1801 | |-------------|--------|------------------|-----------------| 1802 | | timestamp | Integer| Timestamp in nanoseconds for each trade || 1803 | | side | String | Execution taker side| bid, ask | 1804 | | priceEp | Integer| Scaled execution price | | 1805 | | qty | Integer| Execution size | | 1806 | | sequence | Integer| Latest message sequence || 1807 | | symbol | String | Spot symbol name || 1808 | | type | String | Message type |snapshot, incremental | 1809 | 1810 | * Sample 1811 | 1812 | ```javascript 1813 | < { 1814 | "sequence": 1167852, 1815 | "symbol": "sBTCUSDT", 1816 | "trades": [ 1817 | [ 1818 | 1573716998128563500, 1819 | "Buy", 1820 | 867350000000, 1821 | 560000 1822 | ], 1823 | [ 1824 | 1573716995033683000, 1825 | "Buy", 1826 | 867350000000, 1827 | 520000 1828 | ], 1829 | [ 1830 | 1573716991485286000, 1831 | "Buy", 1832 | 867350000000, 1833 | 510000 1834 | ], 1835 | [ 1836 | 1573716988636291300, 1837 | "Buy", 1838 | 867350000000, 1839 | 120000 1840 | ] 1841 | ], 1842 | "type": "snapshot" 1843 | } 1844 | 1845 | < { 1846 | "sequence": 1188273, 1847 | "symbol": "sBTCUSDT", 1848 | "trades": [ 1849 | [ 1850 | 1573717116484024300, 1851 | "Buy", 1852 | 86730000000, 1853 | 210000 1854 | ] 1855 | ], 1856 | "type": "incremental" 1857 | } 1858 | ``` 1859 | 1860 | 1861 | 1862 | ### Unsubscribe Trade 1863 | 1864 | It unsubscribes all trade subscriptions. 1865 | 1866 | * Request 1867 | 1868 | ```javascript 1869 | { 1870 | "id": , 1871 | "method": "trade.subscribe", 1872 | "params": [ 1873 | "" 1874 | ] 1875 | } 1876 | ``` 1877 | 1878 | * Response: 1879 | 1880 | ```javascript 1881 | { 1882 | "error": null, 1883 | "id": , 1884 | "result": { 1885 | "status": "success" 1886 | } 1887 | } 1888 | ``` 1889 | 1890 | 1891 | 1892 | ### Subscribe Kline 1893 | 1894 | On each successful subscription, DataGW will send the 1000 history klines immediately for the subscribed symbol and all 1895 | the later kline update will be published in real-time. 1896 | 1897 | * Request 1898 | 1899 | ```javascript 1900 | { 1901 | "id": , 1902 | "method": "kline.subscribe", 1903 | "params": [ 1904 | "", 1905 | "" 1906 | ] 1907 | } 1908 | ``` 1909 | 1910 | * Response: 1911 | 1912 | ```javascript 1913 | { 1914 | "error": null, 1915 | "id": , 1916 | "result": { 1917 | "status": "success" 1918 | } 1919 | } 1920 | ``` 1921 | 1922 | * Sample: 1923 | 1924 | ```javascript 1925 | # subscribe 1-day kline 1926 | > { 1927 | "id": 1234, 1928 | "method": "kline.subscribe", 1929 | "params": [ 1930 | "sBTCUSDT", 1931 | 86400 1932 | ] 1933 | } 1934 | 1935 | < { 1936 | "error": null, 1937 | "id": 1234, 1938 | "result": { 1939 | "status": "success" 1940 | } 1941 | } 1942 | ``` 1943 | 1944 | #### Kline Message Format： 1945 | 1946 | DataGW publishes kline message with types: incremental, snapshot. Incremental messages are published with 20ms interval. 1947 | And snapshot messages are published on connection initial setup for client recovery. 1948 | 1949 | ```javascript 1950 | { 1951 | "kline": [ 1952 | [ 1953 | , 1954 | "", 1955 | , 1956 | , 1957 | , 1958 | , 1959 | , 1960 | , 1961 | , 1962 | ], 1963 | . 1964 | . 1965 | . 1966 | ], 1967 | "sequence": , 1968 | "symbol": "", 1969 | "type": "" 1970 | } 1971 | ``` 1972 | 1973 | | Field | Type | Description | Possible values | 1974 | |-------------|--------|------------------|-----------------| 1975 | | timestamp | Integer| Timestamp in nanoseconds for each trade || 1976 | | interval | Integer| Kline interval type | 60, 300, 900, 1800, 3600, 14400, 86400, 604800, 2592000, 7776000, 31104000 | 1977 | | lastCloseEp | Integer| Scaled last close price | | 1978 | | openEp | Integer| Scaled open price | | 1979 | | highEp | Integer| Scaled high price | | 1980 | | lowEp | Integer| Scaled low price | | 1981 | | closeEp | Integer| Scaled close price | | 1982 | | volumeEv | Integer| Scaled trade voulme during the current kline interval || 1983 | | turnoverEv | Integer| Scaled turnover value | | 1984 | | sequence | Integer| Latest message sequence || 1985 | | symbol | String | Contract symbol name || 1986 | | type | String | Message type |snapshot, incremental | 1987 | 1988 | * Sample 1989 | 1990 | ```javascript 1991 | < { 1992 | "kline": [ 1993 | [ 1994 | 1590019200, 1995 | 86400, 1996 | 952057000000, 1997 | 952000000000, 1998 | 955587000000, 1999 | 947835000000, 2000 | 954446000000, 2001 | 1162621600, 2002 | 11095452729869 2003 | ], 2004 | [ 2005 | 1589932800, 2006 | 86400, 2007 | 977566000000, 2008 | 978261000000, 2009 | 984257000000, 2010 | 935452000000, 2011 | 952057000000, 2012 | 11785486656, 2013 | 113659374080189 2014 | ], 2015 | [ 2016 | 1589846400, 2017 | 86400, 2018 | 972343000000, 2019 | 972351000000, 2020 | 989607000000, 2021 | 949106000000, 2022 | 977566000000, 2023 | 11337554900, 2024 | 109928494593609 2025 | ] 2026 | ], 2027 | "sequence": 380876982, 2028 | "symbol": "sBTCUSDT", 2029 | "type": "snapshot" 2030 | } 2031 | 2032 | < { 2033 | "kline": [ 2034 | [ 2035 | 1590019200, 2036 | 86400, 2037 | 952057000000, 2038 | 952000000000, 2039 | 955587000000, 2040 | 928440000000, 2041 | 941597000000, 2042 | 4231329700, 2043 | 40057408967508 2044 | ] 2045 | ], 2046 | "sequence": 396865028, 2047 | "symbol": "sBTCUSDT", 2048 | "type": "incremental" 2049 | } 2050 | ``` 2051 | 2052 | 2053 | 2054 | ### Unsubscribe Kline 2055 | 2056 | It unsubscribes all kline subscriptions or for a symbol. 2057 | 2058 | * Request 2059 | 2060 | ```javascript 2061 | # unsubscribe all Kline subscriptions 2062 | { 2063 | "id": , 2064 | "method": "kline.unsubscribe", 2065 | "params": [] 2066 | } 2067 | 2068 | # unsubscribe all Kline subscriptions of a symbol 2069 | { 2070 | "id": , 2071 | "method": "kline.unsubscribe", 2072 | "params": [ 2073 | "" 2074 | ] 2075 | } 2076 | ``` 2077 | 2078 | * Response: 2079 | 2080 | ```javascript 2081 | { 2082 | "error": null, 2083 | "id": , 2084 | "result": { 2085 | "status": "success" 2086 | } 2087 | } 2088 | ``` 2089 | 2090 | 2091 | 2092 | ### Subscribe Wallet-Order messages 2093 | 2094 | WO subscription requires the session been authorized successfully. DataGW extracts the user information from the given 2095 | token and sends WO messages back to client accordingly. 0 or more latest WO snapshot messages will be sent to client 2096 | immediately on subscription, and incremental messages will be sent for later updates. Each account snapshot contains a 2097 | users' wallets and open / max 100 closed / max 100 filled order event message history. 2098 | 2099 | * Request 2100 | 2101 | ```javascript 2102 | { 2103 | "id": , 2104 | "method": "wo.subscribe", 2105 | "params": [ 2106 | "close/fills limits(default 0, means max 100) 2107 | ] 2108 | } 2109 | ``` 2110 | 2111 | * Response: 2112 | 2113 | ```javascript 2114 | { 2115 | "error": null, 2116 | "id": , 2117 | "result": { 2118 | "status": "success" 2119 | } 2120 | } 2121 | ``` 2122 | 2123 | * Sample 2124 | 2125 | ```javascript 2126 | > { 2127 | "id": 1234, 2128 | "method": "wo.subscribe", 2129 | "params": [] 2130 | } 2131 | 2132 | < { 2133 | "error": null, 2134 | "id": 1234, 2135 | "result": { 2136 | "status": "success" 2137 | } 2138 | } 2139 | ``` 2140 | 2141 | #### Wallet-Order Message Sample: 2142 | 2143 | ```javascript 2144 | {"wallets":[],"orders":[{"userID":60463,...}],"sequence":11450, "timestamp":, "type":""} 2145 | ``` 2146 | 2147 | | Field | Type | Description | Possible values | 2148 | |-------------|--------|------------------|-----------------| 2149 | | timestamp | Integer| Transaction timestamp in nanoseconds | | 2150 | | sequence | Integer| Latest message sequence | | 2151 | | type | String | Message type | snapshot, incremental | 2152 | 2153 | * Sample: 2154 | 2155 | ```javascript 2156 | < {"orders":{"closed":[{"action":"New","avgPriceEp":0,"baseCurrency":"BTC","baseQtyEv":10000,"bizError":0,"clOrdID":"123456","createTimeNs":1587463924959744646,"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":1587463924964876798,"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":1587463924964876798,"userID":200076}],"open":[{"action":"New","avgPriceEp":0,"baseCurrency":"BTC","baseQtyEv":100000000,"bizError":0,"clOrdID":"31f793f4-163d-aa3f-5994-0e1164719ba2","createTimeNs":1587547657438535949,"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":1587547657442752950,"triggerTimeNs":0,"userID":200076}]},"sequence":349,"timestamp":1587549121318737606,"type":"snapshot","wallets":[{"balanceEv":0,"currency":"LTC","lastUpdateTimeNs":1587481897840503662,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":351802500000,"currency":"USDT","lastUpdateTimeNs":1587543489127498121,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":630000005401500000,"currency":"BTC","lastUpdateTimeNs":1587547210089640382,"lockedTradingBalanceEv":100000000,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":0,"currency":"ETH","lastUpdateTimeNs":1587481897840503662,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":0,"currency":"XRP","lastUpdateTimeNs":1587481897840503662,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":0,"currency":"LINK","lastUpdateTimeNs":1587481897840503662,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":0,"currency":"XTZ","lastUpdateTimeNs":1587481897840503662,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076}]} 2157 | < {"orders":{"closed":[],"fills":[],"open":[{"action":"New","avgPriceEp":0,"baseCurrency":"BTC","baseQtyEv":100000000,"bizError":0,"clOrdID":"0c1099e5-b900-5351-cf60-edb15ea2539c","createTimeNs":1587549529513521745,"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":1587549529518394235,"triggerTimeNs":0,"userID":200076}]},"sequence":350,"timestamp":1587549529519959388,"type":"incremental","wallets":[{"balanceEv":630000005401500000,"currency":"BTC","lastUpdateTimeNs":1587547210089640382,"lockedTradingBalanceEv":200000000,"lockedWithdrawEv":0,"userID":200076},{"balanceEv":351802500000,"currency":"USDT","lastUpdateTimeNs":1587543489127498121,"lockedTradingBalanceEv":0,"lockedWithdrawEv":0,"userID":200076}]} 2158 | 2159 | ``` 2160 | 2161 | 2162 | 2163 | ### Unsubscribe Wallet-Order 2164 | 2165 | * Request： 2166 | 2167 | ```javascript 2168 | { 2169 | "id": , 2170 | "method": "wo.unsubscribe", 2171 | "params": [] 2172 | } 2173 | ``` 2174 | 2175 | * Response: 2176 | 2177 | ```javascript 2178 | { 2179 | "error": null, 2180 | "id": , 2181 | "result": { 2182 | "status": "success" 2183 | } 2184 | } 2185 | ``` 2186 | 2187 | 2188 | 2189 | ### Subscribe 24 Hours Ticker 2190 | 2191 | On each successful subscription, DataGW will publish 24-hour ticker metrics for all symbols every 1 second. 2192 | 2193 | * Request 2194 | 2195 | ```javascript 2196 | { 2197 | "id": , 2198 | "method": "spot_market24h.subscribe", 2199 | "params": [] 2200 | } 2201 | ``` 2202 | 2203 | * Response: 2204 | 2205 | ```javascript 2206 | { 2207 | "error": null, 2208 | "id": , 2209 | "result": { 2210 | "status": "success" 2211 | } 2212 | } 2213 | ``` 2214 | 2215 | * Sample: 2216 | 2217 | ```javascript 2218 | > { 2219 | "method": "spot_market24h.subscribe", 2220 | "params": [], 2221 | "id": 1234 2222 | } 2223 | 2224 | < { 2225 | "error": null, 2226 | "id": 1234, 2227 | "result": { 2228 | "status": "success" 2229 | } 2230 | } 2231 | ``` 2232 | 2233 | #### Hours Ticker Message Format： 2234 | 2235 | ```javascript 2236 | { 2237 | "spot_market24h": { 2238 | "openEp": , 2239 | "highEp": , 2240 | "lowEp": , 2241 | "lastEp": , 2242 | "bidEp": , 2243 | "askEp": , 2244 | "symbol": "", 2245 | "turnoverEv": , 2246 | "volumeEv": 2247 | }, 2248 | "timestamp": 2249 | } 2250 | ``` 2251 | 2252 | | Field | Type | Description | Possible values | 2253 | |---------------|--------|--------------------------------------------|--------------| 2254 | | open priceEp | Integer| The scaled open price in last 24 hours | | 2255 | | high priceEp | Integer| The scaled highest price in last 24 hours | | 2256 | | low priceEp | Integer| The scaled lowest price in last 24 hours | | 2257 | | last priceEp | Integer| The scaled last price | | 2258 | | bid priceEp | Integer| Scaled bid price | | 2259 | | ask priceEp | Integer| Scaled ask price | | 2260 | | timestamp | Integer| Timestamp in nanoseconds | | 2261 | | symbol | String | Spot Symbol name | [Trading symbols](#productinfo) | 2262 | | turnoverEv | Integer| The scaled turnover value in last 24 hours | | 2263 | | volumeEv | Integer| The scaled trade volume in last 24 hours | | 2264 | 2265 | * Sample: 2266 | 2267 | ```javascript 2268 | < { 2269 | "spot_market24h": { 2270 | "askEp": 892100000000, 2271 | "bidEp": 891835000000, 2272 | "highEp": 898264000000, 2273 | "lastEp": 892486000000, 2274 | "lowEp": 870656000000, 2275 | "openEp": 896261000000, 2276 | "symbol": "sBTCUSDT", 2277 | "timestamp": 1590571240030003249, 2278 | "turnoverEv": 104718804814499, 2279 | "volumeEv": 11841148100 2280 | }, 2281 | "timestamp": 1576490244024818000 2282 | } 2283 | ``` 2284 | 2285 | 2286 | 2287 | ### All Spot trading currencies 2288 | 2289 | | currency | value scale factor | min value | max value | need addr arg | 2290 | |--------|---------------|------------|------------|------------| 2291 | |BTC|8|1|5e+18|0| 2292 | |USDT|8|1|5e+18|0| 2293 | |ETH|8|1|5e+18|0| 2294 | |XRP|8|1|5e+18|1| 2295 | |LINK|8|1|5e+18|0| 2296 | |XTZ|8|1|5e+18|0| 2297 | |LTC|8|1|5e+18|0| 2298 | |ADA|8|1|5e+18|0| 2299 | |TRX|8|1|5e+18|0| 2300 | |ONT|8|1|5e+18|0| 2301 | |BCH|8|1|5e+18|0| 2302 | |NEO|8|1|5e+18|0| 2303 | |EOS|8|1|5e+18|1| 2304 | |COMP|8|1|5e+18|0| 2305 | |LEND|8|1|5e+18|0| 2306 | |YFI|8|1|5e+18|0| 2307 | |DOT|8|1|5e+18|0| 2308 | |UNI|8|1|5e+18|0| 2309 | |AAVE|8|1|5e+18|0| 2310 | |DOGE|8|1|5e+18|0| 2311 | |BAT|8|1|5e+18|0| 2312 | |CHZ|8|1|5e+18|0| 2313 | |MANA|8|1|5e+18|0| 2314 | |ENJ|8|1|5e+18|0| 2315 | |SUSHI|8|1|5e+18|0| 2316 | |SNX|8|1|5e+18|0| 2317 | |GRT|8|1|5e+18|0| 2318 | |MKR|8|1|5e+18|0| 2319 | |ALGO|8|1|5e+18|0| 2320 | |VET|8|1|5e+18|0| 2321 | |ZEC|8|1|5e+18|0| 2322 | |FIL|8|1|5e+18|0| 2323 | |KSM|8|1|5e+18|0| 2324 | |XMR|8|1|5e+18|0| 2325 | |QTUM|8|1|5e+18|0| 2326 | |XLM|8|1|5e+18|1| 2327 | |ATOM|8|1|5e+18|1| 2328 | |LUNA|8|1|5e+18|1| 2329 | |SOL|8|1|5e+18|0| 2330 | |AXS|8|1|5e+18|0| 2331 | |MATIC|8|1|5e+18|0| 2332 | |SHIB|2|1|5e+18|0| 2333 | |FTM|8|1|5e+18|0| 2334 | |DYDX|8|1|5e+18|0| 2335 | |VPAD|4|1|5e+18|0| 2336 | 2337 | 2338 | 2339 | ### All Spot trading products 2340 | 2341 | | symbol| type | price scale factor | ratio scale factor | baseTickSize| baseTickSizeEv| quoteTickSize| quoteTickSizeEv| baseQtyPrecision| quoteQtyPrecision| pricePrecision| minOrderValue| minOrderValueEv| maxBaseOrderSize| maxBaseOrderSizeEv| maxOrderValue| maxOrderValueEv| defaultTakerFee| defaultTakerFeeEr| defaultMakerFee| defaultMakerFeeEr| 2342 | |---------|---------|---------|---------|-------------|-----------|-----------------|------------|------------|-------------|------|--------|-------|------|--------|-------|------|------|-------|-------|--------| 2343 | |sBTCUSDT|Spot|8|8|0.000001 BTC|100|0.01 USDT|1000000|6|2|2|10 USDT|1000000000|1000 BTC|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2344 | |sETHUSDT|Spot|8|8|0.00001 ETH|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|10000 ETH|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2345 | |sXRPUSDT|Spot|8|8|0.1 XRP|10000000|0.00001 USDT|1000|1|2|5|10 USDT|1000000000|5000000 XRP|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2346 | |sLINKUSDT|Spot|8|8|0.01 LINK|1000000|0.0001 USDT|10000|2|2|4|10 USDT|1000000000|5000000 LINK|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2347 | |sXTZUSDT|Spot|8|8|0.01 XTZ|1000000|0.0001 USDT|10000|2|2|4|10 USDT|1000000000|2000000 XTZ|200000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2348 | |sLTCUSDT|Spot|8|8|0.00001 LTC|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|100000 LTC|10000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2349 | |sADAUSDT|Spot|8|8|0.1 ADA|10000000|0.00005 USDT|5000|1|2|5|10 USDT|1000000000|5000000 ADA|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2350 | |sTRXUSDT|Spot|8|8|0.1 TRX|10000000|0.00005 USDT|5000|1|2|5|10 USDT|1000000000|5000000 TRX|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2351 | |sONTUSDT|Spot|8|8|0.1 ONT|10000000|0.0005 USDT|50000|1|2|4|10 USDT|1000000000|5000000 ONT|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2352 | |sBCHUSDT|Spot|8|8|0.00001 BCH|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|10000 BCH|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2353 | |sNEOUSDT|Spot|8|8|0.001 NEO|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|5000000 NEO|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2354 | |sEOSUSDT|Spot|8|8|0.01 EOS|1000000|0.0001 USDT|10000|2|2|4|10 USDT|1000000000|5000000 EOS|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2355 | |sDOGEUSDT|Spot|8|8|1 DOGE|100000000|0.000001 USDT|100|0|2|6|10 USDT|1000000000|5000000 DOGE|500000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2356 | |sBATUSDT|Spot|8|8|0.01 BAT|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|300000 BAT|30000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2357 | |sCHZUSDT|Spot|8|8|0.01 CHZ|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|700000 CHZ|70000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2358 | |sMANAUSDT|Spot|8|8|0.01 MANA|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|400000 MANA|40000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2359 | |sENJUSDT|Spot|8|8|0.01 ENJ|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|200000 ENJ|20000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2360 | |sSUSHIUSDT|Spot|8|8|0.001 SUSHI|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|40000 SUSHI|4000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2361 | |sSNXUSDT|Spot|8|8|0.001 SNX|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|30000 SNX|3000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2362 | |sGRTUSDT|Spot|8|8|0.01 GRT|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|200000 GRT|20000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2363 | |sUNIUSDT|Spot|8|8|0.001 UNI|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|15000 UNI|1500000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2364 | |sAAVEUSDT|Spot|8|8|0.0001 AAVE|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1000 AAVE|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2365 | |sYFIUSDT|Spot|8|8|0.00001 YFI|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|10 YFI|1000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2366 | |sCOMPUSDT|Spot|8|8|0.0001 COMP|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1000 COMP|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2367 | |sMKRUSDT|Spot|8|8|0.00001 MKR|1000|0.01 USDT|1000000|5|2|2|10 USDT|1000000000|100 MKR|10000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2368 | |sDOTUSDT|Spot|8|8|0.001 DOT|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|10000 DOT|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2369 | |sALGOUSDT|Spot|8|8|0.01 ALGO|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|300000 ALGO|30000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2370 | |sVETUSDT|Spot|8|8|0.1 VET|10000000|0.000001 USDT|100|1|2|6|10 USDT|1000000000|2000000 VET|200000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2371 | |sZECUSDT|Spot|8|8|0.0001 ZEC|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|2000 ZEC|200000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2372 | |sFILUSDT|Spot|8|8|0.0001 FIL|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|3000 FIL|300000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2373 | |sKSMUSDT|Spot|8|8|0.0001 KSM|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1000 KSM|100000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2374 | |sXMRUSDT|Spot|8|8|0.0001 XMR|10000|0.01 USDT|1000000|4|2|2|10 USDT|1000000000|1500 XMR|150000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2375 | |sQTUMUSDT|Spot|8|8|0.001 QTUM|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|30000 QTUM|3000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2376 | |sXLMUSDT|Spot|8|8|0.01 XLM|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|1000000 XLM|100000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2377 | |sATOMUSDT|Spot|8|8|0.001 ATOM|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|20000 ATOM|2000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2378 | |sLUNAUSDT|Spot|8|8|0.001 LUNA|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|40000 LUNA|4000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2379 | |sSOLUSDT|Spot|8|8|0.001 SOL|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|10000 SOL|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2380 | |sAXSUSDT|Spot|8|8|0.001 AXS|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|10000 AXS|1000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2381 | |sMATICUSDT|Spot|8|8|0.01 MATIC|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|300000 MATIC|30000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2382 | |sSHIBUSDT|Spot|8|8|1 SHIB|100|0.00000001 USDT|1|0|2|8|10 USDT|1000000000|5000000000 SHIB|500000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2383 | |sFTMUSDT|Spot|8|8|0.01 FTM|1000000|0.00001 USDT|1000|2|2|5|10 USDT|1000000000|200000 FTM|20000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2384 | |sDYDXUSDT|Spot|8|8|0.001 DYDX|100000|0.001 USDT|100000|3|2|3|10 USDT|1000000000|30000 DYDX|3000000000000|5000000 USDT|500000000000000|0.001|100000|0.001|100000| 2385 | |sVPADUSDT|Spot|8|8|0.1 VPAD|1000|0.000001 USDT|100|1|2|6|10 USDT|1000000000|15000000 VPAD|150000000000|500000 USDT|50000000000000|0.001|100000|0.001|100000| 2386 | 2387 | 2388 | 2389 | ### Subscribe Investment Account 2390 | 2391 | on subscription to investment account then you will get your investment information of each currency type. 2392 | 2393 | * Request： 2394 | 2395 | ```javascript 2396 | { 2397 | "id": , 2398 | "method": "wm.subscribe", 2399 | "params": [] 2400 | } 2401 | ``` 2402 | 2403 | * Response: 2404 | 2405 | ```javascript 2406 | { 2407 | "error": null, 2408 | "id": , 2409 | "result": { 2410 | "status":"success" 2411 | } 2412 | } 2413 | ``` 2414 | 2415 | * Sample： 2416 | 2417 | ```javascript 2418 | { 2419 | "id": 1234, 2420 | "method": "wm.subscribe", 2421 | "params": [] 2422 | } 2423 | 2424 | { 2425 | "error": null, 2426 | "id": 1234, 2427 | "result": { 2428 | "status":"success" 2429 | } 2430 | } 2431 | ``` 2432 | 2433 | #### Investment Account Message Format： 2434 | 2435 | ```javascript 2436 | { 2437 | "investments":[ 2438 | { 2439 | "currency":, 2440 | "balanceEv":, 2441 | "userId":, 2442 | "demandPendingInterestBalanceEv":, 2443 | "demandInterestedBalanceEv":, 2444 | "timedDepositBalanceEv":, 2445 | "currentTimeMillis": 2446 | ] 2447 | } 2448 | ``` 2449 | 2450 | | Field | Type | Description | Possible values | 2451 | |-------------|--------|------------------|-----------------| 2452 | | currency | String |invested currency | BTC,ETH | 2453 | | balanceEv | Long |invested amount | 0 | 2454 | | userId | Long | your user id | 1234 | 2455 | | demandPendingInterestBalanceEv | Long | pending interest for flexible product | 0 | 2456 | | demandInterestedBalanceEv | Long | paid interest for flexible product | 0 | 2457 | | timedDepositBalanceEv | Long | amount for fixed product | 20000000000 | 2458 | | currentTimeMillis | Long | time in milli | 1653972360166 | 2459 | 2460 | * Sample： 2461 | 2462 | ```javascript 2463 | { 2464 | "investments":[ 2465 | { 2466 | "currency":"USDT", 2467 | "balanceEv":21797700000, 2468 | "userId":1234, 2469 | "demandPendingInterestBalanceEv":0, 2470 | "demandInterestedBalanceEv":0, 2471 | "timedDepositBalanceEv":20000000000, 2472 | "currentTimeMillis":1653972360161 2473 | }, 2474 | { 2475 | "currency":"BTC", 2476 | "balanceEv":0, 2477 | "userId":1234, 2478 | "demandPendingInterestBalanceEv":0, 2479 | "demandInterestedBalanceEv":0, 2480 | "timedDepositBalanceEv":0, 2481 | "currentTimeMillis":1653972360166 2482 | } 2483 | ] 2484 | } 2485 | ``` 2486 | -------------------------------------------------------------------------------- /Public-Hedged-Perpetual-API.md: -------------------------------------------------------------------------------- 1 | ## Table of Contents * [Phemex Public API](#publicapi) * [General Public API Information](#general) 2 | * [REST API Standards](#restapi) 3 | * [REST API List](#restapilist) 4 | * [Market API List](#marketapilist) 5 | * [Query Product Information](#queryproductinfo) 6 | * [Trade API List](#orderapilist) 7 | * [Place Order With Put Method, *Prefered*](#placeorderwithput) 8 | * [Place Order](#placeorder) 9 | * [Amend order by orderID](#amendorder) 10 | * [Cancel Single Order by orderID or clOrdID](#cancelsingleorder) 11 | * [Bulk Cancel Orders](#cancelorder) 12 | * [Cancel All Orders](#cancelall) 13 | * [Query Account Positions](#queryaccountpositions) 14 | * [Query Account Positions with unrealized PNL](#queryaccountpositionsWithPnl) 15 | * [Switch Position Mode Synchronously](#switchpositionmodesync) 16 | * [Set Leverage](#setleverage) 17 | * [Set RiskLimit](#setrisklimit) 18 | * [Assign Position Balance](#assignpositionbalance) 19 | * [Query Open Orders by Symbol](#queryopenorder) 20 | * [Query Closed Orders by Symbol](#queryorder) 21 | * [Query Order by orderID](#queryorderbyid) 22 | * [Query User Trades by Symbol](#querytrade) 23 | * [Market Data API List ](#mdapilist) 24 | * [Query Order Book](#queryorderbook) 25 | * [Query kline](#querykline) 26 | * [Query Recent Trades](#querytrades) 27 | * [Query 24 Hours Ticker](#query24hrsticker) 28 | * [Query History Trades](#queryhisttrades) 29 | * [Asset API List](#assetapilist) 30 | * [Future Data Api List](#futureDataAPIList) 31 | * [Query Funding Fees History](#futureDataFundingFeesHist) 32 | * [Query Orders History](#futureDataOrdersHist) 33 | * [Query Orders By Ids](#futureDataOrdersByIds) 34 | * [Query Trades History](#futureDataTradesHist) 35 | * [Query Trading Fees History](#futureDataTradingFeesHist) 36 | * [Withdraw](#withdraw) 37 | * [Websocket API Standards](#wsapi) 38 | * [Session Management](#sessionmanagement) 39 | * [API Rate Limits](#wsapiratelimits) 40 | * [WebSocket API List](#wsapilist) 41 | * [Subscribe OrderBook](#booksub) 42 | * [Unsubscribe OrderBook](#bookunsub) 43 | * [Subscribe Trade](#tradesub) 44 | * [Unsubscribe Trade](#tradeunsub) 45 | * [Subscribe Kline](#klinesub) 46 | * [Unsubscribe Kline](#klinesub) 47 | * [Subscribe Account-Order-Position (AOP)](#aopsub) 48 | * [Unsubscribe Account-Order-Position (AOP)](#aopunsub) 49 | * [Subscribe account margin (RAS)](#rassub) 50 | * [Unsubscribe account margin (RAS)](#rasunsub) 51 | * [Subscribe 24 Hours Ticker](#tickersub) 52 | * [Subscribe symbol price](#symbpricesub) 53 | 54 | 55 | 56 | 57 | # Phemex Public API 58 | 59 | 60 | 61 | ## General Public API Information 62 | 63 | * Phemex provides HTTP Rest API for client to operate Orders, all endpoints return a JSON object. 64 | * The default Rest API base endpoint is: **https://api.phemex.com**. The High rate limit Rest API base endpoint is: **https://vapi.phemex.com**. Or for the testnet is: **https://testnet-api.phemex.com** 65 | * Phemex provides WebSocket API for client to receive market data, order and position updates. 66 | * The WebSocket API url is: **wss://phemex.com/ws**. The High rate limit WebSocket API url is: **wss://vapi.phemex.com/ws**. Or for the testnet is: **wss://testnet.phemex.com/ws** 67 | 68 | 69 | 70 | 71 | 72 | ### Market API List 73 | 74 | 75 | 76 | #### Query Product Information 77 | 78 | * Request： 79 | 80 | ``` 81 | GET /public/products 82 | ``` 83 | 84 | you can find products info with hedged mode under node 'perpProductsV2' 85 | 86 | 87 | 88 | 89 | ### Trade API List 90 | 91 | 92 | 93 | 94 | #### Place order with argument in url query string 95 | 96 | * HTTP Request 97 | 98 | ``` 99 | PUT /g-orders/create?clOrdID=&symbol=&reduceOnly=&closeOnTrigger=&orderQtyRq=&ordType=&priceRp=&side=&posSide=&text=&timeInForce=&stopPxRp=&takeProfitRp=&stopLossRp=&pegOffsetValueRp=&pegPriceType=&triggerType=&tpTrigger=&tpSlTs=&slTrigger= 100 | ``` 101 | 102 | | Field | Type | Required | Description | Possible values | 103 | | ---------------- | ------- | -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 104 | | clOrdID | String | - | client order id, max length is 40 | | 105 | | symbol | String | Yes | Which symbol to place order | [Trading symbols](#symbpricesub) | 106 | | reduceOnly | Boolean | - | whether reduce position side only. Enable this flag, i.e. reduceOnly=true, position side won't change | true, false | 107 | | closeOnTrigger | Boolean | - | implicitly reduceOnly, plus cancel other orders in the same direction(side) when necessary | true, false | 108 | | orderQtyRq | String | - | Order real quantity | "1" | 109 | | ordType | String | - | Order type, default to Limit | Market,Limit,Stop,StopLimit,MarketIfTouched,LimitIfTouched,
ProtectedMarket,MarketAsLimit,StopAsLimit,
MarketIfTouchedAsLimit,Bracket,BoTpLimit,BoSlLimit,BoSlMarket | 110 | | priceRp | String | - | Real price, required for limit order | "1" | 111 | | side | String | Yes | Order direction, Buy or Sell | Buy, Sell | 112 | | posSide | String | Yes | Position direction | "Merged" for oneway mode ,
"Long" / "Short" for hedge mode | 113 | | text | String | - | Order comments | | 114 | | timeInForce | String | - | Time in force. default to GoodTillCancel | GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly | 115 | | stopPxRp | String | - | Trigger price for stop orders | "1" | 116 | | takeProfitRp | String | - | Real take profit price | "1" | 117 | | stopLossRp | String | - | Real stop loss price | "1" | 118 | | pegOffsetValueRp | String | - | Trailing offset from current price. Negative value when position is long, positive when position is short | "1" | 119 | | pegPriceType | String | - | Trailing order price type | LastPeg, MidPricePeg, MarketPeg, PrimaryPeg, TrailingStopPeg, TrailingTakeProfitPeg | 120 | | triggerType | String | - | Trigger source | ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit | 121 | | tpTrigger | String | - | Trigger source | ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit | 122 | | slTrigger | String | - | Trigger source | ByMarkPrice, ByIndexPrice, ByLastPrice, ByAskPrice, ByBidPrice, ByMarkPriceLimit, ByLastPriceLimit | 123 | 124 | * HTTP Response: 125 | 126 | ```json 127 | { 128 | "code": 0, 129 | "data": { 130 | "actionTimeNs": 1580547265848034600, 131 | "bizError": 0, 132 | "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f", 133 | "closedPnlRv": "1271.9", 134 | "closedSizeRq": "0.01", 135 | "cumQtyRq": "0.01", 136 | "cumValueRv": "1271.9", 137 | "displayQtyRq": "0.01", 138 | "execInst": "ReduceOnly", 139 | "execStatus": "Init", 140 | "leavesQtyRq": "0.01", 141 | "leavesValueRv": "1271.9", 142 | "ordStatus": "Init", 143 | "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf", 144 | "orderQtyRq": "0.01", 145 | "orderType": "Limit", 146 | "pegOffsetValueRp": "1271.9", 147 | "pegPriceType": "LastPeg", 148 | "priceRq": "98970000", 149 | "reduceOnly": true, 150 | "side": "Sell", 151 | "stopDirection": "Rising", 152 | "stopPxRp": "1271.9", 153 | "symbol": "BTCUSDT", 154 | "timeInForce": "GoodTillCancel", 155 | "transactTimeNs": 0, 156 | "trigger": "ByMarkPrice" 157 | }, 158 | "msg": "string" 159 | } 160 | ``` 161 | 162 | * Important fields description 163 | * More order type examples 164 | 165 | 166 | 167 | 168 | 169 | #### Place Order 170 | 171 | * HTTP Request: 172 | 173 | Request fields are the same as [above place-order](#placeorderwithput) 174 | 175 | ```json 176 | POST /g-orders 177 | 178 | body: 179 | { 180 | "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f", 181 | "closeOnTrigger": true, 182 | "displayQtyRq": "0.01", 183 | "ordType": "Limit", 184 | "orderQtyRq": "0.01", 185 | "pegOffsetValueRp": "1271.9", 186 | "pegPriceType": "LastPeg", 187 | "posSide": "Long", 188 | "priceRp": "1271.9", 189 | "reduceOnly": true, 190 | "side": "Buy", 191 | "slTrigger": "ByMarkPrice", 192 | "stopLossRp": "1271.9", 193 | "stopPxRp": "1271.9", 194 | "symbol": "BTCUSDT", 195 | "takeProfitRp": "1271.9", 196 | "text": "string", 197 | "timeInForce": "GoodTillCancel", 198 | "tpTrigger": "ByMarkPrice", 199 | "triggerType": "ByMarkPrice" 200 | } 201 | ``` 202 | 203 | * Response 204 | 205 | ​ Response is the same as [above place-order](#placeorderwithput) 206 | 207 | 208 | 209 | 210 | 211 | #### Amend order by orderID 212 | 213 | * HTTP Request 214 | 215 | ``` 216 | PUT /g-orders/replace?symbol=&orderID=&origClOrdID=&clOrdID=&price=&priceRp=&orderQtyRq=&stopPxRp=&takeProfitRp=&stopLossRp=&pegOffsetValueRp=&pegPriceType=&triggerType=&posSide= 217 | ``` 218 | 219 | | Field | Required | Description | 220 | | ---------------- | -------- | ------------------------------------- | 221 | | symbol | Yes | order symbol, cannot be changed | 222 | | orderID | Yes | order id, cannot be changed | 223 | | origClOrdID | - | original clOrderID, cannot be changed | 224 | | clOrdID | - | new clOrdID | 225 | | priceRp | - | new order price, real value | 226 | | orderQtyRq | Yes | new orderQty, real value | 227 | | stopPxRp | Yes | new stop price, real value | 228 | | takeProfitRp | Yes | new stop profit price, real value | 229 | | stopLossRp | Yes | new stop loss price, real value | 230 | | pegOffsetValueRp | Yes | new trailing offset, real value | 231 | | pegPriceType | Yes | new peg price type | 232 | | triggerType | Yes | new triggerType | 233 | | posSide | Yes | posSide to check, can not be changed | 234 | 235 | * Response 236 | 237 | ```json 238 | { 239 | "code": 0, 240 | "data": { 241 | "actionTimeNs": 0, 242 | "bizError": 0, 243 | "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f", 244 | "closedPnlRv": "1271.9", 245 | "closedSizeRq": "0.01", 246 | "cumQtyRq": "0.01", 247 | "cumValueRv": "1271.9", 248 | "displayQtyRq": "0.01", 249 | "execInst": "ReduceOnly", 250 | "execStatus": "Init", 251 | "leavesQtyRq": "0.01", 252 | "leavesValueRv": "1271.9", 253 | "ordStatus": "Init", 254 | "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf", 255 | "orderQtyRq": "0.01", 256 | "orderType": "Limit", 257 | "pegOffsetValueRp": "1271.9", 258 | "pegPriceType": "LastPeg", 259 | "priceRp": "1271.9", 260 | "reduceOnly": true, 261 | "side": "Sell", 262 | "stopDirection": "Rising", 263 | "stopPxRp": "1271.9", 264 | "symbol": "BTCUSDT", 265 | "timeInForce": "GoodTillCancel", 266 | "transactTimeNs": 0, 267 | "trigger": "ByMarkPrice", 268 | "takeProfitRp":"1271.9", 269 | "stopLossRp":"1271.9" 270 | }, 271 | "msg": "string" 272 | } 273 | ``` 274 | 275 | 276 | 277 | 278 | 279 | #### Cancel Single Order by orderID 280 | 281 | * HTTP Request 282 | 283 | ``` 284 | DELETE /g-orders/cancel?orderID=&posSide=&symbol= 285 | ``` 286 | 287 | | Field | Type | Required | Description | 288 | | ------- | ------ | -------- | ---------------------------- | 289 | | orderID | String | Yes | order id, cannot be changed | 290 | | symbol | String | Yes | which symbol to cancel order | 291 | | posSide | String | Yes | position direction | 292 | 293 | * Response 294 | 295 | ```json 296 | { 297 | "code": 0, 298 | "data": { 299 | "actionTimeNs": 450000000, 300 | "bizError": 0, 301 | "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f", 302 | "closedPnlRv": "1271.9", 303 | "closedSizeRq": "0.01", 304 | "cumQtyRq": "0.01", 305 | "cumValueRv": "1271.9", 306 | "displayQtyRq": "0.01", 307 | "execInst": "ReduceOnly", 308 | "execStatus": "Init", 309 | "leavesQtyRq": "0.01", 310 | "leavesValueRv": "0.01", 311 | "ordStatus": "Init", 312 | "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf", 313 | "orderQtyRq": "0.01", 314 | "orderType": "Limit", 315 | "pegOffsetValueRp": "1271.9", 316 | "pegPriceType": "LastPeg", 317 | "priceRq": "0.01", 318 | "reduceOnly": true, 319 | "side": "Sell", 320 | "stopDirection": "Rising", 321 | "stopPxRp": "0.01", 322 | "symbol": "BTCUSDT", 323 | "timeInForce": "GoodTillCancel", 324 | "transactTimeNs": 450000000, 325 | "trigger": "ByMarkPrice" 326 | }, 327 | "msg": "string" 328 | } 329 | ``` 330 | 331 | 332 | 333 | 334 | 335 | #### Bulk Cancel Orders 336 | 337 | * Request 338 | 339 | ``` 340 | DELETE /g-orders?symbol=&orderID=,,&posSide= 341 | ``` 342 | 343 | | Field | Type | Required | Description | 344 | | ------- | ------ | -------- | ---------------------------------------------------- | 345 | | orderID | String | Yes | list of order ids to be cancelled, cannot be changed | 346 | | symbol | String | Yes | which symbol to cancel order | 347 | | posSide | String | Yes | position direction | 348 | 349 | * Response 350 | 351 | ```json 352 | { 353 | "code": 0, 354 | "data": { 355 | "actionTimeNs": 450000000, 356 | "bizError": 0, 357 | "clOrdID": "137e1928-5d25-fecd-dbd1-705ded659a4f", 358 | "closedPnlRv": "1271.9", 359 | "closedSizeRq": "0.01", 360 | "cumQtyRq": "0.01", 361 | "cumValueRv": "1271.9", 362 | "displayQtyRq": "0.01", 363 | "execInst": "ReduceOnly", 364 | "execStatus": "Init", 365 | "leavesQtyRq": "0.01", 366 | "leavesValueRv": "1271.9", 367 | "ordStatus": "Init", 368 | "orderID": "ab90a08c-b728-4b6b-97c4-36fa497335bf", 369 | "orderQtyRq": "0.01", 370 | "orderType": "Limit", 371 | "pegOffsetValueRp": "1271.9", 372 | "pegPriceType": "LastPeg", 373 | "priceRq": "0.01", 374 | "reduceOnly": true, 375 | "side": "string", 376 | "stopDirection": "Rising", 377 | "stopPxRp": "1271.9", 378 | "symbol": "BTCUSDT", 379 | "timeInForce": "GoodTillCancel", 380 | "transactTimeNs": 450000000, 381 | "trigger": "ByMarkPrice" 382 | }, 383 | "msg": "string" 384 | } 385 | ``` 386 | 387 | 388 | 389 | 390 | 391 | #### Cancel All Orders 392 | 393 | * Cancel all orders for hedge supported symbols. 394 | * In order to cancel all orders, include conditional order and active order, one must invoke this API twice with different arguments. 395 | * `untriggered=false` to cancel active order including triggerred conditional order. 396 | * `untriggered=true` to cancel conditional order, the order is not triggerred. 397 | 398 | * Request 399 | 400 | ``` 401 | DELETE /g-orders/all?symbol=&untriggered=&text= 402 | ``` 403 | 404 | | Field | Type | Required | Description | 405 | | ----------- | ------- | -------- | ------------------------------------ | 406 | | symbol | String | - | list of symbols to cancel all orders | 407 | | untriggered | boolean | - | | 408 | | text | String | - | | 409 | 410 | * Response 411 | 412 | ```json 413 | { 414 | "code": 0, 415 | "data": 0, 416 | "msg": "string" 417 | } 418 | ``` 419 | 420 | 421 | 422 | 423 | 424 | #### Query Account Positions 425 | 426 | * Request 427 | 428 | ``` 429 | GET /g-accounts/accountPositions?currency=&symbol= 430 | ``` 431 | 432 | | Field | Type | Required | Description | 433 | | -------- | ------ | -------- | ----------- | 434 | | symbol | String | - | | 435 | | currency | String | Yes | | 436 | 437 | * Response 438 | 439 | ```json 440 | { 441 | "code": 0, 442 | "data": { 443 | "account": { 444 | "accountBalanceRv": "1271.9", 445 | "accountId": 123450001, 446 | "bonusBalanceRv": "1271.9", 447 | "currency": "BTC", 448 | "totalUsedBalanceRv": "1271.9", 449 | "userID": 12345 450 | }, 451 | "positions": [ 452 | { 453 | "accountID": 123450001, 454 | "assignedPosBalanceRv": "1271.9", 455 | "avgEntryPrice": "1271.9", 456 | "avgEntryPriceRp": "1271.9", 457 | "bankruptCommRv": "1271.9", 458 | "bankruptPriceRp": "1271.9", 459 | "buyValueToCostRr": "0.1", 460 | "crossMargin": true, 461 | "cumClosedPnlRv": "1271.9", 462 | "cumFundingFeeRv": "1271.9", 463 | "cumTransactFeeRv": "1271.9", 464 | "curTermRealisedPnlRv": "1271.9", 465 | "currency": "BTC", 466 | "deleveragePercentileRr": "0.1", 467 | "estimatedOrdLossRv": "1271.9", 468 | "execSeq": 0, 469 | "initMarginReqRr": "0.1", 470 | "lastFundingTimeNs": 450000000, 471 | "lastTermEndTimeNs": 450000000, 472 | "leverageRr": "0", 473 | "liquidationPriceRp": "1271.9", 474 | "maintMarginReqRr": "0.1", 475 | "makerFeeRateRr": "0.1", 476 | "markPriceRp": "1271.9", 477 | "posCostRv": "1271.9", 478 | "posMode": "Hedged", 479 | "posSide": "Long", 480 | "positionMarginRv": "1271.9", 481 | "positionStatus": "Normal", 482 | "riskLimitRv": "0.1", 483 | "sellValueToCostRr": "0.1", 484 | "side": "Sell", 485 | "size": "0", 486 | "symbol": "BTC", 487 | "takerFeeRateRr": "0.1", 488 | "term": 0, 489 | "transactTimeNs": 450000000, 490 | "usedBalanceRv": "1271.9", 491 | "userID": 12345, 492 | "valueRv": "1271.9" 493 | } 494 | ] 495 | }, 496 | "msg": "string" 497 | } 498 | ``` 499 | 500 | 501 | #### Query Account Positions with unrealized PNL 502 | 503 | 504 | 505 | Below API presents unrealized pnl at `markprice` of positions with **considerable** cost, thus 506 | its [ratelimit](/Generic-API-Info.en.md#contractAPIGroup) weight is very high. 507 | 508 | * Request 509 | 510 | ``` 511 | GET /g-accounts/positions?currency= 512 | ``` 513 | 514 | * Response 515 | 516 | ```json 517 | { 518 | "code": 0, 519 | "msg": "", 520 | "data": { 521 | "account": { 522 | "userID": 4200013, 523 | "accountId": 42000130003, 524 | "currency": "USDT", 525 | "accountBalanceRv": "730.97309163", 526 | "totalUsedBalanceRv": "1.02037554", 527 | "bonusBalanceRv": "0" 528 | }, 529 | "positions": [ 530 | { 531 | "accountID": 42000130003, 532 | "symbol": "XEMUSDT", 533 | "currency": "USDT", 534 | "side": "Buy", 535 | "positionStatus": "Normal", 536 | "crossMargin": false, 537 | "leverageRr": "-10", 538 | "initMarginReqRr": "0.1", 539 | "maintMarginReqRr": "0.01", 540 | "riskLimitRv": "200000", 541 | "sizeRq": "186", 542 | "valueRv": "9.951", 543 | "avgEntryPriceRp": "0.0535", 544 | "posCostRv": "1.00047354", 545 | "assignedPosBalanceRv": "1.086606978", 546 | "bankruptCommRv": "0.00001116", 547 | "bankruptPriceRp": "0.0001", 548 | "positionMarginRv": "730.97308047", 549 | "liquidationPriceRp": "0.0001", 550 | "deleveragePercentileRr": "0", 551 | "buyValueToCostRr": "0.10114", 552 | "sellValueToCostRr": "0.10126", 553 | "markPriceRp": "0.053036917", 554 | "markValueEv": 0, 555 | "unRealisedPosLossEv": 0, 556 | "estimatedOrdLossRv": "0", 557 | "usedBalanceRv": "1.086606978", 558 | "takeProfitEp": 0, 559 | "stopLossEp": 0, 560 | "cumClosedPnlRv": "0", 561 | "cumFundingFeeRv": "0", 562 | "cumTransactFeeRv": "0.0059706", 563 | "realisedPnlEv": 0, 564 | "unRealisedPnlRv": "-0.086133438", 565 | "cumRealisedPnlEv": 0, 566 | "term": 1, 567 | "lastTermEndTimeNs": 0, 568 | "lastFundingTimeNs": 0, 569 | "curTermRealisedPnlRv": "-0.0059706", 570 | "execSeq": 2260172450, 571 | "posSide": "Long", 572 | "posMode": "Hedged" 573 | }, 574 | { 575 | "accountID": 42000130003, 576 | "symbol": "XEMUSDT", 577 | "currency": "USDT", 578 | "side": "None", 579 | "positionStatus": "Normal", 580 | "crossMargin": false, 581 | "leverageRr": "-10", 582 | "initMarginReqRr": "0.1", 583 | "maintMarginReqRr": "0.01", 584 | "riskLimitRv": "200000", 585 | "sizeRq": "0", 586 | "valueRv": "0", 587 | "avgEntryPriceRp": "0", 588 | "posCostRv": "0", 589 | "assignedPosBalanceRv": "0", 590 | "bankruptCommRv": "0", 591 | "bankruptPriceRp": "0", 592 | "positionMarginRv": "0", 593 | "liquidationPriceRp": "0", 594 | "deleveragePercentileRr": "0", 595 | "buyValueToCostRr": "0.10114", 596 | "sellValueToCostRr": "0.10126", 597 | "markPriceRp": "0.053036917", 598 | "markValueEv": 0, 599 | "unRealisedPosLossEv": 0, 600 | "estimatedOrdLossRv": "0", 601 | "usedBalanceRv": "0", 602 | "takeProfitEp": 0, 603 | "stopLossEp": 0, 604 | "cumClosedPnlRv": "0", 605 | "cumFundingFeeRv": "0", 606 | "cumTransactFeeRv": "0", 607 | "realisedPnlEv": 0, 608 | "unRealisedPnlRv": "0", 609 | "cumRealisedPnlEv": 0, 610 | "term": 1, 611 | "lastTermEndTimeNs": 0, 612 | "lastFundingTimeNs": 0, 613 | "curTermRealisedPnlRv": "0", 614 | "execSeq": 0, 615 | "posSide": "Short", 616 | "posMode": "Hedged" 617 | } 618 | ] 619 | } 620 | } 621 | 622 | ``` 623 | 624 | Note Highly recommend calculating `unRealizedPnlEv` in client side with latest `markPrice` to avoid ratelimit 625 | penalty. 626 | 627 | 628 | 629 | 630 | #### Switch Position Mode Synchronously 631 | 632 | * Request 633 | 634 | ``` 635 | PUT /g-positions/switch-pos-mode-sync?symbol=&targetPosMode= 636 | ``` 637 | 638 | | Field | Type | Required | Description | Possible values | 639 | | ------------- | ------ | -------- | ------------------------------ |-----------------| 640 | | symbol | String | Yes | symbol to switch position mode | | 641 | | targetPosMode | String | Yes | the target position mode | OneWay, Hedged | 642 | 643 | * Response 644 | 645 | ```json 646 | { 647 | "code": 0, 648 | "data": "string", 649 | "msg": "string" 650 | } 651 | ``` 652 | 653 | 654 | 655 | 656 | 657 | #### Set Leverage 658 | 659 | * Request 660 | 661 | ``` 662 | PUT /g-positions/leverage?leverageRr=&longLeverageRr=&shortLeverageRr=&symbol= 663 | ``` 664 | 665 | | Field | Type | Required | Description | 666 | | --------------- | ------ | -------- | ------------------------------------------------------------ | 667 | | symbol | String | Yes | symbol to set leverage | 668 | | leverageRr | String | - | new leverage value, if leverageRr exists, the position side is merged.
either leverageRr or longLeverageRr and shortLeverageRr should exist. | 669 | | longLeverageRr | String | - | new long leverage value, if longLeverageRr exists, the position side is hedged.
either leverageRr or longLeverageRr and shortLeverageRr should exist. | 670 | | shortLeverageRr | String | - | new short leverage value, if shortLeverageRr exists, the position side is hedged
either leverageRr or longLeverageRr and shortLeverageRr should exist. | 671 | 672 | * Response 673 | 674 | ```json 675 | { 676 | "code": 0, 677 | "data": "string", 678 | "msg": "string" 679 | } 680 | ``` 681 | 682 | 683 | 684 | 685 | 686 | #### Set RiskLimit 687 | Risk Limit Modification Notice: 688 | 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 689 | automatically adjusted. 690 | 691 | New Risk Limit Configuration Explanation: 692 | 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 693 | configuration is as follows: 694 | ```json 695 | { 696 | "index_id": 1, 697 | "items": [ 698 | { 699 | "notionalValueRv": 50000, 700 | "maxLeverage": 20, 701 | "maintenanceMarginRateRr": "0.01", 702 | "maintenanceAmountRv": "0" 703 | }, 704 | { 705 | "notionalValueRv": 100000, 706 | "maxLeverage": 10, 707 | "maintenanceMarginRateRr": "0.06", 708 | "maintenanceAmountRv": "0" 709 | }, 710 | { 711 | "notionalValueRv": 200000, 712 | "maxLeverage": 5, 713 | "maintenanceMarginRateRr": "0.16", 714 | "maintenanceAmountRv": "0" 715 | }, 716 | { 717 | "notionalValueRv": 300000, 718 | "maxLeverage": 2, 719 | "maintenanceMarginRateRr": "0.46", 720 | "maintenanceAmountRv": "0" 721 | }, 722 | { 723 | "notionalValueRv": 500000, 724 | "maxLeverage": 1, 725 | "maintenanceMarginRateRr": "0.5", 726 | "maintenanceAmountRv": "0" 727 | } 728 | ] 729 | } 730 | ``` 731 | 732 | 733 | 734 | 735 | #### Assign Position Balance 736 | 737 | * Request 738 | 739 | ``` 740 | POST /g-positions/assign?posBalanceRv=&posSide=&symbol= 741 | ``` 742 | 743 | | Field | Type | Required | Description | 744 | | ------------ | ------ | -------- | ---------------------------------------- | 745 | | symbol | String | Yes | symbol to assign position balance | 746 | | posSide | String | Yes | position side to assign position balance | 747 | | posBalanceRv | String | Yes | the position balance value | 748 | 749 | * Response 750 | 751 | ```json 752 | { 753 | "code": 0, 754 | "data": "string", 755 | "msg": "string" 756 | } 757 | ``` 758 | 759 | 760 | 761 | 762 | 763 | #### Query open orders by symbol 764 | 765 | * Order status includes `New`, `PartiallyFilled`, `Filled`, `Canceled`, `Rejected`, `Triggered`, `Untriggered`; 766 | * Open order status includes `New`, `PartiallyFilled`, `Untriggered`; 767 | 768 | * Request 769 | 770 | ``` 771 | GET /g-orders/activeList?symbol= 772 | ``` 773 | 774 | | Field | Type | Description | Possible values | 775 | |---------|--------|--------------------------------------------|--------------| 776 | | symbol | String | which symbol needs to query | [Trading symbols](#symbpricesub) | 777 | 778 | 779 | * Response 780 | * Full order 781 | 782 | ``` 783 | to be added 784 | ``` 785 | 786 | 787 | 788 | #### Query closed orders by symbol 789 | 790 | * This API is for ***closed*** orders. For open orders, please use [open order query](#queryopenorder) 791 | 792 | * Request 793 | 794 | 795 | ``` 796 | GET /exchange/order/v2/orderList?symbol=¤cy=&ordStatus=&ordType=&start=&end=&offset=&limit=&withCount= 797 | ``` 798 | 799 | | Field | Type | Required | Description | Possible values | 800 | |----|----|----|---------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 801 | | symbol | String | No | which symbol needs to query | [Trading symbols](#symbpricesub) | 802 | |currency|String|Yes| which currency needs to query | | 803 | | ordStatus | Integer | No | order status code list filter | New(5), PartiallyFilled(6), Untriggered(1), Filled(7), Canceled(8) | 804 | | 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) | 805 | | start | Integer | Yes | start time range, Epoch millis，available only from the last 2 month || 806 | | end | Integer | Yes | end time range, Epoch millis || 807 | | offset | Integer | Yes | offset to resultset || 808 | | limit | Integer | Yes | limit of resultset, max 200 || 809 | | withCount | boolean | No | if true, result info will contains count info. | true,false | 810 | 811 | - Response 812 | - sample response 813 | 814 | ``` 815 | { 816 | "code": 0, 817 | "msg": "OK", 818 | "data": { 819 | "total": 3, 820 | "rows": [ 821 | { 822 | "createdAt": 1666179379726, 823 | "symbol": "ETHUSDT", 824 | "orderQtyRq": "0.78", 825 | "side": 1, 826 | "priceRp": "1271.9", 827 | "execQtyRq": "0.78", 828 | "leavesQtyRq": "0", 829 | "execPriceRp": "1271.9", 830 | "orderValueRv": "992.082", 831 | "leavesValueRv": "0", 832 | "cumValueRv": "992.082", 833 | "stopDirection": 0, 834 | "stopPxRp": "0", 835 | "trigger": 0, 836 | "actionBy": 1, 837 | "execFeeRv": "0.0012719", 838 | "ordType": 2, 839 | "ordStatus": 7, 840 | "clOrdId": "2739dc9", 841 | "orderId": "2739dc90-41c6-449f-8774-0a62c8d8e320", 842 | "execStatus": 6, 843 | "bizError": 0, 844 | "totalPnlRv": null, 845 | "avgTransactPriceRp": null, 846 | "orderDetailsVos": null, 847 | "tradeType": 1 848 | }, 849 | { 850 | "createdAt": 1666179345898, 851 | "symbol": "ETHUSDT", 852 | "orderQtyRq": "0.78", 853 | "side": 1, 854 | "priceRp": "1271.9", 855 | "execQtyRq": "0.78", 856 | "leavesQtyRq": "0", 857 | "execPriceRp": "1271.9", 858 | "orderValueRv": "992.082", 859 | "leavesValueRv": "0", 860 | "cumValueRv": "992.082", 861 | "stopDirection": 0, 862 | "stopPxRp": "0", 863 | "trigger": 0, 864 | "actionBy": 1, 865 | "execFeeRv": "0.0992082", 866 | "ordType": 2, 867 | "ordStatus": 7, 868 | "clOrdId": "ae20aef", 869 | "orderId": "ae20aef9-a62e-49d6-947e-39a9b2be39dd", 870 | "execStatus": 6, 871 | "bizError": 0, 872 | "totalPnlRv": null, 873 | "avgTransactPriceRp": null, 874 | "orderDetailsVos": null, 875 | "tradeType": 1 876 | }, 877 | { 878 | "createdAt": 1666179331578, 879 | "symbol": "ETHUSDT", 880 | "orderQtyRq": "0.07", 881 | "side": 1, 882 | "priceRp": "1271.9", 883 | "execQtyRq": "0.07", 884 | "leavesQtyRq": "0", 885 | "execPriceRp": "1271.9", 886 | "orderValueRv": "89.033", 887 | "leavesValueRv": "0", 888 | "cumValueRv": "89.033", 889 | "stopDirection": 0, 890 | "stopPxRp": "0", 891 | "trigger": 0, 892 | "actionBy": 1, 893 | "execFeeRv": "0.0089033", 894 | "ordType": 2, 895 | "ordStatus": 7, 896 | "clOrdId": "74a6899", 897 | "orderId": "74a68994-f63e-4a6d-82b6-6f560f7e22a7", 898 | "execStatus": 6, 899 | "bizError": 0, 900 | "totalPnlRv": null, 901 | "avgTransactPriceRp": null, 902 | "orderDetailsVos": null, 903 | "tradeType": 1 904 | } 905 | ] 906 | } 907 | } 908 | ``` 909 | 910 | 911 | 912 | #### Query user order by orderID or Query user order by client order ID 913 | * Request 914 | 915 | to be added 916 | 917 | 918 | 919 | 920 | #### Query user trade 921 | 922 | * Request 923 | 924 | 925 | ``` 926 | GET /exchange/order/v2/tradingList?symbol=¤cy=&execType=&offset=&limit=&withCount= 927 | ``` 928 | 929 | 930 | 931 | | Field | Type | Required | Description | Possible values | 932 | |-----------|---------|----------|------------------------------------------------|--------------------------------------------------------------------| 933 | | symbol | String | No | which symbol needs to query | [Trading symbols](#symbpricesub) | 934 | | currency | String | Yes | which currency needs to query | | 935 | | execType | Integer | No | order status code list filter | New(5), PartiallyFilled(6), Untriggered(1), Filled(7), Canceled(8) | 936 | | offset | Integer | Yes | offset to resultset | | 937 | | limit | Integer | Yes | limit of resultset, max 200 | | 938 | | withCount | boolean | No | if true, result info will contains count info. | true,false | 939 | 940 | - Response 941 | - sample response 942 | 943 | ``` 944 | { 945 | "code": 0, 946 | "msg": "OK", 947 | "data": { 948 | "total": 4, 949 | "rows": [ 950 | { 951 | "createdAt": 1666226932259, 952 | "symbol": "ETHUSDT", 953 | "currency": "USDT", 954 | "action": 1, 955 | "tradeType": 1, 956 | "execQtyRq": "0.01", 957 | "execPriceRp": "1271.9", 958 | "side": 1, 959 | "orderQtyRq": "0.78", 960 | "priceRp": "1271.9", 961 | "execValueRv": "12.719", 962 | "feeRateRr": "0.0001", 963 | "execFeeRv": "0.0012719", 964 | "ordType": 2, 965 | "execId": "8718cae", 966 | "execStatus": 6 967 | }, 968 | { 969 | "createdAt": 1666226903754, 970 | "symbol": "ETHUSDT", 971 | "currency": "USDT", 972 | "action": 1, 973 | "tradeType": 1, 974 | "execQtyRq": "0.77", 975 | "execPriceRp": "1271.9", 976 | "side": 1, 977 | "orderQtyRq": "0.78", 978 | "priceRp": "1271.9", 979 | "execValueRv": "979.363", 980 | "feeRateRr": "0.0001", 981 | "execFeeRv": "0.0979363", 982 | "ordType": 2, 983 | "execId": "c6db276", 984 | "execStatus": 6 985 | }, 986 | { 987 | "createdAt": 1666226903754, 988 | "symbol": "ETHUSDT", 989 | "currency": "USDT", 990 | "action": 1, 991 | "tradeType": 1, 992 | "execQtyRq": "0.78", 993 | "execPriceRp": "1271.9", 994 | "side": 1, 995 | "orderQtyRq": "0.78", 996 | "priceRp": "1271.9", 997 | "execValueRv": "992.082", 998 | "feeRateRr": "0.0001", 999 | "execFeeRv": "0.0992082", 1000 | "ordType": 2, 1001 | "execId": "378d083", 1002 | "execStatus": 6 1003 | }, 1004 | { 1005 | "createdAt": 1666226903754, 1006 | "symbol": "ETHUSDT", 1007 | "currency": "USDT", 1008 | "action": 1, 1009 | "tradeType": 1, 1010 | "execQtyRq": "0.07", 1011 | "execPriceRp": "1271.9", 1012 | "side": 1, 1013 | "orderQtyRq": "0.07", 1014 | "priceRp": "1271.9", 1015 | "execValueRv": "89.033", 1016 | "feeRateRr": "0.0001", 1017 | "execFeeRv": "0.0089033", 1018 | "ordType": 2, 1019 | "execId": "8b8a8a0", 1020 | "execStatus": 6 1021 | } 1022 | ] 1023 | } 1024 | } 1025 | ``` 1026 | 1027 | 1028 | * Possible trade types 1029 | 1030 | |TradeTypes| Description | 1031 | |---------|--------------| 1032 | | Trade | Normal trades | 1033 | | Funding | Funding on positions | 1034 | | AdlTrade | Auto-delevearage trades | 1035 | | LiqTrade | Liquidation trades | 1036 | 1037 | 1038 | 1039 | 1040 | 1041 | ### Market Data API List 1042 | 1043 | 1044 | 1045 | #### Query Order Book 1046 | 1047 | - Request： 1048 | 1049 | ``` 1050 | 1051 | GET /md/v2/orderbook?symbol= 1052 | 1053 | ``` 1054 | 1055 | | Field | Type | Description | Possible values | 1056 | |---------|---------|-----------------------|-----------------------------------| 1057 | | symbol | String | Contract symbol name | [Trading symbols](#symbpricesub) | 1058 | 1059 | - Response: 1060 | 1061 | ``` 1062 | { 1063 | "error": null, 1064 | "id": 0, 1065 | "result": { 1066 | "orderbook_p": { 1067 | "asks": [ 1068 | [ 1069 | , 1070 | 1071 | ], 1072 | ... 1073 | ... 1074 | ... 1075 | ], 1076 | "bids": [ 1077 | [ 1078 | , 1079 | 1080 | ], 1081 | ... 1082 | ... 1083 | ... 1084 | ], 1085 | ] 1086 | }, 1087 | "depth": 30, 1088 | "sequence": , 1089 | "timestamp": , 1090 | "symbol": "", 1091 | "type": "snapshot" 1092 | } 1093 | } 1094 | 1095 | ``` 1096 | 1097 | | Field | Type | Description | Possible values | 1098 | |------------|----------|-----------------------------|----------------------------------| 1099 | | timestamp | Integer | Timestamp in nanoseconds | | 1100 | | priceRp | String | Real book level price | | 1101 | | sizeRq | String | Real book level size | | 1102 | | sequence | Integer | current message sequence || 1103 | | symbol | String | Contract symbol name | [Trading symbols](#symbpricesub) | 1104 | 1105 | - Sample： 1106 | 1107 | ``` 1108 | GET /md/v2/orderbook?symbol=BTCUSDT 1109 | ``` 1110 | 1111 | ``` 1112 | { 1113 | "error": null, 1114 | "id": 0, 1115 | "result": { 1116 | "depth": 30, 1117 | "orderbook_p": { 1118 | "asks": [ 1119 | [ 1120 | "20675.7", 1121 | "0.736" 1122 | ], 1123 | [ 1124 | "20676.2", 1125 | "0.613" 1126 | ], 1127 | ... 1128 | ... 1129 | ... 1130 | ], 1131 | "bids": [ 1132 | [ 1133 | "20672.4", 1134 | "0.818" 1135 | ], 1136 | [ 1137 | "20672.2", 1138 | "0.614" 1139 | ], 1140 | ... 1141 | ... 1142 | ... 1143 | ] 1144 | }, 1145 | "sequence": 77770771, 1146 | "symbol": "BTCUSDT", 1147 | "timestamp": 1666860123727907896, 1148 | "type": "snapshot" 1149 | } 1150 | } 1151 | 1152 | ``` 1153 | 1154 | 1155 | 1156 | ### Query kline 1157 | 1158 | NOTE: 1159 | 1160 | 1. please be noted that kline interfaces have [rate limits](https://github.com/phemex/phemex-api-docs/blob/master/Generic-API-Info.en.md#rate-limits) rule, please check the Other group under [api groups](https://github.com/phemex/phemex-api-docs/blob/master/Generic-API-Info.en.md#api-groups) 1161 | 1162 | 1163 | ``` 1164 | GET /exchange/public/md/v2/kline/last?symbol=&resolution=&limit= 1165 | ``` 1166 | 1167 | | Field | Type | Required | Description | Possible values | 1168 | |------------|---------|----------|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| 1169 | | symbol | String | Yes | which symbol needs to query | [Trading symbols](#symbpricesub) | 1170 | | 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) | 1171 | | limit | Integer | No | records limit | 5 | 1172 | 1173 | 1174 | * Response 1175 | 1176 | ``` 1177 | { 1178 | "code": 0, 1179 | "msg": "OK", 1180 | "data": { 1181 | "total": -1, 1182 | "rows": [[, , , , , , , , ], [...]] 1183 | } 1184 | } 1185 | ``` 1186 | 1187 | 1188 | * Value of `resolution`s 1189 | 1190 | |resolution|Description | 1191 | |----------|------------| 1192 | |60|MINUTE_1| 1193 | |300|MINUTE_5| 1194 | |900|MINUTE_15| 1195 | |1800|MINUTE_30| 1196 | |3600|HOUR_1| 1197 | |14400|HOUR_4| 1198 | |86400|DAY_1| 1199 | |604800|WEEK_1| 1200 | |2592000|MONTH_1| 1201 | |7776000|SEASON_1| 1202 | |31104000|YEAR_1| 1203 | 1204 | * Value of `limit`s 1205 | 1206 | | limit | Description | 1207 | |----------|-------------| 1208 | | 5 | limit 5 | 1209 | | 10 | limit 10 | 1210 | | 50 | limit 50 | 1211 | | 100 | limit 100 | 1212 | | 500 | limit 500 | 1213 | | 1000 | limit 1000 | 1214 | 1215 | 1216 | **NOTE**, for backward compatibility reason, phemex also provides kline query with from/to, however, this interface is **NOT** recommended. 1217 | 1218 | ``` 1219 | GET /exchange/public/md/v2/kline/list?symbol=&to=&from=&resolution= 1220 | ``` 1221 | 1222 | 1223 | | Field | Type | Required | Description | Possible Values | 1224 | |-------------|---------|-------------|------------------------|----------------------------------------------------------------------------------------------------------------| 1225 | |symbol | String | Yes | symbol name | BTCUSD,ETHUSD,uBTCUSD,cETHUSD,XRPUSD... | 1226 | | from | Integer | Yes | start time in seconds | value aligned in resolution boundary | 1227 | | 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 | 1228 | | resolution | Integer | Yes | kline interval | the same as described above | 1229 | 1230 | 1231 | 1232 | 1233 | 1234 | 1235 | #### Query Trade 1236 | 1237 | - Request： 1238 | ``` 1239 | GET /md/v2/trade?symbol= 1240 | ``` 1241 | 1242 | | Field | Type | Description | Possible values | 1243 | |---------|---------|-----------------------|-----------------------------------| 1244 | | symbol | String | Contract symbol name | [Trading symbols](#symbpricesub) | 1245 | 1246 | - Response: 1247 | ``` 1248 | { 1249 | "error": null, 1250 | "id": 0, 1251 | "result": { 1252 | "sequence": , 1253 | "symbol": , 1254 | "trades_p": [ 1255 | [ 1256 | , 1257 | , 1258 | , 1259 | 1260 | ], 1261 | [ 1262 | , 1263 | , 1264 | , 1265 | 1266 | ], 1267 | ... 1268 | ... 1269 | ... 1270 | ], 1271 | "type": "snapshot" 1272 | } 1273 | } 1274 | ``` 1275 | 1276 | | Field | Type |Description| Possible values | 1277 | |------------|---------|----|-----------------------------------| 1278 | | timestamp | Integer |Timestamp in nanoseconds|| 1279 | | Side | String |Trade Side, Buy or Sell|| 1280 | | priceRp | String |Real trade price|| 1281 | | sizeRq | String |Real trade size|| 1282 | | sequence | Integer |current message sequence|| 1283 | | symbol | String |Contract symbol name| [Trading symbols](#symbpricesub) | 1284 | 1285 | - Sample： 1286 | 1287 | ``` 1288 | GET /md/v2/trade?symbol=BTCUSDT 1289 | 1290 | { 1291 | "error": null, 1292 | "id": 0, 1293 | "result": { 1294 | "sequence": 77766796, 1295 | "symbol": "BTCUSDT", 1296 | "trades_p": [ 1297 | [ 1298 | 1666860389799499000, 1299 | "Buy", 1300 | "20702.1", 1301 | "0.949" 1302 | ], 1303 | [ 1304 | 1666860377636154600, 1305 | "Sell", 1306 | "20675.5", 1307 | "0.785" 1308 | ], 1309 | ... 1310 | ... 1311 | ... 1312 | ], 1313 | "type": "snapshot" 1314 | } 1315 | } 1316 | ``` 1317 | 1318 | 1319 | 1320 | 1321 | ``` 1322 | GET /md/v2/ticker/24hr?symbol= 1323 | ``` 1324 | 1325 | |Field|Type|Required|Description| Possible values | 1326 | |----|----|----|----|-----------------------------------| 1327 | |symbol|String|Yes|which symbol needs to query| [Trading symbols](#symbpricesub) | 1328 | 1329 | ``` 1330 | GET /md/v2/ticker/24hr?symbol=BTCUSDT 1331 | ``` 1332 | 1333 | - Response 1334 | - sample response 1335 | 1336 | ``` 1337 | { 1338 | "error": null, 1339 | "id": 0, 1340 | "result": { 1341 | "closeRp": "20731", 1342 | "fundingRateRr": "0.0001", 1343 | "highRp": "20818.8", 1344 | "indexPriceRp": "20737.09857143", 1345 | "lowRp": "20425.2", 1346 | "markPriceRp": "20737.788944", 1347 | "openInterestRv": "0", 1348 | "openRp": "20709", 1349 | "predFundingRateRr": "0.0001", 1350 | "symbol": "BTCUSDT", 1351 | "timestamp": 1667222412794076700, 1352 | "turnoverRv": "139029311.7517", 1353 | "volumeRq": "6747.727" 1354 | } 1355 | } 1356 | ``` 1357 | 1358 | ### Future Data API List 1359 | 1360 | #### Query Funding Fees History 1361 | 1362 | * Http Request 1363 | 1364 | ``` 1365 | GET /api-data/g-futures/funding-fees?symbol= 1366 | ``` 1367 | 1368 | | Field | Type | Required | Description | Possible Values | 1369 | |----------|----------------|----------|---------------------------|-------------------------| 1370 | | symbol | String | True | the currency to query | BTCUSDT ... | 1371 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1372 | | limit | Integer | False | page size | default 20, max 200 | 1373 | 1374 | * Response 1375 | 1376 | ```json 1377 | [ 1378 | { 1379 | "symbol": "ETHUSDT", 1380 | "currency": "USDT", 1381 | "execQtyRq": "0.16", 1382 | "side": "Buy", 1383 | "execPriceRp": "1322.84500459", 1384 | "execValueRv": "211.65520073", 1385 | "fundingRateRr": "0.0001", 1386 | "feeRateRr": "0.0001", 1387 | "execFeeRv": "0.02116552", 1388 | "createTime": 1671004800021 1389 | } 1390 | ] 1391 | ``` 1392 | 1393 | 1394 | 1395 | #### Query Orders History 1396 | 1397 | * Http Request 1398 | 1399 | ``` 1400 | GET /api-data/g-futures/orders?symbol= 1401 | ``` 1402 | 1403 | | Field | Type | Required | Description | Possible Values | 1404 | |----------|----------------|----------|---------------------------|---------------------------------| 1405 | | symbol | String | True | the currency to query | BTCUSDT ... | 1406 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 1407 | | end | Long | False | end time in millisecond | default now | 1408 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1409 | | limit | Integer | False | page size | default 20, max 200 | 1410 | 1411 | * Response 1412 | 1413 | ``` 1414 | [ 1415 | { 1416 | "actionTimeNs": 1667562110213260743, 1417 | "bizError": 0, 1418 | "clOrdId": "cfffa744-712d-867a-e397-9888eec3f6d1", 1419 | "closedPnlRv": "0", 1420 | "closedSizeRq": "0", 1421 | "cumQtyRq": "0.001", 1422 | "cumValueRv": "20.5795", 1423 | "displayQtyRq": "0.001", 1424 | "leavesQtyRq": "0", 1425 | "leavesValueRv": "0", 1426 | "orderId": "743fc923-cb01-4261-88d1-b35dba2cdac0", 1427 | "orderQtyRq": "0.001", 1428 | "ordStatus": "Filled", 1429 | "ordType": "Market", 1430 | "priceRp": "21206.7", 1431 | "reduceOnly": false, 1432 | "side": "Buy", 1433 | "stopDirection": "UNSPECIFIED", 1434 | "stopLossRp": "0", 1435 | "symbol": "BTCUSDT", 1436 | "takeProfitRp": "0", 1437 | "timeInForce": "ImmediateOrCancel", 1438 | "transactTimeNs": 1667562110221077395 1439 | } 1440 | ] 1441 | ``` 1442 | 1443 | 1444 | 1445 | #### Query Orders By Ids 1446 | 1447 | * Http Request 1448 | 1449 | ``` 1450 | GET /api-data/g-futures/orders/by-order-id?symbol= 1451 | ``` 1452 | 1453 | | Field | Type | Required | Description | Possible Values | 1454 | |----------|----------|----------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------| 1455 | | symbol | String | True | the currency to query | BTCUSDT ... | 1456 | | 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 | 1457 | | clOrdID | String | False | client order id | refer to orderID | 1458 | 1459 | * Response 1460 | 1461 | ```json 1462 | [ 1463 | { 1464 | "orderId": "743fc923-cb01-4261-88d1-b35dba2cdac0", 1465 | "clOrdId": "cfffa744-712d-867a-e397-9888eec3f6d1", 1466 | "symbol": "BTCUSDT", 1467 | "side": "Buy", 1468 | "ordType": "Market", 1469 | "actionTimeNs": 1667562110213260743, 1470 | "priceRp": "21206.7", 1471 | "orderQtyRq": "0.001", 1472 | "displayQtyRq": "0.001", 1473 | "timeInForce": "ImmediateOrCancel", 1474 | "reduceOnly": false, 1475 | "takeProfitRp": "0", 1476 | "stopLossRp": "0", 1477 | "closedPnlRv": "0", 1478 | "closedSizeRq": "0", 1479 | "cumQtyRq": "0.001", 1480 | "cumValueRv": "20.5795", 1481 | "leavesQtyRq": "0", 1482 | "leavesValueRv": "0", 1483 | "stopDirection": "UNSPECIFIED", 1484 | "ordStatus": "Filled", 1485 | "transactTimeNs": 1667562110221077395, 1486 | "bizError": 0 1487 | } 1488 | ] 1489 | ``` 1490 | 1491 | 1492 | 1493 | #### Query Trades History 1494 | 1495 | * Http Request 1496 | 1497 | ``` 1498 | GET /api-data/g-futures/trades?symbol= 1499 | ``` 1500 | 1501 | | Field | Type | Required | Description | Possible Values | 1502 | |----------|----------------|----------|---------------------------|---------------------------------| 1503 | | symbol | String | True | the currency to query | BTCUSDT ... | 1504 | | start | Long | False | start time in millisecond | default 2 days ago from the end | 1505 | | end | Long | False | end time in millisecond | default now | 1506 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1507 | | limit | Integer | False | page size | default 20, max 200 | 1508 | 1509 | * Response 1510 | 1511 | ``` 1512 | [ 1513 | { 1514 | "action": "New", 1515 | "clOrdID": "", 1516 | "closedPnlRv": "0", 1517 | "closedSizeRq": "0", 1518 | "currency": "USDT", 1519 | "execFeeRv": "0.00166", 1520 | "execID": "5c3d96e1-8874-53b6-b6e5-9dcc4d28b4ab", 1521 | "execPriceRp": "16600", 1522 | "execQtyRq": "0.001", 1523 | "execStatus": "MakerFill", 1524 | "execValueRv": "16.6", 1525 | "feeRateRr": "0.0001", 1526 | "orderID": "fcdfeafa-ed68-45d4-b2bd-7bc27f2b2b0b", 1527 | "orderQtyRq": "0.001", 1528 | "ordType": "LimitIfTouched", 1529 | "priceRp": "16600", 1530 | "side": "Sell", 1531 | "symbol": "BTCUSDT", 1532 | "tradeType": "Trade", 1533 | "transactTimeNs": 1669407633926215067 1534 | } 1535 | ] 1536 | ``` 1537 | 1538 | 1539 | 1540 | #### Query Trading Fees History 1541 | 1542 | * Http Request 1543 | 1544 | ``` 1545 | GET /api-data/g-futures/trading-fees?symbol= 1546 | ``` 1547 | 1548 | | Field | Type | Required | Description | Possible Values | 1549 | |----------|----------------|----------|---------------------------|-------------------------| 1550 | | symbol | String | True | the currency to query | BTCUSDT ... | 1551 | | offset | Integer | False | page start from 0 | start from 0, default 0 | 1552 | | limit | Integer | False | page size | default 20, max 200 | 1553 | 1554 | * Response 1555 | 1556 | ```json 1557 | [ 1558 | { 1559 | "id": 295, 1560 | "userId": 939565, 1561 | "symbol": "ETHUSDT", 1562 | "currency": "USDT", 1563 | "takerValueRv": "97.1104", 1564 | "takerFeeRateRr": "0.0006", 1565 | "makerValueRv": "97.164", 1566 | "makerFeeRateRr": "0", 1567 | "exchangeFeeRv": "0.06798264", 1568 | "createTime": 1669766400000 1569 | } 1570 | ] 1571 | ``` 1572 | 1573 | 1574 | 1575 | # Websocket API Standards 1576 | 1577 | 1578 | 1579 | ## Session Management 1580 | 1581 | * Each client is required to actively send heartbeat (ping) message to Phemex data gateway ('DataGW' in short) with interval less than 30 seconds, otherwise DataGW will drop the connection. If a client sends a ping message, DataGW will reply with a pong message. 1582 | * Clients can use WS built-in ping message or the application level ping message to DataGW as heartbeat. The heartbeat interval is recommended to be set as *5 seconds*, and actively reconnect to DataGW if don't receive messages in *3 heartbeat intervals*. 1583 | 1584 | 1585 | 1586 | ## API Rate Limits 1587 | 1588 | * Each Client has concurrent connection limit to *5* in maximum. 1589 | * Each connection has subscription limit to *20* in maximum. 1590 | * Each connection has throttle limit to *20* request/s. 1591 | 1592 | 1593 | 1594 | ## WebSocket API List 1595 | 1596 | 1597 | 1598 | ### Heartbeat 1599 | 1600 | * Request： 1601 | ``` 1602 | { 1603 | "id": , 1604 | "method": "server.ping", 1605 | "params": [] 1606 | } 1607 | ``` 1608 | 1609 | * Response: 1610 | ``` 1611 | { 1612 | "error": null, 1613 | "id": , 1614 | "result": "pong" 1615 | } 1616 | ``` 1617 | 1618 | * Sample： 1619 | ``` 1620 | > { 1621 | "id": 1234, 1622 | "method": "server.ping", 1623 | "params": [] 1624 | } 1625 | 1626 | < { 1627 | "error": null, 1628 | "id": 1234, 1629 | "result": "pong" 1630 | } 1631 | ``` 1632 | 1633 | 1634 | 1635 | ### API User Authentication 1636 | 1637 | Market trade/orderbook are published publicly without user authentication. 1638 | While for client private account/position/order data, the client should send user.auth message to Data Gateway to authenticate the session. 1639 | 1640 | * Request 1641 | 1642 | ``` 1643 | { 1644 | "method": "user.auth", 1645 | "params": [ 1646 | "API", 1647 | "", 1648 | "", 1649 | 1650 | ], 1651 | "id": 1234 1652 | } 1653 | ``` 1654 | 1655 | | Field | Type | Description | Possible values | 1656 | |-------------|--------|------------------|-----------------| 1657 | | type | String | Token type | API | 1658 | | token | String | API Key | | 1659 | | signature | String | Signature generated by a funtion as HMacSha256(API Key + expiry) with ***API Secret*** || 1660 | | expiry | Integer| A future time after which request will be rejected, in epoch ***second***. Maximum expiry is request time plus 2 minutes || 1661 | 1662 | * Sample: 1663 | 1664 | ``` 1665 | > { 1666 | "method": "user.auth", 1667 | "params": [ 1668 | "API", 1669 | "806066b0-f02b-4d3e-b444-76ec718e1023", 1670 | "8c939f7a6e6716ab7c4240384e07c81840dacd371cdcf5051bb6b7084897470e", 1671 | 1570091232 1672 | ], 1673 | "id": 1234 1674 | } 1675 | 1676 | < { 1677 | "error": null, 1678 | "id": 1234, 1679 | "result": { 1680 | "status": "success" 1681 | } 1682 | } 1683 | ``` 1684 | 1685 | 1686 | 1687 | 1688 | ### Subscribe OrderBook for new Model 1689 | 1690 | On each successful subscription, DataGW will immediately send the current Order Book snapshot to client and all later order book updates will be published. 1691 | 1692 | * Request 1693 | ``` 1694 | { 1695 | "id": , 1696 | "method": "orderbook_p.subscribe", 1697 | "params": [ 1698 | "" 1699 | ] 1700 | } 1701 | ``` 1702 | 1703 | * Response 1704 | ``` 1705 | { 1706 | "error": null, 1707 | "id": , 1708 | "result": { 1709 | "status": "success" 1710 | } 1711 | } 1712 | ``` 1713 | 1714 | * Sample： 1715 | ``` 1716 | > { 1717 | "id": 1234, 1718 | "method": "orderbook_p.subscribe", 1719 | "params": [ 1720 | "BTCUSDT" 1721 | ] 1722 | } 1723 | 1724 | < { 1725 | "error": null, 1726 | "id": 1234, 1727 | "result": { 1728 | "status": "success" 1729 | } 1730 | } 1731 | ``` 1732 | 1733 | 1734 | #### OrderBook Message: 1735 | 1736 | 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. 1737 | 1738 | * Message Format： 1739 | 1740 | ``` 1741 | { 1742 | "book": { 1743 | "asks": [ 1744 | [ 1745 | , 1746 | 1747 | ], 1748 | . 1749 | . 1750 | . 1751 | ], 1752 | "bids": [ 1753 | [ 1754 | , 1755 | 1756 | ], 1757 | . 1758 | . 1759 | . 1760 | ] 1761 | }, 1762 | "depth": , 1763 | "sequence": , 1764 | "timestamp": , 1765 | "symbol": "", 1766 | } 1767 | 1768 | ``` 1769 | 1770 | | Field | Type | Description | Possible values | 1771 | |-------------|---------|-------------------------|-----------------| 1772 | | side | String | Price level side | bid, ask | 1773 | | priceEp | String | Raw price | | 1774 | | qty | String | Price level size | | 1775 | | sequence | Integer | Latest message sequence | | 1776 | | depth | Integer | Market depth | 30 | 1777 | | type | String | Message type | snapshot, incremental | 1778 | 1779 | 1780 | * Sample： 1781 | 1782 | ``` 1783 | < {"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"} 1784 | < {"depth":30,"orderbook_p":{"asks":[],"bids":[["20700.5","0"],["20340.5","0.06"]]},"sequence":77668209,"symbol":"BTCUSDT","timestamp":1666854173705089711,"type":"incremental"} 1785 | ``` 1786 | 1787 | 1788 | 1789 | ### Unsubscribe OrderBook 1790 | 1791 | It unsubscribes all orderbook related subscriptions. 1792 | 1793 | * Request 1794 | 1795 | ``` 1796 | { 1797 | "id": , 1798 | "method": "orderbook_p.unsubscribe", 1799 | "params": [] 1800 | } 1801 | ``` 1802 | 1803 | * Response: 1804 | 1805 | ``` 1806 | { 1807 | "error": null, 1808 | "id": , 1809 | "result": { 1810 | "status": "success" 1811 | } 1812 | } 1813 | ``` 1814 | 1815 | 1816 | 1817 | 1818 | ### Subscribe Trade 1819 | 1820 | On each successful subscription, DataGW will send the 200 history trades immediately for the subscribed symbol and all the later trades will be published. 1821 | 1822 | * Request 1823 | 1824 | ``` 1825 | { 1826 | "id": , 1827 | "method": "trade_p.subscribe", 1828 | "params": [ 1829 | "" 1830 | ] 1831 | } 1832 | ``` 1833 | 1834 | * Response: 1835 | 1836 | ``` 1837 | { 1838 | "error": null, 1839 | "id": , 1840 | "result": { 1841 | "status": "success" 1842 | } 1843 | } 1844 | ``` 1845 | 1846 | * Sample: 1847 | 1848 | ``` 1849 | > { 1850 | "id": 1234, 1851 | "method": "trade_p.subscribe", 1852 | "params": [ 1853 | "BTCUSDT" 1854 | ] 1855 | } 1856 | 1857 | < { 1858 | "error": null, 1859 | "id": 1234, 1860 | "result": { 1861 | "status": "success" 1862 | } 1863 | } 1864 | ``` 1865 | 1866 | #### Trade Message Format： 1867 | 1868 | 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. 1869 | 1870 | 1871 | ``` 1872 | { 1873 | "trades": [ 1874 | [ 1875 | , 1876 | "", 1877 | "", 1878 | "" 1879 | ], 1880 | . 1881 | . 1882 | . 1883 | ], 1884 | "sequence": , 1885 | "symbol": "", 1886 | "type": "" 1887 | } 1888 | ``` 1889 | 1890 | | Field | Type | Description | Possible values | 1891 | |-----------|--------|-----------------------------------------|-----------------| 1892 | | timestamp | Integer| Timestamp in nanoseconds for each trade || 1893 | | side | String | Execution taker side | bid, ask | 1894 | | price | String| Raw price | | 1895 | | qty | String| Execution size | | 1896 | | sequence | Integer| Latest message sequence || 1897 | | symbol | String | Contract symbol name || 1898 | | type | String | Message type |snapshot, incremental | 1899 | 1900 | 1901 | * Sample 1902 | ``` 1903 | < { 1904 | "sequence": 77702250, 1905 | "symbol": "BTCUSDT", 1906 | "trades_p": [ 1907 | [ 1908 | 1666856076819029800, 1909 | "Sell", 1910 | "20700.3", 1911 | "0.649" 1912 | ] 1913 | ], 1914 | "type": "incremental" 1915 | } 1916 | 1917 | < { 1918 | "sequence": 77663551, 1919 | "symbol": "BTCUSDT", 1920 | "trades_p": [ 1921 | [ 1922 | 1666856062351916300, 1923 | "Sell", 1924 | "20703.6", 1925 | "0.669" 1926 | ], 1927 | [ 1928 | 1666854025545354000, 1929 | "Buy", 1930 | "20699", 1931 | "0.001" 1932 | ] 1933 | ], 1934 | "type": "snapshot" 1935 | } 1936 | ``` 1937 | 1938 | 1939 | 1940 | ### Unsubscribe Trade 1941 | 1942 | It unsubscribes all trade subscriptions or for a symbol. 1943 | 1944 | * Request 1945 | 1946 | ``` 1947 | # unsubscribe all trade subsciptions 1948 | { 1949 | "id": , 1950 | "method": "trade_p.unsubscribe", 1951 | "params": [ 1952 | ] 1953 | } 1954 | 1955 | # unsubscribe all trade subsciptions for a symbol 1956 | { 1957 | "id": , 1958 | "method": "trade_p.unsubscribe", 1959 | "params": [ 1960 | "" 1961 | ] 1962 | } 1963 | ``` 1964 | 1965 | * Response: 1966 | 1967 | ``` 1968 | { 1969 | "error": null, 1970 | "id": , 1971 | "result": { 1972 | "status": "success" 1973 | } 1974 | } 1975 | ``` 1976 | 1977 | 1978 | 1979 | ### Subscribe Kline 1980 | 1981 | 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. 1982 | 1983 | * Request 1984 | 1985 | ``` 1986 | { 1987 | "id": , 1988 | "method": "kline_p.subscribe", 1989 | "params": [ 1990 | "", 1991 | "" 1992 | ] 1993 | } 1994 | ``` 1995 | 1996 | * Response: 1997 | 1998 | ``` 1999 | { 2000 | "error": null, 2001 | "id": , 2002 | "result": { 2003 | "status": "success" 2004 | } 2005 | } 2006 | ``` 2007 | 2008 | * Sample: 2009 | 2010 | ``` 2011 | # subscribe 1-day kline 2012 | > { 2013 | "id": 1234, 2014 | "method": "kline_p.subscribe", 2015 | "params": [ 2016 | "BTCUSDT", 2017 | 86400 2018 | ] 2019 | } 2020 | 2021 | < { 2022 | "error": null, 2023 | "id": 1234, 2024 | "result": { 2025 | "status": "success" 2026 | } 2027 | } 2028 | ``` 2029 | 2030 | #### Kline Message Format： 2031 | 2032 | 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. 2033 | 2034 | ``` 2035 | { 2036 | "kline": [ 2037 | [ 2038 | , 2039 | "", 2040 | , 2041 | , 2042 | , 2043 | , 2044 | , 2045 | , 2046 | , 2047 | ], 2048 | . 2049 | . 2050 | . 2051 | ], 2052 | "sequence": , 2053 | "symbol": "", 2054 | "type": "" 2055 | } 2056 | ``` 2057 | 2058 | | Field | Type | Description | Possible values | 2059 | |------------|---------|------------------------------------------------|-----------------| 2060 | | timestamp | Integer | Timestamp in nanoseconds for each trade || 2061 | | interval | Integer | Kline interval type | 60, 300, 900, 1800, 3600, 14400, 86400, 604800, 2592000, 7776000, 31104000 | 2062 | | lastClose | String | Unscaled last close price | | 2063 | | open | String | Unscaled open price | | 2064 | | high | String | Unscaled high price | | 2065 | | low | String | Unscaled low price | | 2066 | | close | String | Unscaled close price | | 2067 | | volume | String | Trade voulme during the current kline interval || 2068 | | turnover | String | Unscaled turnover value | | 2069 | | sequence | Integer | Latest message sequence || 2070 | | symbol | String | Contract symbol name || 2071 | | type | String | Message type |snapshot, incremental | 2072 | 2073 | 2074 | * Sample 2075 | ``` 2076 | < { 2077 | "kline_p": [ 2078 | [ 2079 | 1666856340, 2080 | 60, 2081 | "20689.5", 2082 | "20686.2", 2083 | "20695.4", 2084 | "20686.2", 2085 | "20691.6", 2086 | "2.742", 2087 | "56731.5609" 2088 | ], 2089 | [ 2090 | 1666856280, 2091 | 60, 2092 | "20700.1", 2093 | "20712.7", 2094 | "20712.7", 2095 | "20689.1", 2096 | "20689.5", 2097 | "4.407", 2098 | "91208.3065" 2099 | ] 2100 | ], 2101 | "sequence": 77711279, 2102 | "symbol": "BTCUSDT", 2103 | "type": "snapshot" 2104 | } 2105 | 2106 | < { 2107 | "kline_p": [ 2108 | [ 2109 | 1666856520, 2110 | 60, 2111 | "20685", 2112 | "20684.8", 2113 | "20684.8", 2114 | "20675.2", 2115 | "20675.2", 2116 | "3.547", 2117 | "73353.8417" 2118 | ] 2119 | ], 2120 | "priceScale": 0, 2121 | "sequence": 77715046, 2122 | "symbol": "BTCUSDT", 2123 | "type": "incremental" 2124 | } 2125 | ``` 2126 | 2127 | 2128 | 2129 | ### Unsubscribe Kline 2130 | 2131 | It unsubscribes all kline subscriptions or for a symbol. 2132 | 2133 | * Request 2134 | 2135 | ``` 2136 | # unsubscribe all Kline subscriptions 2137 | { 2138 | "id": , 2139 | "method": "kline_p.unsubscribe", 2140 | "params": [] 2141 | } 2142 | 2143 | # unsubscribe all Kline subscriptions of a symbol 2144 | { 2145 | "id": , 2146 | "method": "kline_p.unsubscribe", 2147 | "params": [ 2148 | "" 2149 | ] 2150 | } 2151 | ``` 2152 | 2153 | * Response: 2154 | 2155 | ``` 2156 | { 2157 | "error": null, 2158 | "id": , 2159 | "result": { 2160 | "status": "success" 2161 | } 2162 | } 2163 | ``` 2164 | 2165 | 2166 | 2167 | 2168 | ### Subscribe Account-Order-Position (AOP) 2169 | 2170 | 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. 2171 | 2172 | * Request 2173 | 2174 | ``` 2175 | { 2176 | "id": , 2177 | "method": "aop_p.subscribe", 2178 | "params": [] 2179 | } 2180 | ``` 2181 | 2182 | * Response: 2183 | 2184 | ``` 2185 | { 2186 | "error": null, 2187 | "id": , 2188 | "result": { 2189 | "status": "success" 2190 | } 2191 | } 2192 | ``` 2193 | 2194 | * Sample 2195 | ``` 2196 | > { 2197 | "id": 1234, 2198 | "method": "aop_p.subscribe", 2199 | "params": [] 2200 | } 2201 | 2202 | < { 2203 | "error": null, 2204 | "id": 1234, 2205 | "result": { 2206 | "status": "success" 2207 | } 2208 | } 2209 | ``` 2210 | 2211 | 2212 | 2213 | 2214 | #### Account-Order-Position (AOP) Message Sample: 2215 | 2216 | ```json 2217 | {"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},{"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.003","cumValueRv":"62.1753","curAccBalanceRv":"1508.452588802237","curAssignedPosBalanceRv":"24.62786650928","curBonusBalanceRv":"0","curLeverageRr":"-10","curPosSide":"Buy","curPosSize":"0.046","curPosTerm":1,"curPosValueRv":"956.2442","curRiskLimitRv":"1000000","currency":"USDT","cxlRejReason":0,"displayQty":"0.003","execFeeRv":"0.03730518","execID":"b6c8d16b-c777-510c-8476-80f399b2d5ad","execPriceRp":"20725.1","execQty":"0.003","execSeq":77751555,"execStatus":"TakerFill","execValueRv":"62.1753","feeRateRr":"0.0006","lastLiquidityInd":"RemovedLiquidity","leavesQty":"0","leavesValueRv":"0","message":"No error","ordStatus":"Filled","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":"Trade","transactTimeNs":1666858780881545305,"userID":932867}],"positions_p":[{"accountID":9328670003,"assignedPosBalanceRv":"30.861734862748","avgEntryPriceRp":"20787.917391304","bankruptCommRv":"0.0000006","bankruptPriceRp":"0.1","buyLeavesQty":"0","buyLeavesValueRv":"0","buyValueToCostRr":"0.10114","createdAtNs":0,"crossSharedBalanceRv":"1165.319989135354","cumClosedPnlRv":"0","cumFundingFeeRv":"0.089061821453","cumTransactFeeRv":"0.57374652","curTermRealisedPnlRv":"-0.662808341453","currency":"USDT","dataVer":11,"deleveragePercentileRr":"0","displayLeverageRr":"0.79941382","estimatedOrdLossRv":"0","execSeq":77751555,"freeCostRv":"0","freeQty":"-0.046","initMarginReqRr":"0.1","lastFundingTime":1666857600000000000,"lastTermEndTime":0,"leverageRr":"-10","liquidationPriceRp":"0.1","maintMarginReqRr":"0.01","makerFeeRateRr":"-1","markPriceRp":"20735.47347096","minPosCostRv":"0","orderCostRv":"0","posCostRv":"30.284669572349","posMode":"Hedged","posSide":"Long","positionMarginRv":"1196.181723398102","positionStatus":"Normal","riskLimitRv":"1000000","sellLeavesQty":"0","sellLeavesValueRv":"0","sellValueToCostRr":"0.10126","side":"Buy","size":"0.046","symbol":"BTCUSDT","takerFeeRateRr":"-1","term":1,"transactTimeNs":1666858780881545305,"unrealisedPnlRv":"-2.41242033584","updatedAtNs":0,"usedBalanceRv":"30.861734862748","userID":932867,"valueRv":"956.2442"},{"accountID":9328670003,"assignedPosBalanceRv":"9.473634984","avgEntryPriceRp":"20786.455555556","bankruptCommRv":"1.153171711445","bankruptPriceRp":"1000000","buyLeavesQty":"0","buyLeavesValueRv":"0","buyValueToCostRr":"0.10114","createdAtNs":0,"crossSharedBalanceRv":"1165.319989135354","cumClosedPnlRv":"0","cumFundingFeeRv":"-0.074563385402","cumTransactFeeRv":"0.44898744","curTermRealisedPnlRv":"-0.374424054598","currency":"USDT","dataVer":10,"deleveragePercentileRr":"0","displayLeverageRr":"0.63759936","estimatedOrdLossRv":"0","execSeq":77731059,"freeCostRv":"0","freeQty":"0.036","initMarginReqRr":"0.1","lastFundingTime":1666857600000000000,"lastTermEndTime":0,"leverageRr":"-10","liquidationPriceRp":"1000000","maintMarginReqRr":"0.01","makerFeeRateRr":"-1","markPriceRp":"20735.47347096","minPosCostRv":"0","orderCostRv":"0","posCostRv":"9.473634984","posMode":"Hedged","posSide":"Short","positionMarginRv":"1173.640452407909","positionStatus":"Normal","riskLimitRv":"1000000","sellLeavesQty":"0","sellLeavesValueRv":"0","sellValueToCostRr":"0.10126","side":"Sell","size":"0.036","symbol":"BTCUSDT","takerFeeRateRr":"-1","term":1,"transactTimeNs":1666858780876924611,"unrealisedPnlRv":"1.83535504544","updatedAtNs":0,"usedBalanceRv":"9.473634984","userID":932867,"valueRv":"748.3124"},{"accountID":9328670003,"assignedPosBalanceRv":"156.56916092763","avgEntryPriceRp":"1563.815","bankruptCommRv":"0.187657798123","bankruptPriceRp":"1042.55","buyLeavesQty":"0","buyLeavesValueRv":"0","buyValueToCostRr":"0.33433334","createdAtNs":0,"crossSharedBalanceRv":"1165.319989135354","cumClosedPnlRv":"-89.82","cumFundingFeeRv":"0.104061681397","cumTransactFeeRv":"0.4835887","curTermRealisedPnlRv":"-0.328183513333","currency":"USDT","dataVer":14,"deleveragePercentileRr":"0","displayLeverageRr":"2.99999994","estimatedOrdLossRv":"0","execSeq":77731060,"freeCostRv":"0","freeQty":"-0.3","initMarginReqRr":"0.33333333","lastFundingTime":1666857600000000000,"lastTermEndTime":1666755074905395643,"leverageRr":"3","liquidationPriceRp":"1058.2","maintMarginReqRr":"0.01","makerFeeRateRr":"-1","markPriceRp":"1558.51230846","minPosCostRv":"0","orderCostRv":"0","posCostRv":"156.56916092763","posMode":"Hedged","posSide":"Long","positionMarginRv":"156.381503129507","positionStatus":"Normal","riskLimitRv":"500000","sellLeavesQty":"0","sellLeavesValueRv":"0","sellValueToCostRr":"0.33473333","side":"Buy","size":"0.3","symbol":"ETHUSDT","takerFeeRateRr":"-1","term":2,"transactTimeNs":1666858780876924611,"unrealisedPnlRv":"-1.590807462","updatedAtNs":0,"usedBalanceRv":"156.56916092763","userID":932867,"valueRv":"469.1445"},{"accountID":9328670003,"assignedPosBalanceRv":"146.228068892505","avgEntryPriceRp":"1455.495","bankruptCommRv":"0.349516231597","bankruptPriceRp":"1941.75","buyLeavesQty":"0","buyLeavesValueRv":"0","buyValueToCostRr":"0.33433334","createdAtNs":0,"crossSharedBalanceRv":"1165.319989135354","cumClosedPnlRv":"0","cumFundingFeeRv":"-0.159460679685","cumTransactFeeRv":"0.2619891","curTermRealisedPnlRv":"-0.102528420315","currency":"USDT","dataVer":14,"deleveragePercentileRr":"0","displayLeverageRr":"2.99323302","estimatedOrdLossRv":"0","execSeq":77731060,"freeCostRv":"0","freeQty":"0.3","initMarginReqRr":"0.33333333","lastFundingTime":1666857600000000000,"lastTermEndTime":0,"leverageRr":"3","liquidationPriceRp":"1927.21","maintMarginReqRr":"0.01","makerFeeRateRr":"-1","markPriceRp":"1558.51230846","minPosCostRv":"0","orderCostRv":"0","posCostRv":"145.898817344505","posMode":"Hedged","posSide":"Short","positionMarginRv":"145.878552660908","positionStatus":"Normal","riskLimitRv":"500000","sellLeavesQty":"0","sellLeavesValueRv":"0","sellValueToCostRr":"0.33473333","side":"Sell","size":"0.3","symbol":"ETHUSDT","takerFeeRateRr":"-1","term":1,"transactTimeNs":1666858780876924611,"unrealisedPnlRv":"-30.905192538","updatedAtNs":0,"usedBalanceRv":"146.228068892505","userID":932867,"valueRv":"436.6485"}],"sequence":68744,"timestamp":1666858780883525030,"type":"incremental","version":0} 2218 | 2219 | ``` 2220 | 2221 | | Field | Type | Description | Possible values | 2222 | |-------------|--------|------------------|-----------------| 2223 | | timestamp | Integer| Transaction timestamp in nanoseconds | | 2224 | | sequence | Integer| Latest message sequence | | 2225 | | symbol | String | Contract symbol name | | 2226 | | type | String | Message type | snapshot, incremental | 2227 | 2228 | 2229 | 2230 | 2231 | 2232 | ### Unsubscribe Account-Order-Position (AOP) 2233 | * Request： 2234 | 2235 | ``` 2236 | { 2237 | "id": , 2238 | "method": "aop_p.unsubscribe", 2239 | "params": [] 2240 | } 2241 | ``` 2242 | 2243 | * Response: 2244 | 2245 | ``` 2246 | { 2247 | "error": null, 2248 | "id": , 2249 | "result": { 2250 | "status": "success" 2251 | } 2252 | } 2253 | ``` 2254 | 2255 | 2256 | 2257 | ### Subscribe account margin (RAS) 2258 | 2259 | RAS subscription requires the session been authorized successfully. DataGW extracts the user information from the given token and sends RAS messages back to client accordingly. 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 one risk unit for cross margin positions, and each one risk unit for each isolated position. And also one risk wallet for each currency. 2260 | 2261 | * Request: 2262 | 2263 | ``` 2264 | { 2265 | "id": , 2266 | "method": "ras_p.subscribe", 2267 | "params": {} 2268 | } 2269 | ``` 2270 | 2271 | * Response: 2272 | 2273 | ``` 2274 | { 2275 | "error": null, 2276 | "id": , 2277 | "result": { 2278 | "stauts": "success" 2279 | } 2280 | } 2281 | ``` 2282 | 2283 | * Sample 2284 | ``` 2285 | > { 2286 | "id": 1234, 2287 | "method": "ras_p.subscribe", 2288 | "params": {} 2289 | } 2290 | 2291 | < { 2292 | "error": null, 2293 | "id": 1234, 2294 | "result": { 2295 | "stauts": "success" 2296 | } 2297 | } 2298 | ``` 2299 | 2300 | #### account margin (RAS) Message Sample: 2301 | 2302 | ```json 2303 | {"risk_units":[{"estAvailableBalanceRv":"1806.82960617341","lastUpdateTimeNs":"2024-06-07T02:01:51.246394043Z","marginRatioRr":"999","posSide":0,"riskMode":"CrossAsset","symbol":"","totalBalanceRv":"1806.82960617341","totalEquityRv":"1806.82960617341","userID":944384,"userStatus":"Normal","userType":"Normal","valuationCurrency":"USDT","version":111},{"estAvailableBalanceRv":"-7.866995297237","fixedUsedRv":"8.180373498854","lastUpdateTimeNs":"2024-06-07T02:01:51.246394134Z","marginRatioRr":"14.28230196","posSide":3,"riskMode":"Isolated","symbol":"BTCUSDT","totalBalanceRv":"1075.34407386659","totalEquityRv":"1075.657452068207","totalPosCostRv":"1075.34407386659","totalPosMMRv":"74.741248391009","totalPosUnpnlRv":"0.313378201617","userID":944384,"userStatus":"Normal","userType":"Normal","valuationCurrency":"USDT","version":76}],"risk_wallets":[{"balanceRv":"2882.17368004","clReqVid":1,"currency":"USDT","lastUpdateTimeNs":"2024-06-07T02:01:51.246394235Z","userID":944384,"version":51}],"sequence":13144420,"timestamp":0,"type":"snapshot"} 2304 | ``` 2305 | 2306 | | Field | Type | Description | Possible values | 2307 | |-------------|--------|------------------|-----------------| 2308 | | timestamp | Integer| Transaction timestamp in nanoseconds | | 2309 | | sequence | Integer| Latest message sequence | | 2310 | | type | String | Message type | snapshot, incremental | 2311 | 2312 | #### Fields in RiskUnit 2313 | 2314 | | Field | Type | Description | Possible Values | 2315 | |----------|----------|----------------|-----------------| 2316 | | riskMode | String | "CrossAsset" for Cross Margin Positions, and "Isolated" for isolated position | 1, 3 | 2317 | | estAvailableBalanceRv | String | estimated available balance for new orders | | 2318 | | fixedUsedRv | String | margins allocated to fully hedged positions and bankrupt commission | | 2319 | | lastUpdateTimeNs | Integer | the time in ns the message is generated | | 2320 | | MarginRatioRr | String | the margin ratio level for the current risk unit | | 2321 | | posSide | Integer | the position side | 1, 2, 3 | 2322 | | symbol | String | Contract symbol name | | 2323 | | totalBalanceRv | String | sum of balanceRv of all risk wallet | | 2324 | | totalEquityRv | String | total equity excluding debt and interest | | 2325 | | totalPosCostRv | String | total initial margin of position(s) | | 2326 | | totalPosMMRv | String | total maintainence margin of position(s) | | 2327 | | totalPosUnpnlRv | String | sum of unrealised pnl of position(s) | | 2328 | | userID | Integer | user id | | 2329 | | userStatus | String | user status | "Unspecified/Normal" for normal, "Banned" for banned, "Liq*" for liquidation | 2330 | | userType | String| user type | always "Normal" for user | 2331 | | valuationCurrency | String | settle currency | | 2332 | | version | Integer | risk unit version | | 2333 | 2334 | #### Fields of RiskWallet 2335 | 2336 | | Field | Type | Description | Possible values | 2337 | |----------|---------|---------------|-----------------| 2338 | | balanceRv | String | available balance, including bonus and debt | | 2339 | | currency | String | wallet currency | | 2340 | | lastUpdateTimeNs | Integer | the time in ns the message is generated | | 2341 | | userID | Integer | user id | | 2342 | | version | Integer | wallet version | | 2343 | 2344 | 2345 | 2346 | 2347 | 2348 | 2349 | ### Unsubscribe account margin (RAS) 2350 | 2351 | * Request: 2352 | 2353 | ``` 2354 | { 2355 | "id": , 2356 | "method": "ras_p.unsubscribe", 2357 | "params": [] 2358 | } 2359 | ``` 2360 | 2361 | * Response: 2362 | 2363 | ``` 2364 | { 2365 | "error": null, 2366 | "id": , 2367 | "result": { 2368 | "status": "success" 2369 | } 2370 | } 2371 | ``` 2372 | 2373 | 2374 | 2375 | ### Subscribe 24 Hours Ticker 2376 | On each successful subscription, DataGW will publish 24-hour ticker metrics for all symbols every 1 second. 2377 | 2378 | * Request 2379 | 2380 | ``` 2381 | { 2382 | "id": , 2383 | "method": "perp_market24h_pack_p.subscribe", 2384 | "params": [] 2385 | } 2386 | ``` 2387 | 2388 | * Response: 2389 | 2390 | ``` 2391 | { 2392 | "error": null, 2393 | "id": , 2394 | "result": { 2395 | "status": "success" 2396 | } 2397 | } 2398 | ``` 2399 | 2400 | * Sample: 2401 | 2402 | ``` 2403 | > { 2404 | "method": "perp_market24h_pack_p.subscribe", 2405 | "params": [], 2406 | "id": 1234 2407 | } 2408 | 2409 | < { 2410 | "error": null, 2411 | "id": 1234, 2412 | "result": { 2413 | "status": "success" 2414 | } 2415 | } 2416 | ``` 2417 | 2418 | #### Hours Ticker Message Format： 2419 | 2420 | ``` 2421 | { 2422 | "data": [ 2423 | [ 2424 | , 2425 | , 2426 | , 2427 | , 2428 | , 2429 | , 2430 | , 2431 | , 2432 | , 2433 | , 2434 | , 2435 | 2436 | ] 2437 | ], 2438 | "fields": [ 2439 | "symbol", 2440 | "openRp", 2441 | "highRp", 2442 | "lowRp", 2443 | "lastRp", 2444 | "volumeRq", 2445 | "turnoverRv", 2446 | "openInterestRv", 2447 | "indexRp", 2448 | "markRp", 2449 | "fundingRateRr", 2450 | "predFundingRateRr" 2451 | ], 2452 | "method": "perp_market24h_pack_p.update", 2453 | "timestamp": 1666862556850547000, 2454 | "type": "snapshot" 2455 | } 2456 | ``` 2457 | 2458 | | Field | Type | Description | Possible values | 2459 | |-------------------|---------|----------------------------------------------|----------------------------------| 2460 | | symbol | String | Contract symbol name | [Trading symbols](#symbpricesub) | 2461 | | openRp | String | The unscaled open price in last 24 hours | | 2462 | | highRp | String | The unscaled highest price in last 24 hours | | 2463 | | lowRp | String | The unscaled lowest price in last 24 hours | | 2464 | | lastRp | String | The unscaled close price in last 24 hours | | 2465 | | volumeRq | String | Symbol trade volume in last 24 hours | | 2466 | | turnoverRv | String | The unscaled turnover value in last 24 hours | | 2467 | | openInterestRv | String | current open interest | | 2468 | | indexRp | String | Unscaled index price | | 2469 | | markRp | String | Unscaled mark price | | 2470 | | fundingRateRr | String | Unscaled funding rate | | 2471 | | predFundingRateRr | String | Unscaled predicated funding rate | | 2472 | 2473 | 2474 | 2475 | * Sample: 2476 | 2477 | ``` 2478 | < { 2479 | "data": [ 2480 | [ 2481 | "ETHUSDT", 2482 | "1533.72", 2483 | "1594.17", 2484 | "1510.05", 2485 | "1547.52", 2486 | "545942.34", 2487 | "848127644.5712", 2488 | "0", 2489 | "1548.31694379", 2490 | "1548.44513153", 2491 | "0.0001", 2492 | "0.0001" 2493 | ], 2494 | [ 2495 | "BTCUSDT", 2496 | "20614.5", 2497 | "21628.4", 2498 | "19258.6", 2499 | "20626.3", 2500 | "8819.819", 2501 | "182892627.4297", 2502 | "0", 2503 | "20641.8167574", 2504 | "20643.52572781", 2505 | "0.0001", 2506 | "0.0001" 2507 | ] 2508 | ], 2509 | "fields": [ 2510 | "symbol", 2511 | "openRp", 2512 | "highRp", 2513 | "lowRp", 2514 | "lastRp", 2515 | "volumeRq", 2516 | "turnoverRv", 2517 | "openInterestRv", 2518 | "indexRp", 2519 | "markRp", 2520 | "fundingRateRr", 2521 | "predFundingRateRr" 2522 | ], 2523 | "method": "perp_market24h_pack_p.update", 2524 | "timestamp": 1666862556850547000, 2525 | "type": "snapshot" 2526 | } 2527 | ``` 2528 | 2529 | 2530 | 2531 | ### Subscribe tick event for symbol price 2532 | 2533 | * Every trading symbol has a suite of other symbols, each symbol follows same patterns, 2534 | i.e. `index` symbol follows a pattern `.`, 2535 | `mark` symbol follows a pattern `.M`, 2536 | predicated funding rate's symbol follows a pattern `.FR`, 2537 | while funding rate symbol follows a pattern `.FR8H` 2538 | * Price is retrieved by subscribing symbol tick. 2539 | * all available symbols (pfr=predicated funding rate) 2540 | 2541 | | symbol | index symbol | mark symbol | pfr symbol | funding rate symbol | 2542 | |---------|---------------|-------------------|---------------|--------------| 2543 | | BTCUSDT | .BTCUSDT | .MBTCUSDT | .BTCUSDTFR | .BTCUSDTFR8H | 2544 | | ETHUSDT | .ETHUSDT | .METHUSDT | .ETHUSDTFR | .ETHUSDTFR8H | 2545 | | XRPUSDT | .XRPUSDT | .MXRPUSDT | .XRPUSDTFR | .XRPUSDTFR8H | 2546 | | ADAUSDT | .ADAUSDT | .MADAUSDT | .ADAUSDTFR | .ADAUSDTFR8H | 2547 | 2548 | 2549 | * Request 2550 | 2551 | * The symbol in params can be replace by any symbol. 2552 | 2553 | ``` 2554 | { 2555 | "method": "tick_p.subscribe", 2556 | "params": [ ], 2557 | "id": 2558 | } 2559 | ``` 2560 | 2561 | * Response 2562 | 2563 | ack message 2564 | 2565 | ``` 2566 | { 2567 | "error": null, 2568 | "id": , 2569 | "result": { 2570 | "status": "success" 2571 | } 2572 | } 2573 | ``` 2574 | 2575 | push event 2576 | 2577 | ``` 2578 | { 2579 | "tick": { 2580 | "last": , 2581 | "symbol": 2582 | "timestamp": 2583 | } 2584 | } 2585 | 2586 | ``` 2587 | 2588 | 2589 | * Sample 2590 | 2591 | ``` 2592 | {"tick_p":{"last":"20639.38692364","symbol":".BTCUSDT","timestamp":1666863393552000000}} 2593 | {"tick_p":{"last":"20639.15408363","symbol":".BTCUSDT","timestamp":1666863394538132741}} 2594 | ``` 2595 | 2596 | --------------------------------------------------------------------------------