diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..8a9901d Binary files /dev/null and b/.DS_Store differ diff --git a/V3(Recommended)/.DS_Store b/V3(Recommended)/.DS_Store new file mode 100644 index 0000000..86a7ccf Binary files /dev/null and b/V3(Recommended)/.DS_Store differ diff --git a/V3(Recommended)/EN/aster-finance-prediction-api-v3.md b/V3(Recommended)/EN/aster-finance-prediction-api-v3.md new file mode 100644 index 0000000..5b5b8e3 --- /dev/null +++ b/V3(Recommended)/EN/aster-finance-prediction-api-v3.md @@ -0,0 +1,2939 @@ +# Prediction API Overview + +* This document lists the base URL for the API endpoints: [**https://papi.asterdex.com**](https://papi.asterdex.com) +* All API responses are in JSON format. + +## API Agent Address settings + +* Many endpoints require an API Key to access. +* When setting the Agent Address, for security reasons it is recommended to set an IP access whitelist. +* **Never reveal your Agent Address/private key to anyone.** + +If an API Key is accidentally exposed, immediately delete that Key and generate a new one. + +### Attention +* TESTUSDT or any other symbols starting with TEST are symbols used for Aster's INTERNAL TESTING ONLY. Please DO NOT trade on these symbols starting with TEST. Aster does not hold any accountability for loss of funds due to trading on these symbols. However, if you run into issues, you may contact support about this any time, we will try to help you recover your funds. + +### V3 Nonce Mechanism + +* **Nonce** is used to validate the **validity, uniqueness, and replay-protection** of requests. Clients should use the **current timestamp (microsecond precision)** as the nonce, and the difference from server time must not exceed **10 seconds**. + +* Request processing flow: + + 1. If the nonce **has already been used** → rejected as a **duplicate request** + 2. Otherwise, the system checks whether it is **too old** + +* To improve performance, each user maintains only the **most recent 100 nonces**: + + * If the list is full and the new nonce is **smaller than the current minimum** → rejected as **expired** + * Otherwise, the **oldest nonce is removed** and the new one is added + +* Overall effect: **prevents duplicates and stale requests, retaining only recent valid requests** + +### HTTP return codes + +* HTTP `4XX` status codes are used to indicate errors in the request content, behavior, or format. The problem lies with the requester. +* HTTP `403` status code indicates a violation of WAF restrictions (Web Application Firewall). +* HTTP `429` error code indicates a warning that the access frequency limit has been exceeded and the IP is about to be blocked. +* HTTP `418` indicates that after receiving a 429 you continued to access, so the IP has been blocked. +* HTTP `5XX` error codes are used to indicate issues on the Aster service side. + +### API error codes + +* When using the endpoint `/api/v3`, any endpoint may throw exceptions; + +The API error codes are returned in the following format: + +```javascript +{ + "code": -1121, + "msg": "Invalid symbol." +} +``` + +### Basic information about the endpoint + +* Endpoints with the `GET` method must send parameters in the `query string`. +* For `POST`, `PUT`, and `DELETE` endpoints, parameters can be sent in the `query string` with content type `application/x-www-form-urlencoded` , or in the `request body`. +* The order of parameters is not required. + +--- + +## Access restrictions + +### Basic information on access restrictions + +* The `rateLimits` array in `/api/v3/prediction/exchangeInfo` contains objects related to REQUEST\_WEIGHT and ORDERS rate limits for trading. These are further defined in the `enum definitions` section under `rateLimitType`. +* A 429 will be returned when any of the rate limits are violated. + +### IP access limits + +* Each request will include a header named `X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)` that contains the used weight of all requests from the current IP. +* Each endpoint has a corresponding weight, and some endpoints may have different weights depending on their parameters. The more resources an endpoint consumes, the higher its weight will be. +* Upon receiving a 429, you are responsible for stopping requests and must not abuse the API. +* **If you continue to violate access limits after receiving a 429, your IP will be banned and you will receive a 418 error code.** +* Repeated violations of the limits will result in progressively longer bans, **from a minimum of 2 minutes up to a maximum of 3 days**. +* The `Retry-After` header will be sent with responses bearing 418 or 429, and will give the wait time **in seconds** (if 429\) to avoid the ban, or, if 418, until the ban ends. +* **Access restrictions are based on IP, not API Key** + +You are advised to use WebSocket messages to obtain the corresponding data as much as possible to reduce the load and rate-limit pressure from requests. + +### Order rate limits + +* Each successful order response will include a `X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)` header containing the number of order limit units currently used by the account. +* When the number of orders exceeds the limit, you will receive a response with status 429 but without the `Retry-After` header. Please check the order rate limits in `GET api/v3/exchangeInfo` (rateLimitType \= ORDERS) and wait until the ban period ends. +* Rejected or unsuccessful orders are not guaranteed to include the above header in the response. +* **Order placement rate limits are counted per account.** + +### WebSocket connection limits + +* The WebSocket server accepts a maximum of 5 messages per second. Messages include: + * PING frame + * PONG frame + * Messages in JSON format, such as subscribe and unsubscribe. +* If a user sends messages that exceed the limit, the connection will be terminated. IPs that are repeatedly disconnected may be blocked by the server. +* A single connection can subscribe to up to **1024** Streams. + +--- + +## API authentication types + +* Each API has its own authentication type, which determines what kind of authentication should be performed when accessing it. +* The authentication type will be indicated next to each endpoint name in this document; if not specifically stated, it defaults to `NONE`. + +| Security Type | Description | +| ------------- | ----------------------------------------- | +| NONE | API that does not require authentication | +| PREDICTION_TRADE | A valid signer and signature are required | +| USER_DATA | A valid signer and signature are required | +| USER_STREAM | A valid signer and signature are required | +| MARKET_DATA | API that does not require authentication | + +--- + +## SIGNED (TRADE AND USER\_DATA) Endpoint security +* Security Type: PREDICTION_TRADE, USER_DATA, USER_STREAM + + +## Example of POST /api/v3/order + + +#### The following parameters are API registration details. The values for user, signer, and privateKey are for demonstration purposes only (the privateKey corresponds to the signer). + +| Key | Value | Desc +| ---------- | ------------------------------------------------------------------ | ---------- | +| user | 0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e |Login wallet address | +| signer | 0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0 |[Click Here](https://www.asterdex.com/en/api-wallet) | +| privateKey | 0x4fd0a42218f3eae43a6ce26d22544e986139a01e5b34a62db53757ffca81bae1 |[Click Here](https://www.asterdex.com/en/api-wallet) | + +#### The nonce parameter is the current system time in microseconds. If it exceeds the system time or lags behind it by more than 10 seconds, the request is considered invalid. +```python +#python +nonce = math.trunc(time.time()*1000000) +print(nonce) +#1748310859508867 +``` +```java +#python +//java +Instant now = Instant.now(); +long microsecond = now.getEpochSecond() * 1000000 + now.getNano() / 1000; +``` + +#### Example: Post an order (using Python as an example). + + +```python +import time +import urllib +import threading + +import requests +from eth_account.messages import encode_structured_data +from eth_account import Account + +typed_data = { + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "version", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + {"name": "verifyingContract", "type": "address"} + ], + "Message": [ + { "name": "msg", "type": "string" } + ] + }, + "primaryType": "Message", + "domain": { + "name": "AsterSignTransaction", + "version": "1", + "chainId": 1666, + "verifyingContract": "0x0000000000000000000000000000000000000000" + }, + "message": { + "msg": "$msg" + } +} + +headers = { + 'Content-Type': 'application/x-www-form-urlencoded', + 'User-Agent': 'PythonApp/1.0' +} +host = 'https://sapi.asterdex.com' + +# config your user and agent info here +user = '*' +signer = '*' +private_key = "*" + +place_order = {"url":"/api/v3/order","method":"POST","params":{"symbol": "ASTERUSDT", "type": "LIMIT", "side": "BUY", + "timeInForce": "GTC", "quantity": "100", "price": "0.4"}} +_last_ms = 0 +_i = 0 +_nonce_lock = threading.Lock() + +def get_nonce(): + global _last_ms, _i + with _nonce_lock: + now_ms = int(time.time()) + + if now_ms == _last_ms: + _i += 1 + else: + _last_ms = now_ms + _i = 0 + + return now_ms * 1_000_000 + _i + +def send_by_url(api) : + my_dict = api['params'] + url = host + api['url'] + + my_dict['nonce'] = str(get_nonce()) + my_dict['signer'] = signer + + param = urllib.parse.urlencode(my_dict) + print(param) + typed_data['message']['msg'] = param + message = encode_structured_data(typed_data) + signed = Account.sign_message(message, private_key=private_key) + + url = url + '?' + param + '&signature=' + signed.signature.hex() + print(url) + res = requests.post(url, headers=headers) + + print(res.text) + +def send_by_body(api) : + my_dict = api['params'] + url = host +api['url'] + my_dict['nonce'] = str(get_nonce()) + my_dict['signer'] = signer + + param = urllib.parse.urlencode(my_dict) + typed_data['message']['msg'] = param + message = encode_structured_data(typed_data) + + signed = Account.sign_message(message, private_key=private_key) + print(signed.signature.hex()) + + my_dict['signature'] = signed.signature.hex() + + print(my_dict) + res = requests.post(url, data=my_dict, headers=headers) + + print(res.text) + +if __name__ == '__main__': + send_by_url(place_order) + # send_by_body(place_order) + +``` + +## Public API parameters + +### Terminology + +The terminology in this section applies throughout the document. New users are encouraged to read it carefully for better understanding. + +* `base asset` refers to the asset being traded in a trading pair, i.e., the asset name written first; for example, in `BTCUSDT`, `BTC` is the `base asset`. +* `quote asset` refers to the pricing asset of a trading pair, i.e., the asset name written at the latter part; for example, in `BTCUSDT`, `USDT` is the `quote asset`. + +### Enumeration definition + +**Trading pair status (status):** + +* TRADING \- after trade + +**Trading pair type:** + +* PREDICTION \- prediction + +**Order status (status):** + +| Status | Description | +| :---- | :---- | +| NEW | Order accepted by the matching engine | +| PARTIALLY\_FILLED | Part of the order was filled | +| FILLED | The order was fully filled | +| CANCELED | The user canceled the order | +| REJECTED | The order was not accepted by the matching engine and was not processed | +| EXPIRED | Order canceled by the trading engine, for example: Limit FOK order not filled, Market order not fully filled, orders canceled during exchange maintenance | + +**Order types (orderTypes, type):** + +* LIMIT \- Limit Order +* MARKET \- Market Order + +**Order response type (newOrderRespType):** + +* ACK +* RESULT +* FULL + +**Order direction (direction side):** + +* BUY \- Buy +* SELL \- Sell + +**Valid types (timeInForce):** + +This defines how long an order can remain valid before expiring. + +| Status | Description | +| :---- | :---- | +| GTC (Good 'Til Canceled) | The order remains active until it is fully executed or manually canceled. | +| IOC (Immediate or Cancel) | The order will execute immediately for any amount available. Any unfilled portion is automatically canceled. | +| FOK (Fill or Kill) | The order must be fully executed immediately. If it cannot be filled in full, it is canceled right away. | +| GTX (Good till crossing, Post only) | The post-only limit order will only be placed if it can be added as a maker order and not as a taker order. | + +**K-line interval:** + +m (minutes), h (hours), d (days), w (weeks), M (months) + +* 1s (added) +* 1m +* 3m +* 5m +* 15m +* 30m +* 1h +* 2h +* 4h +* 6h +* 8h +* 12h +* 1d +* 3d +* 1w +* 1M + +**Rate limit type (rateLimitType)** + +REQUEST\_WEIGHT + +```json + { + "rateLimitType": "REQUEST_WEIGHT", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 1200 + } +``` + +ORDERS + +```json + { + "rateLimitType": "ORDERS", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 100 + } +``` + +* REQUEST\_WEIGHT \- The maximum sum of request weights allowed within a unit time + +* ORDERS \- Order placement frequency limit per time unit + +**Interval restriction (interval)** + +* MINUTE \- Minute + +--- + +## Filters + +Filters, i.e. Filter, define a set of trading rules. There are two types: filters for trading pairs `symbol filters`, and filters for the entire exchange `exchange filters` (not supported yet) + +### Trading pair filters + +#### PRICE\_FILTER Price filter + +**Format in the /exchangeInfo response:** + +```javascript + { + "minPrice": "0.0001", + "maxPrice": "0.9999", + "filterType": "PRICE_FILTER", + "tickSize": "0.01" + } +``` + +The `Price Filter` checks the validity of the `price` parameter in an order. It consists of the following three parts: + +* `minPrice` defines the minimum allowed value for `price`/`stopPrice`. +* `maxPrice` defines the maximum allowed value for `price`/`stopPrice`. +* `tickSize` defines the step interval for `price`/`stopPrice`, meaning the price must equal minPrice plus an integer multiple of tickSize. + +Each of the above items can be 0; when 0 it means that item is not constrained. + +The logical pseudocode is as follows: + +* `price` \>= `minPrice` +* `price` \<= `maxPrice` +* (`price`\-`minPrice`) % `tickSize` \== 0 + +#### PERCENT\_PRICE price amplitude filter + +**Format in the /exchangeInfo response:** + +```javascript + { + "multiplierDown": "0.9500", + "multiplierUp": "1.0500", + "multiplierDecimal": "4", + "filterType": "PERCENT_PRICE" + } +``` + +The `PERCENT_PRICE` filter defines the valid range of prices based on the index price. + +For the "price percentage" to apply, the "price" must meet the following conditions: + +* `price` \<=`indexPrice` \*`multiplierUp` +* `price`\> \=`indexPrice` \*`multiplierDown` + +#### LOT\_SIZE order size + +**Format in the /exchangeInfo response:** + +```javascript + { + "stepSize": "0.00100000", + "filterType": "LOT_SIZE", + "maxQty": "100000.00000000", + "minQty": "0.00100000" + } +``` + +Lots is an auction term. The `LOT_SIZE` filter validates the `quantity` (i.e., the amount) parameter in orders. It consists of three parts: + +* `minQty` indicates the minimum allowed value for `quantity`. +* `maxQty` denotes the maximum allowed value for `quantity`. +* `stepSize` denotes the allowed step increment for `quantity`. + +The logical pseudocode is as follows: + +* `quantity` \>= `minQty` +* `quantity` \<= `maxQty` +* (`quantity`\-`minQty`) % `stepSize` \== 0 + +#### MARKET\_LOT\_SIZE \- Market order size + +\***/exchangeInfo response format:** + +```javascript + { + "stepSize": "0.00100000", + "filterType": "MARKET_LOT_SIZE" + "maxQty": "100000.00000000", + "minQty": "0.00100000" + } +``` + +The `MARKET_LOT_SIZE` filter defines the `quantity` (i.e., the "lots" in an auction) rules for `MARKET` orders on a trading pair. There are three parts: + +* `minQty` defines the minimum allowed `quantity`. +* `maxQty` defines the maximum allowed quantity. +* `stepSize` defines the increments by which the quantity can be increased or decreased. + +In order to comply with the `market lot size`, the `quantity` must satisfy the following conditions: + +* `quantity` \>= `minQty` +* `quantity` \<= `maxQty` +* (`quantity`\-`minQty`) % `stepSize` \== 0 + +#### predictionEvents \- Prediction Events + +**Format in the /exchangeInfo response:** + +```javascript +"predictionEvents": [ + { + "eventName": "ETH_UP_DOWN_7D", // Prediction event name + "oracleSymbol": "ETHUSDT", // Predicted symbol + "predictionType": "UP_DOWN", // Prediction type + "sides": [ + "UP", + "DOWN" + ], // Prediction directions + "period": "10080M", // Prediction period in minutes + "startTime": 1778476080000, // Event start time + "endTime": 1780376880000, // Event end time + "status": "LIVE", // Event status + "currentRoundId": 3, // Current round ID + "orderTypes": [ + "LIMIT", + "MARKET" + ], // Supported order types + "timeInForce": [ + "GTC", + "IOC", + "FOK", + "GTX" + ], // Supported TIF values + "liveRound":{ + "marketName": "USD1_UP_DOWN_5M_1778483280", // Prediction market name + "symbols": [ + "USD1_UP_DOWN_5M_1778483280_YUSDT", + "USD1_UP_DOWN_5M_1778483280_NUSDT" + ], // Two symbols for the market; Y = up, N = down + "assets": [ + "USD1_UP_DOWN_5M_1778483280_Y", + "USD1_UP_DOWN_5M_1778483280_N" + ], // Two assets for the market; Y = up, N = down + "roundId": 2, // Round ID + "tradingStartTime": 1778482970000, // Trading start time + "tradingEndTime": 1778483520000, // Trading end time + "windowStartTime": 1778483280000, // Window start time + "windowEndTime": 1778483580000, // Window end time + "roundStatus": "SETTLED", // Market status + "openPrice": "0.99920000", // Opening price + "endPrice": "0.99910000", // Ending price + "winAsset": "USD1_UP_DOWN_5M_1778483280_N", // Winning asset: Y if up, N if down + "settleTime": 1778483582057, // Settlement time + "settleHash": "0x3bc0aff52472dafd4b70d3423386a2dabf675fe7cd604e92391e2a4702cf0980" // On-chain settlement hash + }, + "rounds": [ + { + "marketName": "USD1_UP_DOWN_5M_1778483280", // Prediction market name + "symbols": [ + "USD1_UP_DOWN_5M_1778483280_YUSDT", + "USD1_UP_DOWN_5M_1778483280_NUSDT" + ], // Two symbols for the market; Y = up, N = down + "assets": [ + "USD1_UP_DOWN_5M_1778483280_Y", + "USD1_UP_DOWN_5M_1778483280_N" + ], // Two assets for the market; Y = up, N = down + "roundId": 2, // Round ID + "tradingStartTime": 1778482970000, // Trading start time + "tradingEndTime": 1778483520000, // Trading end time + "windowStartTime": 1778483280000, // Window start time + "windowEndTime": 1778483580000, // Window end time + "roundStatus": "SETTLED", // Market status + "openPrice": "0.99920000", // Opening price + "endPrice": "0.99910000", // Ending price + "winAsset": "USD1_UP_DOWN_5M_1778483280_N", // Winning asset: Y if up, N if down + "settleTime": 1778483582057, // Settlement time + "settleHash": "0x3bc0aff52472dafd4b70d3423386a2dabf675fe7cd604e92391e2a4702cf0980" // On-chain settlement hash + } + ] + } +] +``` + +`status` is the event status: + +| Status | Description | +| :---- | :---- | +| `LIVE` | Running | +| `CLOSED` | Closed | +| `INVALID` | Invalid | + +`roundStatus` is the market status: + +| RoundStatus | Description | +| :---- | :---- | +| `PREMARKET` | Pre-market ready (trading available in advance) | +| `TRADING` | Market is open for trading | +| `SETTLED` | Market has been settled | + +* After settlement, the market will be automatically delisted after a period (24H). Delisted markets are no longer displayed. +* For events with `status` of `CLOSED` or `INVALID`, only `reduceOnly` Market Sell orders can be placed. + +# Market data API + +## Noop + +> **Response:** + +```javascript +{ + "code": 200, + "msg": "success" +} +``` + +``POST /api/v3/noop`` + +By using this request, it is possible to efficiently cancel previously sent transactions that are still in the queue and have not completed the on chain operation (Nonce should be equal to this request，no guarantee of success +) + +**Weight:** +1 + +## Test server connectivity + +**Response** + +```javascript +{} +``` + +`GET /api/v3/ping` + +Test whether the REST API can be reached. + +**Weight:** 1 + +**Parameters:** NONE + +## Get server time + +**Response** + +```javascript +{ + "serverTime": 1499827319559 +} +``` + +`GET /api/v3/time` + +Test if the REST API can be reached and retrieve the server time. + +**Weight:** 1 + +**Parameters:** NONE + +## Trading specification information + +**Response** + +```javascript +{ + "timezone": "UTC", + "serverTime": 1756197279679, + "rateLimits": [{ + "rateLimitType": "REQUEST_WEIGHT", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 6000 + }, + { + "rateLimitType": "ORDERS", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 6000 + }, + { + "rateLimitType": "ORDERS", + "interval": "SECOND", + "intervalNum": 10, + "limit": 300 + } + ], + "exchangeFilters": [], + "assets": [{ + "asset": "USD" + }, { + "asset": "USDT" + }, + { + "asset": "BNB" + } + ], + "symbols": [{ + "status": "TRADING", + "baseAsset": "BNB", + "quoteAsset": "USDT", + "pricePrecision": 8, + "quantityPrecision": 8, + "baseAssetPrecision": 8, + "quotePrecision": 8, + "filters": [{ + "minPrice": "0.0001", + "maxPrice": "0.9999", + "filterType": "PRICE_FILTER", + "tickSize": "0.01000000" + }, + { + "stepSize": "0.00100000", + "filterType": "LOT_SIZE", + "maxQty": "1000", + "minQty": "1" + }, + { + "stepSize": "0.00100000", + "filterType": "MARKET_LOT_SIZE", + "maxQty": "900000", + "minQty": "0.00100000" + }, + { + "limit": 200, + "filterType": "MAX_NUM_ORDERS" + }, + { + "minNotional": "5", + "filterType": "MIN_NOTIONAL" + }, + { + "maxNotional": "100", + "filterType": "MAX_NOTIONAL" + }, + { + "maxNotional": "100", + "minNotional": "5", + "avgPriceMins": 5, + "applyMinToMarket": true, + "filterType": "NOTIONAL", + "applyMaxToMarket": true + }, + { + "multiplierDown": "0", + "multiplierUp": "5", + "multiplierDecimal": "0", + "filterType": "PERCENT_PRICE" + }, + { + "bidMultiplierUp": "5", + "askMultiplierUp": "5", + "bidMultiplierDown": "0", + "avgPriceMins": 5, + "multiplierDecimal": "0", + "filterType": "PERCENT_PRICE_BY_SIDE", + "askMultiplierDown": "0" + } + ], + "orderTypes": [ + "LIMIT", + "MARKET" + ], + "timeInForce": [ + "GTC", + "IOC", + "FOK", + "GTX" + ], + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "ocoAllowed": false + }] +} +``` + +`GET /api/v3/prediction/exchangeInfo` + +Retrieve trading rules and trading pair information. + +**Weight:** 1 + +**Parameters:** None + +## Depth information + +**Response** + +```javascript +{ + "lastUpdateId": 1027024, + "E":1589436922972, // Message output time + "T":1589436922959, // Transaction time + "bids": [ + [ + "4.00000000", // PRICE + "431.00000000" // QTY + ] + ], + "asks": [ + [ + "4.00000200", + "12.00000000" + ] + ] +} +``` + +`GET /api/v3/depth` + +**Weight:** + +Based on limit adjustments: + +| Limitations | Weight | +| :---- | :---- | +| 5, 10, 20, 50 | 2 | +| 100 | 5 | +| 500 | 10 | +| 1000 | 20 | + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| limit | INT | NO | Default 100\. Optional values: \[5, 10, 20, 50, 100, 500, 1000\] | + +## Recent trades list + +**Response** + +```javascript +[ + { + "id": 657, + "price": "1.01000000", + "qty": "5.00000000", + "baseQty": "4.95049505", + "time": 1755156533943, + "isBuyerMaker": false + } +] +``` + +`GET /api/v3/trades` + +Get recent trades + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| limit | INT | NO | Default 500; maximum 1000 | + +## Query historical trades (MARKET\_DATA) + +**Response** + +```javascript +[ + { + "id": 1140, + "price": "1.10000000", + "qty": "7.27200000", + "baseQty": "6.61090909", + "time": 1756094288700, + "isBuyerMaker": false + } +] +``` + +`GET /api/v3/historicalTrades` + +Retrieve historical trades + +**Weight:** 20 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| limit | INT | NO | Default 500; maximum 1000\. | +| fromId | LONG | NO | Return starting from which trade id. Defaults to returning the most recent trade records. | + +## Recent trades (aggregated) + +**Response** + +```javascript +[ + { + "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 /api/v3/aggTrades` + +The difference between aggregated trades and individual trades is that trades with the same price, same side, and same time are combined into a single entry. + +**Weight:** 20 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| fromId | LONG | NO | Return results starting from the trade ID that includes fromId | +| startTime | LONG | NO | Return results starting from trades after that time | +| endTime | LONG | NO | Return the trade records up to that moment | +| limit | INT | NO | Default 500; maximum 1000\. | + +* If you send startTime and endTime, the interval must be less than one hour. +* If no filter parameters (fromId, startTime, endTime) are sent, the most recent trade records are returned by default + +## K-line data + +**Response** + +```javascript +[ + [ + 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 + ] +] +``` + +`GET /api/v3/klines` + +Each K-line represents a trading pair. The open time of each K-line can be regarded as a unique ID. + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| interval | ENUM | YES | See the enumeration definition: K-line interval | +| startTime | LONG | NO | | +| endTime | LONG | NO | | +| limit | INT | NO | Default 500; maximum 1500\. | + +* If startTime and endTime are not sent, the most recent trades are returned by default + +## 24h price change + +**Response** + +```javascript +{ + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", //symbol + "priceChange": "-94.99999800", //price change + "priceChangePercent": "-95.960", //price change percent + "weightedAvgPrice": "0.29628482", //weighted avgPrice + "prevClosePrice": "3.89000000", //prev close price + "lastPrice": "4.00000200", //last price + "lastQty": "200.00000000", //last qty + "bidPrice": "0.4999", //first bid price + "bidQty": "431.00", //first bid qty + "askPrice": "0.5001", //first ask price + "askQty": "9.00", //first ask qty + "openPrice": "99.00000000", //open price + "highPrice": "100.00000000", //high price + "lowPrice": "0.10000000", //low price + "volume": "8913.30000000", //volume + "quoteVolume": "15.30000000", //quote volume + "openTime": 1499783499040, //open time + "closeTime": 1499869899040, //close time + "firstId": 28385, // first id + "lastId": 28460, // last id + "count": 76, // count + "baseAsset": "BTC", //base asset + "quoteAsset": "USDT" //quote asset +} +``` + +`GET /api/v3/ticker/24hr` + +24-hour rolling window price change data. Please note that omitting the symbol parameter will return data for all trading pairs; in that case the returned data is an example array for the respective pairs, which is not only large in volume but also has a very high weight. + +**Weight:** 1 \= single trading pair; **40** \= When the trading pair parameter is missing (returns all trading pairs) + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | | + +* Please note that omitting the symbol parameter will return data for all trading pairs + +## Latest price + +**Response** + +```javascript +{ + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "price": "1.30000000", + "time": 1649666690902 +} +``` + +OR + +```javascript +[ + { + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "price": "1.30000000", + "time": 1649666690902 + } +] +``` + +`GET /api/v3/ticker/price` + +Get the latest price for a trading pair + +**Weight:** 1 \= Single trading pair; **2** \= No symbol parameter (returns all pairs) + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | | + +* If no trading pair parameter is sent, information for all trading pairs will be returned + +## Current best order + +**Response** + +```javascript +{ + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "bidPrice": "0.4999", + "bidQty": "431.00", + "askPrice": "0.5001", + "askQty": "9.00" + "time": 1589437530011 // Timestamp +} +``` + +OR + +```javascript +[ + { + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "bidPrice": "0.4999", + "bidQty": "431.00", + "askPrice": "0.5001", + "askQty": "9.00", + "time": 1589437530011 // Timestamp + } +] +``` + +`GET /api/v3/ticker/bookTicker` + +Return the current best orders (highest bid, lowest ask) + +**Weight:** 1 \= Single trading pair; **2** \= No symbol parameter (returns all pairs) + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | | + +* If no trading pair parameter is sent, information for all trading pairs will be returned + +## Get symbol fees + +**Response** + +```javascript +{ + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "makerCommissionRate": "0.000200", + "takerCommissionRate": "0.000700", + "settleCommissionRate": "0.000100" +} +``` + +`GET /api/v3/commissionRate` + +Get symbol fees + +**Weight:** 20 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | + +# Spot account and trading API + +## Place order (TRADE) + +**Response ACK:** + +```javascript +{ + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "orderId": 28, + "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", + "updateTime": 1507725176595, + "price": "0.00000000", + "avgPrice": "0.0000000000000000", + "origQty": "10.00000000", + "cumQty": "0", + "executedQty": "10.00000000", + "cumQuote": "10.00000000", + "status": "FILLED", + "timeInForce": "GTC", + "stopPrice": "0", + "origType": "LIMIT", + "type": "LIMIT", + "side": "SELL", +} +``` + +`POST /api/v3/order` + +Send order + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| side | ENUM | YES | See enum definition: Order direction | +| type | ENUM | YES | See enumeration definition: Order type | +| timeInForce | ENUM | NO | See enum definition: Time in force | +| quantity | DECIMAL | NO | | +| quoteOrderQty | DECIMAL | NO | | +| price | DECIMAL | NO | | +| newClientOrderId | STRING | NO | Client-customized unique order ID. If not provided, one will be generated automatically. | +| stopPrice | DECIMAL | NO | Only STOP, STOP\_MARKET, TAKE\_PROFIT, TAKE\_PROFIT\_MARKET require this parameter | + +Depending on the order `type`, certain parameters are mandatory: + +| Type | Mandatory parameters | +| :---- | :---- | +| LIMIT | timeInForce, quantity, price | +| MARKET | quantity or quoteOrderQty | +| STOP and TAKE\_PROFIT | quantity, price, stopPrice | +| STOP\_MARKET and TAKE\_PROFIT\_MARKET | quantity, stopPrice | + +Other information: + +* Place a `MARKET` `SELL` market order; the user controls the amount of base assets to sell with the market order via `QUANTITY`. + * For example, when placing a `MARKET` `SELL` market order on the `BTC_UP_DOWN_5M_1778483280_YUSDT` pair, use `QUANTITY` to let the user specify how much BTC they want to sell. +* For a `MARKET` `BUY` market order, the user controls how much of the quote asset they want to spend with `quoteOrderQty`; `QUANTITY` will be calculated by the system based on market liquidity. For example, when placing a `MARKET` `BUY` market order on the `BTC_UP_DOWN_5M_1778483280_YUSDT` pair, use `quoteOrderQty` to let the user choose how much USDT to use to buy BTC. +* A `MARKET` order using `quoteOrderQty` will not violate the `LOT_SIZE` limit rules; the order will be executed as closely as possible to the given `quoteOrderQty`. +* Unless a previous order has already been filled, orders set with the same `newClientOrderId` will be rejected. + +## Cancel order (TRADE) + +**Response** + +```javascript +{ + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "orderId": 28, + "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", + "updateTime": 1507725176595, + "price": "0.00000000", + "avgPrice": "0.0000000000000000", + "origQty": "10.00000000", + "cumQty": "0", + "executedQty": "10.00000000", + "cumQuote": "10.00000000", + "status": "CANCELED", + "timeInForce": "GTC", + "stopPrice": "0", + "origType": "LIMIT", + "type": "LIMIT", + "side": "SELL", +} +``` + +`DELETE /api/v3/order` + +Cancel active orders + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| orderId | LONG | NO | | +| origClientOrderId | STRING | NO | | + +At least one of `orderId` or `origClientOrderId` must be sent. + +## Query order (USER\_DATA) + +**Response** + +```javascript +{ + "orderId": 38, + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "status": "FILLED", + "clientOrderId": "afMd4GBQyHkHpGWdiy34Li", + "price": "20", + "avgPrice": "12.0000000000000000", + "origQty": "10", + "executedQty": "10", + "cumQuote": "120", + "timeInForce": "GTC", + "type": "LIMIT", + "side": "BUY", + "stopPrice": "0", + "origType": "LIMIT", + "time": 1649913186270, + "updateTime": 1649913186297 +} +``` + +`GET /api/v3/order` + +Query order status + +* Please note that orders meeting the following conditions will not be returned: + * The final status of the order is `CANCELED` or `EXPIRED`, **and** + * The order has no trade records, **and** + * Order creation time \+ 7 days \< current time + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| orderId | LONG | NO | | +| origClientOrderId | STRING | NO | | + +Note: + +* You must send at least one of `orderId` or `origClientOrderId`. + +## Query Current Open Order (USER\_DATA) + +**Response** + +```javascript +{ + "orderId": 38, + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "status": "NEW", + "clientOrderId": "afMd4GBQyHkHpGWdiy34Li", + "price": "20", + "avgPrice": "12.0000000000000000", + "origQty": "10", + "executedQty": "10", + "cumQuote": "120", + "timeInForce": "GTC", + "type": "LIMIT", + "side": "BUY", + "stopPrice": "0", + "origType": "LIMIT", + "time": 1649913186270, + "updateTime": 1649913186297 +} +``` + +`GET /api/v3/openOrder` + +Query current open order status. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| orderId | LONG | NO | | +| origClientOrderId | STRING | NO | | + +Note: + +* You must send at least one of `orderId` or `origClientOrderId`. + +## Current open orders (USER\_DATA) + +**Response** + +```javascript +[ + { + "orderId": 349661, + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "status": "NEW", + "clientOrderId": "LzypgiMwkf3TQ8wwvLo8RA", + "price": "1.10000000", + "avgPrice": "0.0000000000000000", + "origQty": "5", + "executedQty": "0", + "cumQuote": "0", + "timeInForce": "GTC", + "type": "LIMIT", + "side": "BUY", + "stopPrice": "0", + "origType": "LIMIT", + "time": 1756252940207, + "updateTime": 1756252940207, + } +] +``` + +`GET /api/v3/openOrders` + +Retrieve all current open orders for trading pairs. Use calls without a trading pair parameter with caution. + +**Weight:** + +* With symbol ***1*** +* Without ***40*** + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | | + +* If the symbol parameter is not provided, it will return the order books for all trading pairs. + +## Cancel All Open Orders (TRADE) + +> **Response** + +```javascript +{ + "code": 200, + "msg": "The operation of cancel all open order is done." +} +``` + +`` +DEL /api/v3/allOpenOrders `` + +**Weight:** +- ***1*** + +**Parameters:** + +Name | Type | Mandatory | Description +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +orderIdList | STRING | NO | orderid array string +origClientOrderIdList | STRING | NO | clientOrderId array string + + +## Query all orders (USER\_DATA) + +**Response** + +```javascript +[ + { + "orderId": 349661, + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "status": "NEW", + "clientOrderId": "LzypgiMwkf3TQ8wwvLo8RA", + "price": "1.10000000", + "avgPrice": "0.0000000000000000", + "origQty": "5", + "executedQty": "0", + "cumQuote": "0", + "timeInForce": "GTC", + "type": "LIMIT", + "side": "BUY", + "stopPrice": "0", + "origType": "LIMIT", + "time": 1756252940207, + "updateTime": 1756252940207, + } +] +``` + +`GET /api/v3/allOrders` + +Retrieve all account orders; active, canceled, or completed. + +* Please note that orders meeting the following conditions will not be returned: + * Order creation time \+ 7 days \< current time + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | | +| orderId | LONG | NO | | +| startTime | LONG | NO | | +| endTime | LONG | NO | | +| limit | INT | NO | Default 500; maximum 1000 | + +* The maximum query time range must not exceed 7 days. +* By default, query data is from the last 7 days. + + +`` +GET /api/v3/transactionHistory`` +> **Response** + +```javascript +[ + { + "tranId": 1759115482304540227, + "tradeId": null, + "asset": "ASTER", + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "balanceDelta": "-500.00000000", + "balanceInfo": "TRADE_SOURCE", + "time": 1759115482000, + "type": "TRADE_SOURCE" + } +] +``` + +Query transaction records + +**Weight:** +30 + +**Parameters:** + +| Name | Type | Is it required? | Description | +------------ | ------------ | ------------ | ------------ +asset | STRING | NO | asset +type | STRING | NO | type +startTime | LONG | NO | startTime +endTime | LONG | NO | endTime +limit | LONG | NO | default:100 max:1000 + +**Note:** + +* `type`: `TRADE_TARGET`,`TRADE_SOURCE`,`TRANSFER_SPOT_TO_FUTURE`,`TRANSFER_FUTURE_TO_SPOT`,`TRANSFER_SPOT_TO_SPOT`,`AIRDROP`,`DIVIDEND`,`TRANSFER_REFUND`,`INTERNAL_TRANSFER`,`TRANSFER`,`SWAP`,`COMMISSION_REBATE`,`CASH_BACK`,`STAKING_WITHDRAW`, `STAKING_CLAIM`, `STAKING_DELEGATE` +* If startTime and endTime are not provided, only data from the most recent 7 days will be returned. + +## Perp-spot transfer (TRADE) + +**Response:** + +```javascript +{ + "tranId": 21841, //Tran Id + "status": "SUCCESS" //Status +} +``` + +`POST /api/v3/asset/wallet/transfer ` + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| amount | DECIMAL | YES | Quantity | +| asset | STRING | YES | Asset | +| clientTranId | STRING | YES | Transaction ID | +| kindType | STRING | YES | Transaction type | + +* kindType FUTURE_SPOT(future to spot)/SPOT_FUTURE(spot to future) + +## Prediction market mint (TRADE) + +**Response** + +```javascript +{ + "clientOrderId": "xxx", // Client order ID + "quoteAmount": "10.00000000", // Total quote asset spent + "yesPrice": "0.55000000", // YES token price at mint time + "noPrice": "0.45000000", // NO token price at mint time (yesPrice + noPrice = 1) + "pairCount": "10.00000000" // Number of YES+NO pairs minted +} +``` + +`POST /api/v3/prediction/mint` + +Mint YES+NO token pairs for a prediction market. The system deducts an equivalent amount of quote asset at the current market price and credits equal quantities of YES and NO tokens to the account. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | The YES token trading pair of the prediction market | +| quantity | DECIMAL | YES | Number of YES+NO token pairs to mint | +| newClientOrderId | STRING | NO | Client-customized unique order ID. If not provided, one will be generated automatically. | + +Notes: +* `symbol` must be a valid prediction market token trading pair with status `TRADING` or `PENDING_TRADING` +* `quantity` represents the number of pairs to mint simultaneously; the account will receive equal amounts of YES and NO tokens +* `yesPrice` + `noPrice` = 1 (in quote asset units) + + +## Prediction market burn (TRADE) + +**Response** + +```javascript +{ + "clientOrderId": "xxx", // Client order ID + "quoteAmount": "9.80000000", // Total quote asset returned after burn + "yesPrice": null, // Not returned for burn operations + "noPrice": null, // Not returned for burn operations + "pairCount": "10.00000000" // Number of YES+NO pairs burned +} +``` + +`POST /api/v3/prediction/burn` + +Burn equal quantities of YES+NO token pairs to redeem the corresponding quote asset. The account must hold equal amounts of YES and NO tokens to perform a burn. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | YES | The YES token trading pair of the prediction market | +| quantity | DECIMAL | YES | Number of YES+NO token pairs to burn | +| newClientOrderId | STRING | NO | Client-customized unique order ID. If not provided, one will be generated automatically. | + +Notes: +* `symbol` must be a valid prediction market token trading pair with status `TRADING`, `PENDING_TRADING`, or `CLOSED` +* `quantity` represents the number of pairs to burn simultaneously; the account must hold the corresponding amounts of both YES and NO tokens +* `yesPrice` and `noPrice` are `null` in the burn response +* Burn operations are still available after the market is `CLOSED` + + +## Query prediction market current positions (USER\_DATA) + +**Response** + +```javascript +[ + { + "marketName": "BTC_UP_DOWN_20260512", // Prediction market name + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Trading pair + "assetName": "USDT", // Settlement asset + "type": "YES", // Position direction: "YES" or "NO" + "openAvgPrice": "0.65000000", // Average open price + "cumQty": "100.00000000", // Total position quantity + "closeAvgPrice": "0.00000000", // Average close price (0 if not closed) + "realizedPnl": "0.00000000", // Realized PnL + "closeQty": "0.00000000", // Closed quantity + "insertTime": 1747000000000, // Position open time (millisecond timestamp) + "commissionFee": "0.10000000", // Commission fee paid + "commissionAsset": "USDT", // Commission fee asset + "balance": "65.00000000", // Position value (quantity × average open price) + "availableBalance": "65.00000000", // Available balance + } +] +``` + +`GET /api/v3/prediction/positions` + +Query the current account's prediction market position list. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | Trading pair; if not provided, returns all positions | +| signer | STRING | YES | API wallet address | +| nonce | STRING | YES | Current time in microseconds | +| signature | STRING | YES | Signature | + +## Query prediction market position history (USER\_DATA) + +**Response** + +```javascript +[ + { + "marketName": "BTC_UP_DOWN_20260501", // Prediction market name + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Trading pair + "assetName": "USDT", // Settlement asset + "type": "YES", // Position direction: "YES" or "NO" + "openAvgPrice": "0.72000000", // Average open price + "cumQty": "200.00000000", // Total position quantity + "closeAvgPrice": "1.00000000", // Average close price + "realizedPnl": "56.00000000", // Realized PnL + "closeQty": "200.00000000", // Closed quantity + "insertTime": 1746000000000, // Position open time (millisecond timestamp) + "closeTime": 1746086400000, // Close/settlement time (millisecond timestamp) + "status": "settled", // Position status: "close" (manually closed) or "settled" (market settled) + "commissionFee": "0.10000000", // Commission fee paid + "commissionAsset": "USDT", // Commission fee asset + "settleFee": "2.00000000", // Settlement fee (only present when status is "settled") + "settleAsset": "USDT", // Settlement fee asset + } +] +``` + +`GET /api/v3/prediction/positionHistories` + +Query the current account's prediction market historical position list (closed or settled). + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | Trading pair; if not provided, returns all historical positions | +| startTime | LONG | NO | Start time (millisecond timestamp) | +| endTime | LONG | NO | End time (millisecond timestamp) | +| limit | INT | NO | Number of results; default 100, maximum 1000 | +| signer | STRING | YES | API wallet address | +| nonce | STRING | YES | Current time in microseconds | +| signature | STRING | YES | Signature | + +Notes: +* When both `startTime` and `endTime` are provided, `startTime` must not be greater than `endTime` +* `limit` range is 1 to 1000, default is 100 +* `status` field: `close` means the user manually closed the position; `settled` means the prediction market expired and settled + +## Query prediction market settlement histories (USER\_DATA) + +**Response** + +```javascript +[ + { + "marketName": "BTC_UP_DOWN_20260501", // Prediction market name + "asset": "BTC_UP_DOWN_20260501YES", // Token asset (YES or NO token) + "symbol": "BTC_UP_DOWN_20260501YES", // Trading pair + "marketStartTime": 1746000000000, // Market start time (millisecond timestamp) + "marketEndTime": 1746086400000, // Market end time / settlement time (millisecond timestamp) + "shareAmount": "200.00000000", // Share quantity held at settlement + "settleAsset": "USDT", // Settlement asset + "settleAmount": "200.00000000", // Settlement amount received + "settleFeeAmount": "2.00000000", // Settlement fee charged + "entryPrice": "0.72000000", // Average entry price + "settlePrice": "1.00000000", // Final settlement price + "realizedPnl": "56.00000000", // Realized PnL after settlement + "status": "settled" // Settlement status + } +] +``` + +`GET /api/v3/prediction/settlementHistories` + +Query the current account's prediction market settlement history (markets that have expired and settled). + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | Trading pair; if not provided, returns all settlement records | +| startTime | LONG | NO | Filter by market start time (millisecond timestamp) | +| endTime | LONG | NO | Filter by market end time (millisecond timestamp) | +| limit | INT | NO | Number of results; default 100, maximum 1000 | +| signer | STRING | YES | API wallet address | +| nonce | STRING | YES | Current time in microseconds | +| signature | STRING | YES | Signature | + +Notes: +* When both `startTime` and `endTime` are provided, `startTime` must not be greater than `endTime` +* `limit` range is 1 to 1000, default is 100 +* `settleAmount` is the gross payout; `realizedPnl` equals `settleAmount` minus the cost basis +* `settleFeeAmount` is deducted from the settlement payout + +## Get withdraw fee (NONE) +> **Response:** +```javascript +{ + "tokenPrice": 1.00019000, + "gasCost": 0.5000, + "gasUsdValue": 0.5 +} +``` + +`` +GET /api/v3/aster/withdraw/estimateFee +`` + +**Weight:** +1 + +**Parameters:** + +Name | Type | Mandatory | Description +------------ | ------------ | ------------ | ------------ +chainId | STRING | YES | +asset | STRING | YES | + +**Notes:** +* chainId: 1(ETH),56(BSC),42161(Arbi) +* gasCost: The minimum fee required for a withdrawal + +## Withdraw (USER_DATA) +> **Response:** +```javascript +{ + "withdrawId": "1014729574755487744", + "hash":"0xa6d1e617a3f69211df276fdd8097ac8f12b6ad9c7a49ba75bbb24f002df0ebb" +} +``` + +`` +POST /api/v3/aster/user-withdraw`` + +**Weight:** +5 + +**Parameters:** + +Name | Type | Mandatory | Description +------------ | ------------ | ------------ | ------------ +chainId | STRING | YES | 1(ETH),56(BSC),42161(Arbi) +asset | STRING | YES | +amount | STRING | YES | +fee | STRING | YES | +receiver | STRING | YES | The address of the current account +nonce | STRING | YES | The current time in microseconds +userSignature | STRING | YES | + + +**Note:** +* chainId: 1(ETH),56(BSC),42161(Arbi) +* receiver: The address of the current account +* If the futures account balance is insufficient, funds will be transferred from the spot account to the perp account for withdrawal. +* userSignature demo + +```shell +const domain = { + name: 'Aster', + version: '1', + chainId: 56, + verifyingContract: ethers.ZeroAddress, + } + +const currentTime = Date.now() * 1000 + +const types = { + Action: [ + {name: "type", type: "string"}, + {name: "destination", type: "address"}, + {name: "destination Chain", type: "string"}, + {name: "token", type: "string"}, + {name: "amount", type: "string"}, + {name: "fee", type: "string"}, + {name: "nonce", type: "uint256"}, + {name: "aster chain", type: "string"}, + ], + } + const value = { + 'type': 'Withdraw', + 'destination': '0xD9cA6952F1b1349d27f91E4fa6FB8ef67b89F02d', + 'destination Chain': 'BSC', + 'token': 'USDT', + 'amount': '10.123400', + 'fee': '1.234567891', + 'nonce': currentTime, + 'aster chain': 'Mainnet', + } + + +const signature = await signer.signTypedData(domain, types, value) +``` + +## Account information (USER\_DATA) + +**Response** + +```javascript +{ + "feeTier": 0, + "canTrade": true, + "canDeposit": true, + "canWithdraw": true, + "canBurnAsset": true, + "updateTime": 0, + "balances": [ + { + "asset": "BTC", + "free": "4723846.89208129", + "locked": "0.00000000" + }, + { + "asset": "LTC", + "free": "4763368.68006011", + "locked": "0.00000000" + } + ] +} +``` + +`GET /api/v3/account` + +Retrieve current account information + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | + +## Account trade history (USER\_DATA) + +**Response** + +```javascript +[ + { + "symbol": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "id": 1002, + "orderId": 266358, + "side": "BUY", + "price": "1", + "qty": "2", + "quoteQty": "2", + "commission": "0.00105000", + "commissionAsset": "BNB", + "time": 1755656788798, + "counterpartyId": 19, + "createUpdateId": null, + "maker": false, + "buyer": true + } +] +``` + +`GET /api/v3/userTrades` + +Retrieve the trade history for a specified trading pair of an account + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| symbol | STRING | NO | | +| orderId | LONG | NO | Must be used together with the parameter symbol | +| startTime | LONG | NO | | +| endTime | LONG | NO | | +| fromId | LONG | NO | Starting trade ID. Defaults to fetching the most recent trade. | +| limit | INT | NO | Default 500; maximum 1000 | + +* If both `startTime` and `endTime` are not sent, only data from the last 7 days will be returned. +* The maximum interval between startTime and endTime is 7 days. +* `fromId` cannot be sent together with `startTime` or `endTime`. + +--- + +# WebSocket market data feed + +* The base URL for all wss endpoints listed in this document is: **wss://sstream.asterdex.com** +* Streams have either a single raw stream or a combined stream +* Single raw streams format is \*\*/ws/\*\* +* The URL format for combined streams is \*\*/stream?streams=//\*\* +* When subscribing to combined streams, the event payload is wrapped in this format: \*\*{"stream":"","data":}\*\* +* All trading pairs in stream names are **lowercase** +* Each link to **sstream.asterdex.com** is valid for no more than 24 hours; please handle reconnections appropriately +* Every 3 minutes the server sends a ping frame; the client must reply with a pong frame within 10 minutes, otherwise the server will close the connection. The client is allowed to send unpaired pong frames (i.e., the client may send pong frames at a frequency higher than once every 10 minutes to keep the connection alive). + +## Real-time subscribe/unsubscribe data streams + +* The following messages can be sent via WebSocket to subscribe or unsubscribe to data streams. Examples are shown below. +* The `id` in the response content is an unsigned integer that serves as the unique identifier for exchanges of information. +* If the `result` in the response content is `null`, it indicates the request was sent successfully. + +### Subscribe to a stream + +**Response** + +```javascript +{ + "result": null, + "id": 1 +} +``` + +* **Request** { "method": "SUBSCRIBE", "params": \[ "btc_up_dowm_5m_1778483280_yusdt@aggTrade", "btc_up_dowm_5m_1778483280_yusdt@depth" \], "id": 1 } + +### Unsubscribe from a stream + +**Response** + +```javascript +{ + "result": null, + "id": 312 +} +``` + +* **Request** { "method": "UNSUBSCRIBE", "params": \[ "btc_up_dowm_5m_1778483280_yusdt@depth" \], "id": 312 } + +### Subscribed to the feed + +**Response** + +```javascript +{ + "result": [ + "btc_up_dowm_5m_1778483280_yusdt@aggTrade" + ], + "id": 3 +} +``` + +* **Request** + + { "method": "LIST\_SUBSCRIPTIONS", "id": 3 } + +### Set properties + +Currently, the only configurable property is whether to enable the `combined` ("combined") stream. When connecting using `/ws/` ("raw stream"), the combined property is set to `false`, while connecting using `/stream/` sets the property to `true`. + +**Response** + +```javascript +{ +"result": null, +"id": 5 +} +``` + +* **Request** { "method": "SET\_PROPERTY" "params": \[ "combined", true \], "id": 5 } + +### Retrieve properties + +**Response** + +```javascript +{ + "result": true, // Indicates that combined is set to true. + "id": 2 +} +``` + +* **Request** + + { "method": "GET\_PROPERTY", "params": \[ "combined" \], "id": 2 } + +\#\#\# Error message + +| Error message | Description | +| :---- | :---- | +| {"code": 0, "msg": "Unknown property"} | Parameters applied in SET\_PROPERTY or GET\_PROPERTY are invalid | +| {"code": 1, "msg": "Invalid value type: expected Boolean", "id": '%s'} | Only true or false are accepted | +| {"code": 2, "msg": "Invalid request: property name must be a string"} | The provided attribute name is invalid | +| {"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"} | Parameter ID not provided or ID has an invalid type | +| {"code": 2, "msg": "Invalid request: unknown variant %s, expected one of SUBSCRIBE, UNSUBSCRIBE, LIST\_SUBSCRIPTIONS, SET\_PROPERTY, GET\_PROPERTY at line 1 column 28"} | Typo warning, or the provided value is not of the expected type | +| {"code": 2, "msg": "Invalid request: too many parameters"} | Unnecessary parameters were provided in the data | +| {"code": 2, "msg": "Invalid request: property name must be a string"} | Property name not provided | +| {"code": 2, "msg": "Invalid request: missing field method at line 1 column 73"} | Data did not provide method | +| {"code":3,"msg":"Invalid JSON: expected value at line %s column %s"} | JSON syntax error | + +## Collection transaction flow + +**Payload:** + +```javascript +{ + "e": "aggTrade", // Event type + "E": 123456789, // Event time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "a": 12345, // Aggregate trade ID + "p": "0.001", // Price + "q": "100", // Quantity + "f": 100, // First trade ID + "l": 105, // Last trade ID + "T": 123456785, // Trade time + "m": true, // Is the buyer the market maker? + "M": true // Ignore +} +``` + +The collection transaction stream pushes transaction information and is an aggregation of a single order. + +**Stream name:** `@aggTrade` + +**Update speed:** real-time + +## Tick-by-tick trades + +**Payload:** + +```javascript +{ + "e": "trade", // Event type + "E": 123456789, // Event time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "t": 12345, // Trade ID + "p": "0.001", // Price + "q": "100", // Quantity + "T": 123456785, // Trade time + "m": true, // Is the buyer the market maker? +} +``` + +**Stream name:** `@trade` + +Each trade stream pushes the details of every individual trade. A **trade**, also called a transaction, is defined as a match between exactly one taker and one maker. + +## K-line streams + +**Payload:** + +```javascript +{ + "e": "kline", // Event type + "E": 123456789, // Event time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "k": { + "t": 123400000, // Kline start time + "T": 123460000, // Kline close time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "i": "1m", // Interval + "f": 100, // First trade ID + "L": 200, // Last trade ID + "o": "0.0010", // Open price + "c": "0.0020", // Close price + "h": "0.0025", // High price + "l": "0.0015", // Low price + "v": "1000", // Base asset volume + "n": 100, // Number of trades + "x": false, // Is this kline closed? + "q": "1.0000", // Quote asset volume + "V": "500", // Taker buy base asset volume + "Q": "0.500", // Taker buy quote asset volume + "B": "123456" // Ignore + } +} +``` + +The K-line stream pushes per-second updates for the requested type of K-line (the latest candle). + +**Stream name:** `@kline_` + +**Update speed:** 2000ms + +**K-line interval parameter:** + +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 + +## Simplified ticker by symbol + +**Payload:** + +```javascript + { + "e": "24hrMiniTicker", // Event type + "E": 123456789, // Event time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "c": "0.0025", // Close price + "o": "0.0010", // Open price + "h": "0.0025", // High price + "l": "0.0010", // Low price + "v": "10000", // Total traded base asset volume + "q": "18" // Total traded quote asset volume + } +``` + +Refreshed simplified 24-hour ticker information by symbol + +**Stream name:** `@miniTicker` + +**Update speed:** 1000ms + +## Compact tickers for all symbols in the entire market + +**Payload:** + +```javascript +[ + { + // Same as @miniTicker payload + } +] +``` + +Same as above, but pushes all trading pairs. Note that only updated tickers will be pushed. + +**Stream name:** \!miniTicker@arr + +**Update speed:** 1000ms + +## Full ticker per symbol + +**Payload:** + +```javascript +{ + "e": "24hrTicker", // Event type + "E": 123456789, // Event time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "p": "0.0015", // Price change + "P": "250.00", // Price change percent + "w": "0.0018", // Weighted average price + "c": "0.0025", // Last price + "Q": "10", // Last quantity + "o": "0.0010", // Open price + "h": "0.0025", // High price + "l": "0.0010", // Low price + "v": "10000", // Total traded base asset volume + "q": "18", // Total traded quote asset volume + "O": 0, // Statistics open time + "C": 86400000, // Statistics close time + "F": 0, // First trade ID + "L": 18150, // Last trade Id + "n": 18151 // Total number of trades +} +``` + +Pushes per-second tag statistics for a single trading pair over a rolling 24-hour window. + +**Stream name:** `@ticker` + +**Update speed:** 1000ms + +## Complete ticker for all trading pairs on the entire market + +**Payload:** + +```javascript +[ + { + // Same as @ticker payload + } +] +``` + +Pushes the full 24-hour refreshed ticker information for all trading pairs across the entire market. Note that tickers without updates will not be pushed. + +**Stream name:** `!ticker@arr` + +**Update speed:** 1000ms + +## Best order book information by symbol + +**Payload:** + +```javascript +{ + "u":400900217, // order book updateId + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // symbol + "b":"25.35190000", // best bid price + "B":"31.21000000", // best bid qty + "a":"25.36520000", // best ask price + "A":"40.66000000" // best ask qty +} +``` + +Real-time push of best order book information for the specified trading pair + +**Stream name:** `@bookTicker` + +**Update speed:** Real-time + +## Best order book information across the entire market + +**Payload:** + +```javascript +{ + // Same as @bookTicker payload +} +``` + +Real-time push of the best order information for all trading pairs + +**Stream name:** `!bookTicker` + +**Update speed:** Real-time + +## Limited depth information + +**Payload:** + +```javascript +{ + "e": "depthUpdate", // Event type + "E": 123456789, // Event time + "T": 123456788, // Transaction time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "U": 100, // First update ID in event + "u": 120, // Final update ID in event + "pu": 99, // Final update Id in last stream(ie `u` in last stream) + "bids": [ // Bids to be updated + [ + "0.0024", // Price level to be updated + "10" // Quantity + ] + ], + "asks": [ // Asks to be updated + [ + "0.0026", // Price level to be updated + "100" // Quantity + ] + ] +} +``` + +Limited depth information pushed every second or every 100 milliseconds. Levels indicate how many levels of bid/ask information, optional 5/10/20 levels. + +**Stream names:** `@depth` or `@depth@100ms`. + +**Update speed:** 1000ms or 100ms + +## Incremental depth information + +**Payload:** + +```javascript +{ + "e": "depthUpdate", // Event type + "E": 123456789, // Event time + "T": 123456788, // Transaction time + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // Symbol + "U": 100, // First update ID in event + "u": 120, // Final update ID in event + "pu": 99, // Final update Id in last stream(ie `u` in last stream) + "b": [ // Bids to be updated + [ + "5.4", // Price level to be updated + "10" // Quantity + ] + ], + "a": [ // Asks to be updated + [ + "5.6", // Price level to be updated + "100" // Quantity + ] + ] +} +``` + +Pushes the changed parts of the orderbook (if any) every second or every 100 milliseconds + +**Stream name:** `@depth` or `@depth@100ms` + +**Update speed:** 1000ms or 100ms + +## How to correctly maintain a local copy of an order book + +1. Subscribe to **wss://sstream.asterdex.com/ws/btc_up_dowm_5m_1778483280_yusdt@depth** +2. Start caching the received updates. For the same price level, later updates overwrite earlier ones. +3. Fetch the REST endpoint [**https://sapi.asterdex.com/api/v3/depth?symbol=BTC_UP_DOWN_5M_1778483280_YUSDT\&limit=1000**](https://sapi.asterdex.com/api/v3/depth?symbol=BTC_UP_DOWN_5M_1778483280_YUSDT&limit=1000) to obtain a 1000-level depth snapshot +4. Discard from the currently cached messages those with `u` \<= the `lastUpdateId` obtained in step 3 (drop older, expired information) +5. Apply the depth snapshot to your local order book copy, and resume updating the local copy from the first WebSocket event whose `U` \<= `lastUpdateId`\+1 **and** `u` \>= `lastUpdateId`\+1 +6. Each new event's `U` should equal exactly the previous event's `u`\+1; otherwise packets may have been lost \- restart initialization from step 3 +7. The order quantity in each event represents the current order quantity at that price as an **absolute value**, not a relative change +8. If the order quantity at a given price is 0, it means the orders at that price have been canceled or filled, and that price level should be removed + +# WebSocket account information push + +* The base URL for the API endpoints listed in this document is: [**https://sapi.asterdex.com**](https://sapi.asterdex.com) +* The `listenKey` used to subscribe to account data is valid for 60 minutes from the time of creation +* You can extend the 60-minute validity of a `listenKey` by sending a `PUT` request +* You can immediately close the current data stream and invalidate the `listenKey` by sending a `DELETE` for a `listenKey` +* Sending a `POST` on an account with a valid `listenKey` will return the currently valid `listenKey` and extend its validity by 60 minutes +* The WebSocket interface baseurl: **wss://sstream.asterdex.com** +* The stream name for subscribing to the user account data stream is \*\*/ws/\*\* +* Each connection is valid for no more than 24 hours; please handle disconnections and reconnections appropriately + +## Listen Key (spot account) + +### Generate Listen Key (USER\_STREAM) + +**Response** + +```javascript +{ + "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1" +} +``` + +`POST /api/v3/listenKey` + +Start a new data stream. The data stream will be closed after 60 minutes unless a keepalive is sent. If the account already has a valid `listenKey`, that `listenKey` will be returned and its validity extended by 60 minutes. + +**Weight:** 1 + +**Parameters:** NONE + +### Extend Listen Key validity period (USER\_STREAM) + +**Response** + +```javascript +{} +``` + +`PUT /api/v3/listenKey` + +Validity extended to 60 minutes after this call. It is recommended to send a ping every 30 minutes. + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| listenKey | STRING | YES | | + +### Close Listen Key (USER\_STREAM) + +**Response** + +```javascript +{} +``` + +`DELETE /api/v3/listenKey` + +Close user data stream + +**Weight:** 1 + +**Parameters:** + +| Name | Type | Is it required? | Description | +| :---- | :---- | :---- | :---- | +| listenKey | STRING | YES | | + +## Payload: ACCOUNT\_UPDATE + +An `outboundAccountPosition` event is sent whenever an account balance changes; it contains the assets that may have changed due to the event that generated the balance update. + +**Payload** + +```javascript +{ + "B":[ //Balance + { + "a":"SLP25", //Asset + "f":"10282.42029415", //Free + "l":"653.00000001" //Locked + }, + { + "a":"ADA25", + "f":"9916.96229880", + "l":"34.00510000" + } + ], + "e":"outboundAccountPosition", //Event type + "T":1649926447190, //Time of last account update + "E":1649926447205 //Event Time + "m":"WITHDRAW" // Event reason type +} +``` + +## Payload: Order Update + +Orders are updated via the `executionReport` event + +**Payload** + +```javascript +{ + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", // symbol + "c":"Xzh0gnxT41PStbwqOtXnjD", // client order id + "S":"SELL", // order direction + "o":"LIMIT", // order type + "f":"GTC", // Time in force + "q":"10.001000", // Order quantity + "p":"19.1000000000", // Order price + "ap":"19.0999999955550656", //average price + "P":"0", //stop price + "x":"TRADE", // Current execution type + "X":"PARTIALLY_FILLED", // Current order status + "i":27, // Order ID + "l":"1", // Last executed quantity + "z":"8.999000", // Cumulative filled quantity + "L":"19.1000000000", // Last executed price + "n":"0.00382000", // Commission amount + "N":"SLP25", // Commission asset + "T":1649926447190, //Transaction Time + "t":18, // transaction id + "m":true, // is this trade the maker side? + "ot":"LIMIT", //original order type + "O":0, // Order creation time + "Z":"171.88089996", // Cumulative quote asset transacted quantity + "Y":"19.1000000000000000", // Last quote asset transacted quantity (i.e. lastPrice * lastQty) + "Q":"0", // Quote Order Qty + "e":"executionReport", // event + "E":1649926447209 // event time +} +``` + +**Execution type:** + +* NEW \- New Order +* CANCELED \- Order canceled +* REJECTED \- New order was rejected +* TRADE \- Order had a new fill +* EXPIRED \- Order expired (based on the order's Time In Force parameter) + +## Event: TradePro + +> **Topic Subscribe:** + +```javascript +{ + "method": "SUBSCRIBE", + "params": [ + "btc_up_dowm_5m_1778483280_yusdt@tradepro" + ], + "id": 3 +} +``` + +> **Payload:** + +```javascript +{ + "stream": "btc_up_dowm_5m_1778483280_yusdt@tradepro", + "data": { + "e": "tradepro", + "E": 1773751963081, + "T": 1773751963079, + "s": "BTC_UP_DOWN_5M_1778483280_YUSDT", + "t": 128884613, + "p": "73685.5", + "q": "0.297", + "h": "0X0000000000000000000000000000000000000000000000000000000000000000", + "m": [ + "hidden", + "hidden" + ] + } +} +``` + +* h: Transaction hash of the trade. + +* m: Array containing the participant addresses: + + * m[0]: Taker address + + * m[1]: Maker address + + +\#错误代码 + +error JSON payload: + +```javascript +{ + "code":-1121, + "msg":"Invalid symbol." +} +``` + +Errors consist of two parts: an error code and a message. The code is standardized, but the message may vary. + +## 10xx \- General server or network issues + +### \-1000 UNKNOWN + +* An unknown error occurred while processing the request. + +### \-1001 DISCONNECTED + +* Internal error; unable to process your request. Please try again. + +### \-1002 UNAUTHORIZED + +* You are not authorized to execute this request. + +### \-1003 TOO\_MANY\_REQUESTS + +* Too many requests queued. +* Too many requests; please use the WebSocket for live updates. +* Too many requests; current limit is %s requests per minute. Please use the WebSocket for live updates to avoid polling the API. +* Too many request weights; IP banned until %s. Please use the WebSocket for live updates to avoid bans. + +### \-1004 DUPLICATE\_IP + +* This IP is already on the white list. + +### \-1005 NO\_SUCH\_IP + +* No such IP has been whitelisted. + +### \-1006 UNEXPECTED\_RESP + +* An unexpected response was received from the message bus. Execution status unknown. + +### \-1007 TIMEOUT + +* Timeout waiting for response from backend server. Send status unknown; execution status unknown. + +### \-1014 UNKNOWN\_ORDER\_COMPOSITION + +* The current order parameter combination is not supported. + +### \-1015 TOO\_MANY\_ORDERS + +* Too many new orders. +* Too many new orders; the current limit is %s orders per %s. + +### \-1016 SERVICE\_SHUTTING\_DOWN + +* This service is no longer available. + +### \-1020 UNSUPPORTED\_OPERATION + +* This operation is not supported. + +### \-1022 INVALID\_SIGNATURE + +* The signature for this request is invalid. + +### \-1023 START\_TIME\_GREATER\_THAN\_END\_TIME + +* The start time in the parameters is after the end time. + +## 11xx \- Request issues + +### \-1100 ILLEGAL\_CHARS + +* Illegal characters found in a parameter. +* Illegal characters found in parameter %s; legal range is %s. + +### \-1101 TOO\_MANY\_PARAMETERS + +* Too many parameters sent for this endpoint. +* Too many parameters; expected %s and received %s. +* Duplicate values for a parameter detected. + +### \-1102 MANDATORY\_PARAM\_EMPTY\_OR\_MALFORMED + +* A mandatory parameter was not sent, was empty/null, or malformed. +* Mandatory parameter %s was not sent, was empty/null, or malformed. +* Param %s or %s must be sent, but both were empty/null. + +### \-1103 UNKNOWN\_PARAM + +* An unknown parameter was sent. + +### \-1104 UNREAD\_PARAMETERS + +* Not all sent parameters were read. +* Not all sent parameters were read; read %s parameter(s) but %s parameter(s) were sent. + +### \-1105 PARAM\_EMPTY + +* A parameter was empty. +* Parameter %s was empty. + +### \-1106 PARAM\_NOT\_REQUIRED + +* A parameter was sent when not required. + +### \-1111 BAD\_PRECISION + +* The precision exceeds the maximum defined for this asset. + +### \-1112 NO\_DEPTH + +* No open orders for the trading pair. + +### \-1114 TIF\_NOT\_REQUIRED + +* TimeInForce parameter sent when not required. + +### \-1115 INVALID\_TIF + +* Invalid timeInForce. + +### \-1116 INVALID\_ORDER\_TYPE + +* Invalid orderType. + +### \-1117 INVALID\_SIDE + +* Invalid order side. + +### \-1118 EMPTY\_NEW\_CL\_ORD\_ID + +* New client order ID was empty. + +### \-1119 EMPTY\_ORG\_CL\_ORD\_ID + +* The client's custom order ID is empty. + +### \-1120 BAD\_INTERVAL + +* Invalid time interval. + +### \-1121 BAD\_SYMBOL + +* Invalid trading pair. + +### \-1125 INVALID\_LISTEN\_KEY + +* This listenKey does not exist. + +### \-1127 MORE\_THAN\_XX\_HOURS + +* The query interval is too large. +* More than %s hours between startTime and endTime. + +### \-1128 OPTIONAL\_PARAMS\_BAD\_COMBO + +* Combination of optional parameters invalid. + +### \-1130 INVALID\_PARAMETER + +* The parameter sent contains invalid data. +* Data sent for parameter %s is not valid. + +### \-1136 INVALID\_NEW\_ORDER\_RESP\_TYPE + +* Invalid newOrderRespType. + +## 20xx \- Processing Issues + +### \-2010 NEW\_ORDER\_REJECTED + +* New order rejected. + +### \-2011 CANCEL\_REJECTED + +* Order cancellation rejected. + +### \-2013 NO\_SUCH\_ORDER + +* Order does not exist. + +### \-2014 BAD\_API\_KEY\_FMT + +* API-key format invalid. + +### \-2015 REJECTED\_MBX\_KEY + +* Invalid API key, IP, or permissions for action. + +### \-2016 NO\_TRADING\_WINDOW + +* No trading window could be found for the symbol. Try ticker/24hrs instead. + +### \-2018 BALANCE\_NOT\_SUFFICIENT + +* Balance is insufficient. + +### \-2020 UNABLE\_TO\_FILL + +* Unable to fill. + +### \-2021 ORDER\_WOULD\_IMMEDIATELY\_TRIGGER + +* Order would immediately trigger. + +### \-2022 REDUCE\_ONLY\_REJECT + +* ReduceOnly Order is rejected. + +### \-2024 POSITION\_NOT\_SUFFICIENT + +* Position is not sufficient. + +### \-2025 MAX\_OPEN\_ORDER\_EXCEEDED + +* Reached max open order limit. + +### \-2026 REDUCE\_ONLY\_ORDER\_TYPE\_NOT\_SUPPORTED + +* This OrderType is not supported when reduceOnly. + +## 40xx \- Filters and other Issues + +### \-4000 INVALID\_ORDER\_STATUS + +* Invalid order status. + +### \-4001 PRICE\_LESS\_THAN\_ZERO + +* Price less than 0\. + +### \-4002 PRICE\_GREATER\_THAN\_MAX\_PRICE + +* Price greater than max price. + +### \-4003 QTY\_LESS\_THAN\_ZERO + +* Quantity less than zero. + +### \-4004 QTY\_LESS\_THAN\_MIN\_QTY + +* Quantity less than minimum quantity. + +### \-4005 QTY\_GREATER\_THAN\_MAX\_QTY + +* Quantity greater than maximum quantity. + +### \-4006 STOP\_PRICE\_LESS\_THAN\_ZERO + +* Stop price less than zero. + +### \-4007 STOP\_PRICE\_GREATER\_THAN\_MAX\_PRICE + +* Stop price greater than max price. + +### \-4008 TICK\_SIZE\_LESS\_THAN\_ZERO + +* Tick size less than zero. + +### \-4009 MAX\_PRICE\_LESS\_THAN\_MIN\_PRICE + +* Max price less than min price. + +### \-4010 MAX\_QTY\_LESS\_THAN\_MIN\_QTY + +* Maximum quantity less than minimum quantity. + +### \-4011 STEP\_SIZE\_LESS\_THAN\_ZERO + +* Step size less than zero. + +### \-4012 MAX\_NUM\_ORDERS\_LESS\_THAN\_ZERO + +* Maximum order quantity less than 0\. + +### \-4013 PRICE\_LESS\_THAN\_MIN\_PRICE + +* Price less than minimum price. + +### \-4014 PRICE\_NOT\_INCREASED\_BY\_TICK\_SIZE + +* Price not increased by tick size. + +### \-4015 INVALID\_CL\_ORD\_ID\_LEN + +* Client order ID is not valid. +* Client order ID length should not be more than 36 characters. + +### \-4016 PRICE\_HIGHTER\_THAN\_MULTIPLIER\_UP + +* Price is higher than mark price multiplier cap. + +### \-4017 MULTIPLIER\_UP\_LESS\_THAN\_ZERO + +* Multiplier up less than zero. + +### \-4018 MULTIPLIER\_DOWN\_LESS\_THAN\_ZERO + +* Multiplier down less than zero. + +### \-4019 COMPOSITE\_SCALE\_OVERFLOW + +* Composite scale too large. + +### \-4020 TARGET\_STRATEGY\_INVALID + +* Target strategy invalid for orderType %s, reduceOnly %b' + +### \-4021 INVALID\_DEPTH\_LIMIT + +* Invalid depth limit. +* %s is not a valid depth limit. + +### \-4022 WRONG\_MARKET\_STATUS + +* Market status sent is not valid. + +### \-4023 QTY\_NOT\_INCREASED\_BY\_STEP\_SIZE + +* The increment of the quantity is not a multiple of the step size. + +### \-4024 PRICE\_LOWER\_THAN\_MULTIPLIER\_DOWN + +* Price is lower than mark price multiplier floor. + +### \-4025 MULTIPLIER\_DECIMAL\_LESS\_THAN\_ZERO + +* Multiplier decimal less than zero. + +### \-4026 COMMISSION\_INVALID + +* Commission invalid. +* Incorrect profit value. +* `%s` less than zero. +* `%s` absolute value greater than `%s`. + +### \-4027 INVALID\_ACCOUNT\_TYPE + +* Invalid account type. + +### \-4029 INVALID\_TICK\_SIZE\_PRECISION + +* Tick size precision is invalid. +* Price decimal precision is incorrect. + +### \-4030 INVALID\_STEP\_SIZE\_PRECISION + +* The number of decimal places for the step size is incorrect. + +### \-4031 INVALID\_WORKING\_TYPE + +* Invalid parameter working type: `%s` + +### \-4032 EXCEED\_MAX\_CANCEL\_ORDER\_SIZE + +* Exceeds the maximum order quantity that can be canceled. +* Invalid parameter working type: `%s` + +### \-4044 INVALID\_BALANCE\_TYPE + +* The balance type is incorrect. + +### \-4045 MAX\_STOP\_ORDER\_EXCEEDED + +* Reached the stop-loss order limit. + +### \-4055 AMOUNT\_MUST\_BE\_POSITIVE + +* The quantity must be a positive integer. + +### \-4056 INVALID\_API\_KEY\_TYPE + +* The API key type is invalid. + +### \-4057 INVALID\_RSA\_PUBLIC\_KEY + +* The API key is invalid. + +### \-4058 MAX\_PRICE\_TOO\_LARGE + +* maxPrice and priceDecimal too large, please check. + +### \-4060 INVALID\_POSITION\_SIDE + +* Invalid position side. + +### \-4061 POSITION\_SIDE\_NOT\_MATCH + +* The order's position direction does not match the user's settings. + +### \-4062 REDUCE\_ONLY\_CONFLICT + +* Invalid or improper reduceOnly value. + +### \-4084 UPCOMING\_METHOD + +* Method is not allowed currently. Coming soon. + +### \-4086 INVALID\_PRICE\_SPREAD\_THRESHOLD + +* Invalid price spread threshold. + +### \-4087 REDUCE\_ONLY\_ORDER\_PERMISSION + +* Users can only place reduce-only orders. + +### \-4088 NO\_PLACE\_ORDER\_PERMISSION + +* User cannot place orders currently. + +### \-4114 INVALID\_CLIENT\_TRAN\_ID\_LEN + +* clientTranId is not valid. +* The customer's tranId length should be less than 64 characters. + +### \-4115 DUPLICATED\_CLIENT\_TRAN\_ID + +* clientTranId is duplicated. +* The client's tranId should be unique within 7 days. + +### \-4118 REDUCE\_ONLY\_MARGIN\_CHECK\_FAILED + +* ReduceOnly Order failed. Please check your existing position and open orders + +### \-4131 MARKET\_ORDER\_REJECT + +* The counterparty's best price does not meet the PERCENT\_PRICE filter limit. + +### \-4135 INVALID\_ACTIVATION\_PRICE + +* Invalid activation price. + +### \-4137 QUANTITY\_EXISTS\_WITH\_CLOSE\_POSITION + +* Quantity must be zero when closePosition is true. + +### \-4138 REDUCE\_ONLY\_MUST\_BE\_TRUE + +* Reduce only must be true when closePosition is true. + +### \-4139 ORDER\_TYPE\_CANNOT\_BE\_MKT + +* Order type cannot be a market order if it cannot be canceled. + +### \-4140 INVALID\_OPENING\_POSITION\_STATUS + +* Invalid symbol status for opening position. + +### \-4141 SYMBOL\_ALREADY\_CLOSED + +* Trading pair has been delisted. + +### \-4142 STRATEGY\_INVALID\_TRIGGER\_PRICE + +* Rejected: Take Profit or Stop order would be triggered immediately. + +### \-4164 MIN\_NOTIONAL + +* Order notional must be at least 5.0 (unless you select Reduce Only) +* Order notional must be no smaller than %s (unless you choose Reduce Only) + +### \-4165 INVALID\_TIME\_INTERVAL + +* Invalid time interval +* Maximum time interval is %s days + +### \-4183 PRICE\_HIGHTER\_THAN\_STOP\_MULTIPLIER\_UP + +* Limit price cannot be higher than the cap of %s. +* Take-Profit/Stop-Loss price cannot be higher than the cap of %s. + +### \-4184 PRICE\_LOWER\_THAN\_STOP\_MULTIPLIER\_DOWN + +* Price is below the stop price limit. +* Take-Profit/Stop-Loss price must be above the trigger price × multiplier floor. +* Order price (limit or TP/SL) can't be below %s. diff --git "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-prediction-api_CN-v3.md" "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-prediction-api_CN-v3.md" new file mode 100644 index 0000000..55cb147 --- /dev/null +++ "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-prediction-api_CN-v3.md" @@ -0,0 +1,3073 @@ +# 基本信息 +## API 基本信息 +* 本篇列出接口的baseurl: **https://papi.asterdex.com** +* 所有接口的响应都是 JSON 格式。 +* 所有时间、时间戳均为UNIX时间，单位为**毫秒**。 + +## API Agent Address 设置 +* 很多接口需要API Key才可以访问. +* 设置API Key的同时，为了安全，建议设置IP访问白名单. +* **永远不要把你的API Agent Address/Private Key告诉给任何人** + + + +### 注意事项 +* TESTUSDT 或任何其他以 TEST 开头的交易对仅用于 Aster 的内部测试。请不要在这些以 TEST 开头的交易品种上进行交易。Aster 对因交易这些交易对而造成的资金损失不承担任何责任。但是，如果您遇到问题，您可以随时联系支持人员，我们将尽力帮助您收回资金。 + + +### HTTP 返回代码 +* HTTP `4XX` 错误码用于指示错误的请求内容、行为、格式。问题在于请求者。 +* HTTP `403` 错误码表示违反WAF限制(Web应用程序防火墙)。 +* HTTP `429` 错误码表示警告访问频次超限，即将被封IP。 +* HTTP `418` 表示收到429后继续访问，IP已经被封禁。 +* HTTP `5XX` 错误码用于指示Aster服务侧的问题。 + +### 接口错误代码 +* 使用接口 `/api/v3`, 每个接口都有可能抛出异常; +> API的错误代码返回形式如下: +```javascript +{ + "code": -1121, + "msg": "Invalid symbol." +} +``` + +### 接口的基本信息 + +* `GET` 方法的接口, 参数必须在 `query string`中发送。 +* `POST`, `PUT`, 和 `DELETE` 方法的接口,参数可以在内容形式为`application/x-www-form-urlencoded`的 `query string` 中发送，也可以在 `request body` 中发送。 +* 对参数的顺序不做要求。 + +### V3 Nonce 机制 + +* **Nonce** 用于校验请求的**有效性、唯一性和防重放**。客户端应使用**当前时间戳（微秒级）****作为 nonce**，且与服务端时间误差不超过 **10 秒**。 + +* 请求处理流程： + + 1. 若 nonce **已使用过** → 判定为**重复请求并拒绝** + 2. 否则判断是否**过旧** + +* 为提升性能，每个用户仅维护**最近 100 个 nonce**： + + * 若已满且新 nonce **小于当前最小值** → 判定为**过期并拒绝** + * 否则**移除最旧的 nonce**，加入新的 + +* 总体效果：**防重复、防过期，仅保留近期有效请求** + +--- +## 访问限制 +### 访问限制基本信息 + +* 在 `/api/v3/prediction/exchangeInfo` `rateLimits` 数组中包含与交易的有关REQUEST_WEIGHT和ORDERS速率限制相关的对象。这些在 `限制种类 (rateLimitType)` 下的 `枚举定义` 部分中进一步定义。 +* 违反任何一个速率限制时，将返回429。 + +### IP 访问限制 +* 每个请求的回报中包含一个`X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)`的头，其中包含当前IP所有请求的已使用权重。 +* 每一个接口均有一个相应的权重(weight)，有的接口根据参数不同可能拥有不同的权重。越消耗资源的接口权重就会越大。 +* 收到429时，您有责任停止发送请求，不得滥用API。 +* **收到429后仍然继续违反访问限制，会被封禁IP，并收到418错误码** +* 频繁违反限制，封禁时间会逐渐延长，**从最短2分钟到最长3天**。 +* `Retry-After`的头会与带有418或429的响应发送，并且会给出**以秒为单位**的等待时长(如果是429)以防止禁令，或者如果是418，直到禁令结束。 +* **访问限制是基于IP的，而不是API Key** + + + + +### 下单频率限制 +* 每个成功的下单回报将包含一个`X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)`的头，其中包含当前账户已用的下单限制数量。 +* 当下单数超过限制时，会收到带有429但不含`Retry-After`头的响应。请检查 `GET api/v3/exchangeInfo` 的下单频率限制 (rateLimitType = ORDERS) 并等待封禁时间结束。 +* 被拒绝或不成功的下单并不保证回报中包含以上头内容。 +* **下单频率限制是基于每个账户计数的。** + +### WEB SOCKET 连接限制 + +* Websocket服务器每秒最多接受5个消息。消息包括: + * PING帧 + * PONG帧 + * JSON格式的消息, 比如订阅, 断开订阅. +* 如果用户发送的消息超过限制，连接会被断开连接。反复被断开连接的IP有可能被服务器屏蔽。 +* 单个连接最多可以订阅 **1024** 个Streams。 + + +## 接口鉴权类型 +* 每个接口都有自己的鉴权类型，鉴权类型决定了访问时应当进行何种鉴权 +* 如果需要使用API_WALLET鉴权，应当在请求体中添加signer +* 如果需要使用主地址鉴权，应当在请求体中添加user + +鉴权类型 | 描述 +------------ | ------------ +NONE | 不需要鉴权的接口 +SPOT_TRADE | 需要有效的signer和签名 +USER_DATA | 需要有效的signer和签名 +USER_STREAM | 需要有效的signer和签名 +MARKET_DATA | 不需要鉴权的接口 + + +### POST /api/v3/order 的示例 + +#### 示例 : 以下参数为api注册信息,user,signer,privateKey仅供示范(privateKey为signer的私钥) + + +Key | Value | Desc +------------ | ------------ | ------------ +user | 0x63DD5aCC6b1aa0f563956C0e534DD30B6dcF7C4e | 登陆钱包地址 +signer | 0x21cF8Ae13Bb72632562c6Fff438652Ba1a151bb0 | [点击这里获取](https://www.asterdex.com/zh-CN/api-wallet) +privateKey | 0x4fd0a42218f3eae43a6ce26d22544e986139a01e5b34a62db53757ffca81bae1 | [点击这里获取](https://www.asterdex.com/zh-CN/api-wallet) + +#### 示例 : nonce参数为当前系统微秒值,超过系统时间,或者落后系统时间超过10s为非法请求 +```python +#python +nonce = math.trunc(time.time()*1000000) +print(nonce) +#1748310859508867 +``` +```java +//java +Instant now = Instant.now(); +long microsecond = now.getEpochSecond() * 1000000 + now.getNano() / 1000; +``` + +#### 示例 : 下单 (方法以python为例) + +```python +import time +import urllib +import threading + +import requests +from eth_account.messages import encode_structured_data +from eth_account import Account + +typed_data = { + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "version", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + {"name": "verifyingContract", "type": "address"} + ], + "Message": [ + { "name": "msg", "type": "string" } + ] + }, + "primaryType": "Message", + "domain": { + "name": "AsterSignTransaction", + "version": "1", + "chainId": 1666, + "verifyingContract": "0x0000000000000000000000000000000000000000" + }, + "message": { + "msg": "$msg" + } +} + +headers = { + 'Content-Type': 'application/x-www-form-urlencoded', + 'User-Agent': 'PythonApp/1.0' +} +host = 'https://sapi.asterdex.com' + +# config your user and agent info here +user = '*' +signer = '*' +private_key = "*" + +place_order = {"url":"/api/v3/order","method":"POST","params":{"symbol": "ASTERUSDT", "type": "LIMIT", "side": "BUY", + "timeInForce": "GTC", "quantity": "100", "price": "0.4"}} +_last_ms = 0 +_i = 0 +_nonce_lock = threading.Lock() + +def get_nonce(): + global _last_ms, _i + with _nonce_lock: + now_ms = int(time.time()) + + if now_ms == _last_ms: + _i += 1 + else: + _last_ms = now_ms + _i = 0 + + return now_ms * 1_000_000 + _i + +def send_by_url(api) : + my_dict = api['params'] + url = host + api['url'] + + my_dict['nonce'] = str(get_nonce()) + my_dict['signer'] = signer + + param = urllib.parse.urlencode(my_dict) + print(param) + typed_data['message']['msg'] = param + message = encode_structured_data(typed_data) + signed = Account.sign_message(message, private_key=private_key) + + url = url + '?' + param + '&signature=' + signed.signature.hex() + print(url) + res = requests.post(url, headers=headers) + + print(res.text) + +def send_by_body(api) : + my_dict = api['params'] + url = host +api['url'] + my_dict['nonce'] = str(get_nonce()) + my_dict['signer'] = signer + + param = urllib.parse.urlencode(my_dict) + typed_data['message']['msg'] = param + message = encode_structured_data(typed_data) + + signed = Account.sign_message(message, private_key=private_key) + print(signed.signature.hex()) + + my_dict['signature'] = signed.signature.hex() + + print(my_dict) + res = requests.post(url, data=my_dict, headers=headers) + + print(res.text) + +if __name__ == '__main__': + send_by_url(place_order) + # send_by_body(place_order) + +``` + +## 公开 API 参数 +### 术语 + +这里的术语适用于全部文档，建议特别是新手熟读，也便于理解。 + +* `base asset` 指一个交易对的交易对象，即写在靠前部分的资产名, 比如`BTCUSDT`, `BTC`是`base asset`。 +* `quote asset` 指一个交易对的定价资产，即写在靠后部分的资产名, 比如`BTCUSDT`, `USDT`是`quote asset`。 + +### 枚举定义 +**交易对状态 (状态 status):** + +* TRADING 交易中 + + +**交易对类型:** + +* SPOT 现货 + +**订单状态 (状态 status):** + +状态 | 描述 +-----------| -------------- +`NEW` | 订单被交易引擎接受 +`PARTIALLY_FILLED`| 部分订单被成交 +`FILLED` | 订单完全成交 +`CANCELED` | 用户撤销了订单 +`REJECTED` | 订单没有被交易引擎接受，也没被处理 +`EXPIRED` | 订单被交易引擎取消, 比如
LIMIT FOK 订单没有成交
市价单没有完全成交
交易所维护期间被取消的订单 + + +**订单类型 (orderTypes, type):** + +* LIMIT 限价单 +* MARKET 市价单 + +**订单返回类型 (newOrderRespType):** + +* ACK +* RESULT +* FULL + +**订单方向 (方向 side):** + +* BUY 买入 +* SELL 卖出 + +**有效方式 (timeInForce):** + +这里定义了订单多久能够失效 + +Status | Description +-----------| -------------- +`GTC` | 成交为止
订单会一直有效，直到被成交或者取消。 +`IOC` | 无法立即成交的部分就撤销
订单在失效前会尽量多的成交。 +`FOK` | 无法全部立即成交就撤销
如果无法全部成交，订单会失效。 +`GTX` | 直到挂单成交
限价只挂单。 + +**K线间隔:** + +m -> 分钟; h -> 小时; d -> 天; w -> 周; M -> 月 + +* 1s +* 1m +* 3m +* 5m +* 15m +* 30m +* 1h +* 2h +* 4h +* 6h +* 8h +* 12h +* 1d +* 3d +* 1w +* 1M + +新增了1s参数 + +**限制种类 (rateLimitType)** + +> REQUEST_WEIGHT +```json + { + "rateLimitType": "REQUEST_WEIGHT", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 1200 + } +``` + +> ORDERS +```json + { + "rateLimitType": "ORDERS", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 100 + } +``` + + +* REQUEST_WEIGHT 单位时间请求权重之和上限 + +* ORDERS 单位时间下单次数限制 + + +**限制间隔 (interval)** + +* MINUTE 分 + +--- +## 过滤器 +过滤器，即Filter，定义了一系列交易规则。 +共有两类，分别是针对交易对的过滤器`symbol filters`，和针对整个交易所的过滤器`exchange filters`(暂不支持) + +### 交易对过滤器   + +#### PRICE_FILTER 价格过滤器 + +> **/exchangeInfo 响应中的格式:** +```javascript + { + "minPrice": "556.72", + "maxPrice": "4529764", + "filterType": "PRICE_FILTER", + "tickSize": "0.01"   + } +``` + +`价格过滤器` 用于检测订单中 `price` 参数的合法性。包含以下三个部分: + +* `minPrice` 定义了 `price`/`stopPrice` 允许的最小值。 +* `maxPrice` 定义了 `price`/`stopPrice` 允许的最大值。 +* `tickSize` 定义了 `price`/`stopPrice` 的步进间隔，即price必须等于minPrice+(tickSize的整数倍) + +以上每一项均可为0，为0时代表这一项不再做限制。 + +逻辑伪代码如下: + +* `price` >= `minPrice` +* `price` <= `maxPrice` +* (`price`-`minPrice`) % `tickSize` == 0 + + +#### PERCENT_PRICE 价格振幅过滤器 + +> **/exchangeInfo 响应中的格式:** +```javascript + { + "multiplierDown": "0.9500", + "multiplierUp": "1.0500", + "multiplierDecimal": "4", + "filterType": "PERCENT_PRICE" +  } +``` + +`PERCENT_PRICE`过滤器基于指数价格来定义价格的有效范围。 + +为了通过"价格百分比"，"价格"必须符合以下条件： + +* `price` <=`indexPrice` *`multiplierUp` +* `price`> =`indexPrice` *`multiplierDown` + + +#### LOT_SIZE 订单尺寸 + +> **/exchangeInfo 响应中的格式:** +```javascript + { + "stepSize": "0.00100000", +   "filterType": "LOT_SIZE", + "maxQty": "100000.00000000", +   "minQty": "0.00100000" + } +``` + +Lots是拍卖术语，`LOT_SIZE` 过滤器对订单中的 `quantity` 也就是数量参数进行合法性检查。包含三个部分: + +* `minQty` 表示 `quantity` 允许的最小值。 +* `maxQty` 表示 `quantity` 允许的最大值。 +* `stepSize` 表示 `quantity` 允许的步进值。 + +逻辑伪代码如下: + +* `quantity` >= `minQty` +* `quantity` <= `maxQty` +* (`quantity`-`minQty`) % `stepSize` == 0 + + + + +#### MARKET_LOT_SIZE 市价订单尺寸 + +> ***/exchangeInfo 响应中的格式:** +```javascript + { + "stepSize": "0.00100000", +   "filterType": "MARKET_LOT_SIZE" + "maxQty": "100000.00000000", + "minQty": "0.00100000" + } +``` + + +`MARKET_LOT_SIZE`过滤器为交易对上的`MARKET`订单定义了`数量`(即拍卖中的"手数")规则。 共有3部分： + +* `minQty`定义了允许的最小`quantity`。 +* `maxQty`定义了允许的最大数量。 +* `stepSize`定义了可以增加/减少数量的间隔。 + +为了通过`market lot size`，`quantity`必须满足以下条件： + +* `quantity` >= `minQty` +* `quantity` <= `maxQty` +* (`quantity`-`minQty`) % `stepSize` == 0 + + +#### predictionEvents 预测事件 + +> ***/exchangeInfo 响应中的格式:** +```javascript +"predictionEvents": [ + { + "eventName": "ETH_UP_DOWN_7D", //预测事件 + "oracleSymbol": "ETHUSDT", //预测的SYMBOL + "predictionType": "UP_DOWN", //预测类型 + "sides": [ + "UP", + "DOWN" + ], //预测方向 + "period": "10080M", //预测周期 单位分钟 + "startTime": 1778476080000, //预测事件的开始时间 + "endTime": 1780376880000, //预测事件的结束时间 + "status": "LIVE", //预测事件的状态 + "currentRoundId": 3, //预测事件当前轮次 + "orderTypes": [ + "LIMIT", + "MARKET" + ], //预测事件的订单类型 + "timeInForce": [ + "GTC", + "IOC", + "FOK", + "GTX" + ], //预测事件的TIF + "liveRound":{ + "marketName": "USD1_UP_DOWN_5M_1778483280", //预测市场的名字 + "symbolIds": [ + "USD1_UP_DOWN_5M_1778483280_YUSDT", + "USD1_UP_DOWN_5M_1778483280_NUSDT" + ], // 预测市场的2个SYMBOL,Y代表上涨,N代表下跌 + "assetIds": [ + "USD1_UP_DOWN_5M_1778483280_Y", + "USD1_UP_DOWN_5M_1778483280_N" + ], // 预测市场的2个Asset,Y代表上涨,N代表下跌 + "roundId": 2, //预测市场的轮次ID + "tradingStartTime": 1778482970000, //预测市场的开始交易时间 + "tradingEndTime": 1778483520000, //预测市场的结束交易时间 + "windowStartTime": 1778483280000, //预测市场的窗口开始时间 + "windowEndTime": 1778483580000, //预测市场的窗口结束时间 + "roundStatus": "SETTLED", //预测市场的状态 + "openPrice": "0.99920000", //预测市场的开始价格 + "endPrice": "0.99910000", //预测市场的结束价格 + "winAsset": "USD1_UP_DOWN_5M_1778483280_N", //预测市场的获胜资产 如果上涨则是Y,如果下跌是N + "settleTime": 1778483582057, //预测市场的结算时间 + "settleHash": "0x3bc0aff52472dafd4b70d3423386a2dabf675fe7cd604e92391e2a4702cf0980" //预测市场的结算链上Hash + }, + "rounds": [ + { + "marketName": "USD1_UP_DOWN_5M_1778483280", //预测市场的名字 + "symbolIds": [ + "USD1_UP_DOWN_5M_1778483280_YUSDT", + "USD1_UP_DOWN_5M_1778483280_NUSDT" + ], // 预测市场的2个SYMBOL,Y代表上涨,N代表下跌 + "assetIds": [ + "USD1_UP_DOWN_5M_1778483280_Y", + "USD1_UP_DOWN_5M_1778483280_N" + ], // 预测市场的2个Asset,Y代表上涨,N代表下跌 + "roundId": 2, //预测市场的轮次ID + "tradingStartTime": 1778482970000, //预测市场的开始交易时间 + "tradingEndTime": 1778483520000, //预测市场的结束交易时间 + "windowStartTime": 1778483280000, //预测市场的窗口开始时间 + "windowEndTime": 1778483580000, //预测市场的窗口结束时间 + "roundStatus": "SETTLED", //预测市场的状态 + "openPrice": "0.99920000", //预测市场的开始价格 + "endPrice": "0.99910000", //预测市场的结束价格 + "winAsset": "USD1_UP_DOWN_5M_1778483280_N", //预测市场的获胜资产 如果上涨则是Y,如果下跌是N + "settleTime": 1778483582057, //预测市场的结算时间 + "settleHash": "0x3bc0aff52472dafd4b70d3423386a2dabf675fe7cd604e92391e2a4702cf0980" //预测市场的结算链上Hash + } + ] + } +] +``` + +`status` 为事件的状态 + +Status | Description +-----------| -------------- +`LIVE` | 正在运行。 +`CLOSED` | INVALID。 +`INVALID` | 无效。 + +`roundStatus` 为市场的状态 + +RoundStatus | Description +-----------| -------------- +`PREMARKET` | 预先准备好的市场(可以提前交易) +`TRADING` | 交易中的市场 +`SETTLED` | 已结算的市场 + +* 结算完成一段时间(24H)后，会自动下架，下架后的市场不再展示 +* `status` 为`CLOSED`或者`INVALID`的事件对应的市场，只能下reduceOnly的Market Sell订单 + +# 行情接口 + +## Noop + +> **Response:** + +```javascript +{ + "code": 200, + "msg": "success" +} +``` + +``POST /api/v3/noop`` + +通过此请求，可以高效取消已发送但仍在队列中且尚未完成链上操作的交易（Nonce需与该请求一致,不保证成功） + +**Weight:** +1 + +## 测试服务器连通性 +> **响应** +```javascript +{} +``` +`` +GET /api/v3/ping +`` + +测试能否联通 Rest API。 + +**权重:** +1 + +**参数:** +NONE + + +## 获取服务器时间 +> **响应** +```javascript +{ + "serverTime": 1499827319559 +} +``` +`` +GET /api/v3/time +`` + +测试能否联通 Rest API 并获取服务器时间。 + +**权重:** +1 + +**参数:** +NONE + + +## 交易规范信息 + +> **响应** + +```javascript     +{ + "timezone": "UTC", + "serverTime": 1756197279679, + "rateLimits": [{ + "rateLimitType": "REQUEST_WEIGHT", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 6000 + }, + { + "rateLimitType": "ORDERS", + "interval": "MINUTE", + "intervalNum": 1, + "limit": 6000 + }, + { + "rateLimitType": "ORDERS", + "interval": "SECOND", + "intervalNum": 10, + "limit": 300 + } + ], + "exchangeFilters": [], + "assets": [{ + "asset": "USD" + }, { + "asset": "USDT" + }, + { + "asset": "BNB" + } + ], + "symbols": [{ + "status": "TRADING", + "baseAsset": "BNB", + "quoteAsset": "USDT", + "pricePrecision": 8, + "quantityPrecision": 8, + "baseAssetPrecision": 8, + "quotePrecision": 8, + "filters": [{ + "minPrice": "0.01000000", + "maxPrice": "100000", + "filterType": "PRICE_FILTER", + "tickSize": "0.01000000" + }, + { + "stepSize": "0.00100000", + "filterType": "LOT_SIZE", + "maxQty": "1000", + "minQty": "1" + }, + { + "stepSize": "0.00100000", + "filterType": "MARKET_LOT_SIZE", + "maxQty": "900000", + "minQty": "0.00100000" + }, + { + "limit": 200, + "filterType": "MAX_NUM_ORDERS" + }, + { + "minNotional": "5", + "filterType": "MIN_NOTIONAL" + }, + { + "maxNotional": "100", + "filterType": "MAX_NOTIONAL" + }, + { + "maxNotional": "100", + "minNotional": "5", + "avgPriceMins": 5, + "applyMinToMarket": true, + "filterType": "NOTIONAL", + "applyMaxToMarket": true + }, + { + "multiplierDown": "0", + "multiplierUp": "5", + "multiplierDecimal": "0", + "filterType": "PERCENT_PRICE" + }, + { + "bidMultiplierUp": "5", + "askMultiplierUp": "5", + "bidMultiplierDown": "0", + "avgPriceMins": 5, + "multiplierDecimal": "0", + "filterType": "PERCENT_PRICE_BY_SIDE", + "askMultiplierDown": "0" + } + ], + "orderTypes": [ + "LIMIT", + "MARKET", + "STOP", + "STOP_MARKET", + "TAKE_PROFIT", + "TAKE_PROFIT_MARKET" + ], + "timeInForce": [ + "GTC", + "IOC", + "FOK", + "GTX", + "HIDDEN" + ], + "symbol": "BNBUSDT", + "ocoAllowed": false + }] +} +``` + +`` +GET /api/v3/prediction/exchangeInfo +`` + +获取交易规则和交易对信息。 + +**权重:** +1 + +**参数:** +无 + + +## 深度信息 + +> **响应** + +```javascript +{ + "lastUpdateId": 1027024, + "E":1589436922972, // 消息时间 + "T":1589436922959, // 撮合引擎时间 + "bids": [ + [ + "4.00000000", // 价位 + "431.00000000" // 挂单量 + ] + ], + "asks": [ + [ + "4.00000200", + "12.00000000" + ] + ] +} +``` +`` +GET /api/v3/depth +`` + +**权重:** + +基于限制调整: + +限制 | 权重 +------------ | ------------ +5, 10, 20, 50 | 2 +100 | 5 +500 | 10 +1000 | 20 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +limit | INT | NO | 默认 100. 可选值:[5, 10, 20, 50, 100, 500, 1000] + + +## 近期成交列表 + +> **响应** + +```javascript +[ + { + "id": 657, + "price": "1.01000000", + "qty": "5.00000000", + "baseQty": "4.95049505", + "time": 1755156533943, + "isBuyerMaker": false + } +] +``` +`` +GET /api/v3/trades +`` + +获取近期成交 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +limit | INT | NO | 默认 500；最大1000 + + +## 查询历史成交 (MARKET_DATA) + +> **响应** + +```javascript +[ + { + "id": 1140, + "price": "1.10000000", + "qty": "7.27200000", + "baseQty": "6.61090909", + "time": 1756094288700, + "isBuyerMaker": false + } +] +``` +`` +GET /api/v3/historicalTrades +`` + +获取历史成交。 + +**权重:** +20 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +limit | INT | NO | 默认 500; 最大值 1000. +fromId | LONG | NO | 从哪一条成交id开始返回. 缺省返回最近的成交记录。 + + +## 近期成交(归集) + +> **响应** + +```javascript +[ + { + "a": 26129, // 归集成交ID + "p": "0.01633102", // 成交价 + "q": "4.70443515", // 成交量 + "f": 27781, // 被归集的首个成交ID + "l": 27781, // 被归集的末个成交ID + "T": 1498793709153, // 成交时间 + "m": true, // 是否为主动卖出单 + } +] +``` +`` +GET /api/v3/aggTrades +`` + +归集交易与逐笔交易的区别在于，同一价格、同一方向、同一时间的trade会被聚合为一条 + +**权重:** +20 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +fromId | LONG | NO | 从包含fromId的成交id开始返回结果 +startTime | LONG | NO | 从该时刻之后的成交记录开始返回结果 +endTime | LONG | NO | 返回该时刻为止的成交记录 +limit | INT | NO | 默认 500; 最大 1000. +* 如果发送startTime和endTime，间隔必须小于一小时。 +* 如果没有发送任何筛选参数(fromId, startTime,endTime)，默认返回最近的成交记录 + + +## K线数据 + +> **响应** +```javascript +[ + [ + 1499040000000, // 开盘时间 + "0.01634790", // 开盘价 + "0.80000000", // 最高价 + "0.01575800", // 最低价 + "0.01577100", // 收盘价(当前K线未结束的即为最新价) + "148976.11427815", // 成交量 + 1499644799999, // 收盘时间 + "2434.19055334", // 成交额 + 308, // 成交笔数 + "1756.87402397", // 主动买入成交量 + "28.46694368", // 主动买入成交额 + ] +] +``` +`` +GET /api/v3/klines +`` + +每根K线代表一个交易对。 +每根K线的开盘时间可视为唯一ID + + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +interval | ENUM | YES | 详见枚举定义：K线间隔 +startTime | LONG | NO | +endTime | LONG | NO | +limit | INT | NO | 默认 500; 最大 1500. +* 如果未发送 startTime 和 endTime ，默认返回最近的交易。 + + + +## 24hr 价格变动情况 + +> **响应** + +```javascript +{ + "symbol": "BTCUSDT", + "priceChange": "-94.99999800", //24小时价格变动 + "priceChangePercent": "-95.960", //24小时价格变动百分比 + "weightedAvgPrice": "0.29628482", //加权平均价 + "prevClosePrice": "3.89000000", //上一次结束价格 + "lastPrice": "4.00000200", //最近一次成交价 + "lastQty": "200.00000000", //最近一次成交额 + "bidPrice": "866.66000000", //最高的买入价格 + "bidQty": "72.05100000", //最高的买入价格的数量 + "askPrice": "866.73000000", //最低的卖出价 + "askQty": "1.21700000", //最低的卖出价格的数量 + "openPrice": "99.00000000", //24小时内第一次成交的价格 + "highPrice": "100.00000000", //24小时最高价 + "lowPrice": "0.10000000", //24小时最低价 + "volume": "8913.30000000", //24小时成交量 + "quoteVolume": "15.30000000", //24小时成交额 + "openTime": 1499783499040, //24小时内，第一笔交易的发生时间 + "closeTime": 1499869899040, //24小时内，最后一笔交易的发生时间 + "firstId": 28385, // 首笔成交id + "lastId": 28460, // 末笔成交id + "count": 76, // 成交笔数 + "baseAsset": "BTC", //基础代币 + "quoteAsset": "USDT" //报价代币 +} +``` + +`` +GET /api/v3/ticker/24hr +`` + +24 小时滚动窗口价格变动数据。 请注意，不携带symbol参数会返回全部交易对数据，此时返回的数据为示例相应的数组，不仅数据庞大，而且权重极高 + +**权重:** +1 单一交易对; +**40** 交易对参数缺失; + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | +* 请注意，不携带symbol参数会返回全部交易对数据 + +## 最新价格 + +> **响应** + +```javascript +{ + "symbol": "ADAUSDT", + "price": "1.30000000", + "time": 1649666690902 +} +``` + +> OR + +```javascript +[ + { + "symbol": "ADAUSDT", + "price": "1.30000000", + "time": 1649666690902 + } +] +``` + +`` +GET /api/v3/ticker/price +`` + +获取交易对最新价格 + +**权重:** +1 单一交易对; +**2** 交易对参数缺失; + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | +* 不发送交易对参数，则会返回所有交易对信息 + + +## 当前最优挂单 +> **响应** +```javascript +{ + "symbol": "LTCBTC", + "bidPrice": "4.00000000", + "bidQty": "431.00000000", + "askPrice": "4.00000200", + "askQty": "9.00000000" + "time": 1589437530011 // 交易时间 +} +``` +> OR +```javascript +[ + { + "symbol": "LTCBTC", + "bidPrice": "4.00000000", + "bidQty": "431.00000000", + "askPrice": "4.00000200", + "askQty": "9.00000000", + "time": 1589437530011 // 交易时间 + } +] +``` + +`` +GET /api/v3/ticker/bookTicker +`` + +返回当前最优的挂单(最高买单，最低卖单) + +**权重:** +1 单一交易对; +**2** 交易对参数缺失; + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | +* 不发送交易对参数，则会返回所有交易对信息 + +## 获取Symbol手续费 + +> **响应** + +```javascript +{ + "symbol": "APXUSDT", + "makerCommissionRate": "0.000200",     + "takerCommissionRate": "0.000700", + "settlementFeeRate": "0.000700" +} +``` +`` +GET /api/v3/commissionRate +`` + +获取Symbol手续费。 + +**权重:** +20 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | + + + + + +# 现货账户和交易接口 + + +## 下单 (TRADE) + +> **Response ACK:** + +```javascript +{ + "symbol": "BTCUSDT", // 交易对 + "orderId": 28, // 系统的订单ID + "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", // 客户自己设置的ID + "updateTime": 1507725176595, // 交易的时间戳 + "price": "0.00000000", // 订单价格 + "avgPrice": "0.0000000000000000", //平均价格 + "origQty": "10.00000000", // 用户设置的原始订单数量 + "cumQty": "0", //累计数量 + "executedQty": "10.00000000", // 交易的订单数量 + "cumQuote": "10.00000000", // 累计交易的金额 + "status": "FILLED", // 订单状态 + "timeInForce": "GTC", // 订单的时效方式 + "stopPrice": "0", //触发价格 + "origType": "LIMIT", //触发前订单类型 + "type": "LIMIT", // 订单类型， 比如市价单，现价单等 + "side": "SELL", // 订单方向，买还是卖 +} +``` + +`` +POST /api/v3/order `` + +发送下单。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +side | ENUM | YES | 详见枚举定义：订单方向 +type | ENUM | YES | 详见枚举定义：订单类型 +timeInForce | ENUM | NO | 详见枚举定义：有效方式 +quantity | DECIMAL | NO | +quoteOrderQty|DECIMAL|NO| +price | DECIMAL | NO | +newClientOrderId | STRING | NO | 客户自定义的唯一订单ID。 如果未发送，则自动生成 +stopPrice | DECIMAL | NO | 仅 `STOP`, `STOP_MARKET` , `TAKE_PROFIT`,`TAKE_PROFIT_MARKET` 需要此参数。 + +基于订单 `type`不同，强制要求某些参数: + +类型 | 强制要求的参数 +------------ | ------------ +`LIMIT` | `timeInForce`, `quantity`, `price` +`MARKET` | `quantity` 或 `quoteOrderQty` +`STOP`和`TAKE_PROFIT` | `quantity`, `price`, `stopPrice` +`STOP_MARKET`和`TAKE_PROFIT_MARKET` | `quantity`, `stopPrice` + +其他信息: + +* 下`MARKET` `SELL`市价单，用户通过`QUANTITY`控制想用市价单卖出的基础资产数量。 + * 比如在`BTCUSDT`交易对上下一个`MARKET` `SELL`市价单, 通过`QUANTITY`让用户指明想卖出多少BTC。 +* 下`MARKET` `BUY`的市价单，用户使用 `quoteOrderQty` 控制想用市价单买入的报价资产数量，`QUANTITY`将由系统根据市场流动性计算出来。 +  * 比如在`BTCUSDT`交易对上下一个`MARKET` `BUY`市价单, 通过`quoteOrderQty`让用户选择想使用多少USDT买入BTC。 +* 使用 `quoteOrderQty` 的市价单`MARKET`不会突破`LOT_SIZE`的限制规则; 报单会按给定的`quoteOrderQty`尽可能接近地被执行。 +* 除非之前的订单已经成交, 不然设置了相同的`newClientOrderId`订单会被拒绝。 + + + +## 撤销订单 (TRADE) + +> **响应** + +```javascript +{ + "symbol": "BTCUSDT", // 交易对 + "orderId": 28, // 系统的订单ID + "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", // 客户自己设置的ID + "updateTime": 1507725176595, // 交易的时间戳 + "price": "0.00000000", // 订单价格 + "avgPrice": "0.0000000000000000", //平均价格 + "origQty": "10.00000000", // 用户设置的原始订单数量 + "cumQty": "0", //累计数量 + "executedQty": "10.00000000", // 交易的订单数量 + "cumQuote": "10.00000000", // 累计交易的金额 + "status": "CANCELED", // 订单状态 + "timeInForce": "GTC", // 订单的时效方式 + "stopPrice": "0", //触发价格 + "origType": "LIMIT", //触发前订单类型 + "type": "LIMIT", // 订单类型， 比如市价单，现价单等 + "side": "SELL", // 订单方向，买还是卖 +} +``` + +`` +DELETE /api/v3/order `` + +取消有效订单。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +orderId | LONG | NO | +origClientOrderId | STRING | NO | + +`orderId` 或 `origClientOrderId` 必须至少发送一个 + +## 查询订单 (USER_DATA) + +> **响应** +```javascript +{ + "orderId": 38,   // 系统订单号 + "symbol": "ADA25SLP25",  // 交易对 + "status": "FILLED",  // 订单状态 + "clientOrderId": "afMd4GBQyHkHpGWdiy34Li",  // 用户自定义的订单号 + "price": "20",  // 委托价格 + "avgPrice": "12.0000000000000000",  // 平均成交价 + "origQty": "10",  // 原始委托数量 + "executedQty": "10",  // 成交量 + "cumQuote": "120",  // 成交金额 + "timeInForce": "GTC",  // 有效方法 + "type": "LIMIT",  // 订单类型 + "side": "BUY",  // 买卖方向 + "stopPrice": "0",  // 触发价 + "origType": "LIMIT",  // 触发前订单类型 + "time": 1649913186270,  // 订单时间 + "updateTime": 1649913186297  // 更新时间 +} +``` + +`` +GET /api/v3/order`` + +查询订单状态。 + +* 请注意，如果订单满足如下条件，不会被查询到： + * 订单的最终状态为 `CANCELED` 或者 `EXPIRED`, **并且** + * 订单没有任何的成交记录, **并且** + * 订单生成时间 + 7天 < 当前时间 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +orderId | LONG | NO | +origClientOrderId | STRING | NO | + +注意: + +* 至少需要发送 `orderId` 与 `origClientOrderId`中的一个 + + +## 查询当前挂单 (USER_DATA) + +> **响应** +```javascript +{ + "orderId": 38,   // 系统订单号 + "symbol": "ADA25SLP25",  // 交易对 + "status": "NEW",  // 订单状态 + "clientOrderId": "afMd4GBQyHkHpGWdiy34Li",  // 用户自定义的订单号 + "price": "20",  // 委托价格 + "avgPrice": "12.0000000000000000",  // 平均成交价 + "origQty": "10",  // 原始委托数量 + "executedQty": "10",  // 成交量 + "cumQuote": "120",  // 成交金额 + "timeInForce": "GTC",  // 有效方法 + "type": "LIMIT",  // 订单类型 + "side": "BUY",  // 买卖方向 + "stopPrice": "0",  // 触发价 + "origType": "LIMIT",  // 触发前订单类型 + "time": 1649913186270,  // 订单时间 + "updateTime": 1649913186297  // 更新时间 +} +``` + +`` +GET /api/v3/openOrder`` + +查询订单状态。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +orderId | LONG | NO | +origClientOrderId | STRING | NO | + +注意: + +* 至少需要发送 `orderId` 与 `origClientOrderId`中的一个 + + +## 当前所有挂单 (USER_DATA) + +> **响应** + +```javascript +[ + { + "orderId": 349661, // 系统订单号 + "symbol": "BNBUSDT", // 交易对 + "status": "NEW", // 订单状态 + "clientOrderId": "LzypgiMwkf3TQ8wwvLo8RA", // 用户自定义的订单号 + "price": "1.10000000", // 委托价格 + "avgPrice": "0.0000000000000000", // 平均成交价 + "origQty": "5",  // 原始委托数量 + "executedQty": "0", // 成交量 + "cumQuote": "0", // 成交金额 + "timeInForce": "GTC", // 有效方法 + "type": "LIMIT", // 订单类型 + "side": "BUY", // 买卖方向 + "stopPrice": "0", // 触发价 + "origType": "LIMIT", // 触发前订单类型 + "time": 1756252940207, // 订单时间 + "updateTime": 1756252940207, // 更新时间 + } +] +``` + +`` +GET /api/v3/openOrders `` + +获取交易对的所有当前挂单， 请小心使用不带交易对参数的调用。 + +**权重:** +- 带symbol ***1*** +- 不带 ***40***   + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | + +* 不带symbol参数，会返回所有交易对的挂单 + + + +## 取消当前所有挂单 (USER_DATA) + +> **响应** + +```javascript +{ + "code": 200, + "msg": "The operation of cancel all open order is done." +} +``` + +`` +DEL /api/v3/allOpenOrders `` + +**权重:** +- ***1*** + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +orderIdList | STRING | NO | id数组字符串 +origClientOrderIdList | STRING | NO | clientOrderId数组字符串 + + +## 查询所有订单 (USER_DATA) +> **响应** +```javascript +[ + { + "orderId": 349661, // 系统订单号 + "symbol": "BNBUSDT", // 交易对 + "status": "NEW", // 订单状态 + "clientOrderId": "LzypgiMwkf3TQ8wwvLo8RA", // 用户自定义的订单号 + "price": "1.10000000", // 委托价格 + "avgPrice": "0.0000000000000000", // 平均成交价 + "origQty": "5",  // 原始委托数量 + "executedQty": "0", // 成交量 + "cumQuote": "0", // 成交金额 + "timeInForce": "GTC", // 有效方法 + "type": "LIMIT", // 订单类型 + "side": "BUY", // 买卖方向 + "stopPrice": "0", // 触发价 + "origType": "LIMIT", // 触发前订单类型 + "time": 1756252940207, // 订单时间 + "updateTime": 1756252940207, // 更新时间 + } +] +``` + +`` +GET /api/v3/allOrders`` + +获取所有帐户订单； 有效，已取消或已完成。 + +* 请注意，如果订单满足如下条件，不会被查询到： + * 订单生成时间 + 7天 < 当前时间 + +**权重:** +5 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | +orderId | LONG | NO | +startTime | LONG | NO | +endTime | LONG | NO | +limit | INT | NO | 默认 500; 最大 1000. + +* 查询时间范围最大不得超过7天 +* 默认查询最近7天内的数据 + + + +`` +GET /api/v3/transactionHistory`` +> **响应** + +```javascript +[ + { + "tranId": 1759115482304540227, //划转ID + "tradeId": null, //流水ID + "asset": "ASTER", //资产 + "symbol": "", //交易对 + "balanceDelta": "-500.00000000", //资金流数量，正数代表流入，负数代表流出 + "balanceInfo": "TRADE_SOURCE", //流水描述 + "time": 1759115482000, // 时间 + "type": "TRADE_SOURCE" //资金流类型 + } +] +``` + +查询交易流水 + +**权重:** +30 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +asset | STRING | NO | 资产 +type | STRING | NO | 类别 +startTime | LONG | NO | 开始时间 +endTime | LONG | NO | 结束时间 +limit | LONG | NO | 返回的结果集数量 默认值:100 最大值:1000 + +注意: + +* `type` 取值 `TRADE_TARGET`,`TRADE_SOURCE`,`TRANSFER_SPOT_TO_FUTURE`,`TRANSFER_FUTURE_TO_SPOT`,`TRANSFER_SPOT_TO_SPOT`,`AIRDROP`,`DIVIDEND`,`TRANSFER_REFUND`,`INTERNAL_TRANSFER`,`TRANSFER`,`SWAP`,`COMMISSION_REBATE`,`CASH_BACK`,`STAKING_WITHDRAW`, `STAKING_CLAIM`, `STAKING_DELEGATE` 中的一种 +* 如果`startTime` 和 `endTime` 均未发送, 只会返回最近7天的数据。 + +## 期货现货互转 (TRADE) + +> **响应:** + +```javascript +{ + "tranId": 21841, //交易id + "status": "SUCCESS" //状态 +} +``` + +`` +POST /api/v3/asset/wallet/transfer `` + +**权重:** +5 + +**参数:** + + +名称 | 类型 | 是否必需 | 描述 +---------------- | ------- | -------- | ---- +amount | DECIMAL | YES | 数量 +asset | STRING | YES | 资产 +clientTranId | STRING | YES | 交易id +kindType | STRING | YES | 交易类型 + +注意: +* kindType 取值为FUTURE_SPOT(期货转现货),SPOT_FUTURE(现货转期货) + +## 预测市场铸造 (TRADE) + +> **响应** + +```javascript +{ + "clientOrderId": "xxx", // 客户自定义订单ID + "quoteAmount": "10.00000000", // 花费的报价资产总量 + "yesPrice": "0.55000000", // 铸造时YES代币的价格 + "noPrice": "0.45000000", // 铸造时NO代币的价格（yesPrice + noPrice = 1） + "pairCount": "10.00000000" // 已铸造的YES+NO代币对数量 +} +``` + +`` +POST /api/v3/prediction/mint`` + +为预测市场铸造 YES+NO 代币对。铸造时系统按当前市场价格扣除等值报价资产，同时向账户发放等量的 YES 和 NO 代币。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | 预测市场的 YES 代币交易对 +quantity | DECIMAL | YES | 铸造的 YES+NO 代币对数量 +newClientOrderId | STRING | NO | 客户自定义的唯一订单ID，若不填则自动生成 + +注意: +* `symbol` 必须是有效的预测市场代币交易对，且状态为 `TRADING` 或 `PENDING_TRADING` +* `quantity` 表示同时铸造的 YES 和 NO 代币对数量，铸造后账户将获得等量的 YES 代币和 NO 代币 +* `yesPrice` + `noPrice` = 1（报价资产单位） + + +## 预测市场销毁 (TRADE) + +> **响应** + +```javascript +{ + "clientOrderId": "xxx", // 客户自定义订单ID + "quoteAmount": "9.80000000", // 销毁后返还的报价资产总量 + "yesPrice": null, // 销毁操作不返回价格 + "noPrice": null, // 销毁操作不返回价格 + "pairCount": "10.00000000" // 已销毁的YES+NO代币对数量 +} +``` + +`` +POST /api/v3/prediction/burn`` + +销毁等量的 YES+NO 代币对，赎回相应的报价资产。账户需同时持有等量的 YES 代币和 NO 代币才可销毁。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | YES | 预测市场的 YES 代币交易对 +quantity | DECIMAL | YES | 销毁的 YES+NO 代币对数量 +newClientOrderId | STRING | NO | 客户自定义的唯一订单ID，若不填则自动生成 + +注意: +* `symbol` 必须是有效的预测市场代币交易对，且状态为 `TRADING`、`PENDING_TRADING` 或 `CLOSED` +* `quantity` 表示同时销毁的 YES 和 NO 代币对数量，账户需同时持有对应数量的 YES 代币和 NO 代币 +* 销毁操作响应中 `yesPrice` 和 `noPrice` 为 null +* 市场关闭（`CLOSED`）后仍可进行销毁操作 + + +## 查询预测市场当前仓位 (USER_DATA) + +> **响应** +```javascript +[ + { + "marketName": "BTC_UP_DOWN_20260512", // 预测市场名称 + "symbol": "BTC_UP_DOWN_20260512YES", // 交易对 + "assetName": "USDT", // 结算资产 + "type": "YES", // 持仓方向: "YES" 或 "NO" + "openAvgPrice": "0.65000000", // 开仓均价 + "cumQty": "100.00000000", // 持仓总数量 + "closeAvgPrice": "0.00000000", // 平仓均价（尚未平仓则为0） + "realizedPnl": "0.00000000", // 已实现盈亏 + "closeQty": "0.00000000", // 已平仓数量 + "insertTime": 1747000000000, // 开仓时间（毫秒时间戳） + "commissionFee": "0.10000000", // 手续费 + "commissionAsset": "USDT", // 手续费资产 + "balance": "65.00000000", // 仓位价值（持仓数量 × 开仓均价） + "availableBalance": "65.00000000", // 可用余额 + } +] +``` + +`` +GET /api/v3/prediction/positions +`` + +查询当前账户的预测市场持仓列表。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | 交易对，不传则返回所有持仓 +signer | STRING | YES | API钱包地址 +nonce | STRING | YES | 当前时间的微秒值 +signature | STRING | YES | 签名 + + +## 查询预测市场历史仓位 (USER_DATA) + +> **响应** +```javascript +[ + { + "marketName": "BTC_UP_DOWN_20260501", // 预测市场名称 + "symbol": "BTC_UP_DOWN_20260501YES", // 交易对 + "asset": "USDT", // 结算资产 + "type": "YES", // 持仓方向: "YES" 或 "NO" + "openAvgPrice": "0.72000000", // 开仓均价 + "cumQty": "200.00000000", // 持仓总数量 + "closeAvgPrice": "1.00000000", // 平仓均价 + "realizedPnl": "56.00000000", // 已实现盈亏 + "closeQty": "200.00000000", // 已平仓数量 + "insertTime": 1746000000000, // 开仓时间（毫秒时间戳） + "closeTime": 1746086400000, // 平仓/结算时间（毫秒时间戳） + "status": "settled", // 仓位状态: "close"（手动平仓）或 "settled"（市场结算） + "commissionFee": "0.10000000", // 手续费 + "commissionAsset": "USDT", // 手续费资产 + "settleFee": "2.00000000", // 结算手续费（仅 status 为 "settled" 时存在） + "settleAsset": "USDT", // 结算手续费资产 + } +] +``` + +`` +GET /api/v3/prediction/positionHistories +`` + +查询当前账户的预测市场历史仓位列表（已平仓或已结算）。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | 交易对，不传则返回所有历史仓位 +startTime | LONG | NO | 开始时间（毫秒时间戳） +endTime | LONG | NO | 结束时间（毫秒时间戳） +limit | INT | NO | 返回数量，默认100，最大1000 +signer | STRING | YES | API钱包地址 +nonce | STRING | YES | 当前时间的微秒值 +signature | STRING | YES | 签名 + +注意: +* `startTime` 与 `endTime` 同时传入时，`startTime` 不得大于 `endTime` +* `limit` 取值范围为 1 ~ 1000，默认值为 100 +* `status` 字段说明: `close` 表示用户手动平仓，`settled` 表示预测市场到期结算 + +## 查询预测市场结算历史 (USER_DATA) + +> **响应** +```javascript +[ + { + "marketName": "BTC_UP_DOWN_20260501", // 预测市场名称 + "asset": "BTC_UP_DOWN_20260501YES", // 代币资产（YES 或 NO 代币） + "symbol": "BTC_UP_DOWN_20260501YES", // 交易对 + "marketStartTime": 1746000000000, // 市场开始时间（毫秒时间戳） + "marketEndTime": 1746086400000, // 市场结束/结算时间（毫秒时间戳） + "shareAmount": "200.00000000", // 结算时持有的份额数量 + "settleAsset": "USDT", // 结算资产 + "settleAmount": "200.00000000", // 结算获得金额 + "settleFeeAmount": "2.00000000", // 结算手续费 + "entryPrice": "0.72000000", // 平均入场价格 + "settlePrice": "1.00000000", // 最终结算价格 + "realizedPnl": "56.00000000", // 结算后已实现盈亏 + "status": "settled" // 结算状态 + } +] +``` + +`` +GET /api/v3/prediction/settlementHistories +`` + +查询当前账户的预测市场结算历史（已到期结算的市场）。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | 交易对，不传则返回所有结算记录 +startTime | LONG | NO | 按市场开始时间过滤（毫秒时间戳） +endTime | LONG | NO | 按市场结束时间过滤（毫秒时间戳） +limit | INT | NO | 返回数量，默认100，最大1000 +signer | STRING | YES | API钱包地址 +nonce | STRING | YES | 当前时间的微秒值 +signature | STRING | YES | 签名 + +注意: +* `startTime` 与 `endTime` 同时传入时，`startTime` 不得大于 `endTime` +* `limit` 取值范围为 1 ~ 1000，默认值为 100 +* `settleAmount` 为结算总收入，`realizedPnl` = `settleAmount` 减去成本 +* `settleFeeAmount` 从结算收入中扣除 + +## 现货提现手续费 (NONe) +> **响应** +```javascript +{ + "tokenPrice": 1.00019000, + "gasCost": 0.5000, + "gasUsdValue": 0.5 +} +``` + +`` +GET /api/v3/aster/withdraw/estimateFee +`` + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +chainId | STRING | YES | +asset | STRING | YES | + +注意: +* chainId: 1(ETH),56(BSC),42161(Arbi) +* gasCost: 提现所需的最少数量的手续费 + +## 现货提现 (USER_DATA) +> **响应** +```javascript +{ + "withdrawId": "1014729574755487744", + "hash":"0xa6d1e617a3f69211df276fdd8097ac8f12b6ad9c7a49ba75bbb24f002df0ebb" +} +``` + +`` +POST /api/v3/aster/user-withdraw`` + +**权重:** +5 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +chainId | STRING | YES | +asset | STRING | YES | +amount | STRING | YES | +fee | STRING | YES | +receiver | STRING | YES | +nonce | STRING | YES | 当前时间的微秒值 +userSignature | STRING | YES | + +注意: +* chainId: 1(ETH),56(BSC),42161(Arbi) +* receiver : 当前账户的地址 +* 如果期货余额不足，会从spot账户划转到期货账户，进行提现 +* userSignature demo + +```shell +const domain = { + name: 'Aster', + version: '1', + chainId: 56, + verifyingContract: ethers.ZeroAddress, + } + +const currentTime = Date.now() * 1000 + +const types = { + Action: [ + {name: "type", type: "string"}, + {name: "destination", type: "address"}, + {name: "destination Chain", type: "string"}, + {name: "token", type: "string"}, + {name: "amount", type: "string"}, + {name: "fee", type: "string"}, + {name: "nonce", type: "uint256"}, + {name: "aster chain", type: "string"}, + ], + } + const value = { + 'type': 'Withdraw', + 'destination': '0xD9cA6952F1b1349d27f91E4fa6FB8ef67b89F02d', + 'destination Chain': 'BSC', + 'token': 'USDT', + 'amount': '10.123400', + 'fee': '1.234567891', + 'nonce': currentTime, + 'aster chain': 'Mainnet', + } + + +const signature = await signer.signTypedData(domain, types, value) +``` + +## 账户信息 (USER_DATA) +> **响应** +```javascript +{ + "feeTier": 0, + "canTrade": true, + "canDeposit": true, + "canWithdraw": true, + "canBurnAsset": true, + "updateTime": 0, +   "balances": [ + { + "asset": "BTC", + "free": "4723846.89208129", + "locked": "0.00000000" + }, + { + "asset": "LTC", + "free": "4763368.68006011", + "locked": "0.00000000" + } + ] +} +``` + +`` +GET /api/v3/account`` + +获取当前账户信息。 + +**权重:** +5 + +**参数:** + +名称 | 类型 | 是否必需| 描述 +------------ | ------------ | ------------ | ------------ + + +## 账户成交历史 (USER_DATA) +> **响应** +```javascript +[ + { + "symbol": "BNBUSDT", + "id": 1002, + "orderId": 266358, + "side": "BUY", + "price": "1", + "qty": "2", + "quoteQty": "2", + "commission": "0.00105000", + "commissionAsset": "BNB", + "time": 1755656788798, + "counterpartyId": 19, + "createUpdateId": null, + "maker": false, + "buyer": true + } +] +``` + +`` +GET /api/v3/userTrades `` + +获取账户指定交易对的成交历史 + +**权重:** +5 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +symbol | STRING | NO | +orderId|LONG|NO| 必须要和参数`symbol`一起使用. +startTime | LONG | NO | +endTime | LONG | NO | +fromId | LONG | NO | 起始Trade id。 默认获取最新交易。 +limit | INT | NO | 默认 500; 最大 1000. + +* 如果`startTime` 和 `endTime` 均未发送, 只会返回最近7天的数据。 +* startTime 和 endTime 的最大间隔为7天 +* 不能同时传`fromId`与`startTime` 或 `endTime` +       + + + + +--- +# Websocket 行情推送 + +* 本篇所列出的所有wss接口的baseurl为: **wss://sstream.asterdex.com** +* Streams有单一原始 stream 或组合 stream +* 单一原始 streams 格式为 **/ws/\** +* 组合streams的URL格式为 **/stream?streams=\/\/\** +* 订阅组合streams时，事件payload会以这样的格式封装: **{"stream":"\","data":\}** +* stream名称中所有交易对均为 **小写** +* 每个到 **sstream.asterdex.com** 的链接有效期不超过24小时，请妥善处理断线重连。 +* 每3分钟，服务端会发送ping帧，客户端应当在10分钟内回复pong帧，否则服务端会主动断开链接。允许客户端发送不成对的pong帧(即客户端可以以高于10分钟每次的频率发送pong帧保持链接)。 + +## 实时订阅/取消数据流 + +* 以下数据可以通过websocket发送以实现订阅或取消订阅数据流。示例如下。 +* 响应内容中的`id`是无符号整数，作为往来信息的唯一标识。 +* 如果相应内容中的 `result` 为 `null`，表示请求发送成功。 + + +### 订阅一个信息流 +> **响应** + ```javascript + { + "result": null, + "id": 1 + } + ``` +* **请求** + { + "method": "SUBSCRIBE", + "params": + [ + "btcusdt@aggTrade", + "btcusdt@depth" + ], + "id": 1 + } + + +### 取消订阅一个信息流 + +> **响应** + + ```javascript + { + "result": null, + "id": 312 + } + ``` + +* **请求** + { + "method": "UNSUBSCRIBE", + "params": + [ + "btcusdt@depth" + ], + "id": 312 + } + + +### 已订阅信息流 + +> **响应** + + ```javascript + { + "result": [ + "btcusdt@aggTrade" + ], + "id": 3 + } + ``` + +* **请求** + + { + "method": "LIST_SUBSCRIPTIONS", + "id": 3 + } + + +### 设定属性 +当前，唯一可以设置的属性是设置是否启用`combined`("组合")信息流。 +当使用`/ws/`("原始信息流")进行连接时，combined属性设置为`false`，而使用 `/stream/`进行连接时则将属性设置为`true`。 + +> **响应** + + ```javascript +{ + "result": null, + "id": 5 +} + ``` + +* **请求** + { + "method": "SET_PROPERTY", + "params": + [ + "combined", + true + ], + "id": 5 + } + + +### 检索属性 + +> **响应** + ```javascript + { + "result": true, // Indicates that combined is set to true. + "id": 2 + } + ``` + +* **请求** + + { + "method": "GET_PROPERTY", + "params": + [ + "combined" + ], + "id": 2 + } + + +###错误信息 + +错误信息 | 描述 +---|--- +{"code": 0, "msg": "Unknown property"} | `SET_PROPERTY` 或 `GET_PROPERTY`中应用的参数无效 +{"code": 1, "msg": "Invalid value type: expected Boolean", "id": '%s'} | 仅接受`true`或`false` +{"code": 2, "msg": "Invalid request: property name must be a string"}| 提供的属性名无效 +{"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"}| 参数`id`未提供或`id`值是无效类型 +{"code": 2, "msg": "Invalid request: unknown variant %s, expected one of `SUBSCRIBE`, `UNSUBSCRIBE`, `LIST_SUBSCRIPTIONS`, `SET_PROPERTY`, `GET_PROPERTY` at line 1 column 28"} | 错字提醒，或提供的值不是预期类型 +{"code": 2, "msg": "Invalid request: too many parameters"}| 数据中提供了不必要参数 +{"code": 2, "msg": "Invalid request: property name must be a string"} | 未提供属性名 +{"code": 2, "msg": "Invalid request: missing field `method` at line 1 column 73"} | 数据未提供`method` +{"code":3,"msg":"Invalid JSON: expected value at line %s column %s"} | JSON 语法有误. + + +## 归集交易流 + + +> **Payload:** +```javascript +{ + "e": "aggTrade", // 事件类型 + "E": 123456789, // 事件时间 + "s": "BNBBTC", // 交易对 + "a": 12345, // 归集交易ID + "p": "0.001", // 成交价格 + "q": "100", // 成交数量 + "f": 100, // 被归集的首个交易ID + "l": 105, // 被归集的末次交易ID + "T": 123456785, // 成交时间 + "m": true, // 买方是否是做市方。如true，则此次成交是一个主动卖出单，否则是一个主动买入单。 +} +``` + +归集交易 stream 推送交易信息，是对单一订单的集合。 + +**Stream 名称:** `@aggTrade` + +**Update Speed:** 实时 + + +## 逐笔交易 + + +> **Payload:** +```javascript +{ + "e": "trade", // 事件类型 + "E": 123456789, // 事件时间 + "s": "BNBBTC", // 交易对 + "t": 12345, // 交易ID + "p": "0.001", // 成交价格 + "q": "100", // 成交数量 + "T": 123456785, // 成交时间 + "m": true, // 买方是否是做市方。如true，则此次成交是一个主动卖出单，否则是一个主动买入单。 +} +``` + +**Stream Name:** `@trade` + +逐笔交易推送每一笔成交的信息。**成交**，或者说交易的定义是仅有一个吃单者与一个挂单者相互交易 + + +## K线 Streams +> **Payload:** +```javascript +{ + "e": "kline", // 事件类型 + "E": 123456789, // 事件时间 + "s": "BNBBTC", // 交易对 + "k": { + "t": 123400000, // 这根K线的起始时间 + "T": 123460000, // 这根K线的结束时间 + "s": "BNBBTC", // 交易对 + "i": "1m", // K线间隔 + "f": 100, // 这根K线期间第一笔成交ID + "L": 200, // 这根K线期间末一笔成交ID + "o": "0.0010", // 这根K线期间第一笔成交价 + "c": "0.0020", // 这根K线期间末一笔成交价 + "h": "0.0025", // 这根K线期间最高成交价 + "l": "0.0015", // 这根K线期间最低成交价 + "v": "1000", // 这根K线期间成交量 + "n": 100, // 这根K线期间成交笔数 + "x": false, // 这根K线是否完结(是否已经开始下一根K线) + "q": "1.0000", // 这根K线期间成交额 + "V": "500", // 主动买入的成交量 + "Q": "0.500", // 主动买入的成交额 + "B": "123456" // 忽略此参数 + } +} +``` + +K线stream逐秒推送所请求的K线种类(最新一根K线)的更新。 + +**Stream Name:** `@kline_` + +**Update Speed:** 2000ms + +**K线图间隔参数:** + +m -> 分钟; h -> 小时; d -> 天; w -> 周; M -> 月 + +* 1m +* 3m +* 5m +* 15m +* 30m +* 1h +* 2h +* 4h +* 6h +* 8h +* 12h +* 1d +* 3d +* 1w +* 1M + + +## 按 Symbol 的精简Ticker + +> **Payload:** +```javascript + { + "e": "24hrMiniTicker", // 事件类型 + "E": 123456789, // 事件时间 + "s": "BNBBTC", // 交易对 + "c": "0.0025", // 最新成交价格 + "o": "0.0010", // 24小时前开始第一笔成交价格 + "h": "0.0025", // 24小时内最高成交价 + "l": "0.0010", // 24小时内最低成交价 + "v": "10000", // 成交量 + "q": "18" // 成交额 + } +``` + +按Symbol刷新的最近24小时精简ticker信息 + +**Stream 名称:** `@miniTicker` + +**Update Speed:** 1000ms + + +## 全市场所有Symbol的精简Ticker + +> **Payload:** +```javascript +[ + { + // 数组每一个元素对应一个交易对，内容与 \@miniTicker相同 + } +] +``` + +同上，只是推送所有交易对.需要注意的是，只有更新的ticker才会被推送. + +**Stream名称:** !miniTicker@arr + +**Update Speed:** 1000ms + +## 按Symbol的完整Ticker + +> **Payload:** +```javascript +{ + "e": "24hrTicker", // 事件类型 + "E": 123456789, // 事件时间 + "s": "BNBBTC", // 交易对 + "p": "0.0015", // 24小时价格变化 + "P": "250.00", // 24小时价格变化(百分比) + "w": "0.0018", // 平均价格 + "c": "0.0025", // 最新成交价格 + "Q": "10", // 最新成交交易的成交量 + "o": "0.0010", // 整整24小时前，向后数的第一次成交价格 + "h": "0.0025", // 24小时内最高成交价 + "l": "0.0010", // 24小时内最低成交价 + "v": "10000", // 24小时内成交量 + "q": "18", // 24小时内成交额 + "O": 0, // 统计开始时间 + "C": 86400000, // 统计结束时间 + "F": 0, // 24小时内第一笔成交交易ID + "L": 18150, // 24小时内最后一笔成交交易ID + "n": 18151 // 24小时内成交数 +} +``` + +每秒推送单个交易对的过去24小时滚动窗口标签统计信息。 + +**Stream 名称:** `@ticker` + +**Update Speed:** 1000ms + +## 全市场所有交易对的完整Ticker + +> **Payload:** +```javascript +[ + { + // Same as @ticker payload + } +] +``` + +推送全市场所有交易对刷新的24小时完整ticker信息。需要注意的是，没有更新的ticker不会被推送。 + +**Stream Name:** `!ticker@arr` + +**Update Speed:** 1000ms + + +## 按Symbol的最优挂单信息 + +> **Payload:** +```javascript +{ + "u":400900217, // order book updateId + "s":"BNBUSDT", // 交易对 + "b":"25.35190000", // 买单最优挂单价格 + "B":"31.21000000", // 买单最优挂单数量 + "a":"25.36520000", // 卖单最优挂单价格 + "A":"40.66000000" // 卖单最优挂单数量 +} +``` + +实时推送指定交易对最优挂单信息 + +**Stream Name:** `@bookTicker` + +**Update Speed:** 实时 + +## 全市场最优挂单信息 +> **Payload:** +```javascript +{ + // 同 @bookTicker payload +} +``` + +实时推送所有交易对最优挂单信息 + +**Stream Name:** `!bookTicker` + +**Update Speed:** 实时 + + +## 有限档深度信息 + +> **Payload:** +```javascript +{ + "e": "depthUpdate", // Event type + "E": 123456789, // Event time + "T": 123456788, // Transaction time + "s": "BTCUSDT", // Symbol + "U": 100, // First update ID in event + "u": 120, // Final update ID in event + "pu": 99, // Final update Id in last stream(ie `u` in last stream) +  "bids": [ // Bids to be updated + [ + "0.0024", // Price level to be updated + "10" // Quantity + ] + ], + "asks": [ // Asks to be updated + [ + "0.0026", // Price level to be updated + "100" // Quantity + ] + ] +} +``` + +每秒或每100毫秒推送有限档深度信息。levels表示几档买卖单信息, 可选 5/10/20档 + +**Stream Names:** `@depth` 或 `@depth@100ms`. + +**Update Speed:** 1000ms 或 100ms + + +## 增量深度信息 +> **Payload:** +```javascript +{ + "e": "depthUpdate", // Event type + "E": 123456789, // Event time + "T": 123456788, // Transaction time + "s": "BTCUSDT", // Symbol + "U": 100, // First update ID in event + "u": 120, // Final update ID in event + "pu": 99, // Final update Id in last stream(ie `u` in last stream) + "b": [ // Bids to be updated + [ + "5.4", // Price level to be updated + "10" // Quantity + ] + ], + "a": [ // Asks to be updated + [ + "5.6", // Price level to be updated + "100" // Quantity + ] + ] +} +``` + +每秒或每100毫秒推送orderbook的变化部分(如果有) + +**Stream Name:** `@depth` 或 `@depth@100ms` + +**Update Speed:** 1000ms 或 100ms + +## 如何正确在本地维护一个orderbook副本 +1. 订阅 **wss://sstream.asterdex.com/ws/bnbbtc@depth** +2. 开始缓存收到的更新。同一个价位，后收到的更新覆盖前面的。 +3. 访问Rest接口 **https://sapi.asterdex.com/api/v3/depth?symbol=BNBBTC&limit=1000** 获得一个1000档的深度快照 +4. 将目前缓存到的信息中`u` <= 步骤3中获取到的快照中的`lastUpdateId`的部分丢弃(丢弃更早的信息，已经过期)。 +5. 将深度快照中的内容更新到本地orderbook副本中，并从websocket接收到的第一个`U` <= `lastUpdateId`+1 **且** `u` >= `lastUpdateId`+1 的event开始继续更新本地副本。 +6. 每一个新event的`U`应该恰好等于上一个event的`u`+1，否则可能出现了丢包，请从step3重新进行初始化。 +7. 每一个event中的挂单量代表这个价格目前的挂单量**绝对值**，而不是相对变化。 +8. 如果某个价格对应的挂单量为0，表示该价位的挂单已经撤单或者被吃，应该移除这个价位。 + + + + + + +# Websocket账户信息推送 + +* 本篇所列出API接口的base url : **https://sapi.asterdex.com** +* 用于订阅账户数据的 `listenKey` 从创建时刻起有效期为60分钟 +* 可以通过 `PUT` 一个 `listenKey` 延长60分钟有效期 +* 可以通过`DELETE`一个 `listenKey` 立即关闭当前数据流，并使该`listenKey` 无效 +* 在具有有效`listenKey`的帐户上执行`POST`将返回当前有效的`listenKey`并将其有效期延长60分钟 +* websocket接口的baseurl: **wss://sstream.asterdex.com** +* U订阅账户数据流的stream名称为 **/ws/\** +* 每个链接有效期不超过24小时，请妥善处理断线重连。 + + +## Listen Key(现货账户) + +### 生成 Listen Key (USER_STREAM) + +> **响应** +```javascript +{ + "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1" +} +``` + +`` +POST /api/v3/listenKey +`` + +开始一个新的数据流。除非发送 keepalive，否则数据流于60分钟后关闭。如果该帐户具有有效的`listenKey`，则将返回该`listenKey`并将其有效期延长60分钟。 + +**权重:** +1 + +**参数:** +NONE + +### 延长 Listen Key 有效期 (USER_STREAM) + +> **响应** +```javascript +{} +``` + +`` +PUT /api/v3/listenKey +`` + +有效期延长至本次调用后60分钟,建议每30分钟发送一个 ping 。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +listenKey | STRING | YES + + +### 关闭 Listen Key (USER_STREAM) + +> **响应** +```javascript +{} +``` + +`` +DELETE /api/v3/listenKey +`` + +关闭用户数据流。 + +**权重:** +1 + +**参数:** + +名称 | 类型 | 是否必需 | 描述 +------------ | ------------ | ------------ | ------------ +listenKey | STRING | YES + + +## Payload: 账户更新 + +每当帐户余额发生更改时，都会发送一个事件`outboundAccountPosition`，其中包含可能由生成余额变动的事件而变动的资产。 + +> **Payload** +```javascript +{ + "B":[// 余额 + { + "a":"SLP25",   // 资产名称 + "f":"10282.42029415",   // 可用余额 + "l":"653.00000001"   // 冻结余额 + }, + { + "a":"ADA25", + "f":"9916.96229880", + "l":"34.00510000" + } + ], + "e":"outboundAccountPosition",   // 事件类型 + "T":1649926447190,   // 账户末次更新时间戳 + "E":1649926447205   // 事件时间 + "m":"WITHDRAW" // 事件推出原因 +} +``` + + +## Payload: 订单更新 + +订单通过`executionReport`事件进行更新。 + +> **Payload** + +```javascript +{ + "s":"ADA25SLP25",   // 交易对 + "c":"Xzh0gnxT41PStbwqOtXnjD",  // 客户端自定订单ID + "S":"SELL",   // 订单方向 + "o":"LIMIT",   // 订单类型 + "f":"GTC",   // 有效方式 + "q":"10.001000",   // 订单原始数量 + "p":"19.1000000000",   // 订单原始价格 + "ap":"19.0999999955550656", //平均价格 + "P":"0",  // 条件订单触发价格 + "x":"TRADE",   // 本次事件的具体执行类型 + "X":"PARTIALLY_FILLED",   // 订单的当前状态 + "i":27,   // 订单ID + "l":"1",     // 订单末次成交量 + "z":"8.999000",   // 订单累计已成交量 + "L":"19.1000000000",   // 订单末次成交价格 + "n":"0.00382000",   // 手续费数量 + "N":"SLP25",   // 手续费资产类型 + "T":1649926447190,   // 成交时间 + "t":18,   // 成交ID + "m":true,   // 该成交是作为挂单成交吗？ + "ot":"LIMIT", //初始订单类型 + "O":0,   // 订单时间 + "Z":"171.88089996",   // 累计报价资产交易数量 + "Y":"19.1000000000000000",   // 最近报价交易数量 + "Q":"0",   // 报价数量 + "e":"executionReport",   // 事件类型 + "E":1649926447209  // 事件时间 +} +``` + + +**执行类型:** +* NEW 新订单 +* CANCELED 订单被取消 +* REJECTED 新订单被拒绝 +* TRADE 订单有新成交 +* EXPIRED 订单失效(根据订单的Time In Force参数) + + + +## Event: TradePro + +> **Topic Subscribe:** + +```javascript +{ + "method": "SUBSCRIBE", + "params": [ + "btcusdt@tradepro" + ], + "id": 3 +} +``` + +> **Payload:** + +```javascript +{ + "stream": "btcusdt@tradepro", + "data": { + "e": "tradepro", + "E": 1773751963081, + "T": 1773751963079, + "s": "BTCUSDT", + "t": 128884613, + "p": "73685.5", + "q": "0.297", + "h": "0X0000000000000000000000000000000000000000000000000000000000000000", + "m": [ + "hidden", + "hidden" + ] + } +} +``` + +* h: 该笔交易的交易哈希（Transaction hash） + +* m: 包含交易参与方地址的数组： + + * m[0]: Taker 地址（主动成交方） + + * m[1]: Maker 地址（挂单方） + + + +#错误代码 + +> error JSON payload: + +```javascript +{ + "code":-1121, + "msg":"Invalid symbol." +} +``` + +错误由两部分组成：错误代码和消息。 代码是通用的，但是消息可能会有所不同。 + + +## 10xx - 常规服务器或网络问题 +### -1000 UNKNOWN + * An unknown error occurred while processing the request. + * 处理请求时发生未知错误。 + +### -1001 DISCONNECTED + * Internal error; unable to process your request. Please try again. + * 内部错误; 无法处理您的请求。 请再试一次. + +### -1002 UNAUTHORIZED + * You are not authorized to execute this request. + * 您无权执行此请求。 + +### -1003 TOO_MANY_REQUESTS + * Too many requests queued. + * 排队的请求过多。 + * Too many requests; please use the websocket for live updates. + * 请求权重过多； 请使用websocket获取最新更新。 + * Too many requests; current limit is %s requests per minute. Please use the websocket for live updates to avoid polling the API. + * 请求权重过多； 当前限制为每分钟％s请求权重。 请使用websocket进行实时更新，以避免轮询API。 + * Way too many requests; IP banned until %s. Please use the websocket for live updates to avoid bans. + * 请求权重过多； IP被禁止，直到％s。 请使用websocket进行实时更新，以免被禁。 + +### -1004 DUPLICATE_IP + * This IP is already on the white list + * IP地址已经在白名单 + +### -1005 NO_SUCH_IP + * No such IP has been white listed + * 白名单上没有此IP地址 + +### -1006 UNEXPECTED_RESP + * An unexpected response was received from the message bus. Execution status unknown. + * 从消息总线收到意外的响应。执行状态未知。 + +### -1007 TIMEOUT + * Timeout waiting for response from backend server. Send status unknown; execution status unknown. + * 等待后端服务器响应超时。 发送状态未知； 执行状态未知。 + +### -1014 UNKNOWN_ORDER_COMPOSITION + * Unsupported order combination. + * 不支持当前的下单参数组合 + +### -1015 TOO_MANY_ORDERS + * Too many new orders. + * 新订单太多。 + * Too many new orders; current limit is %s orders per %s. + * 新订单太多； 当前限制为每％s ％s个订单。 + +### -1016 SERVICE_SHUTTING_DOWN + * This service is no longer available. + * 该服务不可用。 + +### -1020 UNSUPPORTED_OPERATION + * This operation is not supported. + * 不支持此操作。 + +### -1022 INVALID_SIGNATURE + * Signature for this request is not valid. + * 此请求的签名无效。 + +### -1023 START_TIME_GREATER_THAN_END_TIME + * Start time is greater than end time. + * 参数里面的开始时间在结束时间之后 + + +## 11xx - Request issues +### -1100 ILLEGAL_CHARS + * Illegal characters found in a parameter. + * 在参数中发现非法字符。 + * Illegal characters found in parameter '%s'; legal range is '%s'. + * 在参数`％s`中发现非法字符； 合法范围是`％s`。 + +### -1101 TOO_MANY_PARAMETERS + * Too many parameters sent for this endpoint. + * 为此端点发送的参数太多。 + * Too many parameters; expected '%s' and received '%s'. + * 参数太多；预期为`％s`并收到了`％s`。 + * Duplicate values for a parameter detected. + * 检测到的参数值重复。 + +### -1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED + * A mandatory parameter was not sent, was empty/null, or malformed. + * 未发送强制性参数，该参数为空/空或格式错误。 + * Mandatory parameter '%s' was not sent, was empty/null, or malformed. + * 强制参数`％s`未发送，为空/空或格式错误。 + * Param '%s' or '%s' must be sent, but both were empty/null! + * 必须发送参数`％s`或`％s`，但两者均为空！ + +### -1103 UNKNOWN_PARAM + * An unknown parameter was sent. + * 发送了未知参数。 + +### -1104 UNREAD_PARAMETERS + * Not all sent parameters were read. + * 并非所有发送的参数都被读取。 + * Not all sent parameters were read; read '%s' parameter(s) but was sent '%s'. + * 并非所有发送的参数都被读取； 读取了`％s`参数，但被发送了`％s`。 + +### -1105 PARAM_EMPTY + * A parameter was empty. + * 参数为空。 + * Parameter '%s' was empty. + * 参数`％s`为空。 + +### -1106 PARAM_NOT_REQUIRED + * A parameter was sent when not required. + * 发送了不需要的参数。 + * Parameter '%s' sent when not required. + * 发送了不需要参数`％s`。 + +### -1111 BAD_PRECISION + * Precision is over the maximum defined for this asset. + * 精度超过为此资产定义的最大值。 + +### -1112 NO_DEPTH + * No orders on book for symbol. + * 交易对没有挂单。 + +### -1114 TIF_NOT_REQUIRED + * TimeInForce parameter sent when not required. + * 发送的`TimeInForce`参数不需要。 + +### -1115 INVALID_TIF + * Invalid timeInForce. + * 无效的`timeInForce` + +### -1116 INVALID_ORDER_TYPE + * Invalid orderType. + * 无效订单类型。 + +### -1117 INVALID_SIDE + * Invalid side. + * 无效买卖方向。 + +### -1118 EMPTY_NEW_CL_ORD_ID + * New client order ID was empty. + * 新的客户订单ID为空。 + +### -1119 EMPTY_ORG_CL_ORD_ID + * Original client order ID was empty. + * 客户自定义的订单ID为空。 + +### -1120 BAD_INTERVAL + * Invalid interval. + * 无效时间间隔。 + +### -1121 BAD_SYMBOL + * Invalid symbol. + * 无效的交易对。 + +### -1125 INVALID_LISTEN_KEY + * This listenKey does not exist. + * 此`listenKey`不存在。 + +### -1127 MORE_THAN_XX_HOURS + * Lookup interval is too big. + * 查询间隔太大。 + * More than %s hours between startTime and endTime. + * 从开始时间到结束时间之间超过`％s`小时。 + +### -1128 OPTIONAL_PARAMS_BAD_COMBO + * Combination of optional parameters invalid. + * 可选参数组合无效。 + +### -1130 INVALID_PARAMETER + * Invalid data sent for a parameter. + * 发送的参数为无效数据。 + * Data sent for parameter '%s' is not valid. + * 发送参数`％s`的数据无效。 + +### -1136 INVALID_NEW_ORDER_RESP_TYPE + * Invalid newOrderRespType. + * 无效的 newOrderRespType。 + + +## 20xx - Processing Issues +### -2010 NEW_ORDER_REJECTED + * NEW_ORDER_REJECTED + * 新订单被拒绝 + +### -2011 CANCEL_REJECTED + * CANCEL_REJECTED + * 取消订单被拒绝 + +### -2013 NO_SUCH_ORDER + * Order does not exist. + * 订单不存在。 + +### -2014 BAD_API_KEY_FMT + * API-key format invalid. + * API-key 格式无效。 + +### -2015 REJECTED_MBX_KEY + * Invalid API-key, IP, or permissions for action. + * 无效的API密钥，IP或操作权限。 + +### -2016 NO_TRADING_WINDOW + * No trading window could be found for the symbol. Try ticker/24hrs instead. + * 找不到该交易对的交易窗口。 尝试改为24小时自动报价。 + +### -2018 BALANCE_NOT_SUFFICIENT + * Balance is insufficient. + * 余额不足 + +### -2020 UNABLE_TO_FILL + * Unable to fill. + * 无法成交 + +### -2021 ORDER_WOULD_IMMEDIATELY_TRIGGER + * Order would immediately trigger. + * 订单可能被立刻触发 + +### -2022 REDUCE_ONLY_REJECT + * ReduceOnly Order is rejected. + * `ReduceOnly`订单被拒绝 + +### -2024 POSITION_NOT_SUFFICIENT + * Position is not sufficient. + * 持仓不足 + +### -2025 MAX_OPEN_ORDER_EXCEEDED + * Reach max open order limit. + * 挂单量达到上限 + +### -2026 REDUCE_ONLY_ORDER_TYPE_NOT_SUPPORTED + * This OrderType is not supported when reduceOnly. + * 当前订单类型不支持`reduceOnly` + +## 40xx - Filters and other Issues +### -4000 INVALID_ORDER_STATUS + * Invalid order status. + * 订单状态不正确 + +### -4001 PRICE_LESS_THAN_ZERO + * Price less than 0. + * 价格小于0 + +### -4002 PRICE_GREATER_THAN_MAX_PRICE + * Price greater than max price. + * 价格超过最大值 + +### -4003 QTY_LESS_THAN_ZERO + * Quantity less than zero. + * 数量小于0 + +### -4004 QTY_LESS_THAN_MIN_QTY + * Quantity less than min quantity. + * 数量小于最小值 + +### -4005 QTY_GREATER_THAN_MAX_QTY + * Quantity greater than max quantity. + * 数量大于最大值 + +### -4006 STOP_PRICE_LESS_THAN_ZERO + * Stop price less than zero. + * 触发价小于最小值 + +### -4007 STOP_PRICE_GREATER_THAN_MAX_PRICE + * Stop price greater than max price. + * 触发价大于最大值 + +### -4008 TICK_SIZE_LESS_THAN_ZERO + * Tick size less than zero. + * 价格精度小于0 + +### -4009 MAX_PRICE_LESS_THAN_MIN_PRICE + * Max price less than min price. + * 最大价格小于最小价格 + +### -4010 MAX_QTY_LESS_THAN_MIN_QTY + * Max qty less than min qty. + * 最大数量小于最小数量 + +### -4011 STEP_SIZE_LESS_THAN_ZERO + * Step size less than zero. + * 步进值小于0 + +### -4012 MAX_NUM_ORDERS_LESS_THAN_ZERO + * Max num orders less than zero. + * 最大订单量小于0 + +### -4013 PRICE_LESS_THAN_MIN_PRICE + * Price less than min price. + * 价格小于最小价格 + +### -4014 PRICE_NOT_INCREASED_BY_TICK_SIZE + * Price not increased by tick size. + * 价格增量不是价格精度的倍数。 + +### -4015 INVALID_CL_ORD_ID_LEN + * Client order id is not valid. + * 客户订单ID有误。 + * Client order id length should not be more than 36 chars + * 客户订单ID长度应该不多于36字符 + +### -4016 PRICE_HIGHTER_THAN_MULTIPLIER_UP + * Price is higher than mark price multiplier cap. + +### -4017 MULTIPLIER_UP_LESS_THAN_ZERO + * Multiplier up less than zero. + * 价格上限小于0 + +### -4018 MULTIPLIER_DOWN_LESS_THAN_ZERO + * Multiplier down less than zero. + * 价格下限小于0 + +### -4019 COMPOSITE_SCALE_OVERFLOW + * Composite scale too large. + +### -4020 TARGET_STRATEGY_INVALID + * Target strategy invalid for orderType '%s',reduceOnly '%b'. + * 目标策略值不适合`%s`订单状态, 只减仓`%b`。 + +### -4021 INVALID_DEPTH_LIMIT + * Invalid depth limit. + * 深度信息的`limit`值不正确。 + * '%s' is not valid depth limit. + * `%s`不是合理的深度信息的`limit`值。 + +### -4022 WRONG_MARKET_STATUS + * market status sent is not valid. + * 发送的市场状态不正确。 + +### -4023 QTY_NOT_INCREASED_BY_STEP_SIZE + * Qty not increased by step size. + * 数量的递增值不是步进值的倍数。 + +### -4024 PRICE_LOWER_THAN_MULTIPLIER_DOWN + * Price is lower than mark price multiplier floor. + +### -4025 MULTIPLIER_DECIMAL_LESS_THAN_ZERO + * Multiplier decimal less than zero. + +### -4026 COMMISSION_INVALID + * Commission invalid. + * 收益值不正确 + * `%s` less than zero. + * `%s`少于0 + * `%s` absolute value greater than `%s` + * `%s`绝对值大于`%s` + +### -4027 INVALID_ACCOUNT_TYPE + * Invalid account type. + * 账户类型不正确。 + +### -4029 INVALID_TICK_SIZE_PRECISION + * Tick size precision is invalid. + * 价格精度小数点位数不正确。 + +### -4030 INVALID_STEP_SIZE_PRECISION + * Step size precision is invalid. + * 步进值小数点位数不正确。 + +### -4031 INVALID_WORKING_TYPE + * Invalid parameter working type + * 不正确的参数类型 + * Invalid parameter working type: `%s` + * 不正确的参数类型: `%s` + +### -4032 EXCEED_MAX_CANCEL_ORDER_SIZE + * Exceed maximum cancel order size. + * 超过可以取消的最大订单量。 + * Invalid parameter working type: `%s` + * 不正确的参数类型: `%s` + +### -4044 INVALID_BALANCE_TYPE + * Balance Type is invalid. + * 余额类型不正确。 + +### -4045 MAX_STOP_ORDER_EXCEEDED + * Reach max stop order limit. + * 达到止损单的上限。 + +### -4055 AMOUNT_MUST_BE_POSITIVE + * Amount must be positive. + * 数量必须是正整数 + +### -4056 INVALID_API_KEY_TYPE + * Invalid api key type. + * API key的类型不正确 + +### -4057 INVALID_RSA_PUBLIC_KEY + * Invalid api public key + * API key不正确 + +### -4058 MAX_PRICE_TOO_LARGE + * maxPrice and priceDecimal too large,please check. + * maxPrice和priceDecimal太大，请检查。 + +### -4060 INVALID_POSITION_SIDE + * Invalid position side. + * 仓位方向不正确。 + +### -4061 POSITION_SIDE_NOT_MATCH + * Order's position side does not match user's setting. + * 订单的持仓方向和用户设置不一致。 + +### -4062 REDUCE_ONLY_CONFLICT + * Invalid or improper reduceOnly value. + * 仅减仓的设置不正确。 + +### -4084 UPCOMING_METHOD + * Method is not allowed currently. Upcoming soon. + * 方法不支持 + +### -4086 INVALID_PRICE_SPREAD_THRESHOLD + * Invalid price spread threshold + * 无效的价差阀值 + +### -4087 REDUCE_ONLY_ORDER_PERMISSION + * User can only place reduce only order + * 用户只能下仅减仓订单 + +### -4088 NO_PLACE_ORDER_PERMISSION + * User can not place order currently + * 用户当前不能下单 + +### -4114 INVALID_CLIENT_TRAN_ID_LEN + * clientTranId is not valid + * clientTranId不正确 + * Client tran id length should be less than 64 chars + * 客户的tranId长度应该小于64个字符 + +### -4115 DUPLICATED_CLIENT_TRAN_ID + * clientTranId is duplicated + * clientTranId重复 + * Client tran id should be unique within 7 days + * 客户的tranId应在7天内唯一 + +### -4118 REDUCE_ONLY_MARGIN_CHECK_FAILED + * ReduceOnly Order Failed. Please check your existing position and open orders + * 仅减仓订单失败。请检查现有的持仓和挂单 + +### -4131 MARKET_ORDER_REJECT + * The counterparty's best price does not meet the PERCENT_PRICE filter limit + * 交易对手的最高价格未达到PERCENT_PRICE过滤器限制 + +### -4135 INVALID_ACTIVATION_PRICE + * Invalid activation price + * 无效的激活价格 + +### -4137 QUANTITY_EXISTS_WITH_CLOSE_POSITION + * Quantity must be zero with closePosition equals true + * 数量必须为0，当closePosition为true时 + +### -4138 REDUCE_ONLY_MUST_BE_TRUE + * Reduce only must be true with closePosition equals true + * Reduce only 必须为true，当closePosition为true时 + +### -4139 ORDER_TYPE_CANNOT_BE_MKT + * Order type can not be market if it's unable to cancel + * 订单类型不能为市价单如果不能取消 + +### -4140 INVALID_OPENING_POSITION_STATUS + * Invalid symbol status for opening position + * 无效的交易对状态 + +### -4141 SYMBOL_ALREADY_CLOSED + * Symbol is closed + * 交易对已下架 + +### -4142 STRATEGY_INVALID_TRIGGER_PRICE + * REJECT: take profit or stop order will be triggered immediately + * 拒绝：止盈止损单将立即被触发 + +### -4164 MIN_NOTIONAL + * Order's notional must be no smaller than 5.0 (unless you choose reduce only) + * 订单的名义价值不可以小于5，除了使用reduce only + * Order's notional must be no smaller than %s (unless you choose reduce only) + * 订单的名义价值不可以小于`%s`，除了使用reduce only + +### -4165 INVALID_TIME_INTERVAL + * Invalid time interval + * 无效的间隔 + * Maximum time interval is %s days + * 最大的时间间隔为 `%s` 天 + +### -4183 PRICE_HIGHTER_THAN_STOP_MULTIPLIER_UP + * Price is higher than stop price multiplier cap. + * 止盈止损订单价格不应高于触发价与报价乘数上限的乘积 + * Limit price can't be higher than %s. + * 止盈止损订单价格不应高于 `%s` + +### -4184 PRICE_LOWER_THAN_STOP_MULTIPLIER_DOWN + * Price is lower than stop price multiplier floor. + * 止盈止损订单价格不应低于触发价与报价乘数下限的乘积 + * Limit price can't be lower than %s. + * 止盈止损订单价格不应低于 `%s`f