Aster Spot

Aster Spot Skill

Spot request on Aster using authenticated API endpoints. Requires API key and secret key for certain endpoints. Return the result in JSON format.

Data Fetching Guidelines (CRITICAL)

NEVER truncate JSON responses with head -c, head -n, or similar — truncated JSON is corrupted and will produce wrong results.

Mandatory Rules

1. Always specify symbol parameter when querying a specific trading pair. Many endpoints return ALL symbols when symbol is omitted, producing responses of 100KB+.
2. Always use limit parameter to constrain result size. Use the smallest limit that satisfies the request (e.g., limit=5 instead of default 500).
3. Use jq to extract fields — never parse raw mega-JSON visually. Pipe through jq to select only needed data.

Progressive Data Exploration Strategy

When the user asks a broad question (e.g., "what spot pairs are available?"), use a layered approach:

1. Step 1 — Get lightweight summary first:

   # Get just the symbol list, not full exchangeInfo
   curl -s "https://sapi.asterdex.com/api/v1/exchangeInfo" | jq '[.symbols[].symbol]'
   

2. Step 2 — Confirm scope with user before fetching detailed data for many symbols.

3. Step 3 — Fetch details for specific symbols only:

   # Get price for ONE symbol, not all
   curl -s "https://sapi.asterdex.com/api/v1/ticker/price?symbol=BTCUSDT"
   

Endpoints That Return Dangerously Large Data (without symbol filter)

Example: Safe vs Unsafe

# BAD — returns ALL symbols, then truncates = corrupted JSON
curl -s ".../api/v1/ticker/price" | head -c 5000

# GOOD — returns single symbol, complete JSON
curl -s ".../api/v1/ticker/price?symbol=BTCUSDT"

# BAD — 500 candles by default
curl -s ".../api/v1/klines?symbol=BTCUSDT&interval=1h"

# GOOD — only 5 candles
curl -s ".../api/v1/klines?symbol=BTCUSDT&interval=1h&limit=5"

# GOOD — extract just symbol names from exchangeInfo
curl -s ".../api/v1/exchangeInfo" | jq '[.symbols[] | {symbol, status}]'

Quick Reference

Parameters

Common Parameters

• symbol: Trading pair (e.g., BTCUSDT)
• limit: Default 500; maximum 1000 (depth endpoint supports: 5, 10, 20, 50, 100, 500, 1000; klines max 1500)
• fromId: Return starting from trade ID (e.g., 1)
• startTime: Timestamp in ms to get data from INCLUSIVE (e.g., 1735693200000)
• endTime: Timestamp in ms to get data until INCLUSIVE (e.g., 1735693200000)
• recvWindow: The value cannot be greater than 60000. Default 5000. (e.g., 5000)
• timestamp: Unix timestamp in milliseconds (e.g., 1735693200000)
• quantity: Order quantity (e.g., 1)
• quoteOrderQty: Quote order quantity (e.g., 100)
• price: Order price (e.g., 50000)
• stopPrice: Required for STOP, STOP_MARKET, TAKE_PROFIT, TAKE_PROFIT_MARKET orders (e.g., 49000)
• newClientOrderId: Client-customized unique order ID. Automatically generated if not sent.
• orderId: Order ID (e.g., 1)
• origClientOrderId: Original client order ID
• orderIdList: Order ID array string (for batch cancel)
• origClientOrderIdList: Client order ID array string (for batch cancel)
• amount: Transfer/withdrawal quantity (e.g., 1.5)
• asset: Asset type (e.g., USDT, BTC)
• clientTranId: Client transaction ID (minimum 20 characters if provided)
• kindType: Transfer direction: FUTURE_SPOT or SPOT_FUTURE
• toAddress: Target EVM address for transfers
• chainId: Chain ID for withdrawals: 1 (ETH), 56 (BSC), 42161 (Arbi)
• fee: Withdrawal fee
• receiver: Current account address (for withdrawals)
• nonce: Current time in microseconds (for withdrawals)
• userSignature: EVM wallet signature
• address: Wallet address (for API key creation)
• userOperationType: Operation type: CREATE_API_KEY
• network: Network type (SOL for Solana network only)
• apikeyIP: Comma-separated IP addresses for whitelist
• desc: API key description (max 20 characters; no duplicates per account)
• listenKey: Listen key for user data streams

Enums

• side: BUY | SELL
• type (order type): LIMIT | MARKET | STOP | TAKE_PROFIT | STOP_MARKET | TAKE_PROFIT_MARKET
• timeInForce: GTC | IOC | FOK | GTX
• interval: 1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M
• kindType: FUTURE_SPOT | SPOT_FUTURE
• orderStatus: NEW | PARTIALLY_FILLED | FILLED | CANCELED | REJECTED | EXPIRED

Authentication

For endpoints that require authentication, you will need to provide Aster API credentials. Required credentials:

• apiKey: Your Aster API key (for header)
• secretKey: Your Aster API secret (for signing)

Base URL:

• Mainnet: https://sapi.asterdex.com

WebSocket:

• Market Streams: wss://sstream.asterdex.com

See references/authentication.md for implementation details.

Security

Share Credentials

Users can provide Aster API credentials by sending a file where the content is in the following format:

abc123...xyz
secret123...key

Never Display Full Secrets

When showing credentials to users:

• API Key: Show first 5 + last 4 characters: bb3b2...02ae
• Secret Key: Always mask, show only last 5: ***...ae1c

Example response when asked for credentials: Account: main API Key: bb3b2...02ae Secret: ***...ae1c Environment: Mainnet

Listing Accounts

When listing accounts, show names and environment only — never keys: Aster Accounts:

• main (Mainnet)
• trading (Mainnet)

Transactions in Mainnet

When performing transactions in mainnet, always confirm with the user before proceeding by asking them to write "CONFIRM" to proceed.

Aster Accounts

main

• API Key: your_mainnet_api_key
• Secret: your_mainnet_secret
• Testnet: false

TOOLS.md Structure

## Aster Accounts

### main
- API Key: abc123...xyz
- Secret: secret123...key
- Testnet: false
- Description: Primary trading account

### trading
- API Key: trade456...abc
- Secret: tradesecret...xyz
- Testnet: false
- Description: Secondary trading account

Agent Behavior

1. Credentials requested: Mask secrets (show last 5 chars only)
2. Listing accounts: Show names and environment, never keys
3. Account selection: Ask if ambiguous, default to main
4. When doing a transaction in mainnet, confirm with user before by asking to write "CONFIRM" to proceed
5. New credentials: Prompt for name, environment, signing mode

Adding New Accounts

When user provides new credentials:

• Ask for account name
• Ask: Mainnet?
• Store in TOOLS.md with masked display confirmation

Signing Requests

All trading endpoints require HMAC SHA256 signature:

1. Build query string with all params + timestamp (Unix ms)
2. Sign query string with secretKey using HMAC SHA256
3. Append signature to query string
4. Include X-MBX-APIKEY header

See references/authentication.md for implementation details.