diff --git a/README.md b/README.md index c80d3d4..f58dc31 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,149 @@ -# Aster API Docs +# Aster API Documentation -Official API documentation for Aster. +Official API documentation for [AsterDEX](https://www.asterdex.com) — Futures, Spot, and Aster Chain. -## 🚀 Quick Start +## Quick start -- 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 +### 1. Choose your API version -## 📖 Docs +| Version | Auth method | Status | Best for | +|---------|------------|--------|----------| +| **V3 (recommended)** | EIP-712 signature | Active | New integrations | +| V1 | HMAC SHA-256 | Deprecated (existing keys still work) | Legacy bots | -### API Overview +> Since March 25, 2026, new V1 API keys can no longer be created. Use V3 for all new projects. -- [Aster API Overview](./Aster%20API%20Overview.md) +### 2. Create your API wallet (V3) + +1. Go to [asterdex.com/en/api-wallet](https://www.asterdex.com/en/api-wallet) +2. Connect your main wallet (MetaMask) +3. Click **"Authorize new API wallet"** +4. Sign the transaction +5. **Save both values immediately** — the private key is shown only once + +You now have 3 values needed for all V3 requests: + +| Value | What it is | Where to find it | +|-------|-----------|-----------------| +| `user` | Your main wallet address | MetaMask — the wallet you deposited with | +| `signer` | Agent/API wallet address | Shown after creation at [/api-wallet](https://www.asterdex.com/en/api-wallet) | +| `private_key` | Agent wallet's private key | Shown **once** at creation — save it immediately | + +> **Note:** A wallet named `@aster-desktop` also appears on the page. This is the internal agent used by the AsterDEX web UI — ignore it for API purposes. + +### 3. Sign your first request + +V3 uses EIP-712 typed data signatures. The signing flow: -### V3 Futures API (Recommended) +1. Build a `msg` string from your request parameters (strict key ordering for trade endpoints) +2. Hash it with the EIP-712 domain `{name: "AsterSignTransaction", version: "1", chainId: 1666}` +3. Sign the hash with your **agent private key** (not your main wallet key) +4. Include `user`, `signer`, `nonce` (microseconds), and `signature` (0x-prefixed) in the request body -- [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) +See working example: [Python demo](demo/aster-code.py) -### V3 Spot API (Recommended) +### 4. Common signature errors -- [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) +If you get `{"code": -1000, "msg": "Signature check failed"}`: -### V1 Futures API (Legacy) +| Check | Fix | +|-------|-----| +| Wrong key | Sign with the **agent** private key, not your main wallet key | +| Signer mismatch | The `signer` field must match the address derived from your private key | +| Agent not approved | Verify agent is listed and active at [/api-wallet](https://www.asterdex.com/en/api-wallet) | +| Clock drift | Nonce must be within 10 seconds of server time (microsecond precision) | +| Param ordering | Trade endpoints use strict key order: `symbol, side, type, quantity, price, timeInForce, leverage, orderId` | -- [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) +## API documentation -- [Spot API V1 (EN)](./V1(Legacy)/EN/aster-finance-spot-api.md) -- [Spot API V1 (中文)](./V1(Legacy)/中文/aster-finance-spot-api_CN.md) +### Overview + +- [Aster API Overview](./Aster%20API%20Overview.md) + +### Futures + +| Document | Language | +|----------|----------| +| [Futures API V3](V3(Recommended)/EN/aster-finance-futures-api-v3.md) | English | +| [Futures API V3 文档](V3(Recommended)/中文/aster-finance-futures-api-v3_CN.md) | 中文 | +| [Futures Testnet API V3](V3(Recommended)/EN/aster-finance-futures-api-testnet.md) | English | +| [Futures Testnet API V3 文档](V3(Recommended)/中文/aster-finance-futures-api-testnet_CN.md) | 中文 | +| [Futures API V1](V1(Legacy)/EN/aster-finance-futures-api.md) | English | +| [Futures API V1 文档](V1(Legacy)/中文/aster-finance-futures-api_CN.md) | 中文 | + +### Spot + +| Document | Language | +|----------|----------| +| [Spot API V3](V3(Recommended)/EN/aster-finance-spot-api-v3.md) | English | +| [Spot API V3 文档](V3(Recommended)/中文/aster-finance-spot-api_CN-v3.md) | 中文 | +| [Spot Testnet API V3](V3(Recommended)/EN/aster-finance-spot-api-testnet.md) | English | +| [Spot Testnet API V3 文档](V3(Recommended)/中文/aster-finance-spot-api-testnet_CN.md) | 中文 | +| [Spot API V1](V1(Legacy)/EN/aster-finance-spot-api.md) | English | +| [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) +| Document | Language | +|----------|----------| +| [Aster Chain RPC](RPC/aster-chain-rpc.md) | English | +| [Aster Chain RPC 文档](RPC/aster-chain-rpc_CN.md) | 中文 | + +### Account & operations + +| Document | Description | +|----------|-------------| +| [API key registration](demo/aster-api-key-registration.md) | How to create API keys | +| [Deposit & withdrawal](demo/aster-deposit-withdrawal.md) | Deposit and withdrawal guide | +| [Spot asset consolidation](demo/consolidation.js) | Asset consolidation script example | + +--- + +## Code examples + +### Official demos + +| Language | File | Description | +|----------|------|-------------| +| Python | [demo/aster-code.py](demo/aster-code.py) | V3 EIP-712 signing — Futures | +| Python | [demo/sol_agent.py](demo/sol_agent.py) | Solana wallet agent demo | +| JavaScript | [demo/consolidation.js](demo/consolidation.js) | Spot asset consolidation | +| JavaScript | [demo/create-apikey-for-others.js](demo/create-apikey-for-others.js) | Create API keys for sub-accounts | + +### Official tools + +| Tool | Description | Link | +|------|-------------|------| +| aster-connector-python | Lightweight Python connector | [github.com/asterdex/aster-connector-python](https://github.com/asterdex/aster-connector-python) | +| aster-mcp | MCP server for Cursor/Claude | [github.com/asterdex/aster-mcp](https://github.com/asterdex/aster-mcp) | +| aster-skills-hub | Agent skills for OpenClaw | [github.com/asterdex/aster-skills-hub](https://github.com/asterdex/aster-skills-hub) | + +### Community tools + +| Tool | Description | Link | +|------|-------------|------| +| kairos-aster-sdk | Full Python SDK — Futures, Spot & WebSocket V3 with EIP-712 abstraction | [github.com/Valisthea/kairos-aster-sdk-V3](https://github.com/Valisthea/kairos-aster-sdk-V3) | + +--- + +## API endpoints + +| API | REST base URL | WebSocket | +|-----|--------------|-----------| +| Futures V3 | `https://fapi.asterdex.com/fapi/v3/` | `wss://fstream.asterdex.com` | +| Futures V1 | `https://fapi.asterdex.com/fapi/v1/` | `wss://fstream.asterdex.com` | +| Spot | `https://sapi.asterdex.com` | `wss://sstream.asterdex.com` | +| Futures testnet | `https://fapi.asterdex-testnet.com/fapi/v3/` | `wss://fstream.asterdex-testnet.com` | +| Spot testnet | `https://sapi.asterdex-testnet.com` | `wss://sstream.asterdex-testnet.com` | + +--- -### Demo +## Additional resources -- [API Key Registration](./demo/aster-api-key-registration.md) -- [Spot Asset Consolidation](./demo/consolidation.js) -- [Deposit & Withdrawal](./demo/aster-deposit-withdrawal.md) +- [API website with full endpoint docs](https://asterdex.github.io/aster-api-website/futures-v3/general-info/) +- [Aster Code (builder integration)](https://asterdex.github.io/aster-api-website/asterCode/integration-flow/) +- [Error codes reference](https://asterdex.github.io/aster-api-website/futures-v3/error-codes/) +- [Official docs](https://docs.asterdex.com/for-developers/aster-api) +- [API wallet management](https://www.asterdex.com/en/api-wallet)