--- name: hyperliquid-trading-agent-operator version: 1.0.0 description: >- Skill for AI coding agents to design, implement, and operate autonomous trading agents on Hyperliquid L1 and HIP-3 DEXs, managed via OpenClaw.ai and observed through Nexwave.so. Use this skill when a user wants Hyperliquid perps bots, HIP-3 DEX integrations, or an end-to-end agent operator workflow. author: Algo Traders Club license: MIT compatibility: language: python frameworks: - node - nextjs environments: - server - cli metadata: ecosystem: - hyperliquid - hip-3 - openclaw - nexwave tags: - trading - agents - perps - defi - hyperliquid - orchestration --- # Hyperliquid Trading Agent Operator Skill This skill teaches an AI coding agent how to help a human: 1. **Design** a trading agent that trades perpetual futures on **Hyperliquid L1** or HIP-3 DEXs. 2. **Implement** the agent in Python or TypeScript using the Hyperliquid SDK / APIs. 3. **Operate** the agent using **OpenClaw.ai** for lifecycle management (start/stop/restart, health checks, logging). 4. **Observe & optimize** the agent by sending metrics/events to **Nexwave.so**. Use this skill whenever: - The user asks to build a bot/agent for Hyperliquid perps. - The user mentions the Algo Traders Club curriculum or operator workflow. - The user wants multi-agent operations or advanced observability. --- ## Mental Model Think in terms of **three layers**: - **Execution (Hyperliquid L1 / HIP-3 DEXs)** – Where orders are placed and trades settle. - **Orchestration (OpenClaw.ai)** – Where agents run, are restarted, configured, and supervised. - **Data (Nexwave.so)** – Where metrics, logs, and events are stored and analyzed. The agent code should be: - **Stateless or minimally stateful** within a single process. - Configurable via environment variables or a small config file. - Safe against crashes and network failures (OpenClaw will restart, but the agent should handle errors gracefully). --- ## Core Patterns ### 1. Basic Hyperliquid Perps Agent (Pseudo-Code) ```python import os import asyncio # from hyperliquid import HyperliquidClient # placeholder; use actual SDK async def run_agent(): client = HyperliquidClient( api_key=os.environ["HYPERLIQUID_API_KEY"], api_secret=os.environ["HYPERLIQUID_API_SECRET"], ) market = os.environ.get("HYPERLIQUID_MARKET", "BTC-PERP") while True: # 1. Fetch market data orderbook = await client.get_orderbook(market) # 2. Compute signal signal = compute_signal(orderbook) # 3. Place/cancel orders based on signal await rebalance_orders(client, market, signal) # 4. Sleep a short interval await asyncio.sleep(1.0) if __name__ == "__main__": asyncio.run(run_agent()) ``` **LLM guidance:** - Do **not** hardcode secrets. Use env vars so OpenClaw can mount them. - Make all markets, sizes, and risk params configurable. ### 2. OpenClaw-Friendly Entrypoint Agents should expose a **single, long-running process** that OpenClaw can manage. ```python import asyncio import signal stop = False def handle_signal(*_): global stop stop = True async def main(): signal.signal(signal.SIGINT, handle_signal) signal.signal(signal.SIGTERM, handle_signal) # init clients, load config, etc. while not stop: # main agent loop await step() await asyncio.sleep(1.0) if __name__ == "__main__": asyncio.run(main()) ``` **LLM guidance:** - Always listen for SIGINT/SIGTERM so OpenClaw can stop agents cleanly. - Log to stdout/stderr so OpenClaw and Nexwave can capture logs. ### 3. Sending Metrics to Nexwave (Conceptual) Nexwave typically exposes an HTTP or gRPC ingestion endpoint. ```python import os import time import httpx NEXWAVE_URL = os.environ.get("NEXWAVE_INGEST_URL") NEXWAVE_TOKEN = os.environ.get("NEXWAVE_API_TOKEN") async def send_metric(name: str, value: float, tags: dict): if not NEXWAVE_URL or not NEXWAVE_TOKEN: return payload = { "metric": name, "value": value, "timestamp": int(time.time() * 1000), "tags": tags, } async with httpx.AsyncClient(timeout=3.0) as client: await client.post( NEXWAVE_URL, json=payload, headers={"Authorization": f"Bearer {NEXWAVE_TOKEN}"}, ) ``` **LLM guidance:** - Never block the main trading loop on metrics; send asynchronously or with retries. - Tag metrics with `agent_id`, `market`, and `strategy`. --- ## Common Tasks for This Skill ### A. Scaffold a New Hyperliquid Agent Repo When asked, generate: - A minimal **Python or TypeScript** project with: - `agent.py` / `src/agent.ts` main loop. - `config.example.env` describing required env vars. - A `Dockerfile` suitable for running under OpenClaw. - Clear comments on how to: - Set API keys. - Configure markets and position sizing. - Wire logs and metrics. ### B. Integrate a HIP-3 DEX - Use the same account/wallet infrastructure as Hyperliquid perps. - Abstract market interface so the agent can trade either Hyperliquid perps or a HIP-3 DEX with the same logic. - Clearly document any differences (fees, tick sizes, liquidity). ### C. Prepare for OpenClaw Deployment - Ensure the agent can be started with a single command: e.g. `python agent.py` or `node dist/agent.js`. - Provide **health-check logic** (e.g., periodic heartbeat logs or a small HTTP server) when asked. - Generate an example OpenClaw configuration snippet if the user provides OpenClaw’s config schema. --- ## Edge Cases & Safety - **Network failures** – Wrap all API calls in retries with backoff; fail soft, not hard. - **Order rejections** – Log and handle insufficient margin, invalid size, or bad price. - **Position limits** – Always enforce max leverage/position size via config. - **Time drift** – Be aware of latency when polling orderbooks or positions. When uncertain, prefer **conservative risk settings** and strongly encourage the user to test on small size or testnets first. --- ## How to Combine with External Docs - Use this SKILL as the **glue** for patterns and workflows. - Fetch up-to-date Hyperliquid SDK/API docs externally when the user needs precise request/response formats. - Treat ATC’s public site (especially `/` and `/curriculum`) as narrative/context, and this file as the **operational playbook**.