Introducing Futures Pro (v2) APIs

General

MainnetURL:https://ascendex.com

Testnet

Testnet URL:https://api-test.ascendex-sandbox.com

You are free to register one or more accounts in the testnet. You can use the magic code888888 to bypass all verification code checks (email verification, phone number verification, two-step authentication, etc.).

You accounts will automatically receive initial funding.

Please expect the testnet to be reset every a few days.

Obtain API Keys

Prior to use API, you need to login the website to create API Key with proper permissions. The API key is shared for all instruments in AscendEx including cash, margin and futures.

You can create and manage your API Keyshere.

Every user can create up to 10 API Keys, each can be applied with either permission below:

• View permission: It is used to query the data, such as order query, trade query.
• Trade permission: It is used to place order, cancel order and transfer, etc.
• Transfer permission: It is used to create/cancel asset transfer order, etc.

Please remember below information after creation:

• Access Key is used in API request
• Secret Key is used to generate the signature (only visible once after creation)
• The API Key can bind maximum 20 IP addresses (either host IP or network IP), we strongly suggest you bind IP address for security purpose. The API Key without IP binding will be expired after 90 days.

SDKs and Client Libraries

Official SDK

CCXT is our authorized SDK provider and you may access the AscendEX API through CCXT. For more information, please visit:https://ccxt.trade

Demo Code

Python Demo:https://github.com/ascendex/ascendex-futures-api-demo-v2

Market Making Incentive Program

AscendEX offers a Market Making Incentive Program for professional liquidity providers. Key benefits of this program include:

• Favorable fee structure.
• Monthly bonus pending satisfying KPI.
• Direct Market Access and Co-location service.

Users with good maker strategies and significant trading volume are welcome to participate in this long-term program. If your account has a trading volume of more than 150,000,000 USDT in the last 30 days on any exchange, please send the following information via email to institution@ascendex.com, with the subject "Market Maker Incentive Application":

• One AscendEX account ID.
• A brief explanation of your market making method (NO detail is needed), as well as estimation of maker orders' percentage.

Got Questions?

Join our official telegram channel:https://t.me/AscendEX_Official_API

Change Log

2022-08-16

Funding Payment History added to get account funding payment history.

2022-05-19

Limit Info API is deprecated, useLimit Info API v2 to get ban info and message threshold info.

2022-02-28

• Added theLimit Info API to get ban info and risk limit info.

2021-11-22

• Added theticker API for futures contracts.
• Added theVIP fee schedule API and theFee Schedule by Symbol API.

2021-03-18

• Added WebSocketQuery Open Orders API.

2021-03-03

• Fixed bug of cancelling a filled order with empty fields error response.
• Addedsymbol to error response from WebSocketPlace Order.
• UpdatednextFundingTime value in RESTfulFutures Pricing Data response.
• Updated nextFundingTimef value in WebSocketFutures Pricing Data message.
• Added error response demo inPlace New Order.
• Added error response demo inPlace Batch Orders.
• Fixed bug inCancel All Open Orders when no data is passed in request body.
• Fixed bug ofURL Not Found inAccount Info.
• AddedopenInterest inFutures Pricing Data
• Addedoi (open interest) inChannel: Futures Pricing Data

2021-02-26

• UpdatedrespInst field requirement inPlace Batch Orders.
• UpdatedrespInst field explanation inPlace New Order.

2021-02-25

• Updatedid field requirement in WebSocketPlace Order request.

2021-02-23

• Removed collapseDecimals field fromFutures Contracts Info response.

2021-02-22

• Added RESTfulCurrent Order History API.

2021-02-21

• AddedOrder Id Generate Algorithm.
• Added RESTfulPlace Batch Orders API.
• Added RESTfulCancel Batch Orders API.
• Added RESTfulQuery Order By ID API.

2021-02-19

• Added WebSocketAccount Snapshot API.
• Added WebSocketPlace Order API.
• Added WebSocketCancel Order API.
• Added WebSocketCancel All Orders API.

2021-02-18

• ReplacedbaseAsset andquoteAsset withsettlementAsset inFutures Contract Info response.
• UpdatedAccount Info API path.

Futures Trading System Specification

Contract Position Notional (CPN)

• CPN = abs(position size * mark price) for the contract

CPN is defined for each contract.

Margin Group

The Isolated Group

The isolated group manages a single position with a certain amount of margin moved out of the crossed group. It isolates the risk of the position from other margin groups. Your maximum loss will be limited to the total margin moved into the isolated group.

Each account may have at most one isolated group per contract.

The Crossed Group

The crossed group manages all positions except those in isolated groups.

Total Margin

For the isolated group

Total margin is set by the user. You can find its value in theisolatedMargin field from thePosition endpoint.

You can increase / decrease the total margin of the isolated margin group via theChange Margin endpoint.

For the isolated group, we also refer tototal margin asisolated margin.

For the crossed group

• Total Margin = sum(Asset Balance * Reference Price * Collateral Discount Factor) for each collateral asset

Discount factor can be found in thediscountFactor field from theFutures Collateral Asset Info endpoint.

Group Collateral Balance

For the isolated group

• Group Collateral Balance = isolated margin + unrealized pnl of the isolated position

For the crossed group

• Group Collateral Balance = total margin of the crossed group + total unrealized pnl of all positions in the crossed group

TheGroup Collateral Balance is important to determine the risk level of the margin group. If it becomes lower than theposition maintanence margin, all positions in the margin group are expected to be liquidated.

Position Initial/Maintenance Margin Rate

Initial/Maintenance Margin Rate is system-specified for each position bracket and each contract. You may refer to themarginRequirements section from theFutures Contract Info endpoint for position brackets.

You should compareContract Position Notional (CPN) with each position bracket to determine your initial and maintenance margin rate.

Position Initial/Maintenance Margin

For the isolated group

• Position Initial Margin = CPN * Initial Margin Rate
• Position Maintenance Margin = CPN * Maintenance Margin

For the crossed group

• Position Initial Margin = sum(CPN * Initial Margin Rate) for each contract in the crossed group
• Position Maintenance Margin = sum(CPN * Maintenance Margin Rate) for each contract in the crossed group

Liquidation Price

• V = Total Margin + Unrealized Pnl - Maintenance Margin

For long positions

• R = abs(position size) * (1 - maintenance margin rate)
• Liquidation Price = mark price - V / R

If the calculated liquidation price is negative, the position won't be liquidation even when the price becomes zero.

For short positions

• R = abs(position size) * (1 + maintenance margin rate)
• Liquidation Price = mark price + V / R

Unrealized PnL

TheUnrealized PnL of a position is calculated as:

• Unrealized PnL = mark price * position + reference cost

Note thatposition andreference cost are of opposite signs.

TheUnrealized PnL will be rolled (settled) when:

• position is closed or flipped side (long becomes short, vice versa)
• every 15 minutes AND abs(Unrealized Pnl) >= 10 USDT

Assume your current position is P, the current reference cost if RC, and unrealized PnL is L, after rolling:

• position = P
• reference cost = RC + L
• realized PnL = 0

You should always include the unrealized PnL when calculating the collateral balance.

Realized PnL

Realized Pnl is merely a bookkeeping entry for all profits and losses realized by the current position under the assumption that the position was built on an average cost basis.

If you are mostly concerned about the risk of your positions, you can ignore the realized PnL.

RESTful APIs

Exchange Latency Info

Latency Info

curl -X GET https://ascendex.com/api/pro/v1/exchange-info?requestTime="$(date +%s%N | cut -b1-13)"

Latency Info - Sample response::

{"code":0,"data":{"requestTimeEcho":1640052379050,"requestReceiveAt":1640052379063,"latency":13}}

HTTP Request

GET /api/pro/v1/exchange-info

Request Parameters

General Info (Public)

Futures Contracts Info

Response - Futures Contracts Info

{"code":0,"data":[{"symbol":"BTC-PERP","status":"Normal","displayName":"BTCUSDT",//thenamedisplayedonthewebpage"settlementAsset":"USDT",//settlementasset"underlying":"BTC/USDT","tradingStartTime":1579701600000,"priceFilter":{"minPrice":"0.25",//theorderpricecannotbesmallerthantheminPrice"maxPrice":"1000000",//theorderpricecannotbegreaterthanthemaxPrice"tickSize":"0.25"//theorderpricemustbeamultipleofthetickSize},"lotSizeFilter":{"minQty":"0.0001",//theorderquantitycannotbesmallerthantheminQty"maxQty":"1000000000",//theorderquantitycannotbegreaterthanthemaxQty"lotSize":"0.0001"//theorderquantitymustbeamultipleofthelotSize},"marginRequirements":[{"positionNotionalLowerbound":"0",//positionlowerbound"positionNotionalUpperbound":"50000",//positionupperbound"initialMarginRate":"0.01",//initialmarginrate"maintenanceMarginRate":"0.006"//maintenancemarginrate},{"positionNotionalLowerbound":"50000","positionNotionalUpperbound":"200000","initialMarginRate":"0.02","maintenanceMarginRate":"0.012"}]}]}

Get information for all futures contracts.

HTTP Request

GET /api/pro/v2/futures/contract

Response

Futures Collateral Asset Info

Response - Futures Collateral Asset Info

{"code":0,"data":[{"asset":"BTC","assetName":"Bitcoin","conversionFactor":"0.995","discountFactor":"0.98","displayName":"BTC","statusCode":"Normal"},{"asset":"USDT","assetName":"Tether","conversionFactor":"1","discountFactor":"1","displayName":"USDT","statusCode":"Normal"},{"asset":"USDTR","assetName":"Futures Reward Token","conversionFactor":"1","discountFactor":"1","displayName":"USDTR","statusCode":"NoTransaction"}]}

Get information for all futures collateral assets.

HTTP Request

GET /api/pro/v2/futures/collateral

Market Data (Public)

Anyone can access public market data via the API endpoints. No authentication is needed.

Futures Pricing Data

Requesting pricing data for all futures contract

{"code":0,"data":{"contracts":[{"symbol":"BTC-PERP",//contractsymbol"time":1614815005717,//servertime(UTCtimestampinmilliseconds)"fundingRate":"0.000564448",//fundingrate"indexPrice":"50657.35",//indexpriceoftheunderlying"markPrice":"50667.130409723",//markpriceofthecontract"openInterest":"90.7366",//fundingrate"nextFundingTime":1614816000000//nextfundingtime(UTCtimestampinmilliseconds)}],"collaterals":[{"asset":"USDTR","referencePrice":"1"},{"asset":"USDC","referencePrice":"0.9994"},{"asset":"ETH","referencePrice":"1582.3264074"},{"asset":"PAX","referencePrice":"0.99645"},{"asset":"BTC","referencePrice":"50636.14"},{"asset":"USDT","referencePrice":"1"}],}}

Get pricing data for all futures contracts.

HTTP Request

GET /api/pro/v2/futures/pricing-data

Bar Info

Request

curl -X GET "https://ascendex.com/api/pro/v1/barhist/info"

Sample response

{"code":0,"data":[{"name":"1","intervalInMillis":60000},{"name":"5","intervalInMillis":300000},{"name":"15","intervalInMillis":900000},{"name":"30","intervalInMillis":1800000},{"name":"60","intervalInMillis":3600000},{"name":"120","intervalInMillis":7200000},{"name":"240","intervalInMillis":14400000},{"name":"360","intervalInMillis":21600000},{"name":"720","intervalInMillis":43200000},{"name":"1d","intervalInMillis":86400000},{"name":"1w","intervalInMillis":604800000},{"name":"1m","intervalInMillis":2592000000}]}

HTTP Request

GET /api/pro/v1/barhist/info

This API returns a list of all bar intervals supported by the server.

Request Parameters

This API endpoint does not take any parameters.

Resposne

Plesae note that the one-month bar (1m) always resets at the month start. TheintervalInMillis value for the one-monthbar is only indicative.

The value in thename field should be your input to theHistorical Bar Data API.

Historical Bar Data

Request

curl -X GET "https://ascendex.com/api/pro/v1/barhist?symbol=BTC-PERP&interval=1"

Sample response

{"code":0,"data":[{"m":"bar","s":"BTC-PERP","data":{"i":"1","ts":1637619240000,"o":"56263","c":"56260","h":"56263","l":"56239","v":"0.0126"}},{"m":"bar","s":"BTC-PERP","data":{"i":"1","ts":1637619300000,"o":"56243","c":"56243","h":"56243","l":"56243","v":"0.0001"}}]}

HTTP Request

GET /api/pro/v1/barhist

This API returns a list ofbars, with each contains the open/close/high/low prices of a symbol for a specific time range.

Request Parameters

The requested time range is determined by three parameters -to,from, andn - according to rules below:

• from/to each specifies the start timestamp of the first/last bar.
• to is always honored. If not provided, this field will be set to the current system time.
• Forfrom andto:
  • if onlyfrom is provided, then the request range is determined by[from, to], inclusive. However, if the range is too wide,the server will increasefrom so the number of bars in the response won't exceed 500.
  • if onlyn is provided, then the server will return the most recentn data bars to timeto. However, ifn is greater than 500, only 500 bars will be returned.
  • if bothfrom andn are specified, the server will pick one that returns fewer bars.

Response

Code Sample

Please refer python code to [get bar history]{https://github.com/ascendex/ascendex-pro-api-demo/blob/main/python/query_pub_barhist.py}

Ticker

Ticker for one trading pair

//curl-XGET'https://ascendex.com/api/pro/v2/futures/ticker?symbol=BTC-PERP'{"code":0,"data":{"symbol":"BTC-PERP","open":"59488","close":"56725","high":"59724","low":"56672","baseVol":"208.7414","ask":["56730","0.0005"],"bid":["56710","0.0042"]}}

List of Tickers for one or multiple trading pairs

//curl-XGET"https://ascendex.com/api/pro/v2/futures/ticker?symbol=BTC-PERP,"{"code":0,"data":[{"symbol":"BTC-PERP","open":"59488","close":"56716","high":"59724","low":"56672","baseVol":"208.7414","ask":["56720","0.2315"],"bid":["56712","0.0024"]}]}

HTTP Request

GET api/pro/v2/futures/ticker

You can get summary statistics of one or multiple symbols (spot market) with this API.

Request Parameters

This API endpoint accepts one optional string fieldsymbol:

• If you do not specifysymbol, the API will responde with tickers of all symbols in a list.
• If you setsymbol to be a single symbol, such asASD/USDT, the API will respond with the ticker of the target symbol as an object. If you want to wrap the object in a one-element list, append a comma to the symbol, e.g.ASD/USDT,.
• You shall specifysymbol as a comma separated symbol list, e.g.ASD/USDT,BTC/USDT. The API will respond with a list of tickers.

Respond Content

The API will respond with a ticker object or a list of ticker objects, depending on how you set thesymbol parameter.

Each ticker object contains the following fields:

Code Sample

Please refer to python code to [query ticker info]{https://github.com/ascendex/ascendex-pro-api-demo/blob/main/python/query_pub_ticker.py}

Authenticate a RESTful Request

Create Request

To access private data via RESTful APIs, you must include the following headers:

• x-auth-key - required, the api key as a string.
• x-auth-timestamp - required, the UTC timestamp in milliseconds of your request
• x-auth-signature - required, the request signature (seeSign a Request)

The timestamp in the header will be checked against server time. If the difference is greater than 30 seconds, the request will be rejected.

Sign a Request

Signing a RESTful Request

# bashAPIPATH=infoAPIKEY=CEcrjGyipqt0OflgdQQSRGdrDXdDUY2xSECRET=hV8FgjyJtpvVeAcMAgzgAFQCN36wmbWuN7o3WPcYcYhFd8qvE43gzFGVsFcCqMNkTIMESTAMP=`date +%s%N |cut-c-13`# 1608133910000MESSAGE=$TIMESTAMP+$APIPATHSIGNATURE=`echo-n$MESSAGE | openssl dgst-sha256-hmac$SECRET-binary |base64`echo$SIGNATURE# /pwaAgWZQ1Xd/J4yZ4ReHSPQxd3ORP/YR8TvAttqqYM=curl-X GET-i\-H"Accept: application/json"\-H"Content-Type: application/json"\-H"x-auth-key:$APIKEY"\-H"x-auth-signature:$SIGNATURE"\-H"x-auth-timestamp:$TIMESTAMP"\  https://ascendex.com/api/pro/v1/info

# python 3.6+importtime,hmac,hashlib,base64api_path="info"api_key="CEcrjGyipqt0OflgdQQSRGdrDXdDUY2x"sec_key="hV8FgjyJtpvVeAcMAgzgAFQCN36wmbWuN7o3WPcYcYhFd8qvE43gzFGVsFcCqMNk"timestamp=int(round(time.time()*1e3))# 1608133910000message=bytes(f"{timestamp}+{api_path}",'utf-8')secret=bytes(sec_key,'utf-8')signature=base64.b64encode(hmac.new(secret,message,digestmod=hashlib.sha256).digest())header={"x-auth-key":api_key,"x-auth-signature":signature,"x-auth-timestamp":timestamp,}print(signature)# b'/pwaAgWZQ1Xd/J4yZ4ReHSPQxd3ORP/YR8TvAttqqYM='

// java 1.8+importjavax.crypto.Mac;importjavax.crypto.spec.SecretKeySpec;importorg.apache.commons.codec.binary.Base64;publicclassSignatureExample{publicstaticvoidmain(String[]args){try{longtimestamp=System.currentTimeMillis();// 1562952827927Stringapi_path="user/info";Stringsecret="hV8FgjyJtpvVeAcMAgzgAFQCN36wmbWuN7o3WPcYcYhFd8qvE43gzFGVsFcCqMNk";Stringmessage=timestamp+"+"+api_path;Macsha256_HMAC=Mac.getInstance("HmacSHA256");SecretKeySpecsecret_key=newSecretKeySpec(secret.getBytes(),"HmacSHA256");sha256_HMAC.init(secret_key);Stringhash=Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));System.out.println(hash);// vBZf8OQuiTJIVbNpNHGY3zcUsK5gJpwb5lgCgarpxYI=}catch(Exceptione){System.out.println("Error");}}}

To query APIs with private data, you must include a signature using base64 encoded HMAC sha256 algorithm. The prehash string is<timestamp>+<api-path>. Thetimestamp is the UTC timestamp in milliseconds. Theapi-path is provided in each API description.

See the code demos in (bash/python/java) on the right.

Account Data

Account Info

Account Info - Sample response:

{"code":0,"data":{"accountGroup":0,"email":"yyzzxxz@gmail.com","expireTime":1604620800000,//expiretime,UTCtimestampinmilliseconds.If-1,theapikeywillnotexpire"allowedIps":["123.123.123.123"],"cashAccount":["sample-cash-account-id"],"marginAccount":["sample-margin-account-id"],"futuresAccount":["sample-futures-account-id"],"userUID":"U0866943712","tradePermission":true,"transferPermission":true,"viewPermission":true,"limitQuota":1000}}

HTTP Request

GET /api/pro/v2/account/info

Signature

You should sign the message in header as specified inAuthenticate a RESTful Request section.

prehash string

<timestamp>+v2/account/info

Obtain the account information.

You can obtain youraccountGroup from this API, which you will need to include in the URL for all your private RESTful requests.

Response Content

See a demo atquery private account info.

VIP Fee Schedule

Fee Schedule - Sample response for general info::

{"code":0,"data":{"domain":"futures","userUID":"U0866943712","vipLevel":0,"genericFee":{"largeCap":{"maker":"0.00085","taker":"0.00085"},"smallCap":{"maker":"0.001","taker":"0.001"}}}}

HTTP Request

GET <account-group>/api/pro/v1/futures/fee/info

Signature

You should sign the message in header as specified inAuthenticate a RESTful Request section.

prehash string

<timestamp>+fee/info

See a demo atquery fee.

Fee Schedule by Symbol

Fee Schedule - Sample response for each symbol::

{"code":0,"data":{"domain":"futures","userUID":"U0866943712","vipLevel":0,"productFee":[{"fee":{"maker":"0.0001","taker":"0.0001"},"symbol":"BTC-PERP"},{"fee":{"maker":"0.0001","taker":"0.0001"},"symbol":"ETH-PERP"}]}}

HTTP Request

GET <account-group>/api/pro/v1/futures/fee

Signature

You should sign the message in header as specified inAuthenticate a RESTful Request section.

prehash string

<timestamp>+fee

See a demo atquery fee.

Risk Limit Info(Deprecated)

This API has been deprecated, please userisk limit info v2 instead.

Risk Limit Info

curl -X GET https://ascendex.com/api/pro/v1/risk-limit-info"

Risk Limit Info - Sample response::

{"code":0,"data":{"ip":"0.0.0.0","webSocket":{"windowSizeInMinutes":5,"maxNumRequests":45,"maxSessionPerIp":30,"isBanned":true,"bannedUntil":1644807691158,"violationCode":100014,"reason":"exceeds MAX_REQ_COUNT_PER_IP[45], 49 requests recently"}}}

HTTP Request

GET /api/pro/v1/risk-limit-info

Request Parameters

Risk Limit Info (v2)

Risk Limit Info v2

Our message thresholds in web socket are based onop field andaction field. Each threshold will have two levels, which are based on counts of messages received in1 minute. If level 1 threshold is violated, this type of messages will be ignored in the following 15 minutes, other functions are not affected. If you keep sending these messages and triggered level 2 threshold, the violated WebSocket session will be killed and this ip will be banned for 15 minutes. Currently, We have following threshold groups:

• admin op, includesauth/ping/pong

• stream op, includessub/unsub

• req op, includes allreq op, butorder req andsnapshot req have their own thresholds

  • order req, includesplace_order/cancel_order/cancel_all
  • snapshot req, includesdepth_snapshot/depth_snapshot_top100

All the operations fall into sameop/req group will share a threshold, meaning the sum of count of these messages should not violate the threshold.

Forreq op, we have two fine granularity thresholdorder req andsnapshot req, which will have their specialized threshold value for messages belonging to their types.

curl -X GET https://ascendex.com/api/pro/v2/risk-limit-info"

Risk Limit Info - Sample response::

{"code":0,"data":{"ip":"173.123.133.23","webSocket":{"status":{"isBanned":false,"bannedUntil":-1,"violationCode":0,"reason":""},"limits":{"maxWebSocketSessionsPerIpAccountGroup":20,"maxWebSocketSessionsPerIpTotal":300},"messageThreshold":{"level1OpThreshold":{"auth":800,"ping":800,"pong":800,"sub":150,"unsub":150,"req":10000},"level2OpThreshold":{"auth":1000,"ping":1000,"pong":1000,"sub":200,"unsub":200,"req":10000},"level1ReqThreshold":{"place_order":8000,"cancel_order":8000,"cancel_all":8000,"batch_place_order":10000,"batch_cancel_order":10000,"depth_snapshot":400,"depth_snapshot_top100":400,"market_trades":10000,"balance":10000,"open_order":10000,"margin_risk":10000,"futures_account_snapshot":10000,"futures_open_orders":10000},"level2ReqThreshold":{"place_order":10000,"cancel_order":10000,"cancel_all":10000,"batch_place_order":10000,"batch_cancel_order":10000,"depth_snapshot":500,"depth_snapshot_top100":500,"market_trades":10000,"balance":10000,"open_order":10000,"margin_risk":10000,"futures_account_snapshot":10000,"futures_open_orders":10000}}}}}

HTTP Request

GET /api/pro/v2/risk-limit-info

Request Parameters

Position

Response

{"code":0,"data":{"ac":"FUTURES",//accountcategory"accountId":"sample-futures-account-id",//accountID"collaterals":[{"asset":"ETH",//collateralasset"balance":"100",//balance"discountFactor":"0.95",//discountfactor"referencePrice":"481.79793092"//referenceprice(quoteinUSDT)},{"asset":"BTC","balance":"10","discountFactor":"0.98","referencePrice":"17600.095"},{"asset":"USDT","balance":"10000","discountFactor":"1","referencePrice":"1"}],"contracts":[{"symbol":"BTC-PERP",//contractsymbol"side":"LONG",//side"position":"0.5",//positiveforlongpositionandnegativeforshortposition"referenceCost":"-16800",//referencecost"unrealizedPnl":"0",//unrealizedpnl"realizedPnl":"0",//realizedpnl"avgOpenPrice":"0",//AverageOpeningPrice"marginType":"cross",//margintype:isolated/cross"isolatedMargin":"0",//isolatedmargin"leverage":"10",//leverage"takeProfitPrice":"0",//takeprofitprice(bypositionexitorder)"takeProfitTrigger":"market",//takeprofittrigger(bypositionexitorder)"stopLossPrice":"0",//stoplossprice(bypositionexitorder)"stopLossTrigger":"market",//stoplosstrigger(bypositionexitorder)"buyOpenOrderNotional":"1362.419625",//buyopenordernotional"sellOpenOrderNotional":"0",//sellopenordernotional"indexPrice":"17600.095",//priceofthecontract'sunderlyingproductprice"markPrice":"-1"//contract'smarkprice}]}}

Get current position data - a full snapshot of your futures account.

HTTP Request

GET /<grp>/api/pro/v2/futures/position

Prehash String

<timestamp>+v2/futures/position

Free Margin

Response

{"code":0,"data":{"collaterals":[{"asset":"BTC",//collateralasset"availableForTransfer":"1"//maximumamountallowedtobetransferredout},{"asset":"USDT","availableForTransfer":"10000"}],"crossed":{"freeMargin":"30000"},"isolated":[{"freeMargin":"0","symbol":"BTC-PERP"}]}}

Get free margin for each margin group (crossed & isolated) and amount avaible for withdrawal for each collateral asset.

SeeChange Margin on how to increase or decrease margin for the isolated position.

HTTP Request

GET /<grp>/api/pro/v2/futures/free-margin

Prehash String

<timestamp>+v2/futures/free-margin

Change Margin (for Isolated Positions)

Successful Response

{"code":0}

You can only change margin for isolated margin positions.

SeeFree Margin on the maximum amount you can increase / decrease the isolated margin.

HTTP Request

POST /<grp>/api/pro/v2/futures/isolated-position-margin

Prehash String

<timestamp>+v2/futures/isolated-position-margin

Request Parameters

to a negative number will decrease the isolated margin.

When you increase/decrease the isolated margin by a certain amount, the same amount X will be deducted/added from your USDT balance in the collateral.

When you have non-USDT collateral assets, you may be able to increase the isolated margin by an amount more than your USDT balance. In which case, your USDT balance will become negative after the operation.

Change Margin Type

Response

{"code":0}

You can change the margin type of a position:

• crossed margin (crossed)
• isolated margin (isolated)

HTTP Request

POST /<grp>/api/pro/v2/futures/margin-type

Prehash String

<timestamp>+v2/futures/margin-type

Request Parameters

Change Contract Leverage

Response

{"code":0,"data":{"leverage":10,"symbol":"BTC-PERP"}}

HTTP Request

POST /<grp>/api/pro/v2/futures/leverage

Request Parameters

Deposit to the Futures Account

Successful Response

{"code":0}

You can deposit collateral assets to your Futures account from your Cash account.

HTTP Request

POST /<grp>/api/pro/v2/futures/transfer/deposit

Prehash String

<timestamp>+v2/futures/transfer/deposit

Request Parameters

Withdraw from the Futures Account

Successful Response

{"code":0}

You can withdraw collateral assets from your Futures account to your Cash account.

HTTP Request

POST /<grp>/api/pro/v2/futures/transfer/withdraw

Prehash String

<timestamp>+v2/futures/transfer/withdraw

Request Parameters

Funding Payment History

Response

{"code":0,"data":{"data":[{"fundingRate":"0.00003666","paymentInUSDT":"-0.000142423","symbol":"BTC-PERP","timestamp":1642780800000},{"fundingRate":"0.000109429","paymentInUSDT":"-0.000428031","symbol":"BTC-PERP","timestamp":1642752000000}],"hasNext":true,"page":1,"pageSize":2}}

Get funding payment history of your account.

HTTP Request

GET /<grp>/api/pro/v2/futures/funding-payments

Prehash String

<timestamp>+v2/futures/funding-payments

Request Parameters

Code Sample

Please refer to python code toget funding history

Order

Generate Order Id

We use the following method to generate an unique id for each order place/cancel request. (You could getuserUID fromAccount Info API.)

Method

• A = 'a' for order via rest api, or 's' for order via websocket;

• B = Convert timestamp (in miliseconds) to hex string;

• C = User UID (11 chars, starting with 'U' followed by 10 digits);

• D = If user provide client order Id (with length >= 9, letters and digits only), then take the right 9 chars; otherwise, we randomly generate 9 chars;

• Final order Id is concatenation of strings A, B, C, D from above steps, i.e., orderId = A + B + C + D.

Extra info onid

• id value must satisfy regrex pattern"^\w[\w\-]*\w$" (i.e. start and end with word character), and with length up to 32. ("Invalid Client Order id" error for violation)

• id value with length 9 is recommended, since we take the right most 9 chars for order Id generation.

• id value with length < 9 will not be used in order Id generation, but we still echo it back in order ack message (empty string when noid value provided).

• If a validid value is provided when placing order, order Id from server side is pre-determined. This could be helpful for order status check in case of accidently internet connection issue.

Code Sample

Please refer to python code togen server order id

New Order

Successful Response

{"code":0,"data":{"meta":{"action":"place-order","id":"abcd1234abcd1234","respInst":"ACCEPT"//ACK,ACCEPT,orDONE},"order":{"ac":"FUTURES","accountId":"sample-futures-account-id","seqNum":14,//sequencenumber,also-1inACKmode"time":1605677683714,"orderId":"sample-order-id","orderType":"Limit","side":"Buy","symbol":"BTC-PERP","price":"9500","orderQty":"0.1","stopPrice":"0","stopBy":"market","status":"New","lastExecTime":1605677684479,"lastPx":"0","lastQty":"0","avgFilledPx":"0","cumFilledQty":"0","fee":"0","cumFee":"0","feeAsset":"USDT","errorCode":""}}}

Error Response

{"ac":"FUTURES","accountId":"sample-futures-account-id","action":"place-order","code":300014,"info":{"id":"abcd1234abcd1234","symbol":"BTC-PERP"},"message":"Order price doesn't conform to the required tick size: 1","reason":"TICK_SIZE_VIOLATION"}

HTTP Request

POST /<grp>/api/pro/v2/futures/order

Prehash String

<timestamp>+v2/futures/order

Request Parameters

Place Batch Orders

Place Batch Orders - Request Body

{"orders":[{"id":"sampleRequestId1","time":1613878579169,"symbol":"BTC-PERP","price":"34000","orderQty":"0.1","orderType":"limit","side":"buy","respInst":"ACK"},{"id":"sampleRequestId2","time":1613878579169,"symbol":"BTC-PERP","price":"35000","orderQty":"0.2","orderType":"market","side":"buy","respInst":"ACK"}]}

Place Batch Orders - Successful ACK Response (Status 200, code 0)

{"code":0,"data":{"meta":{"action":"batch-place-order","respInst":"ACK"},"orders":[{"id":"sampleRequestId1","orderId":"a177c2a8cfe1U0123456789eqntvwWsy","orderType":"Limit","symbol":"BTC-PERP","timestamp":1613878579202},{"id":"sampleRequestId2","orderId":"a177c2a8cfe1U0123456789equestId2","orderType":"Market","symbol":"BTC-PERP","timestamp":1613878579202}]}}

Error Response

{"ac":"FUTURES","accountId":"sample-futures-account-id","action":"batch-place-order","code":300013,"info":[{"code":300013,"id":"sampleRequestId1","message":"Some invalid order in this batch.","reason":"INVALID_BATCH_ORDER","symbol":"BTC-PERP"},{"code":320008,"id":"sampleRequestId2","message":"Futures account exposure higher than system acceptable level.","reason":"FUTURES_TOO_RISKY","symbol":"BTC-PERP"}],"message":"Batch Order failed, please check each order info for detail.","reason":"INVALID_BATCH_ORDER"}

Place multiple orders in a batch. If any order(s) fails our basic check, the whole batch request will fail.

You may submit up to 10 orders at a time. Server will respond with error if you submit more than 10 orders.

HTTP Request

POST /<grp>/api/pro/v2/futures/order/batch

Prehash String

<timestamp>+v2/futures/order/batch

Request Parameters

please refer toplacing new order for order item definition.

respInst field is required for market order and onlyACK is allowed.

Cancel Order

Response

{"code":0,"data":{"meta":{"action":"cancel-order",//action"id":"abcd1234abcd1234",//userprovidedID"respInst":"ACCEPT"//responseinstruction},"order":{"ac":"FUTURES",//accountcategory"accountId":"sample-futures-account-id",//accountID"seqNum":14,//sequencenumber"time":1605677683714,//ordercreationtime(UTCtimeinmilliseconds)"orderId":"sample-order-id",//orderID"orderType":"Limit",//ordertype"side":"Buy",//side"symbol":"BTC-PERP",//contractsymbol"price":"9500",//orderprice"orderQty":"0.1",//orderqty"stopPrice":"0",//stopprice"stopBy":"market",//stoppricetrigger"status":"Canceled",//orderstatus"lastExecTime":1605677684479,//lastexecutiontime(UTCtimeinmilliseconds)"lastPx":"0",//lastfilledprice"lastQty":"0",//lastfilledquantity"avgFilledPx":"0",//averagefilledpriceofallfills"cumFilledQty":"0",//cummulativefilledquantity"fee":"0",//feeofthelastfill"cumFee":"0",//cummulativefee"feeAsset":"USDT",//feeasset"errorCode":""//errorcode}}}

HTTP Request

DELETE /<grp>/api/pro/v2/futures/order

Prehash String

<timestamp>+v2/futures/order

Request Parameters

Response

respInst

Cancel Batch Orders

Cancel Batch Orders - Request Body

{"orders":[{"id":"sampleRequestId1","orderId":"a177c2a8cfe1U0123456789eqntvwWsy","symbol":"BTC-PERP","time":1613900544076},{"id":"sampleRequestId2","orderId":"a177c2a8cfe1U0123456789equestId2","symbol":"BTC-PERP","time":1613900544076}]}

Cancel Batch Orders - Successful ACK Response (Status 200, code 0)

{"code":0,"data":{"meta":{"action":"batch-cancel-order","respInst":"ACK"},"orders":[{"id":"sampleRequestId1","orderId":"a177c2a8cfe1U0123456789eqntvwWsy","orderType":"","symbol":"BTC-PERP","timestamp":1613900544091},{"id":"sampleRequestId2","orderId":"a177c2a8cfe1U0123456789equestId2","orderType":"","symbol":"BTC-PERP","timestamp":1613900544168}]}}

Cancel multiple orders in a batch. If any order(s) fails our basic check, the whole batch request will fail.

You may submit up to 10 orders to cancel at a time. Server will respond with error if you submit more than 10 orders.

HTTP Request

DELETE /<grp>/api/pro/v2/futures/order/batch

Prehash String

<timestamp>+v2/futures/order/batch

Request Parameters

please refer tocancel order for order item definition

Cancel All Open Orders

Response

{"code":0}

HTTP Request

DELETE /<grp>/api/pro/v2/futures/order/all

Prehash String

<timestamp>+v2/futures/order/all

Request Parameters

List Open Orders

Response

{"code":0,"data":[{"ac":"FUTURES",//accountcategory"accountId":"sample-futures-account-id",//accountID"seqNum":14,//sequencenumber"time":1605677683714,//ordercreationtime"orderId":"sample-order-id",//orderID"orderType":"Limit",//ordertype"side":"Buy",//orderside"symbol":"BTC-PERP",//contractsymbol"price":"9500",//orderprice"orderQty":"0.1",//orderquantity"stopPrice":"0",//stopprice"stopBy":"market",//stoppricetrigger"status":"New",//orderstatus"lastExecTime":1605677684479,//lastexecutiontime"lastPx":"0",//lastfilledprice"lastQty":"0",//lastfilledquantity"avgFilledPx":"0",//averagefilledpriceofallfills"cumFilledQty":"0",//cummulativefilledquantity"fee":"0",//feeofthelastfill"cumFee":"0",//cummulativefee"feeAsset":"USDT",//feeasset"errorCode":""//errorcode}]}

HTTP Request

GET /<grp>/api/pro/v2/futures/order/open

Prehash String

<timestamp>+v2/futures/order/open

List Current History Orders

Current History Orders - Request Body

{"symbol":"BTC-PERP","n":20,"executedOnly":true}

Successful Response (Status 200, code 0)

{"code":0,"data":[{"ac":"FUTURES","accountId":"sampleFuturesAccountId","avgFilledPx":"58501","cumFee":"0.058501","cumFilledQty":"0.001","errorCode":"","execInst":"NULL_VAL","fee":"0.058501","feeAsset":"USDT","lastExecTime":1613992168196,"lastPx":"58501","lastQty":"0.001","orderId":"a177c29e4064U0123456789dVeUxlVyA","orderQty":"0.001","orderType":"Limit","posStopLossPrice":"0","posStopLossTrigger":"market","posTakeProfitPrice":"0","posTakeProfitTrigger":"market","price":"59027","seqNum":1041950,"side":"Buy","status":"Filled","stopBy":"market","stopPrice":"0","symbol":"BTC-PERP","time":1613992168190},...]}

This API returns all current history orders for futures account.

HTTP Request

GET <account-group>/api/pro/v2/futures/order/hist/current

Prehash String

<timestamp>+v2/futures/order/hist/current

Request Parameters

Response

Return a list of history orders in"data" field.

Query Order By ID

Query order with single order id - Request Body

{"orderId":"a177c29e4064U0123456789dVeUxlVyA"}

Successful Response (Status 200, code 0)

{"code":0,"accountId":"sampleFuturesAccountId","ac":"FUTURES","data":{"ac":"FUTURES","accountId":"sampleFuturesAccountId","avgFilledPx":"0","cumFee":"0","cumFilledQty":"0","errorCode":"","execInst":"NULL_VAL","fee":"0","feeAsset":"USDT","lastExecTime":1613877923408,"lastPx":"0","lastQty":"0","orderId":"a177c29e4064U0123456789dVeUxlVyA","orderQty":"0.1","orderType":"Limit","posStopLossPrice":"0","posStopLossTrigger":"None","posTakeProfitPrice":"0","posTakeProfitTrigger":"None","price":"34000","seqNum":18586710,"side":"Buy","status":"New","stopBy":"","stopPrice":"0","symbol":"BTC-PERP","time":1613877922641}}

Query Order with multiple order ids - Request Body

{"orderId":"a177c29e4064U0123456789dVeUxlVyA,a177c29e4064U0123456789dVeUxlVyB"}

Successful Response (Status 200, code 0)

{"code":0,"accountId":"sampleFuturesAccountId","ac":"FUTURES","data":[{"ac":"FUTURES","accountId":"sampleFuturesAccountId","orderId":"a177c29e4064U0123456789dVeUxlVyA",...},{"ac":"FUTURES","accountId":"sampleFuturesAccountId","orderId":"a177c29e4064U0123456789dVeUxlVyB",...}]}

HTTP Request

GET /<grp>/api/pro/v2/futures/order/status

Prehash String

<timestamp>+v2/futures/order/status

Request Parameters

The API will respond with a list of objects in the data field. Each object in the list contains information of a single order. There's one exception, if you use only a single orderId, the data field of the API response will be simplified to a single object. If you want the API to respond with a list of only one object in this case, add a comma (,) to the orderId.

Balance Snapshot And Update Detail

Here we provide rest API to get daily balance snapshot, and intraday balance and order fills update details. We recommend calling balance snapshot endpoint(futures/balance/snapshot) to get balance at the beginning of the day, and get the sequence numbersn; then start to query balance or order fills update fromfutures/balance/history by setting parametersn value to besn + 1.

Please note we enforce rate limit 8 / minute. Data query for most recent 7 days is supported.

Futures Account Balance Snapshot

This API returns futures balance snapshot on daily basis.

HTTP Request

GET api/pro/data/v1/futures/balance/snapshot

Signature

You should sign the message in header as specified inAuthenticate a RESTful Request section.

Prehash String

<timestamp>+data/v1/futures/balance/snapshot

Request Parameters

Response Content

meta field provides some basic info about the balance snapshot data.

meta schema

collateralBalance field provides array of ‘asset’ and ‘totalBalance’ for collateral balance.

collateralBalance schema

contractBalance field provides array of current contract positions infomation.

contractBalance schema

Code Sample

Please refer to python code toquery balance snapshot

Futures Order and Balance Detail

This API is for intraday balance change detail from balance event and order fillss.

HTTP Request

GET api/pro/data/v1/futures/balance/history

Prehash String

<timestamp>+data/v1/futures/balance/history

Futures Account Balance Detail - Sample response

{"balance":[{"data":[{"asset":"XPRTPC","curBalance":"-7.873230189","deltaQty":"0.004117158"}],"eventType":"Fundingpayment","sn":18591022051,"transactTime":1634947227877},{"data":[{"asset":"BTCPC","curBalance":"-307.654491085","deltaQty":"10.673854479"},{"asset":"USDT","curBalance":"149.493187792","deltaQty":"10.673854479"}],"eventType":"Futuressettlement","sn":18590550015,"transactTime":1634913817331}],"meta":{"ac":"futures","accountId":"futfi7p9j312936d2hkjJpAahWyb4RCJ"},"order":[{"data":[{"asset":"PORTP","curBalance":"1","dataType":"trade","deltaQty":"1"},{"asset":"PORTPC","curBalance":"-6.213726","dataType":"trade","deltaQty":"-6.21"},{"asset":"PORTPC","curBalance":"-6.213726","dataType":"fee","deltaQty":"-0.003726"}],"liquidityInd":"RemovedLiquidity","orderId":"r17ca5840c64U7684578612bportL84r","orderType":"Market","side":"Buy","sn":18589783182,"transactTime":1634864467246}]}

Request Parameters

Response Content

Meta

meta field provides some basic info.

meta schema

Order

order field provides an array of asset balance detail from order fill event.

order schema

order balance detail by asset

data schema

Balance

balance field provides an array of asset balance detail due to balance event.

balance schema

data schema

Code Sample

Please refer to python code toquery order and balance detail

WebSocket

How to Connect

Base endpoints:

• Testnet:

  • Public endpoint:wss://api-test.ascendex-sandbox.com:443/api/pro/v2/stream
  • Private endpoint:wss://api-test.ascendex-sandbox.com:443/<grp>/api/pro/v2/stream

• Mainnet:

  • Public endpoint:wss://ascendex.com:443/api/pro/v2/stream
  • Private endpoint:wss://ascendex.com:443/<grp>/api/pro/v2/streamYou can only authenticate a WebSocket session via a private endpoint.

WebSocket Authentication

You must authenticate the websocket session in order to recieve private data and send account specific requests (e.g. placing new orders).

You have two options to authenticate a websocket session.

• by adding authentication data in the request header when connecting to websocket.
• by sending anop:auth message to the server after you have connected to websocket.

Once you successfully connect to the websocket, you will receive aconnected message:

• for authenticated websocket session:{"m":"connected","type":"auth"}
• for unauthenticated websocket session:{"m":"connected","type":"unauth"}

If the session is disconnected for some reason, you will receive adisconnected message:

• {"m":"disconnected","code":100005,"reason":"INVALID_WS_REQUEST_DATA","info":"Session is disconnected due to missing pong message from the client"}

Method 1 - WebSocket Authentication with Request Headers

Authenticate with Headers

# # Install wscat from Node.js if you haven't# npm install -g wscatAPIPATH=v2/streamAPIKEY=BclE7dBGbS1AP3VnOuq6s8fJH0fWbH7rSECRET=fAZcQRUMxj3eX3DreIjFcPiJ9UR3ZTdgIw8mxddvtcDxLoXvdbXJuFQYadUUsF7qTIMESTAMP=`date +%s%N |cut-c-13`MESSAGE=$TIMESTAMP+$APIPATHSIGNATURE=`echo-n$MESSAGE | openssl dgst-sha256-hmac$SECRET-binary |base64`wscat-H"x-auth-key:$APIKEY"\-H"x-auth-signature:$SIGNATURE"\-H"x-auth-timestamp:$TIMESTAMP"\-c wss://api-test.ascendex-sandbox.com:443/api/pro/v2/stream-w 1-x'{"op":"sub", "id": "abc123", "ch": "order:cshQtyfq8XLAA9kcf19h8bXHbAwwoqDo:ASD/USDT"}'

This is similar to the way you authenticate any RESTful request. You need to add the following header fields to the connection request:

• x-auth-key
• x-auth-timestamp
• x-auth-signature

The server will then check if the data is correctly signed before upgrading the connection protocol to WebSocket.

Note that if you specify these header fields, the server will reject the websocket connection request if authentication fails.

Method 2 - WebSocket Authentication by Sending the Auth Message

Authenticate by Sending theauth Message

# # Install wscat from Node.js if you haven't# npm install -g wscatAPIPATH=v2/streamAPIKEY=BclE7dBGbS1AP3VnOuq6s8fJH0fWbH7rSECRET=fAZcQRUMxj3eX3DreIjFcPiJ9UR3ZTdgIw8mxddvtcDxLoXvdbXJuFQYadUUsF7qTIMESTAMP=`date +%s%N |cut-c-13`MESSAGE=$TIMESTAMP+$APIPATHSIGNATURE=`echo-n$MESSAGE | openssl dgst-sha256-hmac$SECRET-binary |base64`wscat-c wss://api-test.ascendex-sandbox.com:443/1/api/pro/v2/stream-w 1-x"{\"op\":\"auth\",\"id\":\"abc123\",\"t\":$TIMESTAMP, "key":\"$APIKEY\",\"sig\":\"$SIGNATURE\"}"

You can also authenticate a live websocket session by sending anop:auth message to the server.

More comprehensive examples can be found at:

• Python demo forwebsocket auth

Authentication Response

Auth success message

{"m":"auth","id":"abc123","code":0}

Auth error message

{"m":"auth","id":"abc123","code":200006,"err":"Unable to find User Account Data"}

You will receive a message for authentication result after you send authentication request.