Back to results
Nunchi-trade/agent-cli(opens in a new tab)
Language: Python
- stars
- 521
- watchers
- 3
- forks
- 136
- open issues
- 30
- Last updated
- 07/08/2026
gem-hunterLanguage: Python
14 strategies • APEX multi-slot orchestrator • REFLECT nightly review • MCP server • Agent Skills
Docs • App • Research • Discord • X
Ship market-making, momentum, arbitrage, and LLM-powered strategies on Hyperliquid perps and YEX yield markets. Full autonomous stack: Guard trailing stops, Radar opportunity screening, Pulse momentum detection, APEX orchestrator, REFLECT performance review. Works as a standalone CLI, a Claude Code skill, an OpenClaw AgentSkill, or an MCP server.
git clone https://github.com/Nunchi-trade/agent-cli.git && cd agent-cli bash scripts/bootstrap.sh # Creates venv, installs, validates
hl wallet auto --save-env # Create wallet + save creds (no prompts) hl setup claim-usdyp # Claim testnet USDyP hl builder approve # Approve builder fee (one-time) hl run avellaneda_mm --mock --max-ticks 3 # Validate hl apex run --mock --max-ticks 5 # Full pipeline test
export HL_PRIVATE_KEY=0x... export HL_TESTNET=true # default hl setup check # Validate environment hl builder approve # Approve builder fee hl run engine_mm -i ETH-PERP --tick 10
export HL_PRIVATE_KEY=0x... export HL_TESTNET=false hl builder approve --mainnet hl run engine_mm -i ETH-PERP --tick 10 --mainnet hl apex run --mainnet
Propose a read-only BTCSWP funding-rate hedge from the CLI or any MCP client. The default hl hedge propose path reads the current account position; passing --perp-notional switches to pure sizing mode with no account fetch or order execution.
hl hedge info --json hl hedge propose --asset BTC --side long --perp-notional 150000 --funding-apr 42 hl hedge propose --asset BTC --side long --perp-notional 150000 --funding-rate-8h 0.0003 --json hl hedge backtest --csv funding.csv --asset BTC --side long --perp-notional 150000
Backtest CSVs need a funding_rate_8h, perp_funding_rate_8h, funding_rate, or rate column. Add hedge_rate_8h, btcswp_rate_8h, or btcswp_funding_rate_8h when you have realized BTCSWP rates; otherwise the backtest uses an idealized offset.
MCP tools: funding_hedge_info, funding_hedge_propose, funding_hedge_backtest
14 built-in strategies across four categories. Every strategy extends BaseStrategy with a single on_tick() method — no shared state, no hidden coupling between strategies.
Provide two-sided liquidity and earn the spread. These strategies quote bids and asks around a fair value estimate, managing inventory risk through skew and sizing adjustments.
| Strategy | Description | Key Parameters | When to Use |
|---|---|---|---|
engine_mm |
Production quoting engine — composite 4-signal fair value, dynamic spreads (fee + vol + toxicity + event), inventory skew, multi-level quote ladder. Auto-halts on oracle staleness. Requires quoting_engine module. |
base_size, num_levels |
Primary MM strategy. Handles all market conditions including volatile regimes and stale data. |
avellaneda_mm |
Avellaneda-Stoikov optimal market maker. Reservation price adjusts with inventory; optimal spread from risk aversion gamma and order flow intensity k. Vol-bin classifier + drawdown amplifier. |
gamma, k, base_size |
When you want theoretically grounded inventory-aware quoting with well-understood parameters. |
regime_mm |
Vol-regime adaptive — classifies market into 4 volatility regimes (quiet/normal/volatile/extreme), switches spread width, sizing, and aggressiveness per regime. Requires quoting_engine module. |
base_size |
Volatile markets where a single spread width doesn't work. Auto-adapts without manual tuning. |
simple_mm |
Symmetric bid/ask quoting at fixed spread around mid. No inventory adjustment. | spread_bps, size |
Testnet validation, baseline benchmarking, or low-vol stable pairs. |
grid_mm |
Fixed-interval grid levels above and below mid. Places N orders at equal spacing. Requires quoting_engine module. |
grid_spacing_bps, num_levels, size_per_level |
Range-bound markets where you want to accumulate and distribute across a price band. |
liquidation_mm |
Provides liquidity during cascade/liquidation events. Detects OI drops and widens spreads to capture forced-seller flow. Requires quoting_engine module. |
oi_drop_threshold_pct, cascade_spread_mult |
Liquidation-heavy markets. Only active during cascade conditions — sits idle otherwise. |
Exploit pricing dislocations across venues, instruments, or time horizons.
| Strategy | Description | Key Parameters | When to Use |
|---|---|---|---|
funding_arb |
Cross-venue funding rate arbitrage — captures funding divergence between HL and external venues. Quoting-engine powered with bias from funding delta. Requires quoting_engine module. |
divergence_threshold_bps, max_bias_bps |
When funding rates diverge between venues. Works well on high-funding instruments. |
basis_arb |
Trades implied basis from funding rate — enters when annualized basis (contango/backwardation) exceeds threshold. | basis_threshold_bps, size |
Capturing contango/backwardation dislocations. Pairs well with funding_arb. |
Enter positions based on technical signals or momentum indicators.
| Strategy | Description | Key Parameters | When to Use |
|---|---|---|---|
momentum_breakout |
Enters on volume + price breakout above/below N-period range. Requires both price and volume confirmation. | lookback, breakout_threshold_bps, size |
Trending markets with clear breakout patterns. |
mean_reversion |
Trades when price deviates from SMA beyond a threshold. | window, threshold_bps, size |
Range-bound markets with predictable mean-reversion behavior. |
aggressive_taker |
Crosses the spread with directional bias. Sinusoidal amplitude modulation. | size, bias_amplitude |
When you have strong directional conviction and want immediate fills. |
Supporting strategies for portfolio management, block liquidity, and autonomous decision-making.
| Strategy | Description | Key Parameters | When to Use |
|---|---|---|---|
hedge_agent |
Inventory exposure reducer. Fires when net notional exceeds threshold. This is not the BTCSWP funding-rate hedge; use hl hedge propose / hl hedge backtest for that. |
notional_threshold |
Always-on risk overlay. Pairs with any MM or signal strategy. |
rfq_agent |
Block-size dark RFQ liquidity — quotes for large orders with wider spreads. | min_size, spread_bps |
Institutional/block flow. Provides hidden liquidity for large counterparties. |
claude_agent |
Multi-model LLM trading agent. Sends market snapshot to an LLM (Gemini, Claude, or OpenAI), receives structured trade decisions. | model, base_size |
Experimental/research. Autonomous decision-making using LLM reasoning. |
The engine-powered strategies (engine_mm, funding_arb, regime_mm, liquidation_mm) share a common pipeline:
Market Data -> Composite Fair Value -> Dynamic Spread -> Inventory Skew -> Multi-Level Ladder -> Orders
(4-signal blend) (fee+vol+tox) (price+size) (exponential decay)
| Provider | Models | Env Variable |
|---|---|---|
| Google Gemini | gemini-2.0-flash (default), gemini-2.5-pro |
GEMINI_API_KEY |
| Anthropic Claude | claude-haiku-4-5-20251001, claude-sonnet-4-20250514 |
ANTHROPIC_API_KEY |
| OpenAI | gpt-4o, gpt-4o-mini, o3-mini |
OPENAI_API_KEY |
Built on the open Agent Skills standard. Each skill is self-contained with instructions, scripts, and references.
| Skill | What it does | Install |
|---|---|---|
| Onboard | Step-by-step first-time setup — from zero to first trade. Decision trees, verification at each step, error recovery. | SKILL.md |
| APEX Strategy | Fully autonomous 2-3 slot trading. Composes Radar + Pulse + Guard. Proven on testnet: signal detection, entry, trailing stop, exit. | SKILL.md |
| Radar | 4-stage funnel screening all HL perps. Scores 0-400 across market structure, technicals, funding, and BTC macro. | SKILL.md |
| Pulse | Detects sudden capital inflow via OI delta, volume surge, funding flips. IMMEDIATE signals at 100 confidence. | SKILL.md |
| Guard (Dynamic Stop Loss) | 2-phase trailing stop with tiered profit-locking. ROE-based triggers that auto-account for leverage. | SKILL.md |
| REFLECT | Nightly self-improvement loop. Analyzes every trade, finds patterns, generates actionable recommendations. | SKILL.md |
Grab the raw URL and go:
https://raw.githubusercontent.com/Nunchi-trade/agent-cli/main/skills/onboard/SKILL.md
https://raw.githubusercontent.com/Nunchi-trade/agent-cli/main/skills/apex/SKILL.md
https://raw.githubusercontent.com/Nunchi-trade/agent-cli/main/skills/radar/SKILL.md
https://raw.githubusercontent.com/Nunchi-trade/agent-cli/main/skills/pulse/SKILL.md
https://raw.githubusercontent.com/Nunchi-trade/agent-cli/main/skills/guard/SKILL.md
https://raw.githubusercontent.com/Nunchi-trade/agent-cli/main/skills/reflect/SKILL.md
clawhub install nunchi-trade/yex-trader
git clone https://github.com/Nunchi-trade/agent-cli.git ~/agent-cli cd ~/agent-cli && pip install -e . mkdir -p ~/.claude/skills/yex-trader cp ~/agent-cli/cli/skill.md ~/.claude/skills/yex-trader/SKILL.md
First-time setup skill that walks an agent from zero to first trade in 9 steps. Decision trees at each step, verification commands, error recovery tables.
# The onboard skill automates this entire flow: bash scripts/bootstrap.sh # Step 1: Environment hl wallet auto --save-env # Step 2: Wallet hl setup claim-usdyp # Step 4: Fund account hl builder approve # Step 5: Builder fee hl run avellaneda_mm --mock --max-ticks 3 # Step 6: Validate
Trailing stop system with tiered profit-locking. Protects profits while letting winners run.
Two phases:
| Preset | Phase 1 Retrace | Tiers | Stagnation TP |
|---|---|---|---|
moderate |
3% | 6 tiers (10-100% ROE) | No |
tight |
5% | 4 tiers (10-75% ROE) | Yes (8% ROE, 1h) |
hl guard run -i ETH-PERP --preset tight
Multi-factor screening engine that evaluates all HL perps for trade setups. 4-stage funnel, scores 0-400.
| Pillar | Weight | Signals |
|---|---|---|
| Market Structure | 35 | Volume, OI, liquidity |
| Technicals | 30 | RSI, EMA, patterns, hourly trend |
| Funding | 20 | Rate extremes, direction bias |
| BTC Macro | 15 | Trend alignment, regime filter |
hl radar once --mock # Single scan hl radar run --mock # Continuous (every 15 min)
Detects assets with sudden capital inflow using OI, volume, funding, and price signals. Runs every 60 seconds.
5-tier signal taxonomy for entry classification, plus informational signals for Radar scoring:
| Tier | Signal | Trigger | Confidence |
|---|---|---|---|
| 1 | FIRST_JUMP |
First asset in sector with OI + volume breakout | 100 |
| 2 | CONTRIB_EXPLOSION |
OI +15% AND volume 5x (simultaneous extreme) | 95 |
| 3 | IMMEDIATE_MOVER |
OI +15% OR volume 5x (either extreme) | 80 |
| 4 | NEW_ENTRY_DEEP |
OI grows 8%+ but volume stays low — smart money accumulation | 65 |
| 5 | DEEP_CLIMBER |
Sustained OI climb 5%+ per window over 3+ consecutive scans | 55 |
| — | VOLUME_SURGE |
4h volume / average > 3x | 70 |
| — | OI_BREAKOUT |
OI jumps 8%+ above baseline | 60 |
| — | FUNDING_FLIP |
Funding rate reverses or accelerates 50%+ | 50 |
hl pulse once --mock # Single scan hl pulse run --mock # Continuous (every 60s)
The top-level orchestrator. Composes Radar + Pulse + Guard into a single autonomous strategy managing 2-3 concurrent positions.
Tick schedule (60s base):
Entry priority (tier-based):
| Priority | Source | Condition |
|---|---|---|
| 1 | FIRST_JUMP | First sector mover (tier 1) |
| 2 | CONTRIB_EXPLOSION | Simultaneous extreme OI + volume (tier 2) |
| 3 | Smart money | Pulse confidence > 90 |
| 4 | IMMEDIATE_MOVER | Either extreme metric (tier 3) |
| 5 | Radar | Score > 170 |
| 6 | NEW_ENTRY_DEEP | Limit-order accumulation (tier 4) |
| 7 | DEEP_CLIMBER | Sustained OI trend (tier 5) |
Presets:
| Preset | Slots | Leverage | Radar Threshold | Daily Loss Limit |
|---|---|---|---|---|
default |
3 | 10x | 170 | $500 |
conservative |
2 | 5x | 190 | $250 |
aggressive |
3 | 15x | 150 | $1,000 |
hl apex run --mock --max-ticks 10 # Mock test hl apex run # Live testnet hl apex run --preset conservative --mainnet # Live mainnet
Nightly self-improvement loop. Reads trade history, computes metrics, detects patterns, generates actionable recommendations.
| Metric | Description |
|---|---|
| Win Rate | % of round trips with positive net PnL |
| FDR | Fee Drag Ratio — fees as % of gross wins |
| Direction Split | Long vs short win rates and PnL |
| Holding Periods | Bucketed by <5m, 5-15m, 15-60m, 1-4h, 4h+ |
| Monster Dependency | % of net PnL from best single trade |
hl reflect run --since 2026-03-01
hl reflect report
hl reflect history -n 10When running inside APEX, REFLECT executes automatically every 240 ticks (~4 hours) and at a configurable UTC hour (default 04:00). It reads the trade log, computes performance metrics, and auto-adjusts APEX parameters based on findings:
| Finding | Automatic Adjustment |
|---|---|
| FDR > 30% (fees eating profits) | Raise radar threshold, disable immediate mover entries |
| Win rate < 40% | Tighten both radar and movers confidence thresholds |
| 5+ consecutive losses | Reduce daily loss limit by 20% |
| Direction imbalance (e.g. longs losing) | Limit same-direction slots |
| Fees exceed gross PnL | Emergency mode: disable auto-entries, raise all thresholds |
| Profitable + healthy | Slightly relax thresholds toward defaults |
All adjustments have guardrail bounds — parameters can't swing wildly. Disable with reflect_auto_adjust: false in APEX config.
Scheduled tasks (built into APEX tick loop):
data/apex/reflect/Built-in safety systems that protect positions even when the runner process crashes.
Guard places a trigger order directly on Hyperliquid as a safety net. If the runner crashes, the exchange-side stop loss remains active. Synced on entry, tier ratchet, and startup — intentionally left in place on shutdown.
Position Entry → Place SL trigger order at Phase 1 floor
Tier Ratchet → Cancel old SL, place new at higher tier floor
Position Close → Cancel SL trigger order
Runner Crash → Exchange SL stays active (that's the point)
Bidirectional reconciliation between APEX slots and Hyperliquid positions. Detects orphaned exchange positions, orphaned slots, and size mismatches. Runs on startup and periodically via watchdog.
hl apex reconcile # Check for discrepancies hl apex reconcile --fix # Auto-adopt orphans, fix sizes
| Discrepancy | Severity | Auto-Fix |
|---|---|---|
| Orphan exchange position | Critical | Adopt into empty slot + create Guard |
| Orphan slot (no position) | Warning | Mark slot closed |
| Size mismatch >10% | Critical | Update slot to match exchange |
Graduated risk response with three states and automatic transitions:
OPEN ──(2 consecutive losses)──→ COOLDOWN ──(trigger again)──→ CLOSED
↑ │ │
└──────(auto-expiry 30 min)────────┘ │
└────────────────────(daily reset)──────────────────────────────┘
| State | Entries | Exits | Trigger |
|---|---|---|---|
OPEN |
Allowed | Allowed | Default |
COOLDOWN |
Blocked | Allowed | 2+ consecutive losses or drawdown >= 50% of limit |
CLOSED |
Blocked | Blocked | Daily loss limit hit |
Exchange-level stop losses remain active in all states.
Anti-churn protection:
Closed position state files archived to data/archive/{YYYY-MM-DD}/ on close. Trade audit trail (trades.jsonl) is never archived.
hl apex archive # Archive all closed state files hl apex archive --days 7 # Only older than 7 days hl apex archive --dry-run # Preview without moving
Entry orders default to ALO (post-only) for maker rebates (~3 bps savings per round-trip). Falls back to GTC if ALO is rejected. Exits and Guard closes always use IOC.
Connects REFLECT to an autonomous optimization loop. A backtest harness replays historical trades against config variants, and an iterative agent loop finds parameter improvements.
python3 scripts/backtest_apex.py --config apex_config.json --trades data/cli/trades.jsonl
REFLECT auto-generates research directions:
| Finding | Suggested Direction |
|---|---|
| FDR > 30% | Raise radar_score_threshold in [170, 250] |
| Win rate < 40% | Sweep pulse_confidence_threshold in [70, 95] |
| Direction imbalance | Set max_same_direction to 1 |
| Healthy + profitable | Try lowering radar_score_threshold in [140, 170] |
# Core trading hl run <strategy> [options] # Start autonomous trading hl status [--watch] # Show positions, PnL, risk hl trade <inst> <side> <size> # Place a single order hl account # Show HL account state hl strategies # List all strategies hl skills list # Discover installed skills # Autonomous stack hl apex run [options] # APEX multi-slot orchestrator hl apex reconcile [--fix] # Reconcile state vs exchange hl apex archive [--days N] # Archive closed state files hl radar run [options] # Opportunity radar hl pulse run [options] # Pulse momentum detector hl guard run -i ETH-PERP [options] # Guard trailing stop hl reflect run [--since DATE] # Performance review hl hedge info [--json] # Funding hedge profiles and schemas hl hedge propose [options] # BTCSWP funding hedge proposal hl hedge backtest --csv <path> # Local funding hedge cashflow backtest # Infrastructure hl builder approve [--mainnet] # Approve builder fee hl wallet auto [--save-env] # Create wallet (agent-friendly) hl setup check # Validate environment hl setup bootstrap # Auto-setup venv + install hl setup claim-usdyp # Claim testnet USDyP hl mcp serve # Start MCP server
Expose all trading tools via Model Context Protocol for AI agent integration.
Use the hosted Nunchi MCP when you want a Robinhood-style setup: paste one URL into your AI client, authenticate, and grant scoped tool access. Your AI client receives a scoped MCP token, not your exchange private key.
https://agent.nunchi.trade/mcp/trading
Client setup:
# Cursor Settings -> Cursor Settings -> Tools & MCPs -> Connect MCP URL: https://agent.nunchi.trade/mcp/trading # Claude Code claude mcp add nunchi-trading --transport http https://agent.nunchi.trade/mcp/trading # Codex CLI codex mcp add nunchi-trading --url https://agent.nunchi.trade/mcp/trading
After connecting, authenticate in the browser consent flow and start with:
Run setup_check, then show my account status and available strategies.
Hosted access defaults to read-only/testnet. Write tools (trade, run_strategy, apex_run) and mainnet access require explicit consent and gateway-enforced limits.
hl mcp serve # stdio transport (default) hl mcp serve --transport sse # SSE transport
24 tools exposed: strategies, builder_status, wallet_list, wallet_auto, setup_check, funding_hedge_info, funding_hedge_propose, funding_hedge_backtest, account, status, trade, run_strategy, radar_run, apex_status, apex_run, reflect_run, schedule_cancel, emergency_close_all, order_status, funding_rates, agent_memory, trade_journal, judge_report, obsidian_context
Fast tools (strategies, builder, wallet, setup, memory, journal, judge) call Python directly — zero subprocess overhead. Local MCP is for development and agent harness testing only; hosted deployment goes through Nunchi Auth and the subscription-gated hosted-agent flow.
Every deployed agent also exposes an HTTP REST API and SSE real-time feed for dashboards, monitoring, and external integrations. A separate leaderboard microservice tracks agent PnL rankings.
Full API Reference →
July 2026 Exhibit A Testing Plan →
The only supported hosted deployment path is Nunchi-hosted: users pay in web-auth, bind an agent wallet, and Nunchi provisions and manages the agent on Nunchi-owned Railway infrastructure.
Start here:
Launch a hosted agent through Nunchi Auth
User flow:
Hosted agents use Nunchi-owned inference credentials by default:
| Variable | Default | Description |
|---|---|---|
AI_PROVIDER |
openrouter |
OpenAI-compatible hosted inference |
AI_MODEL |
openrouter/auto |
Low-latency/cost-aware default for chat and tool use |
NUNCHI_REFLECT_MODEL |
openrouter/fusion |
Higher-confidence model for REFLECT/research-style analysis |
Users do not need Railway credentials, Railway project access, or provider API keys. Billing, entitlement checks, wallet binding, secret injection, lifecycle controls, and hosted endpoint discovery all live in web-auth. This repository intentionally does not include Dockerfiles, railway.toml, or public deployment templates.
YEX (Nunchi HIP-3) yield perpetuals on Hyperliquid:
| Instrument | HL Coin | Description |
|---|---|---|
| VXX-USDYP | yex:VXX | Volatility index yield perp |
| US3M-USDYP | yex:US3M | US 3M Treasury rate yield perp |
| BTCSWP-USDYP | yex:BTCSWP | BTC interest rate swap yield perp — tracks the BTC-denominated swap curve |
hl run avellaneda_mm -i VXX-USDYP --tick 15 hl run funding_arb -i US3M-USDYP --tick 30 hl run engine_mm -i BTCSWP-USDYP --tick 10
cli/ CLI commands and trading engine
commands/ Subcommand modules (run, apex, radar, pulse, guard, reflect, house, ...)
mcp_server.py MCP server (24 tools via FastMCP)
hl_adapter.py Direct HL API adapter (live + mock)
builder_fee.py Builder fee config (HL native BuilderInfo)
keystore.py Encrypted keystore (geth-compatible)
strategy_registry.py Strategy + YEX market definitions
strategies/ 14 trading strategy implementations
modules/ Pure logic modules (zero I/O)
apex_engine.py APEX decision engine
radar_engine.py Opportunity radar
pulse_engine.py Pulse momentum detector (5-tier signal taxonomy)
trailing_stop.py Guard trailing stop (Phase 1 auto-cut)
reflect_engine.py Performance analysis
reconciliation.py Clearinghouse reconciliation engine
archiver.py State file archiving
skills/ Agent Skills (SKILL.md + runners)
onboard/ First-time setup guide
apex/ APEX orchestrator
radar/ Opportunity radar
pulse/ Pulse momentum detector
guard/ Dynamic stop loss
reflect/ Performance review
sdk/ Strategy base class and model registry
parent/ HL API proxy, position tracking, risk management
scripts/ Backtest harness, bootstrap
tests/ Test suite (483 tests)
Create a Python file that subclasses BaseStrategy:
from sdk.strategy_sdk.base import BaseStrategy from common.models import MarketSnapshot, StrategyDecision class MyStrategy(BaseStrategy): def __init__(self, lookback=10, threshold=0.5, size=0.1, **kwargs): super().__init__(strategy_id="my_strategy") self.lookback, self.threshold, self.size = lookback, threshold, size self._prices = [] def on_tick(self, snapshot, context=None): mid = snapshot.mid_price self._prices.append(mid) if len(self._prices) < self.lookback: return [] pct = (mid - self._prices[-self.lookback]) / self._prices[-self.lookback] * 100 if abs(pct) > self.threshold: return [StrategyDecision( action="place_order", instrument=snapshot.instrument, side="buy" if pct > 0 else "sell", size=self.size, limit_price=round(snapshot.ask if pct > 0 else snapshot.bid, 2), )] return []
hl run my_strategies.my_strategy:MyStrategy -i ETH-PERP --tick 10
| Variable | Required | Description |
|---|---|---|
HL_PRIVATE_KEY |
Yes* | Hyperliquid private key |
HL_KEYSTORE_PASSWORD |
Alt* | Password for encrypted keystore |
HL_TESTNET |
No | true (default) or false for mainnet |
BUILDER_ADDRESS |
No | Override builder fee address |
BUILDER_FEE_TENTHS_BPS |
No | Override fee rate (default: 100 = 10 bps) |
ANTHROPIC_API_KEY |
No | For claude_agent with Claude |
GEMINI_API_KEY |
No | For claude_agent with Gemini |
OPENAI_API_KEY |
No | For claude_agent with OpenAI |
* Either HL_PRIVATE_KEY or a keystore with HL_KEYSTORE_PASSWORD is required.
pip install -e ".[dev]" pytest tests/ -v # 483 tests
Built by Nunchi • MIT License