Aster Futures

Aster Futures Skill

Futures request on Aster using authenticated API endpoints. Authentication uses EIP-712 ECDSA signing with API wallet (main wallet + signer wallet). 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 futures are available?"), use a layered approach:

1. Step 1 — Get lightweight summary first:

   # Get just the symbol list, not full exchangeInfo
   curl -s "https://fapi.asterdex.com/fapi/v3/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://fapi.asterdex.com/fapi/v3/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 ".../fapi/v3/ticker/price" | head -c 5000

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

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

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

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

Quick Reference

Parameters

Common Parameters

• symbol: Trading pair symbol (e.g., BTCUSDT)
• pair: Trading pair for index price endpoints (e.g., BTCUSDT)
• side: Order side BUY or SELL
• type: Order type (LIMIT, MARKET, STOP, STOP_MARKET, TAKE_PROFIT, TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET)
• positionSide: Position side; default BOTH for One-way Mode; LONG/SHORT for Hedge Mode
• timeInForce: Time in force (GTC, IOC, FOK, GTX)
• quantity: Order quantity (e.g., 0.1)
• price: Order price (e.g., 50000)
• stopPrice: Stop price for STOP/STOP_MARKET/TAKE_PROFIT/TAKE_PROFIT_MARKET orders
• closePosition: Close-All flag; "true" or "false"; cannot be used with quantity
• activationPrice: Activation price for TRAILING_STOP_MARKET orders
• callbackRate: Callback rate for TRAILING_STOP_MARKET; range 0.1-5
• workingType: Stop price trigger type; "MARK_PRICE" or "CONTRACT_PRICE"
• priceProtect: Price protection flag; "TRUE" or "FALSE"
• reduceOnly: Reduce-only flag; default "false"
• newClientOrderId: Unique client order ID
• newOrderRespType: Response type; "ACK" or "RESULT"
• orderId: Order ID (e.g., 22542179)
• origClientOrderId: Original client order ID
• orderIdList: List of order IDs to cancel (max 10)
• origClientOrderIdList: List of client order IDs to cancel (max 10)
• batchOrders: List of order objects (max 5)
• countdownTime: Countdown time in milliseconds; set to 0 to cancel countdown
• leverage: Leverage value; range 1-125
• marginType: Margin type; ISOLATED or CROSSED
• amount: Margin amount for position margin modification
• dualSidePosition: Position mode; "true" = Hedge Mode; "false" = One-way Mode
• multiAssetsMargin: Multi-assets mode; "true" = Multi-Assets Mode; "false" = Single-Asset Mode
• asset: Asset name (e.g., USDT)
• clientTranId: Client transfer ID (unique within 7 days)
• kindType: Transfer direction; FUTURE_SPOT or SPOT_FUTURE
• incomeType: Income type filter (TRANSFER, WELCOME_BONUS, REALIZED_PNL, FUNDING_FEE, COMMISSION, INSURANCE_CLEAR, MARKET_MERCHANT_RETURN_REWARD)
• autoCloseType: Force order type; LIQUIDATION or ADL
• fromId: ID to get trades from INCLUSIVE (e.g., 1)
• startTime: Timestamp in ms to filter from INCLUSIVE (e.g., 1735693200000)
• endTime: Timestamp in ms to filter until INCLUSIVE (e.g., 1735693200000)
• limit: Result limit; varies per endpoint (e.g., 500)
• interval: Kline interval (e.g., 1h)
• recvWindow: Request validity window; cannot be greater than 60000 (e.g., 5000)
• timestamp: Request timestamp in milliseconds (e.g., 1735693200000)
• chainIds: Chain ID(s), comma-separated (for deposit/withdraw asset queries)
• chainId: Chain ID (for withdraw operations)
• networks: Network type (EVM, SOLANA), comma-separated
• network: Network type (EVM, SOL)
• currency: Currency name (e.g., ASTER)
• accountType: Account type (spot, perp)
• fee: Withdraw fee in token units
• receiver: Receipt address for withdrawals
• nonce: Unique number for signing (microsecond timestamp for API auth; milliseconds x 1000 for EIP712 withdraw)
• userSignature: EIP712 signature for EVM withdrawals
• signature: ECDSA API signature