diff --git a/V3(Recommended)/EN/aster-finance-futures-api-v3.md b/V3(Recommended)/EN/aster-finance-futures-api-v3.md index 6e828ff..e2686d2 100644 --- a/V3(Recommended)/EN/aster-finance-futures-api-v3.md +++ b/V3(Recommended)/EN/aster-finance-futures-api-v3.md @@ -119,8 +119,15 @@ - [Register and Approve Agent (PUBLIC)](#register-and-approve-agent-public) - [Get Direct Announcements (USER_DATA)](#get-direct-announcements-user_data) - [Get Direct Announcement By ID (USER_DATA)](#get-direct-announcement-by-id-user_data) + - [Get Builder User Accounts (USER_DATA)](#get-builder-user-accounts-user_data) + - [Get Builder User Open Orders (USER_DATA)](#get-builder-user-open-orders-user_data) + - [Get Builder User Balances (USER_DATA)](#get-builder-user-balances-user_data) + - [Get Builder User Position Risk (USER_DATA)](#get-builder-user-position-risk-user_data) + - [Get Builder User Commission Rates (USER_DATA)](#get-builder-user-commission-rates-user_data) - [Get Builder Trades (USER_DATA)](#get-builder-trades-user_data) + - [Get Builder All Orders (USER_DATA)](#get-builder-all-orders-user_data) - [Get Builder Approved User List (USER_DATA)](#get-builder-approved-user-list-user_data) + - [Get All Asset Logos](#get-all-asset-logos) - [User Data Streams](#user-data-streams) - [Start User Data Stream (USER_STREAM)](#start-user-data-stream-user_stream) - [Keepalive User Data Stream (USER_STREAM)](#keepalive-user-data-stream-user_stream) @@ -4936,6 +4943,409 @@ Retrieves a single direct announcement by its ID for the authenticated user. --- +# Get Builder User Accounts (USER_DATA) + +> **Response:** + +```javascript +{ + "total": 2, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "feeTier": 0, + "canTrade": true, + "canDeposit": true, + "canWithdraw": true, + "updateTime": 1751500000000, + "accountType": 0, + "dualSidePosition": false, + "jointMargin": false, + "feeBurn": false, + "feeBurnAssetId": 0, + "symbolConfig": [ + { + "symbol": "BTCUSDT", + "leverage": 20, + "notionalLimitCoef": "10" + } + ] + } + ] +} +``` + +`GET /fapi/v3/builder/userAccounts` + +Query account information for the users trading under the caller's builder code, with pagination. The authenticated account is used as the builder identity — there is no separate `builder` address parameter. + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | +| symbol | STRING | NO | When sent, only this symbol's entry is returned in `symbolConfig` | +| page | INT | NO | Page number, starting from `1`. Default: `1` | +| limit | INT | NO | Number of results per page. Default `50`; max `1000` | +| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention | +| signer | STRING | YES | Signer address associated with the authenticated account | +| signature | STRING | YES | Signature over the request body | + +* If `userAddresses` is sent, only those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, every user currently bound to this builder is paginated through instead, ordered by the time the binding was created. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. +* The caller's own account must already have a generated on-chain address (i.e. have completed at least one deposit), or the request is rejected. + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| total | LONG | Total number of matching users | +| currentPage | INT | Current page number | +| totalPages | INT | Total number of pages | +| pageSize | INT | Number of records per page | +| hasMore | BOOLEAN | Whether more pages are available | +| rows | ARRAY | List of account records | +| rows[].address | STRING | Wallet address of the user | +| rows[].feeTier | INT | Account commission tier | +| rows[].canTrade | BOOLEAN | Whether the account can trade | +| rows[].canDeposit | BOOLEAN | Whether the account can deposit | +| rows[].canWithdraw | BOOLEAN | Whether the account can withdraw | +| rows[].updateTime | LONG | Last update time (milliseconds) | +| rows[].accountType | INT | Account type | +| rows[].dualSidePosition | BOOLEAN | Whether Hedge Mode is enabled | +| rows[].jointMargin | BOOLEAN | Whether Multi-Assets Mode is enabled | +| rows[].feeBurn | BOOLEAN | Whether fee burn is enabled | +| rows[].feeBurnAssetId | INT | Fee burn asset ID | +| rows[].symbolConfig | ARRAY | Per-symbol configuration | +| rows[].symbolConfig[].symbol | STRING | Symbol | +| rows[].symbolConfig[].leverage | INT | Current initial leverage | +| rows[].symbolConfig[].notionalLimitCoef | STRING | Notional limit coefficient | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | + +--- + +# Get Builder User Open Orders (USER_DATA) + +> **Response:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "symbol": "BTCUSDT", + "orderId": 1917641, + "clientOrderId": "abc", + "price": "0", + "origQty": "0.40", + "executedQty": "0", + "avgPrice": "0.00000", + "stopPrice": "9300", + "status": "NEW", + "side": "BUY", + "positionSide": "SHORT", + "type": "TRAILING_STOP_MARKET", + "timeInForce": "GTC", + "time": 1579276756075, + "workingType": "CONTRACT_PRICE" + } + ] +} +``` + +`GET /fapi/v3/builder/userOpenOrders` + +Query current open orders for the users trading under the caller's builder code, with pagination. The authenticated account is used as the builder identity — there is no separate `builder` address parameter. + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | +| symbol | STRING | NO | When sent, only open orders on this symbol are returned | +| page | INT | NO | Page number, starting from `1`. Default: `1` | +| limit | INT | NO | Number of results per page. Default `50`; max `1000` | +| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention | +| signer | STRING | YES | Signer address associated with the authenticated account | +| signature | STRING | YES | Signature over the request body | + +* If `userAddresses` is sent, only those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, every user currently bound to this builder is paginated through instead, ordered by the time the binding was created. `page`/`limit` page through the bound users, not the individual orders — each returned user may contribute zero or more rows. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. +* The caller's own account must already have a generated on-chain address (i.e. have completed at least one deposit), or the request is rejected. + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| total | LONG | Total number of matching users on this page's underlying query | +| currentPage | INT | Current page number | +| totalPages | INT | Total number of pages | +| pageSize | INT | Number of records per page | +| hasMore | BOOLEAN | Whether more pages are available | +| rows | ARRAY | List of open orders across the returned users | +| rows[].address | STRING | Wallet address of the order owner | +| rows[].symbol | STRING | Symbol | +| rows[].orderId | LONG | Order ID | +| rows[].clientOrderId | STRING | Client order ID | +| rows[].price | STRING | Order price | +| rows[].origQty | STRING | Original order quantity | +| rows[].executedQty | STRING | Executed quantity | +| rows[].avgPrice | STRING | Average filled price | +| rows[].stopPrice | STRING | Stop price | +| rows[].status | STRING | Order status | +| rows[].side | STRING | Order side | +| rows[].positionSide | STRING | Position side: `BOTH`, `LONG`, `SHORT` | +| rows[].type | STRING | Order type | +| rows[].timeInForce | STRING | Time in force | +| rows[].time | LONG | Order time (milliseconds) | +| rows[].workingType | STRING | Working type | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | + +--- + +# Get Builder User Balances (USER_DATA) + +> **Response:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "asset": "USDT", + "walletBalance": "23.72469206", + "price": "1", + "balanceInUsd": "23.72469206" + } + ] +} +``` + +`GET /fapi/v3/builder/userBalances` + +Query wallet balances for the users trading under the caller's builder code, with pagination. The authenticated account is used as the builder identity — there is no separate `builder` address parameter. + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | +| page | INT | NO | Page number, starting from `1`. Default: `1` | +| limit | INT | NO | Number of results per page. Default `50`; max `1000` | +| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention | +| signer | STRING | YES | Signer address associated with the authenticated account | +| signature | STRING | YES | Signature over the request body | + +* If `userAddresses` is sent, only those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, every user currently bound to this builder is paginated through instead, ordered by the time the binding was created. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. +* The caller's own account must already have a generated on-chain address (i.e. have completed at least one deposit), or the request is rejected. + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| total | LONG | Total number of matching users | +| currentPage | INT | Current page number | +| totalPages | INT | Total number of pages | +| pageSize | INT | Number of records per page | +| hasMore | BOOLEAN | Whether more pages are available | +| rows | ARRAY | List of balance records across the returned users | +| rows[].address | STRING | Wallet address of the balance owner | +| rows[].asset | STRING | Asset name | +| rows[].walletBalance | STRING | Wallet balance | +| rows[].price | STRING | Asset price used to compute `balanceInUsd` | +| rows[].balanceInUsd | STRING | Wallet balance converted to USD | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | + +--- + +# Get Builder User Position Risk (USER_DATA) + +> **Response:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "symbol": "BTCUSDT", + "positionAmt": "20.000", + "entryPrice": "6563.66500", + "markPrice": "6679.50671178", + "unRealizedProfit": "2316.83423560", + "liquidationPrice": "5930.78", + "leverage": "10", + "maxNotionalValue": "20000000", + "marginType": "isolated", + "isolatedMargin": "15517.54150468", + "isAutoAddMargin": "false", + "positionSide": "LONG", + "notional": "133593.13423560", + "isolatedWallet": "13200.70726908", + "updateTime": 1625474304765 + } + ] +} +``` + +`GET /fapi/v3/builder/userPositionRisk` + +Query current position information for the users trading under the caller's builder code, with pagination. The authenticated account is used as the builder identity — there is no separate `builder` address parameter. + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | +| symbol | STRING | NO | When sent, only positions on this symbol are returned | +| page | INT | NO | Page number, starting from `1`. Default: `1` | +| limit | INT | NO | Number of results per page. Default `50`; max `1000` | +| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention | +| signer | STRING | YES | Signer address associated with the authenticated account | +| signature | STRING | YES | Signature over the request body | + +* If `userAddresses` is sent, only those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, every user currently bound to this builder is paginated through instead, ordered by the time the binding was created. `page`/`limit` page through the bound users, not the individual positions — each returned user may contribute zero or more rows. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. +* The caller's own account must already have a generated on-chain address (i.e. have completed at least one deposit), or the request is rejected. +* For a user in One-way Mode, only the `BOTH`-side position is returned; for a user in Hedge Mode, the `LONG`/`SHORT`-side positions are returned. +* `liquidationPrice` is reported as `0` whenever the underlying value would be negative. +* This batch endpoint only returns positions with a non-zero `positionAmt`. This differs from the single-account `GET /fapi/v3/positionRisk`, which returns every symbol's position including ones with `positionAmt = 0`. + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| total | LONG | Total number of matching users on this page's underlying query | +| currentPage | INT | Current page number | +| totalPages | INT | Total number of pages | +| pageSize | INT | Number of records per page | +| hasMore | BOOLEAN | Whether more pages are available | +| rows | ARRAY | List of position records across the returned users | +| rows[].address | STRING | Wallet address of the position owner | +| rows[].symbol | STRING | Symbol | +| rows[].positionAmt | STRING | Position amount | +| rows[].entryPrice | STRING | Average entry price | +| rows[].markPrice | STRING | Mark price | +| rows[].unRealizedProfit | STRING | Unrealized profit | +| rows[].liquidationPrice | STRING | Liquidation price | +| rows[].leverage | STRING | Current initial leverage | +| rows[].maxNotionalValue | STRING | Maximum available notional with current leverage | +| rows[].marginType | STRING | Margin type: `isolated` or `cross` | +| rows[].isolatedMargin | STRING | Isolated margin | +| rows[].isAutoAddMargin | STRING | Whether auto-add-margin is enabled for the position | +| rows[].positionSide | STRING | Position side: `BOTH`, `LONG`, `SHORT` | +| rows[].notional | STRING | Position notional value | +| rows[].isolatedWallet | STRING | Isolated wallet balance | +| rows[].updateTime | LONG | Last update time (milliseconds) | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | + +--- + +# Get Builder User Commission Rates (USER_DATA) + +> **Response:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "symbol": "BTCUSDT", + "makerCommissionRate": "0.0002", + "takerCommissionRate": "0.0004" + } + ] +} +``` + +`GET /fapi/v3/builder/userCommissionRates` + +Query commission rates on a symbol for the users trading under the caller's builder code, with pagination. The authenticated account is used as the builder identity — there is no separate `builder` address parameter. + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | +| symbol | STRING | YES | Symbol to look up commission rates for | +| page | INT | NO | Page number, starting from `1`. Default: `1` | +| limit | INT | NO | Number of results per page. Default `50`; max `1000` | +| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention | +| signer | STRING | YES | Signer address associated with the authenticated account | +| signature | STRING | YES | Signature over the request body | + +* If `userAddresses` is sent, only those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, every user currently bound to this builder is paginated through instead, ordered by the time the binding was created. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. +* The caller's own account must already have a generated on-chain address (i.e. have completed at least one deposit), or the request is rejected. +* Each user's `makerCommissionRate`/`takerCommissionRate` is derived from their own fee tier plus any per-symbol fee adjustment on their account, the same computation used by `GET /fapi/v3/commissionRate`. + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| total | LONG | Total number of matching users | +| currentPage | INT | Current page number | +| totalPages | INT | Total number of pages | +| pageSize | INT | Number of records per page | +| hasMore | BOOLEAN | Whether more pages are available | +| rows | ARRAY | List of commission-rate records | +| rows[].address | STRING | Wallet address of the user | +| rows[].symbol | STRING | Symbol | +| rows[].makerCommissionRate | STRING | Maker commission rate | +| rows[].takerCommissionRate | STRING | Taker commission rate | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | + +--- + # Get Builder Trades (USER_DATA) > **Response:** @@ -4962,7 +5372,7 @@ Retrieves a single direct announcement by its ID for the authenticated user. "activeBuy": false, "feeAsset": "USDT", "totalQuota": "15.63802", - "fee": "0.07819010", + "fee": "-0.07819010", "orderId": 25851813, "realizedProfit": "-0.91539999", "marginAsset": "USDT", @@ -4983,6 +5393,7 @@ Query the paginated trade history of users trading under the caller's builder co | Name | Type | Required | Description | |------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | | startTime | LONG | NO | Timestamp in ms | | endTime | LONG | NO | Timestamp in ms | | page | INT | NO | Page number, starting from `1`. Default: `1` | @@ -4992,9 +5403,12 @@ Query the paginated trade history of users trading under the caller's builder co | signature | STRING | YES | Signature over the request body | * If neither `startTime` nor `endTime` is sent, the recent 7 days' data is returned. -* The resolved `startTime` must not be earlier than 30 days before the current time, or the request is rejected. +* The resolved `startTime` must not be earlier than 90 days before the current time, or the request is rejected. * `endTime` cannot be more than 1 day ahead of the current server time. * Results are ordered by trade time descending. +* If `userAddresses` is sent, only trades of those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, trades of every user currently bound to this builder are returned instead. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. **Response Fields:** @@ -5019,12 +5433,124 @@ Query the paginated trade history of users trading under the caller's builder co | rows[].activeBuy | BOOLEAN | Whether the trade was an active buy | | rows[].feeAsset | STRING | Commission asset | | rows[].totalQuota | STRING | Notional value of the trade (price × qty) | -| rows[].fee | STRING | Commission paid | +| rows[].fee | STRING | Fee for the trade, from the trading user's perspective: negative when a fee is charged, positive when a rebate is applied. Unlike most other decimal fields in this response, `fee` is not stripped of trailing zeros | | rows[].orderId | LONG | Order ID | | rows[].realizedProfit | STRING | Realized profit | | rows[].marginAsset | STRING | Margin (settlement) asset | | rows[].userAddress | STRING | Wallet address of the trading user | | rows[].builderFee | STRING | Builder fee charged on the trade | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | + +--- + +# Get Builder All Orders (USER_DATA) + +> **Response:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "avgPrice": "0.00000", + "clientOrderId": "abc", + "cumQuote": "0", + "executedQty": "0", + "orderId": 1917641, + "origQty": "0.40", + "origType": "TRAILING_STOP_MARKET", + "price": "0", + "reduceOnly": false, + "side": "BUY", + "positionSide": "SHORT", + "status": "NEW", + "stopPrice": "9300", + "closePosition": false, + "symbol": "BTCUSDT", + "time": 1579276756075, + "timeInForce": "GTC", + "type": "TRAILING_STOP_MARKET", + "activatePrice": "9020", + "priceRate": "0.3", + "updateTime": 1579276756075, + "workingType": "CONTRACT_PRICE", + "priceProtect": false, + "address": "0x1234...abcd" + } + ] +} +``` + +`GET /fapi/v3/builder/userAllOrders` + +Query the paginated historical order records (active, canceled, or filled) of users trading under the caller's builder code. The authenticated account is used as the builder identity — there is no separate `builder` address parameter. + +**Weight:** 5 + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| userAddresses | STRING | NO | Comma-separated list of up to 50 user wallet addresses to query | +| symbol | STRING | NO | When sent, only orders on this symbol are returned | +| startTime | LONG | NO | Timestamp in ms | +| endTime | LONG | NO | Timestamp in ms | +| page | INT | NO | Page number, starting from `1`. Default: `1` | +| limit | INT | NO | Number of results per page. Default `50`; max `1000` | +| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention | +| signer | STRING | YES | Signer address associated with the authenticated account | +| signature | STRING | YES | Signature over the request body | + +* If neither `startTime` nor `endTime` is sent, the recent 7 days' data is returned. +* The resolved `startTime` must not be earlier than 90 days before the current time, or the request is rejected. +* `endTime` cannot be more than 1 day ahead of the current server time. +* If `userAddresses` is sent, only orders of those addresses are returned; each address must have already approved the caller's address as its builder, otherwise it is left out of `rows` and reported in `errors` instead. +* If `userAddresses` is omitted, orders of every user currently bound to this builder are returned instead. +* `userAddresses` accepts at most 50 addresses per request; sending more is rejected. + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| total | LONG | Total number of matching orders | +| currentPage | INT | Current page number | +| totalPages | INT | Total number of pages | +| pageSize | INT | Number of records per page | +| hasMore | BOOLEAN | Whether more pages are available | +| rows | ARRAY | List of order records | +| rows[].orderId | LONG | Order ID | +| rows[].symbol | STRING | Symbol | +| rows[].status | STRING | Order status | +| rows[].clientOrderId | STRING | Client order ID | +| rows[].price | STRING | Order price | +| rows[].avgPrice | STRING | Average filled price | +| rows[].origQty | STRING | Original order quantity | +| rows[].executedQty | STRING | Executed quantity | +| rows[].cumQuote | STRING | Cumulative quote quantity | +| rows[].timeInForce | STRING | Time in force | +| rows[].type | STRING | Order type | +| rows[].reduceOnly | BOOLEAN | Whether reduce-only | +| rows[].side | STRING | Order side | +| rows[].stopPrice | STRING | Stop price. Please ignore when order type is `TRAILING_STOP_MARKET` | +| rows[].workingType | STRING | Working type | +| rows[].origType | STRING | Original order type | +| rows[].time | LONG | Order time (milliseconds) | +| rows[].updateTime | LONG | Update time (milliseconds) | +| rows[].priceRate | STRING | Callback rate, only returned with `TRAILING_STOP_MARKET` orders | +| rows[].activatePrice | STRING | Activation price, only returned with `TRAILING_STOP_MARKET` orders | +| rows[].positionSide | STRING | Position side: `BOTH`, `LONG`, `SHORT` | +| rows[].closePosition | BOOLEAN | Whether Close-All | +| rows[].priceProtect | BOOLEAN | Whether the conditional order trigger is protected | +| rows[].address | STRING | Wallet address of the order owner | +| errors | ARRAY | Present only when one or more requested addresses could not be returned | +| errors[].address | STRING | The address that was left out of `rows` | +| errors[].errorMsg | STRING | Reason the address was left out of `rows`: `This function can only be used after deposit` (address has no generated account), `User privacy mode is enabled, this operation is not allowed.`, `Failed to check privacy switch status for this address.`, or `This user address is not bound to this builder.` (only possible when `userAddresses` is explicitly supplied) | --- @@ -5090,6 +5616,42 @@ Query the list of users who have approved the caller's address as their builder. --- +# Get All Asset Logos + +> **Response:** + +```javascript +[ + { + "assetCode": "BTC", + "logoUrl": "https://example.com/logo/btc.png" + }, + { + "assetCode": "ETH", + "logoUrl": "https://example.com/logo/eth.png" + } +] +``` + +`GET /fapi/v3/common/asset/all-asset-logo` + +Query the logo URL of every active asset. This is a public endpoint — no authentication is required. + +**Weight:** 1 + +**Parameters:** + +None + +**Response Fields:** + +| Field | Type | Description | +|-------|------|-------------| +| assetCode | STRING | Asset name | +| logoUrl | STRING | URL of the asset's logo image | + +--- + # User Data Streams * The base API endpoint is: **https://fapi.asterdex.com** @@ -5839,6 +6401,10 @@ Codes are universal,but messages can vary. * Leverage is smaller than permitted: insufficient margin balance. +> -2031 INVALID_BUILDER_PARAMETER + +* Invalid builder parameter. + ## 40xx - Filters and other Issues > -4000 INVALID_ORDER_STATUS @@ -6251,7 +6817,23 @@ Codes are universal,but messages can vary. ## 50xx - Deposit and Withdrawal Issues +> -5047 INVALID_START_TIME + +* StartTime must be within the last %s days. + > -5050 DEPOSIT_REQUIRED * This function can only be used after deposit. +> -5051 PRIVACY_CHECK_FAILED + +* Failed to check privacy switch status for this address. + +> -5052 USER_PRIVACY_MODE_ENABLED + +* User privacy mode is enabled, this operation is not allowed. + +> -5053 USER_NOT_BOUND_TO_BUILDER + +* This user address is not bound to this builder. + diff --git "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" index 6797227..6fe68d8 100644 --- "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" +++ "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-v3_CN.md" @@ -117,8 +117,15 @@ - [注册并授权 Agent (PUBLIC)](#注册并授权-agent-public) - [查询直发公告列表 (USER_DATA)](#查询直发公告列表-user_data) - [按ID查询直发公告 (USER_DATA)](#按id查询直发公告-user_data) + - [查询Builder用户账户信息 (USER_DATA)](#查询builder用户账户信息-user_data) + - [查询Builder用户当前挂单 (USER_DATA)](#查询builder用户当前挂单-user_data) + - [查询Builder用户余额 (USER_DATA)](#查询builder用户余额-user_data) + - [查询Builder用户持仓风险 (USER_DATA)](#查询builder用户持仓风险-user_data) + - [查询Builder用户手续费率 (USER_DATA)](#查询builder用户手续费率-user_data) - [查询Builder交易记录 (USER_DATA)](#查询builder交易记录-user_data) + - [查询Builder全部订单 (USER_DATA)](#查询builder全部订单-user_data) - [查询Builder已授权用户列表 (USER_DATA)](#查询builder已授权用户列表-user_data) + - [查询全部资产Logo](#查询全部资产logo) - [Websocket 账户信息推送](#websocket-账户信息推送) - [生成listenKey (USER_STREAM)](#生成listenkey-user_stream) - [延长listenKey有效期 (USER_STREAM)](#延长listenkey有效期-user_stream) @@ -5102,6 +5109,409 @@ typed_data = { --- +# 查询Builder用户账户信息 (USER_DATA) + +> **响应:** + +```javascript +{ + "total": 2, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "feeTier": 0, + "canTrade": true, + "canDeposit": true, + "canWithdraw": true, + "updateTime": 1751500000000, + "accountType": 0, + "dualSidePosition": false, + "jointMargin": false, + "feeBurn": false, + "feeBurnAssetId": 0, + "symbolConfig": [ + { + "symbol": "BTCUSDT", + "leverage": 20, + "notionalLimitCoef": "10" + } + ] + } + ] +} +``` + +`GET /fapi/v3/builder/userAccounts` + +分页查询在当前调用者的Builder代码下交易的用户账户信息。以已认证账户本身作为Builder身份，无需单独传入`builder`地址参数。 + +**权重:** 5 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +|------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | +| symbol | STRING | NO | 传入时，`symbolConfig` 中仅返回该交易对的配置 | +| page | INT | NO | 页码，从 `1` 开始。默认: `1` | +| limit | INT | NO | 每页返回数量。默认 `50`；最大 `1000` | +| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 | +| signer | STRING | YES | 与当前认证账户关联的 signer 地址 | +| signature | STRING | YES | 对请求体的签名 | + +* 如果传入 `userAddresses`，仅返回这些地址的信息；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则分页返回当前绑定到该Builder的全部用户，按绑定时间先后排序。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求被拒绝。 +* 调用者自身账户必须已生成链上地址（即已完成过至少一次充值），否则请求会被拒绝。 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| total | LONG | 符合条件的用户总数 | +| currentPage | INT | 当前页码 | +| totalPages | INT | 总页数 | +| pageSize | INT | 每页数量 | +| hasMore | BOOLEAN | 是否还有下一页 | +| rows | ARRAY | 账户记录列表 | +| rows[].address | STRING | 用户钱包地址 | +| rows[].feeTier | INT | 账户手续费等级 | +| rows[].canTrade | BOOLEAN | 是否可交易 | +| rows[].canDeposit | BOOLEAN | 是否可充值 | +| rows[].canWithdraw | BOOLEAN | 是否可提现 | +| rows[].updateTime | LONG | 最后更新时间（毫秒） | +| rows[].accountType | INT | 账户类型 | +| rows[].dualSidePosition | BOOLEAN | 是否为双向持仓模式 | +| rows[].jointMargin | BOOLEAN | 是否开启联合保证金模式 | +| rows[].feeBurn | BOOLEAN | 是否开启手续费销毁 | +| rows[].feeBurnAssetId | INT | 手续费销毁资产ID | +| rows[].symbolConfig | ARRAY | 各交易对配置 | +| rows[].symbolConfig[].symbol | STRING | 交易对 | +| rows[].symbolConfig[].leverage | INT | 当前初始杠杆 | +| rows[].symbolConfig[].notionalLimitCoef | STRING | 名义价值限制系数 | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | + +--- + +# 查询Builder用户当前挂单 (USER_DATA) + +> **响应:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "symbol": "BTCUSDT", + "orderId": 1917641, + "clientOrderId": "abc", + "price": "0", + "origQty": "0.40", + "executedQty": "0", + "avgPrice": "0.00000", + "stopPrice": "9300", + "status": "NEW", + "side": "BUY", + "positionSide": "SHORT", + "type": "TRAILING_STOP_MARKET", + "timeInForce": "GTC", + "time": 1579276756075, + "workingType": "CONTRACT_PRICE" + } + ] +} +``` + +`GET /fapi/v3/builder/userOpenOrders` + +分页查询在当前调用者的Builder代码下交易的用户当前挂单。以已认证账户本身作为Builder身份，无需单独传入`builder`地址参数。 + +**权重:** 5 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +|------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | +| symbol | STRING | NO | 传入时，仅返回该交易对的挂单 | +| page | INT | NO | 页码，从 `1` 开始。默认: `1` | +| limit | INT | NO | 每页返回数量。默认 `50`；最大 `1000` | +| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 | +| signer | STRING | YES | 与当前认证账户关联的 signer 地址 | +| signature | STRING | YES | 对请求体的签名 | + +* 如果传入 `userAddresses`，仅返回这些地址的挂单；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则分页返回当前绑定到该Builder的全部用户的挂单，用户按绑定时间先后排序。`page`/`limit` 是对绑定用户分页，而非对具体挂单分页——每个返回的用户可能贡献零条或多条记录。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求被拒绝。 +* 调用者自身账户必须已生成链上地址（即已完成过至少一次充值），否则请求会被拒绝。 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| total | LONG | 本次查询涉及的用户总数 | +| currentPage | INT | 当前页码 | +| totalPages | INT | 总页数 | +| pageSize | INT | 每页数量 | +| hasMore | BOOLEAN | 是否还有下一页 | +| rows | ARRAY | 所有返回用户的挂单列表 | +| rows[].address | STRING | 挂单所属用户的钱包地址 | +| rows[].symbol | STRING | 交易对 | +| rows[].orderId | LONG | 订单ID | +| rows[].clientOrderId | STRING | 客户端订单ID | +| rows[].price | STRING | 委托价格 | +| rows[].origQty | STRING | 原始委托数量 | +| rows[].executedQty | STRING | 已成交数量 | +| rows[].avgPrice | STRING | 平均成交价格 | +| rows[].stopPrice | STRING | 触发价格 | +| rows[].status | STRING | 订单状态 | +| rows[].side | STRING | 买卖方向 | +| rows[].positionSide | STRING | 持仓方向：`BOTH`、`LONG`、`SHORT` | +| rows[].type | STRING | 订单类型 | +| rows[].timeInForce | STRING | 有效方式 | +| rows[].time | LONG | 下单时间（毫秒） | +| rows[].workingType | STRING | 触发价格类型 | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | + +--- + +# 查询Builder用户余额 (USER_DATA) + +> **响应:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "asset": "USDT", + "walletBalance": "23.72469206", + "price": "1", + "balanceInUsd": "23.72469206" + } + ] +} +``` + +`GET /fapi/v3/builder/userBalances` + +分页查询在当前调用者的Builder代码下交易的用户钱包余额。以已认证账户本身作为Builder身份，无需单独传入`builder`地址参数。 + +**权重:** 5 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +|------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | +| page | INT | NO | 页码，从 `1` 开始。默认: `1` | +| limit | INT | NO | 每页返回数量。默认 `50`；最大 `1000` | +| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 | +| signer | STRING | YES | 与当前认证账户关联的 signer 地址 | +| signature | STRING | YES | 对请求体的签名 | + +* 如果传入 `userAddresses`，仅返回这些地址的余额；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则分页返回当前绑定到该Builder的全部用户，按绑定时间先后排序。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求被拒绝。 +* 调用者自身账户必须已生成链上地址（即已完成过至少一次充值），否则请求会被拒绝。 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| total | LONG | 符合条件的用户总数 | +| currentPage | INT | 当前页码 | +| totalPages | INT | 总页数 | +| pageSize | INT | 每页数量 | +| hasMore | BOOLEAN | 是否还有下一页 | +| rows | ARRAY | 所有返回用户的余额记录列表 | +| rows[].address | STRING | 余额所属用户的钱包地址 | +| rows[].asset | STRING | 资产名称 | +| rows[].walletBalance | STRING | 钱包余额 | +| rows[].price | STRING | 用于计算 `balanceInUsd` 的资产价格 | +| rows[].balanceInUsd | STRING | 折合美元的钱包余额 | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | + +--- + +# 查询Builder用户持仓风险 (USER_DATA) + +> **响应:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "symbol": "BTCUSDT", + "positionAmt": "20.000", + "entryPrice": "6563.66500", + "markPrice": "6679.50671178", + "unRealizedProfit": "2316.83423560", + "liquidationPrice": "5930.78", + "leverage": "10", + "maxNotionalValue": "20000000", + "marginType": "isolated", + "isolatedMargin": "15517.54150468", + "isAutoAddMargin": "false", + "positionSide": "LONG", + "notional": "133593.13423560", + "isolatedWallet": "13200.70726908", + "updateTime": 1625474304765 + } + ] +} +``` + +`GET /fapi/v3/builder/userPositionRisk` + +分页查询在当前调用者的Builder代码下交易的用户持仓风险信息。以已认证账户本身作为Builder身份，无需单独传入`builder`地址参数。 + +**权重:** 5 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +|------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | +| symbol | STRING | NO | 传入时，仅返回该交易对的持仓 | +| page | INT | NO | 页码，从 `1` 开始。默认: `1` | +| limit | INT | NO | 每页返回数量。默认 `50`；最大 `1000` | +| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 | +| signer | STRING | YES | 与当前认证账户关联的 signer 地址 | +| signature | STRING | YES | 对请求体的签名 | + +* 如果传入 `userAddresses`，仅返回这些地址的持仓；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则分页返回当前绑定到该Builder的全部用户的持仓，用户按绑定时间先后排序。`page`/`limit` 是对绑定用户分页，而非对具体持仓分页——每个返回的用户可能贡献零条或多条记录。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求被拒绝。 +* 调用者自身账户必须已生成链上地址（即已完成过至少一次充值），否则请求会被拒绝。 +* 单向持仓模式的用户仅返回 `BOTH` 方向持仓；双向持仓模式的用户返回 `LONG`/`SHORT` 方向持仓。 +* 当 `liquidationPrice` 计算结果为负数时，统一返回 `0`。 +* 本批量接口仅返回 `positionAmt` 不为零的持仓；这与单账户接口 `GET /fapi/v3/positionRisk` 不同，后者会返回包括 `positionAmt = 0` 在内的所有交易对持仓。 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| total | LONG | 本次查询涉及的用户总数 | +| currentPage | INT | 当前页码 | +| totalPages | INT | 总页数 | +| pageSize | INT | 每页数量 | +| hasMore | BOOLEAN | 是否还有下一页 | +| rows | ARRAY | 所有返回用户的持仓记录列表 | +| rows[].address | STRING | 持仓所属用户的钱包地址 | +| rows[].symbol | STRING | 交易对 | +| rows[].positionAmt | STRING | 持仓数量 | +| rows[].entryPrice | STRING | 平均开仓价格 | +| rows[].markPrice | STRING | 标记价格 | +| rows[].unRealizedProfit | STRING | 未实现盈亏 | +| rows[].liquidationPrice | STRING | 强平价格 | +| rows[].leverage | STRING | 当前初始杠杆 | +| rows[].maxNotionalValue | STRING | 当前杠杆下最大可用名义价值 | +| rows[].marginType | STRING | 保证金模式：`isolated` 或 `cross` | +| rows[].isolatedMargin | STRING | 逐仓保证金 | +| rows[].isAutoAddMargin | STRING | 是否自动追加保证金 | +| rows[].positionSide | STRING | 持仓方向：`BOTH`、`LONG`、`SHORT` | +| rows[].notional | STRING | 持仓名义价值 | +| rows[].isolatedWallet | STRING | 逐仓钱包余额 | +| rows[].updateTime | LONG | 最后更新时间（毫秒） | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | + +--- + +# 查询Builder用户手续费率 (USER_DATA) + +> **响应:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "address": "0x1234...abcd", + "symbol": "BTCUSDT", + "makerCommissionRate": "0.0002", + "takerCommissionRate": "0.0004" + } + ] +} +``` + +`GET /fapi/v3/builder/userCommissionRates` + +分页查询在当前调用者的Builder代码下交易的用户在指定交易对上的手续费率。以已认证账户本身作为Builder身份，无需单独传入`builder`地址参数。 + +**权重:** 5 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +|------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | +| symbol | STRING | YES | 要查询手续费率的交易对 | +| page | INT | NO | 页码，从 `1` 开始。默认: `1` | +| limit | INT | NO | 每页返回数量。默认 `50`；最大 `1000` | +| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 | +| signer | STRING | YES | 与当前认证账户关联的 signer 地址 | +| signature | STRING | YES | 对请求体的签名 | + +* 如果传入 `userAddresses`，仅返回这些地址的手续费率；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则分页返回当前绑定到该Builder的全部用户，按绑定时间先后排序。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求被拒绝。 +* 调用者自身账户必须已生成链上地址（即已完成过至少一次充值），否则请求会被拒绝。 +* 每个用户的 `makerCommissionRate`/`takerCommissionRate` 由其自身手续费等级及该账户在该交易对上的手续费调整值计算得出，与 `GET /fapi/v3/commissionRate` 的计算方式一致。 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| total | LONG | 符合条件的用户总数 | +| currentPage | INT | 当前页码 | +| totalPages | INT | 总页数 | +| pageSize | INT | 每页数量 | +| hasMore | BOOLEAN | 是否还有下一页 | +| rows | ARRAY | 手续费率记录列表 | +| rows[].address | STRING | 用户钱包地址 | +| rows[].symbol | STRING | 交易对 | +| rows[].makerCommissionRate | STRING | 挂单手续费率 | +| rows[].takerCommissionRate | STRING | 吃单手续费率 | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | + +--- + # 查询Builder交易记录 (USER_DATA) > **响应:** @@ -5128,7 +5538,7 @@ typed_data = { "activeBuy": false, "feeAsset": "USDT", "totalQuota": "15.63802", - "fee": "0.07819010", + "fee": "-0.07819010", "orderId": 25851813, "realizedProfit": "-0.91539999", "marginAsset": "USDT", @@ -5149,6 +5559,7 @@ typed_data = { | 名称 | 类型 | 是否必需 | 描述 | |------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | | startTime | LONG | NO | 起始时间戳（毫秒） | | endTime | LONG | NO | 结束时间戳（毫秒） | | page | INT | NO | 页码，从 `1` 开始。默认: `1` | @@ -5158,9 +5569,12 @@ typed_data = { | signature | STRING | YES | 对请求体的签名 | * 如果 `startTime` 和 `endTime` 都未发送，则返回最近7天的数据。 -* 最终生效的 `startTime` 不能早于当前时间之前30天，否则请求会被拒绝。 +* 最终生效的 `startTime` 不能早于当前时间之前90天，否则请求会被拒绝。 * `endTime` 不能超过当前服务器时间1天以上。 * 结果按成交时间倒序排列。 +* 如果传入 `userAddresses`，仅返回这些地址的成交记录；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则返回当前绑定到该Builder的全部用户的成交记录。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求被拒绝。 **响应字段:** @@ -5185,12 +5599,124 @@ typed_data = { | rows[].activeBuy | BOOLEAN | 是否为主动买入 | | rows[].feeAsset | STRING | 手续费资产 | | rows[].totalQuota | STRING | 成交名义价值（价格 × 数量） | -| rows[].fee | STRING | 手续费 | +| rows[].fee | STRING | 该笔成交的手续费，以交易用户视角为准：收取手续费时为负数，收到返佣时为正数。与本响应中大多数其他小数字段不同，`fee` 不会去除末尾的零 | | rows[].orderId | LONG | 订单ID | | rows[].realizedProfit | STRING | 已实现盈亏 | | rows[].marginAsset | STRING | 保证金（结算）资产 | | rows[].userAddress | STRING | 交易用户的钱包地址 | | rows[].builderFee | STRING | 该笔成交收取的Builder手续费 | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | + +--- + +# 查询Builder全部订单 (USER_DATA) + +> **响应:** + +```javascript +{ + "total": 1, + "currentPage": 1, + "totalPages": 1, + "pageSize": 50, + "hasMore": false, + "rows": [ + { + "avgPrice": "0.00000", + "clientOrderId": "abc", + "cumQuote": "0", + "executedQty": "0", + "orderId": 1917641, + "origQty": "0.40", + "origType": "TRAILING_STOP_MARKET", + "price": "0", + "reduceOnly": false, + "side": "BUY", + "positionSide": "SHORT", + "status": "NEW", + "stopPrice": "9300", + "closePosition": false, + "symbol": "BTCUSDT", + "time": 1579276756075, + "timeInForce": "GTC", + "type": "TRAILING_STOP_MARKET", + "activatePrice": "9020", + "priceRate": "0.3", + "updateTime": 1579276756075, + "workingType": "CONTRACT_PRICE", + "priceProtect": false, + "address": "0x1234...abcd" + } + ] +} +``` + +`GET /fapi/v3/builder/userAllOrders` + +分页查询在当前调用者的Builder代码下交易的用户历史订单（活跃、已撤销或已成交）。以已认证账户本身作为Builder身份，无需单独传入`builder`地址参数。 + +**权重:** 5 + +**参数:** + +| 名称 | 类型 | 是否必需 | 描述 | +|------|------|---------|------| +| userAddresses | STRING | NO | 逗号分隔的用户钱包地址列表，最多50个 | +| symbol | STRING | NO | 传入时，仅返回该交易对的订单 | +| startTime | LONG | NO | 起始时间戳（毫秒） | +| endTime | LONG | NO | 结束时间戳（毫秒） | +| page | INT | NO | 页码，从 `1` 开始。默认: `1` | +| limit | INT | NO | 每页返回数量。默认 `50`；最大 `1000` | +| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 | +| signer | STRING | YES | 与当前认证账户关联的 signer 地址 | +| signature | STRING | YES | 对请求体的签名 | + +* 如果 `startTime` 和 `endTime` 都未发送，则返回最近7天的数据。 +* 最终生效的 `startTime` 不能早于当前时间之前90天，否则请求会被拒绝。 +* `endTime` 不能超过当前服务器时间1天以上。 +* 如果传入 `userAddresses`，仅返回这些地址的订单；每个地址必须已将调用者地址授权为其Builder，否则该地址不会出现在 `rows` 中，而是记录在 `errors` 里。 +* 如果不传 `userAddresses`，则返回当前绑定到该Builder的全部用户的订单。 +* `userAddresses` 每次请求最多支持50个地址，超出则请求会被拒绝。 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| total | LONG | 符合条件的订单总数 | +| currentPage | INT | 当前页码 | +| totalPages | INT | 总页数 | +| pageSize | INT | 每页数量 | +| hasMore | BOOLEAN | 是否还有下一页 | +| rows | ARRAY | 订单记录列表 | +| rows[].orderId | LONG | 订单ID | +| rows[].symbol | STRING | 交易对 | +| rows[].status | STRING | 订单状态 | +| rows[].clientOrderId | STRING | 客户端订单ID | +| rows[].price | STRING | 委托价格 | +| rows[].avgPrice | STRING | 平均成交价格 | +| rows[].origQty | STRING | 原始委托数量 | +| rows[].executedQty | STRING | 已成交数量 | +| rows[].cumQuote | STRING | 成交金额 | +| rows[].timeInForce | STRING | 有效方式 | +| rows[].type | STRING | 订单类型 | +| rows[].reduceOnly | BOOLEAN | 是否只减仓 | +| rows[].side | STRING | 买卖方向 | +| rows[].stopPrice | STRING | 触发价格，仅在订单类型为 `TRAILING_STOP_MARKET` 时可忽略 | +| rows[].workingType | STRING | 触发价格类型 | +| rows[].origType | STRING | 原始订单类型 | +| rows[].time | LONG | 下单时间（毫秒） | +| rows[].updateTime | LONG | 更新时间（毫秒） | +| rows[].priceRate | STRING | 回调比例，仅 `TRAILING_STOP_MARKET` 订单返回 | +| rows[].activatePrice | STRING | 追踪止损激活价格，仅 `TRAILING_STOP_MARKET` 订单返回 | +| rows[].positionSide | STRING | 持仓方向：`BOTH`、`LONG`、`SHORT` | +| rows[].closePosition | BOOLEAN | 是否为全部平仓 | +| rows[].priceProtect | BOOLEAN | 是否开启条件单触发保护 | +| rows[].address | STRING | 订单所属用户的钱包地址 | +| errors | ARRAY | 仅当部分请求地址无法返回时才出现 | +| errors[].address | STRING | 未出现在 `rows` 中的地址 | +| errors[].errorMsg | STRING | 该地址被排除的原因：`This function can only be used after deposit`（该地址尚未生成账户/未充值）、`User privacy mode is enabled, this operation is not allowed.`（已开启隐私模式）、`Failed to check privacy switch status for this address.`（隐私状态校验失败）或 `This user address is not bound to this builder.`（仅在显式传入 `userAddresses` 时可能出现，表示该地址未绑定该Builder） | --- @@ -5256,6 +5782,42 @@ typed_data = { --- +# 查询全部资产Logo + +> **响应:** + +```javascript +[ + { + "assetCode": "BTC", + "logoUrl": "https://example.com/logo/btc.png" + }, + { + "assetCode": "ETH", + "logoUrl": "https://example.com/logo/eth.png" + } +] +``` + +`GET /fapi/v3/common/asset/all-asset-logo` + +查询所有生效资产的Logo地址。这是公共接口，无需鉴权。 + +**权重:** 1 + +**参数:** + +无 + +**响应字段:** + +| 字段 | 类型 | 描述 | +|------|------|------| +| assetCode | STRING | 资产名称 | +| logoUrl | STRING | 该资产的Logo图片地址 | + +--- + # Websocket 账户信息推送 @@ -6014,6 +6576,10 @@ None * Leverage is smaller than permitted: insufficient margin balance. * 调整初始杠杆过低，导致可用余额不足 +> -2031 INVALID_BUILDER_PARAMETER + * Invalid builder parameter. + * Builder参数不合法 + ## 40xx - Filters and other Issues > -4000 INVALID_ORDER_STATUS * Invalid order status. @@ -6432,10 +6998,26 @@ None ## 50xx - Deposit and Withdrawal Issues +> -5047 INVALID_START_TIME + * StartTime must be within the last %s days. + * 起始时间必须在最近 %s 天以内 + > -5050 DEPOSIT_REQUIRED * This function can only be used after deposit. * 该功能需要先完成充值后才能使用 +> -5051 PRIVACY_CHECK_FAILED + * Failed to check privacy switch status for this address. + * 检查该地址的隐私开关状态失败 + +> -5052 USER_PRIVACY_MODE_ENABLED + * User privacy mode is enabled, this operation is not allowed. + * 用户已开启隐私模式，不允许该操作 + +> -5053 USER_NOT_BOUND_TO_BUILDER + * This user address is not bound to this builder. + * 该用户地址未绑定到此Builder + --- ## 更新日志