Nexwave Energy Operator v0

Nexwave Energy Operator v0 is an autonomous oil trading agent for Hyperliquid. It trades CL-USDC perpetual futures on-chain via the HIP-3 DEX Trader.xyz.

Our goal is to become the OpenClaw for energy markets: high-quality, actionable trading signals that drive profitable execution with minimal human intervention.

What It Does

• Single-asset focus: CL-USDC (Crude Oil) perpetuals on Hyperliquid HIP-3 (Trader.xyz).
• Autonomous execution: Market data → signals → orders; position sync and risk checks run continuously.
• Signal quality first: Architecture is built to accept signals from OpenClaw or other reasoning engines and execute them reliably—so the bottleneck is signal quality, not infrastructure.

Why CL on HIP-3

• Trader.xyz runs builder-deployed perpetuals on Hyperliquid L1 (HIP-3), including xyz:CL (Crude Oil).
• CME-aligned hours and isolated margin; full on-chain settlement and transparency.
• One market, one stack: we optimize for oil first and aim for OpenClaw-grade signal quality.

Architecture

Trader.xyz (HIP-3) / Hyperliquid L1
         │
         ▼
  Market Data Service ──► Redis ──► DB Writer ──► TimescaleDB
         │                                              │
         │              API Gateway (port 8000) ◄───────┤
         │                        ▲                      │
         │                        │                      │
  Trading Engine ◄────────────────┴──────────────────────┘
  (executes signals; position sync; risk checks)

Core services:

• Market Data Service — WebSocket to Hyperliquid; streams CL (and configurable symbols) into Redis.
• DB Writer — Batches ticks into TimescaleDB; feeds candles and history.
• API Gateway — FastAPI on port 8000; REST + WebSocket for prices, positions, performance.
• Trading Engine — Consumes signals (e.g. from OpenClaw), places orders on Hyperliquid, syncs positions, enforces risk (isolated margin, lot/tick rounding, frequency limits).

Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.11+ (for local dev)
• Hyperliquid account; API wallet approved for trading (see scripts/approve_hyperliquid_agent.py)

Install and run

git clone <this-repo>
cd energy-operator
cp env.example .env   # set NEXWAVE_WALLET_ADDRESS, HYPERLIQUID_PRIVATE_KEY, etc.
docker compose up -d --remove-orphans

• Health: curl http://localhost:8000/health
• API docs: http://localhost:8000/docs

Run services locally (no Docker)

uv sync && source .venv/bin/activate
python -m src.nexwave.services.market_data.client    # terminal 1
python -m src.nexwave.services.db_writer.service     # terminal 2
python -m src.nexwave.services.api_gateway.main      # terminal 3
python -m src.nexwave.services.trading_engine.engine # terminal 4

Configuration

Key env vars (see env.example):

# Hyperliquid (required for execution)
NEXWAVE_WALLET_ADDRESS=0x...   # main account (receives PnL)
HYPERLIQUID_PRIVATE_KEY=0x...   # API wallet (signs orders; must be approved as agent)

# Trading
STRATEGY_ID=vwm_momentum_1
PORTFOLIO_VALUE=100000
# VWM_* and VWM_TP_* for strategy and take-profit tuning

# Database
DATABASE_URL=postgresql://nexwave:...@postgres:5432/nexwave
REDIS_URL=redis://redis:6379

Supported pair: Only xyz:CL (Crude Oil, Trader.xyz HIP-3). Pair config is in src/nexwave/common/pairs.py; all other pairs have been removed for strict energy focus.

API (summary)

• Market: GET /api/v1/pairs, GET /api/v1/latest-prices, GET /api/v1/candles/{symbol}/{timeframe}
• Trading: GET /api/v1/positions, GET /api/v1/performance, GET /api/analytics
• Stream: WS /ws/market-data

OpenClaw integration

The repo includes an Agent Skills–compatible skill so OpenClaw (or any skills-capable agent) can query your operator: positions, prices, performance, analytics.

• Skill: SKILL.md at repo root (name: energy-operator).
• Add to OpenClaw: Point your skills directory at this repo (or add this repo as the skill source). The agent discovers the skill and calls the operator API for oil positions, CL price, or performance.
• Operator must be running: The skill only talks to the operator over HTTP (default http://localhost:8000). Run the operator via Docker or locally so the API is reachable from where OpenClaw runs.
• No credential advice: We do not provide advice on storing or managing private keys or wallet security. See DISCLAIMER.md.

For OpenClaw users

• Clone & run: Have your OpenClaw instance clone https://github.com/nexwave-so/energy-operator.git, configure .env on the host, and start the operator (Docker or Python services).
• Monitor: Use the skill to watch /health, positions, P&L, win rate, daily stats, and candles via the HTTP API.
• Improve strategies: Let OpenClaw use its coding tools to edit this repo (trading engine, risk, params), run the operator, and iterate based on closed PnL and performance endpoints.
• Bring in more data later: When you need richer context, fetch additional data from Nexwave via x402 and feed it into your strategy logic; the operator stays the execution layer.
• Advanced analytics (SQL): Point OpenClaw at DATABASE_URL so it can run custom TimescaleDB/Postgres queries (ticks, candles, positions, orders) for deeper quantitative analysis, for example:

-- 30 days of daily CL P&L and notional
SELECT
  date(opened_at)           AS day,
  COUNT(*)                  AS trades,
  SUM(unrealized_pnl)       AS pnl,
  SUM(amount * entry_price) AS notional
FROM positions
WHERE symbol = 'xyz:CL'
GROUP BY day
ORDER BY day DESC
LIMIT 30;

-- Recent trade distribution by side and status
SELECT
  side,
  status,
  COUNT(*)                       AS trades,
  SUM(amount * COALESCE(price, average_fill_price)) AS notional
FROM orders
WHERE symbol = 'xyz:CL'
  AND created_at >= now() - interval '7 days'
GROUP BY side, status
ORDER BY notional DESC;

Tech Stack

• Backend: Python 3.11+, FastAPI, TimescaleDB, Redis, SQLAlchemy
• Infrastructure: Docker Compose (API on 8000)
• Execution: Hyperliquid SDK; HIP-3 (Trader.xyz) for xyz:CL

Goal: OpenClaw-Grade Signals

We are not trying to be a generic multi-asset platform. We focus on:

1. Reliable execution — Orders hit Hyperliquid with correct size, margin, and risk checks.
2. Clear interfaces — So OpenClaw (or any signal provider) can send high-quality oil signals and we execute them.
3. Profitable trades — By improving signal quality and execution together; the operator is the execution layer.

Links

• Hyperliquid: hyperliquid.xyz
• Trader.xyz (HIP-3): trade.xyz
• GitHub: github.com/nexwave-so/energy-operator
• Twitter: @nexwave_so
• Disclaimer (no wallet/security advice): DISCLAIMER.md

License

MIT

---

Nexwave Energy Operator v0 — Autonomous CL-USDC oil trading on Hyperliquid HIP-3 (Trader.xyz). Built to be the OpenClaw for profitable energy signals.