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

Enums

• side: BUY | SELL
• positionSide: BOTH | LONG | SHORT
• type (order): LIMIT | MARKET | STOP | STOP_MARKET | TAKE_PROFIT | TAKE_PROFIT_MARKET | TRAILING_STOP_MARKET
• timeInForce: GTC | IOC | FOK | GTX
• workingType: MARK_PRICE | CONTRACT_PRICE
• marginType: ISOLATED | CROSSED
• newOrderRespType: ACK | RESULT
• interval: 1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M
• orderStatus: NEW | PARTIALLY_FILLED | FILLED | CANCELED | REJECTED | EXPIRED
• contractStatus: PENDING_TRADING | TRADING | PRE_SETTLE | SETTLING | CLOSE
• incomeType: TRANSFER | WELCOME_BONUS | REALIZED_PNL | FUNDING_FEE | COMMISSION | INSURANCE_CLEAR | MARKET_MERCHANT_RETURN_REWARD
• autoCloseType: LIQUIDATION | ADL
• kindType: FUTURE_SPOT | SPOT_FUTURE
• positionMarginType: 1 (add margin) | 2 (reduce margin)

Authentication

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

• Main Wallet Address (user): Your Aster main wallet address
• API Wallet Address (signer): Your API wallet address (obtained via Pro API registration at asterdex.com)
• API Wallet Private Key: Your API wallet private key (for ECDSA signing)

Base URLs:

• Mainnet REST: https://fapi.asterdex.com
• Mainnet WebSocket: wss://fstream.asterdex.com
• Deposit/Withdraw Portal: https://www.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:

0x1234...abcd
0x5678...efgh
private_key_hex...

Line 1: Main wallet address (user) Line 2: API wallet address (signer) Line 3: API wallet private key

Never Display Full Secrets

When showing credentials to users:

• Main Wallet: Show first 6 + last 4 characters: 0x1234...abcd
• API Wallet: Show first 6 + last 4 characters: 0x5678...efgh
• Private Key: Always mask, show only last 5: ***...f1a2b

Example response when asked for credentials: Account: main Main Wallet: 0x1234...abcd API Wallet: 0x5678...efgh Private Key: ***...f1a2b Environment: Mainnet

Listing Accounts

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

• main (Mainnet)
• trading-01 (Mainnet)
• arb-bot (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

• Main Wallet: your_main_wallet_address
• API Wallet: your_api_wallet_address
• Private Key: your_api_wallet_private_key
• Description: Primary trading account

TOOLS.md Structure

## Aster Accounts

### main
- Main Wallet: 0x1234...abcd
- API Wallet: 0x5678...efgh
- Private Key: private_key_hex...
- Description: Primary trading account

### trading-01
- Main Wallet: 0xaaaa...1111
- API Wallet: 0xbbbb...2222
- Private Key: private_key_hex...
- Description: Automated trading

### arb-bot
- Main Wallet: 0xcccc...3333
- API Wallet: 0xdddd...4444
- Private Key: private_key_hex...
- Description: Arbitrage bot account

Agent Behavior

1. Credentials requested: Mask private keys (show last 5 chars only), mask wallet addresses (show first 6 + last 4)
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, main wallet, API wallet, private key

Adding New Accounts

When user provides new credentials:

• Ask for account name
• Ask for main wallet address (user)
• Ask for API wallet address (signer)
• Ask for API wallet private key
• Store in TOOLS.md with masked display confirmation

Signing Requests

All authenticated endpoints require EIP-712 ECDSA signature:

1. Collect all API parameters as key-value pairs (all values as strings)
2. Sort parameters by ASCII key order
3. Combine sorted parameters with user (main wallet address), signer (API wallet address), and nonce (microsecond timestamp) using Web3 ABI encoding
4. Generate Keccak256 hash of the ABI-encoded data
5. Sign the hash with the API wallet's private key via ECDSA
6. Include user, signer, nonce, and signature in the request
7. Timestamp must be current milliseconds; request valid within recvWindow (default 5000ms)

See references/authentication.md for implementation details.