Harden demo scripts: dead eth-account import, nonce, success-check

.gitignore

@@ -0,0 +1,2 @@
+.idea
+.claude

Aster API Overview.md

@@ -0,0 +1,111 @@
+# Aster API V1 vs V3
+
+This page provides a quick comparison between Aster `V1` and `V3`, focusing on authentication, endpoint structure, capability coverage, and the most important architectural value behind V3.  
+
+**`Starting from March 25, 2026, V1 new API Key creation is no longer supported. Existing API Keys will continue to work.`**
+
+
+> **Key takeaways**
+>
+> 1. Authentication moves from `API Key + HMAC` to `API Wallet / Agent + Web3-style signing`
+> 2. The futures structure is upgraded on top of `Aster L1`, giving `V3` stronger `Take Order` performance while consolidating the main paths into `/fapi/v3/*`
+
+---
+
+## Overview
+
+### How To Understand It
+
+- `V1` is the standard API Key model.
+- `V3` introduces the API Wallet / Agent model, and its authentication flow is closer to on-chain signing.
+- `V3` futures are built on top of `Aster L1`, which gives stronger `Take Order` performance.
+- `V3` goes through the blockchain, which makes historical trades traceable in the future, with stronger security and visibility.
+- `V3` uses `nonce` to prevent replay attacks, making requests more secure.
+- `V3` supports `Noop`, which can cancel orders faster.
+- Most business capabilities still exist in both versions.
+- The biggest change is not order semantics, but the authentication layer.
+
+---
+
+## Authentication
+
+### V1
+
+In `V1`, authentication follows the typical `API Key + Secret` model:
+
+- Send `X-MBX-APIKEY` in the request header
+- Include `timestamp` in request parameters
+- Optionally include `recvWindow`
+- Generate `signature` using `HMAC SHA256`
+
+The signing payload is usually based on request parameters, which means `query string + request body`.
+
+### V3
+
+In `V3`, authentication is no longer centered only around `apiSecret`.
+
+In addition to business parameters, requests also include:
+
+- `user`: main account wallet address
+- `signer`: API wallet address
+- `nonce`: microsecond timestamp
+- `signature`: signed by the API wallet private key
+- `timestamp`
+
+The signing flow can be understood as:
+
+1. Convert all business parameters into strings
+2. Sort them by ASCII key order
+3. Encode them together with `user`, `signer`, and `nonce`
+4. Generate a Keccak hash
+5. Sign it with ECDSA using the API wallet private key
+
+`nonce` also plays an important role in V3, because it prevents replay attacks and makes requests more secure.
+
+> **Why this matters**
+>
+> `V1` is well suited to the standard API Key integration model.
+> `V3` is built around signer identity and is better aligned with the Aster L1 architecture.
+
+### Core Value Of V3
+
+- `V3` futures are built on top of `Aster L1`, giving stronger `Take Order` performance.
+- `V3` goes through the blockchain, so historical trades can be traced in the future, with stronger security and visibility.
+- `V3` uses `nonce` to prevent replay and make requests more secure.
+- `V3` supports `Noop`, which can cancel orders faster.
+
+## Migration Notes
+
+A practical migration order is:
+
+1. Build a dedicated signing module first
+2. Centralize the authentication context:
+   - `user`
+   - `signer`
+   - `signerPrivateKey`
+   - `timestamp`
+   - `nonce`
+3. Get one simple order or query flow working first
+4. Validate the signing logic with a simple trade flow
+5. Then move to batch and fund-related operations
+
+### Common Mistakes
+
+The most common issues during V3 migration are:
+
+- incorrect parameter sorting
+- mixing milliseconds and microseconds
+- forgetting `user` or `signer`
+- assuming V3 is still plain HMAC
+- relying too much on endpoint titles instead of the authentication section
+
+---
+
+- `V1` is fundamentally the standard `API Key` model.
+- `V3` introduces the `API Wallet / Agent` model, and its authentication flow is closer to on-chain signing.
+- The two versions remain broadly aligned in business capability, with the main difference concentrated in the authentication layer.
+- On futures, `V3` is built on top of `Aster L1`, which gives it stronger `Take Order` performance and a more unified endpoint structure.
+- `V3` goes through the blockchain, making future historical trade traceability possible with stronger security and visibility.
+- `V3` uses `nonce` to prevent replay and improve request security.
+- `V3` supports `Noop`, which can cancel orders faster.
+- Fund-related APIs still require extra attention because they often involve additional wallet-based signing.

CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## 2026-05-26
+
+### Added
+
+#### Prediction API Testnet Documentation / 预测市场 API 测试网文档
+
+Added full API reference documentation for the Prediction API on testnet (`https://papi.asterdex-testnet.com`), covering:
+
+- **Market data**: `GET /api/v3/prediction/ping`, `GET /api/v3/prediction/time`, `GET /api/v3/prediction/exchangeInfo`, depth, trades, klines, tickers, best order book
+- **Trading**: `POST /api/v3/order` (Place order), `DELETE /api/v3/order` (Cancel order), `GET /api/v3/order`, open orders, all orders, cancel all open orders
+- **Prediction market**: mint (`POST /api/v3/prediction/mint`), burn (`POST /api/v3/prediction/burn`), positions (`GET /api/v3/prediction/positionRisk`), position history, settlement history
+- **Account**: perp-spot transfer, withdraw fee, withdraw, account info, trade history
+- **WebSocket streams**: trades, klines, tickers, order book depth (limited & incremental), listen key lifecycle, `ACCOUNT_UPDATE` payload
+
+Documentation available in both English (`V3(Recommended)/EN/aster-finance-prediction-api-tesetnet.md`) and Chinese (`V3(Recommended)/中文/aster-finance-prediction-api-testnet.md`).
+
+---
+
+## 2026-05-21
+
+### Added
+
+#### `POST /aster-chain/v3/transfer` — Transfer to Address / 转账至地址
+
+A new WITHDRAW-authenticated endpoint for transferring assets to another registered Aster Chain user address. Returns `transferId`, `asset`, `amount`, `toAddress`, `timestamp`, and `status`.
+
+#### STP Mode APIs / 自成交防止模式接口
+
+- `POST /fapi/v3/stpMode` — Change STP Mode / 更改STP模式 (TRADE, weight 1)
+- `GET /fapi/v3/stpMode` — Get Current STP Mode / 查询STP模式 (USER_DATA, weight 30)
+
+Supports `EXPIRE_TAKER`, `EXPIRE_MAKER`, `EXPIRE_BOTH`. Added `stpMode` optional parameter to `POST /fapi/v3/order` for per-order STP override.
+
+
+### Added
+
+#### `POST /fapi/v3/stpMode` — Change STP Mode / 更改STP模式
+
+A new TRADE endpoint that sets the account-level **Self-Trade Prevention (STP) mode** applied to all orders by default. Accepted values: `EXPIRE_TAKER`, `EXPIRE_MAKER`, `EXPIRE_BOTH`.
+
+#### `GET /fapi/v3/stpMode` — Get Current STP Mode / 查询STP模式
+
+A new USER_DATA endpoint that returns the account's current STP mode.
+
+### Changed
+
+#### `POST /fapi/v3/order` — New Order: added optional `stpMode` parameter
+
+Added `stpMode` (ENUM, optional) to the place-order parameter list. When specified, it overrides the account-level STP default for that individual order.
+
+---
+
+## 2026-05-20
+
+### Added
+
+#### Strategy Order APIs / 策略订单接口
+
+- `POST /fapi/v3/placeStrategyOrder` — Place Strategy Order / 策略下单
+- `POST /fapi/v3/updateStrategyOrder` — Update Strategy Order / 更新策略订单
+- `GET /fapi/v3/strategyOrder` — Query Strategy Open Order / 查询策略当前挂单
+- `GET /fapi/v3/strategyOrder/history` — Query Strategy History Order / 查询策略历史订单
+
+Supports OTO, OCO, and OTOCO strategy types.
+
+---
+
+## 2026-05-19
+
+### Added
+
+#### `POST /fapi/v3/chase` — Place Chase Order / 下追单
+
+A new public endpoint that **places a BBO-pegged GTX limit order with automatic price tracking**. The strategy service polls each tick and re-pegs the order to `bid1 − chaseOffset` (BUY) or `ask1 + chaseOffset` (SELL). The chase auto-cancels when the market moves beyond `maxChaseOffset` from the original BBO. Supports `priceLimit`, `quantityUnit` (`BASE` / `QUOTE`), and optional `maxChaseOffset` in `ABSOLUTE` or `PERCENTAGE` units.
+
+### Changed
+
+#### `PUT /fapi/v3/order` — Modify Order: clarified BBO-pegged behavior
+
+Added a note that BBO-pegged orders (placed with `pegPriceType = COUNTERPARTY_1 / QUEUE_1`) cannot have their price re-resolved via plain modify — to continuously track the BBO use a Chase order (`POST /fapi/v3/chase`).
+
+---
+
+## 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 / 用户资产迁移历史

README.md

@@ -1,8 +1,50 @@
-# API Documentation for Aster Finance
+# Aster API Docs
 
-[Aster Finance API Document](./aster-finance-api.md)
+Official API documentation for Aster.
 
-# Aster Finance API 文档
+## 🚀 Quick Start
 
-[Aster Finance API 文档](./aster-finance-api_CN.md)
+- Use **V3 (Recommended)** for all new integrations
+- Starting from **March 25, 2026**, V1 new API Key creation is no longer supported. Existing API Keys will continue to work.
+- Choose **EN** / **中文** based on your preference
 
+## 📖 Docs
+
+### API Overview
+
+- [Aster API Overview](./Aster%20API%20Overview.md)
+
+### V3 Futures API (Recommended)
+
+- [Futures API V3 (EN)](./V3(Recommended)/EN/aster-finance-futures-api-v3.md)
+- [Futures API V3 (中文)](./V3(Recommended)/中文/aster-finance-futures-api-v3_CN.md)
+- [Futures Testnet API V3 (EN)](./V3(Recommended)/EN/aster-finance-futures-api-testnet.md)
+- [Futures Testnet API V3 (中文)](./V3(Recommended)/中文/aster-finance-futures-api-testnet_CN.md)
+
+### V3 Spot API (Recommended)
+
+- [Spot API V3 (EN)](./V3(Recommended)/EN/aster-finance-spot-api-v3.md)
+- [Spot API V3 (中文)](./V3(Recommended)/中文/aster-finance-spot-api_CN-v3.md)
+- [Spot Testnet API V3 (EN)](./V3(Recommended)/EN/aster-finance-spot-api-testnet.md)
+- [Spot Testnet API V3 (中文)](./V3(Recommended)/中文/aster-finance-spot-api-testnet_CN.md)
+
+### V1 Futures API (Legacy)
+
+- [Futures API V1 (EN)](./V1(Legacy)/EN/aster-finance-futures-api.md)
+- [Futures API V1 (中文)](./V1(Legacy)/中文/aster-finance-futures-api_CN.md)
+
+### V1 Spot API (Legacy)
+
+- [Spot API V1 (EN)](./V1(Legacy)/EN/aster-finance-spot-api.md)
+- [Spot API V1 (中文)](./V1(Legacy)/中文/aster-finance-spot-api_CN.md)
+
+### RPC
+
+- [Aster Chain RPC](./RPC/aster-chain-rpc.md)
+- [Aster Chain RPC 文档](./RPC/aster-chain-rpc_CN.md)
+
+### Demo
+
+- [API Key Registration](./demo/aster-api-key-registration.md)
+- [Spot Asset Consolidation](./demo/consolidation.js)
+- [Deposit & Withdrawal](./demo/aster-deposit-withdrawal.md)