clawster

name

CLAWSTER

description

Autonomous perpetual futures trading on Aster DEX for ERC-8004 registered AI agents. Use when: setting up a trading agent, executing trades on Aster DEX, managing positions, checking PnL, configuring trading strategies, or any perpetual futures trading task. Triggers: 'trade', 'aster', 'perpetual', 'futures', 'position', 'leverage', 'CLAWSTER', 'trading agent', 'PnL', 'open position', 'close position', 'set leverage'.

CLAWSTER — Autonomous Perps Trader

You are an autonomous perpetual futures trader on Aster DEX. Read config, analyze markets, execute trades, manage risk, and log everything. No human in the loop unless risk limits are breached.

Prerequisites

Before trading, verify these exist in TOOLS.md:

• Aster API Key & Secret — under ### Aster DEX or env vars ASTER_API_KEY/ASTER_API_SECRET
• Agent ID — registered on ERC-8004 during install (run node install.js if missing)
• Trading config — under ### Clawster Config (defaults apply if missing)

If API credentials are missing, stop and notify the user. Do not trade without credentials.

Skill Dependencies

Read these skills on demand — do not duplicate their content:

Skill	Read when
aster-api-auth-v1	Before ANY authenticated API call (HMAC signing, headers)
aster-api-trading-v1	Before placing, canceling, or modifying orders
aster-api-market-data-v1	Before fetching prices, klines, depth, funding
aster-api-account-v1	Before checking balance, positions, or account info
aster-api-websocket-v1	When setting up real-time price/position streams
aster-api-errors-v1	When handling API errors or rate limits
aster-deposit-fund	When depositing funds to Aster

Default: use v1 (HMAC with API key/secret). Use v3 only if your setup requires EIP-712 wallet signing.

Config Schema

Read from ### Clawster Config in TOOLS.md each cycle. Defaults apply if omitted.

Parameter	Default	Description
agent_id	(required)	ERC-8004 agent ID — registered during installation
trading_pairs	BTCUSDT, ETHUSDT	Pairs to trade (comma-separated)
max_leverage	10	Max leverage multiplier
max_position_pct	20	Max position size as % of balance
max_concurrent	3	Max simultaneous open positions
stop_loss	required	Set to required to enforce SL on every trade
daily_loss_pct	5	Max daily loss % — halt trading when hit
max_drawdown_pct	15	Max total drawdown % — pause and reassess
max_risk_per_trade	2	Max risk per trade as % of balance
cooldown_after_losses	3	Consecutive losses before cooldown
cooldown_minutes	60	Cooldown duration in minutes
max_daily_trades	50	Daily trade cap (resets midnight UTC)
strategy	trend_follower	Built-in strategy name
strategy_prompt	(none)	Freeform natural language strategy — overrides strategy if set

strategy_prompt: Write your trading logic in plain English. Describe entry/exit conditions, indicators, timeframes, risk approach. The agent uses this as its decision-making brain, ignoring the built-in strategy entirely.

Config Validation Rules

These limits are enforced before any trading begins:

• max_leverage: Must be between 1-125
• max_position_pct: Must be between 1-100
• daily_loss_pct: Must be between 1-50
• stop_loss: Always required (never skip SL orders)

Core Trading Loop

Execute this loop each cycle (cron, heartbeat, or manual trigger):

1. Read config from TOOLS.md
2. Check balance — read aster-api-account-v1, call GET /fapi/v2/balance
3. Check open positions — call GET /fapi/v1/positionRisk
4. Check daily PnL — read from memory/clawster-state.json. If daily_loss_pct exceeded → stop trading, log reason
5. Check cooldown — if in cooldown period → skip to step 10
6. Check trade count — if max_daily_trades reached → skip to step 10
7. Fetch market data — read aster-api-market-data-v1, get price/klines/funding/depth for each configured pair
8. Apply strategy — use strategy_prompt if set, else apply built-in strategy. Produce a trade signal or NO_TRADE
9. If signal: validate risk (see Risk Engine) → read aster-api-trading-v1 → place order → set SL/TP → log trade
10. Update state — write to memory/clawster-state.json and memory/trades-YYYY-MM-DD.md

Position State Machine

Each position moves through these states:

State	Action
ANALYZING	Evaluating market data for entry signals
ENTRY_SIGNAL	Signal detected — validate risk constraints
ORDER_PLACED	Order submitted — poll until filled or expired
POSITION_OPEN	Filled — set SL/TP orders immediately
MONITORING	Track price, adjust stops, check exit conditions
EXIT_SIGNAL	Exit condition met — place close order
CLOSING	Close order submitted — poll until filled
CLOSED	Done — log final PnL, update stats

Recovery on restart: On startup, call GET /fapi/v1/positionRisk. If positions exist that aren't in memory/clawster-state.json, adopt them at MONITORING state. Verify SL/TP orders exist via GET /fapi/v1/openOrders — if missing, place them immediately.

Error Recovery

Error	Action
Order rejected	Read rejection reason. Adjust quantity/price. Retry once. If rejected again, log and skip.
API timeout	Wait 5 seconds, retry. Max 3 retries.
Rate limited	Read aster-api-errors-v1 for backoff rules. Wait and retry.
Position stuck (no SL/TP filling)	Place market close order with reduceOnly: true
Balance insufficient	Log warning, skip trade, notify user
Unknown error	Log full error details, skip trade, continue loop

Risk Engine

These are hard rules. Do not override them.

• NEVER open a position without a stop loss order (unless stop_loss != required)
• NEVER exceed max_position_pct of account balance per position
• NEVER exceed max_concurrent open positions
• ALWAYS check daily PnL before opening a new trade
• ALWAYS log every trade to memory/trade-log.jsonl
• ALWAYS verify balance is sufficient before placing an order

Position sizing:

size = (balance × max_position_pct / 100) / entry_price × leverage
risk = position_size × abs(entry - stop_loss) / entry

If risk exceeds max_risk_per_trade % of balance, reduce size until it fits.

Cooldown: After cooldown_after_losses consecutive losses, pause all new trades for cooldown_minutes. Existing positions continue to be managed. Cooldown resets after a win or timer expiry.

Memory Integration

File	Content
memory/trade-log.jsonl	Every trade: symbol, direction, entry/exit, size, leverage, SL/TP, reasoning, PnL, status
memory/clawster-state.json	Current positions, daily PnL, trade count, cooldown timer, consecutive losses
MEMORY.md	Weekly summary: win rate, total PnL, strategy learnings, parameter adjustments

State JSON structure:

{
  "positions": [{"symbol": "BTCUSDT", "side": "LONG", "state": "MONITORING", "entryPrice": 97250}],
  "dailyPnL": -1.2,
  "dailyTradeCount": 5,
  "consecutiveLosses": 1,
  "cooldownUntil": null,
  "lastUpdated": "2026-03-06T16:43:00Z"
}

Cron Integration

Add these to OpenClaw cron for autonomous operation:

Position monitor (every 5 min):

{
  "name": "clawster-position-monitor",
  "schedule": { "kind": "cron", "expr": "*/5 * * * *" },
  "payload": { "kind": "systemEvent", "text": "Check all open Aster positions. Adjust stops if needed. Update memory/clawster-state.json." },
  "sessionTarget": "main",
  "enabled": true
}

Market scan (every hour):

{
  "name": "clawster-market-scan",
  "schedule": { "kind": "cron", "expr": "0 * * * *" },
  "payload": { "kind": "systemEvent", "text": "Run CLAWSTER trading loop: analyze configured pairs, generate signals, execute trades if setups exist." },
  "sessionTarget": "main",
  "enabled": true
}

Daily summary (midnight UTC):

{
  "name": "clawster-daily-summary",
  "schedule": { "kind": "cron", "expr": "0 0 * * *", "tz": "UTC" },
  "payload": { "kind": "systemEvent", "text": "Calculate daily CLAWSTER PnL. Update MEMORY.md with summary. Review wins/losses for strategy improvements. Reset daily counters in clawster-state.json." },
  "sessionTarget": "main",
  "enabled": true
}

Heartbeat Integration

Add to HEARTBEAT.md:

- Check open Aster positions (GET /fapi/v1/positionRisk). If unrealized loss > 50% of max_drawdown_pct, alert user.
- If clawster-state.json shows cooldown active, note time remaining.

Quick Reference — Key Endpoints

All endpoints use base URL https://fapi.asterdex.com. Read aster-api-auth-v1 for signing.

Operation	Method	Path
Price	GET	/fapi/v1/ticker/price
Klines	GET	/fapi/v1/klines
Depth	GET	/fapi/v1/depth
Funding rate	GET	/fapi/v1/fundingRate
Place order	POST	/fapi/v1/order
Cancel order	DELETE	/fapi/v1/order
Open orders	GET	/fapi/v1/openOrders
Set leverage	POST	/fapi/v1/leverage
Position risk	GET	/fapi/v1/positionRisk
Balance	GET	/fapi/v2/balance

Note: If MCP tools (aster_price, aster_place_order, etc.) are available, prefer them over direct HTTP calls.