docs: add registerAndApproveAgent API documentation

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 2026-05-12
+
+### Added
+
+#### `POST /fapi/v3/registerAndApproveAgent` — Register and Approve Agent / 注册并授权 Agent
+
+A new public endpoint that **registers an API agent account and grants trading/withdrawal permissions in a single atomic call**.
+
+---
+
+## 2025-xx-xx
+
+### Added
+
+#### `POST /fapi/v3/asset/migrateUser` — Migrate User Assets / 用户资产迁移
+
+#### `GET /fapi/v3/asset/migrateUser/history` — Migrate User Assets History / 用户资产迁移历史

V3(Recommended)/EN/aster-finance-futures-api-testnet.md

@@ -102,6 +102,7 @@
   - [Sub-Account Transfer (TRADE)](#sub-account-transfer-trade)
   - [Migrate User Assets (WITHDRAW)](#migrate-user-assets-withdraw)
   - [Migrate User Assets History (USER_DATA)](#migrate-user-assets-history-user_data)
+  - [Register and Approve Agent (PUBLIC)](#register-and-approve-agent-public)
 - [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)
@@ -3830,6 +3831,98 @@ toAccountAddress={toAccountAddress}&asset={asset}&amount={amount}&kindType={kind
 
 
 
+
+# Register and Approve Agent (PUBLIC)
+
+> **Response:**
+
+```javascript
+{
+    "code": 200,
+    "msg": "success"
+}
+```
+
+`POST /fapi/v3/registerAndApproveAgent`
+
+Registers a new API agent account and grants it trading/withdrawal permissions in a single call. Once approved, the agent can use API Keys to act on behalf of the user within the specified permission scope.
+
+**Weight:** 50
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| user | STRING | YES | User's wallet address |
+| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention |
+| agentName | STRING | YES | Display name for the agent |
+| agentAddress | STRING | YES | Agent's wallet address |
+| expired | LONG | YES | Agent expiration timestamp (milliseconds) |
+| signatureChainId | LONG | YES | Chain ID used when generating the signature (`56` for EVM addresses, `101` for Solana addresses) |
+| signature | STRING | YES | Signature over the message body, signed using the user's wallet private key (see Signature Instructions below) |
+| canSpotTrade | BOOLEAN | YES | Whether the agent is permitted to place spot orders |
+| canPerpTrade | BOOLEAN | YES | Whether the agent is permitted to place perpetual futures orders |
+| canWithdraw | BOOLEAN | YES | Whether the agent is permitted to initiate withdrawals |
+| ipWhitelist | STRING | NO | Space-separated list of permitted IP addresses or CIDR ranges (e.g. `192.168.1.1 10.0.0.0/24`). **Required when `canWithdraw` is `true`.** |
+| agentCode | STRING | NO | Referral/invitation code for agent registration |
+
+---
+
+### Signature Instructions
+
+Sign the following message body using the **user's wallet private key**:
+
+```
+msg: user={user}&nonce={nonce}&agentName={agentName}&agentAddress={agentAddress}&expired={expired}&signatureChainId={signatureChainId}&canSpotTrade={canSpotTrade}&canPerpTrade={canPerpTrade}&canWithdraw={canWithdraw}&ipWhitelist={ipWhitelist}
+```
+
+> **EVM addresses only:** wrap the `msg` string above as `message.msg` in the following EIP-712 typed data structure before signing:
+
+```
+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": 714,
+    "verifyingContract": "0x0000000000000000000000000000000000000000"
+  },
+  "message": {
+    "msg": "$msg"
+  }
+}
+```
+
+#### Supported Signing Algorithms
+
+| Account Type | Signing Algorithm | Encoding |
+|---|---|---|
+| EVM Address | EIP-712 Typed Data (chainId=56, message.msg=message body) | Hex |
+| Solana Address | Ed25519 | Base58 |
+
+---
+
+### Important Notes
+
+* `nonce` must be a microsecond-precision timestamp. The difference from server time must not exceed **10 seconds**, and the same nonce cannot be reused.
+* `expired` is the agent's validity deadline in **milliseconds**. The agent will automatically expire after this timestamp.
+* `ipWhitelist` uses **spaces** as the delimiter and supports CIDR notation (e.g. `192.168.1.1 10.0.0.0/24`). **`ipWhitelist` is required and must not be empty when `canWithdraw` is `true`.**
+* This endpoint is **unauthenticated** — no API Key or HMAC header is required. All authorization is verified through the on-chain `signature`.
+* This endpoint combines agent registration and permission granting into a single call, equivalent to the standalone registration step followed by `approveAgent`.
+
+
+
 # User Data Streams
 
 * The base API endpoint is: **https://fapi.asterdex-testnet.com**

V3(Recommended)/EN/aster-finance-futures-api-v3.md

@@ -106,6 +106,7 @@
   - [Sub-Account Transfer (TRADE)](#sub-account-transfer-trade)
   - [Migrate User Assets (WITHDRAW)](#migrate-user-assets-withdraw)
   - [Migrate User Assets History (USER_DATA)](#migrate-user-assets-history-user_data)
+  - [Register and Approve Agent (PUBLIC)](#register-and-approve-agent-public)
 - [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)
@@ -4093,6 +4094,98 @@ toAccountAddress={toAccountAddress}&asset={asset}&amount={amount}&kindType={kind
 
 
 
+
+# Register and Approve Agent (PUBLIC)
+
+> **Response:**
+
+```javascript
+{
+    "code": 200,
+    "msg": "success"
+}
+```
+
+`POST /fapi/v3/registerAndApproveAgent`
+
+Registers a new API agent account and grants it trading/withdrawal permissions in a single call. Once approved, the agent can use API Keys to act on behalf of the user within the specified permission scope.
+
+**Weight:** 50
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| user | STRING | YES | User's wallet address |
+| nonce | LONG | YES | Microsecond-level timestamp, used for replay attack prevention |
+| agentName | STRING | YES | Display name for the agent |
+| agentAddress | STRING | YES | Agent's wallet address |
+| expired | LONG | YES | Agent expiration timestamp (milliseconds) |
+| signatureChainId | LONG | YES | Chain ID used when generating the signature (`56` for EVM addresses, `101` for Solana addresses) |
+| signature | STRING | YES | Signature over the message body, signed using the user's wallet private key (see Signature Instructions below) |
+| canSpotTrade | BOOLEAN | YES | Whether the agent is permitted to place spot orders |
+| canPerpTrade | BOOLEAN | YES | Whether the agent is permitted to place perpetual futures orders |
+| canWithdraw | BOOLEAN | YES | Whether the agent is permitted to initiate withdrawals |
+| ipWhitelist | STRING | NO | Space-separated list of permitted IP addresses or CIDR ranges (e.g. `192.168.1.1 10.0.0.0/24`). **Required when `canWithdraw` is `true`.** |
+| agentCode | STRING | NO | Referral/invitation code for agent registration |
+
+---
+
+### Signature Instructions
+
+Sign the following message body using the **user's wallet private key**:
+
+```
+msg: user={user}&nonce={nonce}&agentName={agentName}&agentAddress={agentAddress}&expired={expired}&signatureChainId={signatureChainId}&canSpotTrade={canSpotTrade}&canPerpTrade={canPerpTrade}&canWithdraw={canWithdraw}&ipWhitelist={ipWhitelist}
+```
+
+> **EVM addresses only:** wrap the `msg` string above as `message.msg` in the following EIP-712 typed data structure before signing:
+
+```
+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"
+  }
+}
+```
+
+#### Supported Signing Algorithms
+
+| Account Type | Signing Algorithm | Encoding |
+|---|---|---|
+| EVM Address | EIP-712 Typed Data (chainId=56, message.msg=message body) | Hex |
+| Solana Address | Ed25519 | Base58 |
+
+---
+
+### Important Notes
+
+* `nonce` must be a microsecond-precision timestamp. The difference from server time must not exceed **10 seconds**, and the same nonce cannot be reused.
+* `expired` is the agent's validity deadline in **milliseconds**. The agent will automatically expire after this timestamp.
+* `ipWhitelist` uses **spaces** as the delimiter and supports CIDR notation (e.g. `192.168.1.1 10.0.0.0/24`). **`ipWhitelist` is required and must not be empty when `canWithdraw` is `true`.**
+* This endpoint is **unauthenticated** — no API Key or HMAC header is required. All authorization is verified through the on-chain `signature`.
+* This endpoint combines agent registration and permission granting into a single call, equivalent to the standalone registration step followed by `approveAgent`.
+
+
+
 # User Data Streams
 
 * The base API endpoint is: **https://fapi.asterdex.com**

V3(Recommended)/中文/aster-finance-futures-api-testnet_CN.md

@@ -96,6 +96,7 @@
 	- [子账户划转 (TRADE)](#子账户划转-trade)		
 	- [用户资产迁移 (WITHDRAW)](#用户资产迁移-withdraw)		
 	- [用户资产迁移历史 (USER_DATA)](#用户资产迁移历史-user_data)		
+	- [注册并授权 Agent (PUBLIC)](#注册并授权-agent-public)		
 - [Websocket 账户信息推送](#websocket-账户信息推送)
 	- [生成listenKey (USER_STREAM)](#生成listenkey-user_stream)
 	- [延长listenKey有效期 (USER_STREAM)](#延长listenkey有效期-user_stream)
@@ -4062,6 +4063,98 @@ toAccountAddress={toAccountAddress}&asset={asset}&amount={amount}&kindType={kind
 
 
 
+
+# 注册并授权 Agent (PUBLIC)
+
+> **响应:**
+
+```javascript
+{
+    "code": 200,
+    "msg": "success"
+}
+```
+
+`POST /fapi/v3/registerAndApproveAgent`
+
+注册新的 API Agent 账户并一次性授予其交易/提现权限。Agent 授权后，可使用 API Key 在指定权限范围内代表用户进行操作。
+
+**权重:** 50
+
+**参数:**
+
+| 名称 | 类型 | 是否必需 | 描述 |
+|------|------|---------|------|
+| user | STRING | YES | 用户钱包地址 |
+| nonce | LONG | YES | 微秒级时间戳，用于防重放攻击 |
+| agentName | STRING | YES | Agent 的显示名称 |
+| agentAddress | STRING | YES | Agent 的钱包地址 |
+| expired | LONG | YES | Agent 到期时间戳（毫秒） |
+| signatureChainId | LONG | YES | 生成签名时所使用的链 ID（EVM 地址填 `56`，Solana 地址填 `101`） |
+| signature | STRING | YES | 对消息体的签名，必须使用用户钱包私钥签名（见下方签名说明） |
+| canSpotTrade | BOOLEAN | YES | 是否允许 Agent 下现货订单 |
+| canPerpTrade | BOOLEAN | YES | 是否允许 Agent 下永续合约订单 |
+| canWithdraw | BOOLEAN | YES | 是否允许 Agent 发起提现 |
+| ipWhitelist | STRING | NO | 允许访问的 IP 地址或 CIDR 段列表，以**空格**分隔（如 `192.168.1.1 10.0.0.0/24`）。**当 `canWithdraw` 为 `true` 时必填，不可为空。** |
+| agentCode | STRING | NO | Agent 注册邀请码 |
+
+---
+
+### 签名说明
+
+使用**用户钱包私钥**对以下消息体签名：
+
+```
+msg: user={user}&nonce={nonce}&agentName={agentName}&agentAddress={agentAddress}&expired={expired}&signatureChainId={signatureChainId}&canSpotTrade={canSpotTrade}&canPerpTrade={canPerpTrade}&canWithdraw={canWithdraw}&ipWhitelist={ipWhitelist}
+```
+
+> **EVM 地址专用：** 将上述 `msg` 字符串作为 EIP-712 结构化数据中 `message.msg` 的值进行签名，结构如下：
+
+```
+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": 714,
+    "verifyingContract": "0x0000000000000000000000000000000000000000"
+  },
+  "message": {
+    "msg": "$msg"
+  }
+}
+```
+
+#### 支持的签名算法
+
+| 账户类型 | 签名算法 | 编码格式 |
+|---|---|---|
+| EVM 地址 | EIP-712 Typed Data（chainId=56，message.msg=消息体） | Hex |
+| Solana 地址 | Ed25519 | Base58 |
+
+---
+
+### 注意事项
+
+* `nonce` 必须为微秒精度时间戳，与服务器时间差不得超过 **10 秒**，且同一 nonce 不可重复使用。
+* `expired` 为 Agent 的有效期截止时间，单位为**毫秒**，超时后 Agent 将自动失效。
+* `ipWhitelist` 以**空格**作为分隔符，支持 CIDR 格式（如 `192.168.1.1 10.0.0.0/24`）。**当 `canWithdraw` 为 `true` 时，`ipWhitelist` 必填且不可为空。**
+* 本接口**无需鉴权**——无需传入 API Key 或 HMAC 请求头，所有授权均通过链上 `signature` 验证。
+* 本接口将 Agent 注册与权限授予合并为单次调用，等同于独立注册接口与 `approveAgent` 接口的组合操作。
+
+
+
 # Websocket 账户信息推送