EVClaw Trading Skill
Mode: Live Agent (context → main agent → execute) Exchanges: Lighter (crypto perps), Hyperliquid (HIP3 stocks)
Architecture
Cycle Trigger → Cycle File + Context → System Event → Main Agent (gpt-5.2)
↓ ↓ ↓ ↓
tracker:8443 <runtime_dir>/evclaw_* live_agent.py JSON context selection
↓
<runtime_dir>/evclaw_candidates_*.json
↓
Main Agent validate + record proposals
↓
OpenClaw agent executes proposals
↓
Executor → HL and/or Lighter
See references/architecture.md for detailed system architecture.
Key Features
- Live agent trading (context → main agent → execute)
- Snapshot-driven cycle handling + context builder
- Per-venue execution (no requirement that a symbol exists on both exchanges)
- Dynamic sizing + exposure limits via DynamicRiskManager
- Decay-based exits as primary exit logic
- Optional SL/TP emergency backstop (config flag)
- Token bucket rate limiting (40 req/60s)
- Atomic position persistence for crash recovery
- Agent-driven incident response (triage + remediation workflow)
Commands
/live-agent run/execute
Main agent workflow (context → validate → record proposals; OpenClaw agent executes in AGI-only mode).
# Record proposals from the most recent pending cycle
python3 ${EVCLAW_ROOT}/live_agent.py run --from-pending
Execute from candidates (manual review first):
python3 ${EVCLAW_ROOT}/live_agent.py execute \
--seq 12345 \
--cycle-file ${EVCLAW_RUNTIME_DIR}/evclaw_cycle_12345.json \
--candidates-file ${EVCLAW_RUNTIME_DIR}/evclaw_candidates_12345.json
cli execute --cycle-file <path> --symbol <symbol> --direction LONG|SHORT --size-usd <float>
Execute a decision from a cycle file (execution-by-call).
Important command split:
/execute <PLAN_ID> chase|limit-> helper skill plan execution (openclaw_skills/execute).python3 ${EVCLAW_ROOT}/cli.py execute --cycle-file ...-> low-level executor entrypoint.
Parameters:
| Param | Type | Default | Description |
|---|---|---|---|
| --cycle-file | string | required | Path to cycle JSON from cycle_trigger.py |
| --symbol | string | required | Trading symbol (e.g., ETH, xyz:NVDA) |
| --direction | string | required | LONG or SHORT |
| --size-usd | float | required | Position size in USD |
| --dry-run | flag | false | Dry run (no real orders) |
python3 ${EVCLAW_ROOT}/cli.py execute \
--cycle-file ${EVCLAW_RUNTIME_DIR}/evclaw_cycle_123.json \
--symbol ETH --direction LONG --size-usd 500
/trade <symbol> <direction> <size_usd>
Execute a manual trade decision.
python3 ${EVCLAW_ROOT}/cli.py trade <symbol> <direction> <size_usd>
/signals [symbol] [--min-z <float>] [--top <int>]
View current actionable signals from the tracker.
python3 ${EVCLAW_ROOT}/cli.py signals [symbol] [--min-z <float>] [--top <int>]
/positions [--all] [--close <symbol>] [--export]
View and manage open positions.
python3 ${EVCLAW_ROOT}/cli.py positions [--all] [--close <symbol>] [--export]
Python Scripts
| Script | Purpose | Invocation |
|---|---|---|
main.py | Analysis/report loop (no execution) | python3 main.py |
sse_consumer.py | SSE client for tracker stream | python3 sse_consumer.py |
context_builder_v2.py | Build full cycle context + opportunities | Imported by main |
trading_brain.py | Conviction-based decisioning | Imported by main |
risk_manager.py | Dynamic sizing + decay exits | Imported by main |
executor.py | Order execution | Used by cli.py execute |
learning_engine.py | Signal weight learning | python3 learning_engine.py |
cli.py | Command-line interface | python3 cli.py <command> |
Analysis Mode (No Execution)
# Analyze a saved cycle file
python3 ${EVCLAW_ROOT}/main.py --cycle-file ${EVCLAW_RUNTIME_DIR}/evclaw_cycle_123.json
# With custom config
python3 ${EVCLAW_ROOT}/main.py --config custom.yaml --cycle-file ${EVCLAW_RUNTIME_DIR}/evclaw_cycle_123.json
# Live SSE analysis (reports only)
python3 ${EVCLAW_ROOT}/main.py
Testing
python3 ${EVCLAW_ROOT}/tests/test_trading_brain.py
python3 ${EVCLAW_ROOT}/tests/test_executor.py
Configuration
Configuration is loaded from skill.yaml. Key settings include:
config.mode_controller.mode: Trading mode (conservative,balanced,aggressive)config.brain: Conviction thresholds and weightsconfig.risk: Position sizing and exposure limitsconfig.executor: SL/TP, chase settings, SR-limit config
See references/configuration.md for complete config reference.
Symbol Routing
| Pattern | Exchange | Example |
|---|---|---|
xyz:<TICKER> | HIP3 wallet (HIP3 stocks) | xyz:NVDA, xyz:TSLA |
<SYMBOL> | Lighter (crypto perps) | ETH, BTC, kPEPE |
Overrides can be configured in skill.yaml under exchanges.router.overrides.
HIP3 Live Agent: HIP3 symbols (xyz:) are HIP3 wallet-only. If executor.hl_wallet_enabled: true, live mode can execute HIP3 without requiring Lighter availability.
Decision Logic
Conviction Scoring
- Each signal contributes to a conviction score (0.0 - 1.0)
- Signals are weighted (CVD/FADE/LIQ_PNL/WHALE/DEAD/OFM/HIP3_MAIN)
- Recommendations are produced above the brain confidence threshold
Veto Conditions
| Condition | Effect |
|---|---|
| WHALE opposite direction | VETO trade |
| CVD opposite with strong z-score | VETO trade |
Risk & Exits
- Dynamic risk sizing based on conviction and exposure
- Decay-based exits are primary (trigger signal flip)
- SL/TP optional emergency backstop (
executor.enable_sltp_backstop)
See references/signals.md for signal types and scoring.
Context Learning
The learning engine tracks win rates by context conditions and adjusts sizing accordingly:
- When enough data exists (≥10 trades per condition), the learning engine provides a multiplier
- Win rate > 45% → boost sizing (up to 1.5x)
- Win rate < 45% → reduce sizing (down to 0.5x)
Context features tracked: trend_alignment, vol_regime, funding_alignment, smart_money, signal_strength.
See references/signals.md for context features details.
Order Type Selection
| Order Type | When to Use |
|---|---|
| CHASE LIMIT | High conviction (≥0.6), trend-aligned, time-sensitive |
| LIMIT ORDER | Lower conviction (<0.6), counter-trend, patient fill preferred |
Error Handling
| Error | Handling |
|---|---|
| SSE disconnect | Exponential backoff reconnect (2s-30s) |
| Rate limit (429) | Wait for token bucket refill |
| Order rejected | Log and abort (don't retry) |
| SL/TP placement fail | Log warning, position remains open |
| Position fetch fail | Use cached state |
Logging
Logs are written to stdout with format:
2026-01-25 12:00:00 [executor] INFO: Executing LONG for ETH
Log levels:
- INFO: Trade execution, position changes
- WARNING: Rate limits, SL/TP failures
- ERROR: Order failures, exchange errors
Memory Files
Persistent state is stored in memory/:
| File | Purpose |
|---|---|
signal_weights.yaml | Per-signal confidence multipliers |
trade_journal.yaml | Trade history (rolling 1000) |
circuit_breaker.yaml | Daily loss, loss streak state |
positions.yaml | Active positions |
symbol_blacklist.yaml | Blacklisted symbols |
context_feature_stats.json | Win rates by context condition |
mistakes.json | Classified trading mistakes |
See references/memory-files.md for file formats.
Requirements
Python Packages
- aiohttp>=3.9.0
- pyyaml>=6.0
- requests>=2.31.0
- python-dotenv>=1.0.1
- hyperliquid-python-sdk>=0.21.0
- lighter-sdk (optional, installed from
requirements-lighter.txtwhen Lighter venue is enabled)
System Dependencies
- Python 3.10+
- Lighter env vars:
LIGHTER_BASE_URL,LIGHTER_ACCOUNT_INDEX,LIGHTER_API_KEY_PRIVATE_KEY,LIGHTER_API_KEY_INDEX - Hyperliquid env vars:
HYPERLIQUID_ADDRESS(main wallet address),HYPERLIQUID_AGENT_PRIVATE_KEY(delegated signer key; not main wallet private key) - Optional Hyperliquid:
HYPERLIQUID_PRIVATE_NODE,EVCLAW_INCLUDE_WALLET_HIP3_FILLS - Venue controls:
EVCLAW_ENABLED_VENUES - Massive env var (HIP3 predator signals):
MASSIVE_API_KEY - Tracker APIs (hosted externally via evplus tracker):
EVCLAW_TRACKER_BASE_URLEVCLAW_TRACKER_HIP3_PREDATOR_URLEVCLAW_TRACKER_HIP3_SYMBOLS_URLEVCLAW_TRACKER_SYMBOL_URL_TEMPLATE
- EVClaw OSS is network-only: all tracker data is fetched from
tracker.evplus.ai - SSE tracker running on tracker.evplus.ai:8443
Sub-Skills
EVClaw includes sub-skills in openclaw_skills/:
- trade: Manual trade planner (
/trade <SYMBOL>) - execute: Execute stored trade plans (
/execute <PLAN_ID>) - hedge: Portfolio hedging operations
- stats: Trading statistics and reports
- best3: Top 3 opportunities display