diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..4c7d277 --- /dev/null +++ b/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 / 用户资产迁移历史 diff --git a/V3(Recommended)/EN/aster-finance-futures-api-testnet.md b/V3(Recommended)/EN/aster-finance-futures-api-testnet.md index fa4fc18..37129fb 100644 --- a/V3(Recommended)/EN/aster-finance-futures-api-testnet.md +++ b/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** diff --git a/V3(Recommended)/EN/aster-finance-futures-api-v3.md b/V3(Recommended)/EN/aster-finance-futures-api-v3.md index 25a7669..f19aca7 100644 --- a/V3(Recommended)/EN/aster-finance-futures-api-v3.md +++ b/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** diff --git "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" "b/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" index 16d10f0..2254320 100644 --- "a/V3(Recommended)/\344\270\255\346\226\207/aster-finance-futures-api-testnet_CN.md" +++ "b/V3(Recommended)/\344\270\255\346\226\207/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 账户信息推送 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 cad2d1f..bf31e74 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" @@ -104,6 +104,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) @@ -4252,6 +4253,97 @@ 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": 1666, + "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 账户信息推送