aster-futures

Files (3)

• SKILL.md
• _meta.json
• authentication.md · references/

SKILL.md (first lines)

# 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:**
   ```bash
   # 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:**
   ```bash
   # 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)

| Endpoint | Without `symbol` | With `symbol` |
|----------|------------------|---------------|
| `/fapi/v3/exchangeInfo` | ALL symbols + filters (100KB+) | N/A — use `jq` to filter |
| `/fapi/v3/ticker/24hr` | 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

```bash
# 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

| Endpoint | Description | Required | Optional | Authentication |
|----------|-------------|----------|----------|----------------|
| `/fapi/v3/ping` (GET) | Test connectivity | None | None | No |
| `/fapi/v3/time` (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 |

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills