Comment on page
💾
API Documentation
- The base endpoint is: https://fapi.apollox.finance
- All endpoints return either a JSON object or array.
- Data is returned in ascending order. Oldest first, newest last.
- All time and timestamp related fields are in milliseconds.
- All data types adopt definition in JAVA.
- HTTP
4XX
return codes are used for for malformed requests; the issue is on the sender's side. - HTTP
403
return code is used when the WAF Limit (Web Application Firewall) has been violated. - HTTP
429
return code is used when breaking a request rate limit. - HTTP
418
return code is used when an IP has been auto-banned for continuing to send requests after receiving429
codes. - HTTP
5XX
return codes are used for internal errors; the issue is on APX side. - HTTP
503
return code is used when the API successfully sent the message but not get a response within the timeout period. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.
- Any endpoint can return an ERROR
The error payload is as follows:
{
"code": -1121,
"msg": "Invalid symbol."
}
- Specific error codes and messages defined in Error Codes.
- For
GET
endpoints, parameters must be sent as aquery string
. - For
POST
,PUT
, andDELETE
endpoints, the parameters may be sent as aquery string
or in therequest body
with content typeapplication/x-www-form-urlencoded
. You may mix parameters between both thequery string
andrequest body
if you wish to do so. - Parameters may be sent in any order.
- If a parameter sent in both the
query string
andrequest body
, thequery string
parameter will be used.
- The
/fapi/v1/exchangeInfo
rateLimits
array contains objects related to the exchange'sRAW_REQUEST
,REQUEST_WEIGHT
, andORDER
rate limits. These are further defined in theENUM definitions
section underRate limiters (rateLimitType)
. - A
429
will be returned when either rate limit is violated.
APX Finance has the right to further tighten the rate limits on users with intent to attack.
- Every request will contain
X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
in the response headers which has the current used weight for the IP for all request rate limiters defined. - Each route has a
weight
which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavierweight
. - When a 429 is received, it's your obligation as an API to back off and not spam the API.
- Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (HTTP status 418).
- IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
- The limits on the API are based on the IPs, not the API keys.
It is strongly recommended to use websocket stream for getting data as much as possible, which can not only ensure the timeliness of the message, but also reduce the access restriction pressure caused by the request.
- Every order response will contain a
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the account for all order rate limiters defined. - Rejected/unsuccessful orders are not guaranteed to have
X-MBX-ORDER-COUNT-**
headers in the response. - The order rate limit is counted against each account.
- Each endpoint has a security type that determines the how you will interact with it.
- API-keys are passed into the Rest API via the
X-MBX-APIKEY
header. - API-keys and secret-keys are case sensitive.
- API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.
- By default, API-keys can access all secure routes.
Security Type | Description |
---|---|
NONE | Endpoint can be accessed freely. |
TRADE | Endpoint requires sending a valid API-Key and signature. |
USER_DATA | Endpoint requires sending a valid API-Key and signature. |
USER_STREAM | Endpoint requires sending a valid API-Key. |
MARKET_DATA | Endpoint requires sending a valid API-Key. |
TRADE
andUSER_DATA
endpoints areSIGNED
endpoints.
SIGNED
endpoints require an additional parameter,signature
, to be sent in thequery string
orrequest body
.- Endpoints use
HMAC SHA256
signatures. TheHMAC SHA256 signature
is a keyedHMAC SHA256
operation. Use yoursecretKey
as the key andtotalParams
as the value for the HMAC operation. - The
signature
is not case sensitive. - Please make sure the
signature
is the end part of yourquery string
orrequest body
. totalParams
is defined as thequery string
concatenated with therequest body
.
- A
SIGNED
endpoint also requires a parameter,timestamp
, to be sent which should be the millisecond timestamp of when the request was created and sent. - An additional parameter,
recvWindow
, may be sent to specify the number of milliseconds aftertimestamp
the request is valid for. IfrecvWindow
is not sent, it defaults to 5000.
The logic is as follows:
if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow){
// process request
}
else {
// reject request
}
Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With
recvWindow
, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.It is recommended to use a small recvWindow of 5000 or less!
Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using
echo
, openssl
, and curl
.Key | Value |
---|---|
apiKey | dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83 |
secretKey | 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9 |
Parameter | Value |
---|---|
symbol | BTCUSDT |
side | BUY |
type | LIMIT |
timeInForce | GTC |
quantity | 1 |
price | 9000 |
recvWindow | 5000 |
timestamp | 1591702613943 |
Example 1: As a query string
Example 1
HMAC SHA256 signature:
$ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
(stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9
curl command:
(HMAC SHA256)
$ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi/apollox.finance/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'
- queryString:symbol=BTCUSDT &side=BUY &type=LIMIT &timeInForce=GTC &quantity=1 &price=9000 &recvWindow=5000 ×tamp=1591702613943
Example 2: As a request body
Example 2
HMAC SHA256 signature:
$ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
(stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9
curl command:
(HMAC SHA256)
$ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi/apollox.finance/fapi/v1/order' -d 'symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'
- requestBody:symbol=BTCUSDT &side=BUY &type=LIMIT &timeInForce=GTC &quantity=1 &price=9000 &recvWindow=5000 ×tamp=1591702613943
Example 3: Mixed query string and request body
Example 3
HMAC SHA256 signature:
$ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
(stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9
curl command:
(HMAC SHA256)
$ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi/apollox.finance/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=9000&recvWindow=5000×tamp=1591702613943&signature=3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'
- queryString: symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC
- requestBody: quantity=1&price=9000&recvWindow=5000×tamp= 1591702613943
Note that the signature is different in example 3.
There is no & between "GTC" and "quantity=1".
base asset
refers to the asset that is thequantity
of a symbol.quote asset
refers to the asset that is theprice
of a symbol.
Symbol type:
- FUTURE
Contract type (contractType):
- PERPETUAL
Contract status(contractStatus,status):
- PENDING_TRADING
- TRADING
- PRE_SETTLE
- SETTLING
- CLOSE
Order status (status):
- NEW
- PARTIALLY_FILLED
- FILLED
- CANCELED
- REJECTED
- EXPIRED
Order types (orderTypes, type):
- LIMIT
- MARKET
- STOP
- STOP_MARKET
- TAKE_PROFIT
- TAKE_PROFIT_MARKET
- TRAILING_STOP_MARKET
Order side (side):
- BUY
- SELL
Position side (positionSide):
- BOTH
- LONG
- SHORT
Time in force (timeInForce):
- GTC - Good Till Cancel
- IOC - Immediate or Cancel
- FOK - Fill or Kill
- GTX - Good Till Crossing (Post Only)
Working Type (workingType)
- MARK_PRICE
- CONTRACT_PRICE
Response Type (newOrderRespType)
- ACK
- RESULT
Kline/Candlestick chart intervals:
m -> minutes; h -> hours; d -> days; w -> weeks; M -> months
- 1m
- 3m
- 5m
- 15m
- 30m
- 1h
- 2h
- 4h
- 6h
- 8h
- 12h
- 1d
- 3d
- 1w
- 1M
Rate limiters (rateLimitType)
REQUEST_WEIGHT
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 2400
}
ORDERS
{
"rateLimitType": "ORDERS",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 1200
}
- REQUEST_WEIGHT
- ORDERS
Rate limit intervals (interval)
- MINUTE
Filters define trading rules on a symbol or an exchange.
PRICE_FILTER
/exchangeInfo format:
{
"filterType": "PRICE_FILTER",
"minPrice": "0.00000100",
"maxPrice": "100000.00000000",
"tickSize": "0.00000100"
}
The
PRICE_FILTER
defines the price
rules for a symbol. There are 3 parts:minPrice
defines the minimumprice
/stopPrice
allowed; disabled onminPrice
== 0.maxPrice
defines the maximumprice
/stopPrice
allowed; disabled onmaxPrice
== 0.tickSize
defines the intervals that aprice
/stopPrice
can be increased/decreased by; disabled ontickSize
== 0.
Any of the above variables can be set to 0, which disables that rule in the
price filter
. In order to pass the price filter
, the following must be true for price
/stopPrice
of the enabled rules:price
>=minPrice
price
<=maxPrice
- (
price
-minPrice
) %tickSize
== 0
LOT_SIZE
/exchangeInfo format:
{
"filterType": "LOT_SIZE",
"minQty": "0.00100000",
"maxQty": "100000.00000000",
"stepSize": "0.00100000"
}
The
LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for a symbol. There are 3 parts:minQty
defines the minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
can be increased/decreased by.
In order to pass the
lot size
, the following must be true for quantity
:quantity
>=minQty
quantity
<=maxQty
- (
quantity
-minQty
) %stepSize
== 0
MARKET_LOT_SIZE
/exchangeInfo format:
{
"filterType": "MARKET_LOT_SIZE",
"minQty": "0.00100000",
"maxQty": "100000.00000000",
"stepSize": "0.00100000"
}
The
MARKET_LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for MARKET
orders on a symbol. There are 3 parts:minQty
defines the minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
can be increased/decreased by.
In order to pass the
market lot size
, the following must be true for quantity
:quantity
>=minQty
quantity
<=maxQty
- (
quantity
-minQty
) %stepSize
== 0
MAX_NUM_ORDERS
/exchangeInfo format:
{
"filterType": "MAX_NUM_ORDERS",
"limit": 200
}
The
MAX_NUM_ORDERS
filter defines the maximum number of orders an account is allowed to have open on a symbol.Note that both "algo" orders and normal orders are counted for this filter.
MAX_NUM_ALGO_ORDERS
/exchangeInfo format:
{
"filterType": "MAX_NUM_ALGO_ORDERS",
"limit": 100
}
The
MAX_NUM_ALGO_ORDERS
filter defines the maximum number of all kinds of algo orders an account is allowed to have open on a symbol.The algo orders include
STOP
, STOP_MARKET
, TAKE_PROFIT
, TAKE_PROFIT_MARKET
, and TRAILING_STOP_MARKET
orders.PERCENT_PRICE
/exchangeInfo format:
{
"filterType": "PERCENT_PRICE",
"multiplierUp": "1.1500",
"multiplierDown": "0.8500",
"multiplierDecimal": 4
}
The
PERCENT_PRICE
filter defines valid range for a price based on the mark price.In order to pass the
percent price
, the following must be true for price
:- BUY:
price
<=markPrice
*multiplierUp
- SELL:
price
>=markPrice
*multiplierDown
MIN_NOTIONAL
/exchangeInfo format:
{
"filterType": "MIN_NOTIONAL",
"notional": "1"
}
The
MIN_NOTIONAL
filter defines the minimum notional value allowed for an order on a symbol. An order's notional value is the price
* quantity
. Since MARKET
orders have no price, the mark price is used.Response:
{}
GET /fapi/v1/ping
Test connectivity to the Rest API.
Weight: 1
Parameters: NONE
Response:
{
"serverTime": 1499827319559
}
GET /fapi/v1/time
Test connectivity to the Rest API and get the current server time.
Weight: 1
Parameters: NONE
Response:
{
"exchangeFilters": [],
"rateLimits": [
{
"interval": "MINUTE",
"intervalNum": 1,
"limit": 2400,
"rateLimitType": "REQUEST_WEIGHT"
},
{
"interval": "MINUTE",
"intervalNum": 1,
"limit": 1200,
"rateLimitType": "ORDERS"
}
],
"serverTime": 1565613908500, // Ignore please. If you want to check current server time, please check via "GET /fapi/v1/time"
"assets": [ // assets information
{
"asset": "BUSD",
"marginAvailable": true, // whether the asset can be used as margin in Multi-Assets mode
"autoAssetExchange": 0 // auto-exchange threshold in Multi-Assets margin mode
},
{
"asset": "USDT",
"marginAvailable": true,
"autoAssetExchange": 0
},
{
"asset": "BTC",
"marginAvailable": false,
"autoAssetExchange": null
}
],
"symbols": [
{
"symbol": "DOGEUSDT",
"pair": "DOGEUSDT",
"contractType": "PERPETUAL",
"deliveryDate": 4133404800000,
"onboardDate": 1598252400000,
"status": "TRADING",
"maintMarginPercent": "2.5000", // ignore
"requiredMarginPercent": "5.0000", // ignore
"baseAsset": "BLZ",
"quoteAsset": "USDT",
"marginAsset": "USDT",
"pricePrecision": 5, // please do not use it as tickSize
"quantityPrecision": 0, // please do not use it as stepSize
"baseAssetPrecision": 8,
"quotePrecision": 8,
"underlyingType": "COIN",
"underlyingSubType": ["STORAGE"],
"settlePlan": 0,
"triggerProtect": "0.15", // threshold for algo order with "priceProtect"
"filters": [
{
"filterType": "PRICE_FILTER",
"maxPrice": "300",
"minPrice": "0.0001",
"tickSize": "0.0001"
},
{
"filterType": "LOT_SIZE",
"maxQty": "10000000",
"minQty": "1",
"stepSize": "1"
},
{
"filterType": "MARKET_LOT_SIZE",
"maxQty": "590119",
"minQty": "1",
"stepSize": "1"
},
{
"filterType": "MAX_NUM_ORDERS",
"limit": 200
},
{
"filterType": "MAX_NUM_ALGO_ORDERS",
"limit": 100
},
{
"filterType": "MIN_NOTIONAL",
"notional": "1",
},
{
"filterType": "PERCENT_PRICE",
"multiplierUp": "1.1500",
"multiplierDown": "0.8500",
"multiplierDecimal": 4
}
],
"OrderType": [
"LIMIT",
"MARKET",
"STOP",
"STOP_MARKET",
"TAKE_PROFIT",
"TAKE_PROFIT_MARKET",
"TRAILING_STOP_MARKET"
],
"timeInForce": [
"GTC",
"IOC",
"FOK",
"GTX"
],
"liquidationFee": "0.010000", // liquidation fee rate
"marketTakeBound": "0.30", // the max price difference rate( from mark price) a market order can make
}
],
"timezone": "UTC"
}
GET /fapi/v1/exchangeInfo
Current exchange trading rules and symbol information
Weight: 1
Parameters: NONE
Response:
{
"lastUpdateId": 1027024,
"E": 1589436922972, // Message output time
"T": 1589436922959, // Transaction time
"bids": [
[
"4.00000000", // PRICE
"431.00000000" // QTY
]
],
"asks": [
[
"4.00000200",
"12.00000000"
]
]
}
GET /fapi/v1/depth
Weight:
Adjusted based on the limit:
Limit | Weight |
---|---|
5, 10, 20, 50 | 2 |
100 | 5 |
500 | 10 |
1000 | 20 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; Valid limits:[5, 10, 20, 50, 100, 500, 1000] |
Response:
[
{
"id": 28457,
"price": "4.00000100",
"qty": "12.00000000",
"quoteQty": "48.00",
"time": 1499865549590,
"isBuyerMaker": true,
}
]
GET /fapi/v1/trades
Get recent market trades
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000. |
- Market trades means trades filled in the order book. Only market trades will be returned, which means the insurance fund trades and ADL trades won't be returned.
Response:
[
{
"id": 28457,
"price": "4.00000100",
"qty": "12.00000000",
"quoteQty": "8000.00",
"time": 1499865549590,
"isBuyerMaker": true,
}
]
GET /fapi/v1/historicalTrades
Get older market historical trades.
Weight: 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000. |
fromId | LONG | NO | TradeId to fetch from. Default gets most recent trades. |
- Market trades means trades filled in the order book. Only market trades will be returned, which means the insurance fund trades and ADL trades won't be returned.
Response:
[
{
"a": 26129, // Aggregate tradeId
"p": "0.01633102", // Price
"q": "4.70443515", // Quantity
"f": 27781, // First tradeId
"l": 27781, // Last tradeId
"T": 1498793709153, // Timestamp
"m": true, // Was the buyer the maker?
}
]
GET /fapi/v1/aggTrades
Get compressed, aggregate market trades. Market trades that fill at the time, from the same order, with the same price will have the quantity aggregated.
Weight: 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
fromId | LONG | NO | ID to get aggregate trades from INCLUSIVE. |
startTime | LONG | NO | Timestamp in ms to get aggregate trades from INCLUSIVE. |
endTime | LONG | NO | Timestamp in ms to get aggregate trades until INCLUSIVE. |
limit | INT | NO | Default 500; max 1000. |
- If both startTime and endTime are sent, time between startTime and endTime must be less than 1 hour.
- If fromId, startTime, and endTime are not sent, the most recent aggregate trades will be returned.
- Only market trades will be aggregated and returned, which means the insurance fund trades and ADL trades won't be aggregated.
Response:
[
[
1499040000000, // Open time
"0.01634790", // Open
"0.80000000", // High
"0.01575800", // Low
"0.01577100", // Close
"148976.11427815", // Volume
1499644799999, // Close time
"2434.19055334", // Quote asset volume
308, // Number of trades
"1756.87402397", // Taker buy base asset volume
"28.46694368", // Taker buy quote asset volume
"17928899.62484339" // Ignore.
]
]
GET /fapi/v1/klines
Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
Weight: based on parameter
LIMIT
LIMIT | weight |
---|---|
[1,100) |