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. 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. 1. Step 1 — Get lightweight summary first:

CODEBLOCK0

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

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

CODEBLOCK1

Endpoints That Return Dangerously Large Data (without symbol filter)

Endpoint	Without INLINECODE8	With INLINECODE9
INLINECODE10	ALL symbols + filters (100KB+)	N/A — use jq to filter
INLINECODE12

ALL symbols (50KB+) | Single object (~500B) | | /fapi/v3/ticker/price | ALL symbols (10KB+) | Single object (~80B) | | /fapi/v3/ticker/bookTicker | ALL symbols (20KB+) | Single object (~150B) | | /fapi/v3/premiumIndex | ALL symbols (30KB+) | Single object (~300B) | | /fapi/v3/depth | N/A (symbol required) | Varies by limit: use limit=5 for overview | | /fapi/v3/klines | N/A (symbol required) | Default 500 candles — always set limit | | /fapi/v3/trades | N/A (symbol required) | Default 500 trades — always set limit |

Example: Safe vs Unsafe

CODEBLOCK2

---

Quick Reference

Endpoint	Description	Required	Optional	Authentication
INLINECODE23 (GET)	Test connectivity	None	None	No
INLINECODE24 (GET)

Check server time | None | None | No |
| /fapi/v3/exchangeInfo (GET) | Exchange information | None | None | No |
| /fapi/v3/depth (GET) | Order book | symbol | limit | No |
| /fapi/v3/trades (GET) | Recent trades list | symbol | limit | No |
| /fapi/v3/historicalTrades (GET) | Old trades lookup | symbol | limit, fromId | Yes |
| /fapi/v3/aggTrades (GET) | Compressed/Aggregate trades list | symbol | fromId, startTime, endTime, limit | No |
| /fapi/v3/klines (GET) | Kline/Candlestick data | symbol, interval | startTime, endTime, limit | No |
| /fapi/v3/indexPriceKlines (GET) | Index price kline data | pair, interval | startTime, endTime, limit | No |
| /fapi/v3/markPriceKlines (GET) | Mark price kline data | symbol, interval | startTime, endTime, limit | No |
| /fapi/v3/premiumIndex (GET) | Mark price and funding rate | None | symbol | No |
| /fapi/v3/fundingRate (GET) | Funding rate history | None | symbol, startTime, endTime, limit | No |
| /fapi/v3/ticker/24hr (GET) | 24hr ticker price change statistics | None | symbol | No |
| /fapi/v3/ticker/price (GET) | Symbol price ticker | None | symbol | No |
| /fapi/v3/ticker/bookTicker (GET) | Symbol order book ticker | None | symbol | No |
| /fapi/v3/order (POST) | New order | symbol, side, type, timestamp | positionSide, timeInForce, quantity, reduceOnly, price, newClientOrderId, stopPrice, closePosition, activationPrice, callbackRate, workingType, priceProtect, newOrderRespType, recvWindow | Yes |
| /fapi/v3/batchOrders (POST) | Place multiple orders | batchOrders, timestamp | recvWindow | Yes |
| /fapi/v3/order (GET) | Query order | symbol, timestamp | orderId, origClientOrderId, recvWindow | Yes |
| /fapi/v3/order (DELETE) | Cancel order | symbol, timestamp | orderId, origClientOrderId, recvWindow | Yes |
| /fapi/v3/allOpenOrders (DELETE) | Cancel all open orders | symbol, timestamp | recvWindow | Yes |
| /fapi/v3/batchOrders (DELETE) | Cancel multiple orders | symbol, timestamp | orderIdList, origClientOrderIdList, recvWindow | Yes |
| /fapi/v3/countdownCancelAll (POST) | Auto-cancel all open orders (countdown) | symbol, countdownTime, timestamp | recvWindow | Yes |
| /fapi/v3/openOrder (GET) | Query current open order | symbol, timestamp | orderId, origClientOrderId, recvWindow | Yes |
| /fapi/v3/openOrders (GET) | Current all open orders | timestamp | symbol, recvWindow | Yes |
| /fapi/v3/allOrders (GET) | All orders | symbol, timestamp | orderId, startTime, endTime, limit, recvWindow | Yes |
| /fapi/v3/balance (GET) | Futures account balance | timestamp | recvWindow | Yes |
| /fapi/v3/account (GET) | Account information | timestamp | recvWindow | Yes |
| /fapi/v3/leverage (POST) | Change initial leverage | symbol, leverage, timestamp | recvWindow | Yes |
| /fapi/v3/marginType (POST) | Change margin type | symbol, marginType, timestamp | recvWindow | Yes |
| /fapi/v3/positionMargin (POST) | Modify isolated position margin | symbol, amount, type, timestamp | positionSide, recvWindow | Yes |
| /fapi/v3/positionMargin/history (GET) | Position margin change history | symbol, timestamp | type, startTime, endTime, limit, recvWindow | Yes |
| /fapi/v3/positionRisk (GET) | Position information | timestamp | symbol, recvWindow | Yes |
| /fapi/v3/positionSide/dual (POST) | Change position mode | dualSidePosition, timestamp | recvWindow | Yes |
| /fapi/v3/positionSide/dual (GET) | Get current position mode | timestamp | recvWindow | Yes |
| /fapi/v3/multiAssetsMargin (POST) | Change multi-assets mode | multiAssetsMargin, timestamp | recvWindow | Yes |
| /fapi/v3/multiAssetsMargin (GET) | Get current multi-assets mode | timestamp | recvWindow | Yes |
| /fapi/v3/asset/wallet/transfer (POST) | Transfer between futures and spot | amount, asset, clientTranId, kindType, timestamp | None | Yes |
| /fapi/v3/userTrades (GET) | Account trade list | symbol, timestamp | startTime, endTime, fromId, limit, recvWindow | Yes |
| /fapi/v3/income (GET) | Get income history | timestamp | symbol, incomeType, startTime, endTime, limit, recvWindow | Yes |
| /fapi/v3/leverageBracket (GET) | Notional and leverage brackets | timestamp | symbol, recvWindow | Yes |
| /fapi/v3/adlQuantile (GET) | Position ADL quantile estimation | timestamp | symbol, recvWindow | Yes |
| /fapi/v3/forceOrders (GET) | User's force orders | timestamp | symbol, autoCloseType, startTime, endTime, limit, recvWindow | Yes |
| /fapi/v3/commissionRate (GET) | User commission rate | symbol, timestamp | recvWindow | Yes |
| /fapi/v3/listenKey (POST) | Start user data stream | None | None | Yes |
| /fapi/v3/listenKey (PUT) | Keepalive user data stream | None | None | Yes |
| /fapi/v3/listenKey (DELETE) | Close user data stream | None | None | Yes |
| GET /bapi/futures/v1/public/future/aster/deposit/assets | Get all deposit assets | chainIds, accountType | networks | No |
| GET /bapi/futures/v1/public/future/aster/withdraw/assets | Get all withdraw assets | chainIds, accountType | networks | No |
| GET /bapi/futures/v1/public/future/aster/estimate-withdraw-fee | Estimate withdraw fee | chainId, network, currency, accountType | None | No |
| POST /fapi/aster/user-withdraw | Withdraw by API (EVM Futures) | chainId, asset, amount, fee, receiver, nonce, userSignature, timestamp, signature | recvWindow | Yes |
| POST /fapi/aster/user-solana-withdraw | Withdraw by API (Solana Futures) | chainId, asset, amount, fee, receiver, timestamp, signature | recvWindow | Yes |

---

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, STOPMARKET, TAKEPROFIT, TAKEPROFITMARKET, TRAILINGSTOPMARKET)
• 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/STOPMARKET/TAKEPROFIT/TAKEPROFITMARKET orders
• closePosition: Close-All flag; "true" or "false"; cannot be used with quantity
• activationPrice: Activation price for TRAILINGSTOPMARKET orders
• callbackRate: Callback rate for TRAILINGSTOPMARKET; range 0.1-5
• workingType: Stop price trigger type; "MARKPRICE" or "CONTRACTPRICE"
• 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; FUTURESPOT or SPOTFUTURE
• incomeType: Income type filter (TRANSFER, WELCOMEBONUS, REALIZEDPNL, FUNDINGFEE, COMMISSION, INSURANCECLEAR, MARKETMERCHANTRETURN_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 | STOPMARKET | TAKEPROFIT | TAKEPROFITMARKET | TRAILINGSTOPMARKET
• timeInForce: GTC | IOC | FOK | GTX
• workingType: MARKPRICE | CONTRACTPRICE
• marginType: ISOLATED | CROSSED
• newOrderRespType: ACK | RESULT
• interval: 1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M
• orderStatus: NEW | PARTIALLYFILLED | FILLED | CANCELED | REJECTED | EXPIRED
• contractStatus: PENDINGTRADING | TRADING | PRESETTLE | SETTLING | CLOSE
• incomeType: TRANSFER | WELCOMEBONUS | REALIZEDPNL | FUNDINGFEE | COMMISSION | INSURANCECLEAR | MARKETMERCHANTRETURNREWARD
• autoCloseType: LIQUIDATION | ADL
• kindType: FUTURESPOT | SPOTFUTURE
• 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:

CODEBLOCK3

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: INLINECODE75
• API Wallet: Show first 6 + last 4 characters: INLINECODE76
• Private Key: Always mask, show only last 5: INLINECODE77

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: yourmainwalletaddress
• API Wallet: yourapiwalletaddress
• Private Key: yourapiwalletprivatekey
• Description: Primary trading account

TOOLS.md Structure

CODEBLOCK4

Agent Behavior

1. 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. 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.