---
title: Hyperliquid Adaptive Bot
emoji: "🤖"
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---

# Hyperliquid Adaptive Bot

This project now includes an adaptive ML bot that uses your existing Hyperliquid framework.

## What it does

- Trades **only** `HYPE` (single-asset mode)
- Runs in **paper mode by default**
- Learns from closed paper trades with an online ML model (`SGDClassifier`)
- Persists everything learned to disk (`learning_state.joblib`) so restart resumes learning
- Persists paper runtime state (equity, open positions, entry features) so restart does not break learning continuity
- Uses a profitability gate before any live execution is allowed
- Sends Telegram alerts on trade open/close and a midnight UTC summary
- Sends a readiness alert when paper performance is strong enough for live trading
- Optional startup live transaction test (tiny BUY then SELL) to verify live order execution path
- Can mirror to live orders only when:
  - `--enable-live` is set
  - paper performance is consistently profitable
  - manual approval is granted (`ALLOW_LIVE_TRADING=1` or approval flag file exists)
  - `HL_PRIVATE_KEY` is configured

## Files

- `hbot.py`: existing Hyperliquid API framework and order placement helpers
- `adaptive_bot.py`: new adaptive ML paper/live-gated trading bot
- `hf_advisor.py`: optional external advisor client (e.g., Hugging Face endpoint)
- `smoke_test.py`: offline persistence and learning smoke test
- `ml_diagnostics.py`: offline + live learning diagnostics report
- `diagnostics_smoke_test.py`: quick smoke test for diagnostics logic
- `advisor_smoke_test.py`: quick smoke test for advisor parsing behavior
- `paper_report.json`: runtime status and metrics output (created at runtime)

## Health endpoints (for HF + UptimeRobot)

- `GET /` -> lightweight status response (`200`) for uptime checks
- `GET /healthz` -> same as root (`200`)
- `GET /status` -> concise overview (equity, open position count, performance, live gate)
- `GET /status/full` -> full runtime JSON (equity, open positions, metrics, thresholds)
- `GET /trades` -> open positions list and count

If your Space is `https://chigginrice-hyperliquid-bot.hf.space/`, your existing root monitor will work as-is.

## Quick start

1. Install dependencies:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

2. Run the offline smoke test:

```bash
python smoke_test.py
```

Optional: run diagnostics smoke test:

```bash
python diagnostics_smoke_test.py
```

Optional: run advisor smoke test:

```bash
python advisor_smoke_test.py
```

3. Start the adaptive paper bot:

```bash
python adaptive_bot.py --interval 15m --poll-seconds 45
```

4. Check ML learning quality from saved state:

```bash
python ml_diagnostics.py --state-file learning_state.joblib
```

If the bot is running locally, include live status snapshot:

```bash
python ml_diagnostics.py --state-file learning_state.joblib --status-url http://127.0.0.1:7860/status/full
```

JSON output (useful for storing artifacts in CI/HF workflows):

```bash
python ml_diagnostics.py --state-file learning_state.joblib --json
```

Send a compact diagnostics snapshot to Telegram:

```bash
python ml_diagnostics.py --state-file learning_state.joblib --send-telegram
```

Optional knobs for early growth from scratch:

```bash
python adaptive_bot.py --interval 15m --exploration-rate 0.08
```

Safer learning defaults (already enabled by default):

```bash
python adaptive_bot.py --interval 15m --min-model-samples-for-signal 50 --pause-on-negative-expectancy
```

Auto-expire the safety pause after 3 hours (default) so the bot can retry entries:

```bash
python adaptive_bot.py --interval 15m --pause-cooldown-minutes 180
```

Enable periodic ML progress updates to Telegram (good for phone monitoring):

```bash
python adaptive_bot.py --interval 15m --telegram-ml-report-hours 6 --telegram-ml-report-min-trades 15
```

Enable volatility/regime-aware risk sizing (defaults shown):

```bash
python adaptive_bot.py \
  --interval 15m \
  --risk-volatility-floor-mult 0.45 \
  --risk-volatility-cap-mult 1.20 \
  --risk-regime-adapt-strength 0.35 \
  --risk-regime-min-samples 12
```

Advisor is built into the bot and always enabled (local in-process engine). You can optionally attach a remote endpoint (for example, Hugging Face) to augment it:

```bash
python adaptive_bot.py \
  --interval 15m \
  --hf-advisor-url "https://your-endpoint.example/predict" \
  --hf-advisor-mode blend \
  --hf-advisor-blend-weight 0.35 \
  --hf-advisor-min-confidence 0.60
```

Advisor modes:

- `confirm`: only trade when advisor agrees with the model side at/above min confidence
- `veto`: advisor can block opposite-side model trades at/above min confidence
- `blend`: blend local `p_long` with advisor `p_long` and decide from the blended score

If `--hf-advisor-url` is not set, the local advisor still runs and decisions continue with no external dependency.

## Optional: allow live mirror only after paper consistency gate

```bash
export HL_PRIVATE_KEY="your_private_key"
# optional if using delegated account
export HL_ACCOUNT_ADDRESS="0x..."
python adaptive_bot.py --interval 15m --enable-live
```

By default, live arm still requires manual approval even after the paper gate is passed:

```bash
export ALLOW_LIVE_TRADING=1
# or: touch allow_live_trading.flag
python adaptive_bot.py --interval 15m --enable-live
```

Strict two-step approval mode (recommended for safety):

```bash
export ALLOW_LIVE_TRADING=1
touch allow_live_trading.flag
python adaptive_bot.py --interval 15m --enable-live --live-approval-mode both
```

Optional startup live execution test (real tiny transaction):

```bash
python adaptive_bot.py --interval 15m --enable-live --live-startup-test --live-startup-test-coin HYPE --live-startup-test-notional 12
```

## Docker (Hugging Face)

`Dockerfile` is included for Docker-based hosting.

Build locally:

```bash
docker build -t hyperliquid-adaptive-bot .
```

Run locally in paper mode:

```bash
docker run --rm \
  -e BOT_INTERVAL=15m \
  -e BOT_POLL_SECONDS=45 \
  -v "$(pwd)/data:/data" \
  hyperliquid-adaptive-bot
```

Run with live mode allowed after paper gate passes:

```bash
docker run --rm \
  -e BOT_ENABLE_LIVE=1 \
  -e HL_PRIVATE_KEY="your_private_key" \
  -e HL_ACCOUNT_ADDRESS="0x..." \
  -v "$(pwd)/data:/data" \
  hyperliquid-adaptive-bot
```

Environment variables used by the container:

- `BOT_INTERVAL` (default `15m`)
- `BOT_POLL_SECONDS` (default `45`)
- `BOT_STATE_FILE` (default `/data/learning_state.joblib`)
- `BOT_REPORT_FILE` (default `/data/paper_report.json`)
- `BOT_ENABLE_LIVE` (set any non-empty value to append `--enable-live`)
- `BOT_HEALTH_HOST` (default `0.0.0.0`)
- `BOT_HEALTH_PORT` (default `7860`)
- `PORT` (default `7860`, used by Hugging Face Spaces)
- `BOT_HF_ADVISOR_URL` (optional external advisor endpoint)
- `BOT_HF_ADVISOR_TOKEN` (optional bearer token)
- `BOT_HF_ADVISOR_MODE` (`confirm|veto|blend`, default `blend`)
- `BOT_HF_ADVISOR_MIN_CONFIDENCE` (default `0.60`)
- `BOT_HF_ADVISOR_BLEND_WEIGHT` (default `0.35`)
- `BOT_HF_ADVISOR_TIMEOUT_SECONDS` (default `4.0`)
- `BOT_MIN_MODEL_SAMPLES_FOR_SIGNAL` (default `50`)
- `BOT_PAUSE_ON_NEGATIVE_EXPECTANCY` (`1/true/yes` by default)
- `BOT_PAUSE_EXPECTANCY_LOOKBACK` (default `30`)
- `BOT_PAUSE_EXPECTANCY_THRESHOLD_USD` (default `-1.0`)
- `BOT_PAUSE_MAX_DRAWDOWN_PCT` (default `12.0`)
- `BOT_PAUSE_COOLDOWN_MINUTES` (default `180`, set `0` to disable auto-expiry)
- `ALLOW_LIVE_TRADING` (set to `1/true/yes` to manually approve live trading)
- `BOT_LIVE_STARTUP_TEST` (set non-empty to add `--live-startup-test`)
- `BOT_LIVE_STARTUP_TEST_COIN` (default `HYPE`)
- `BOT_LIVE_STARTUP_TEST_NOTIONAL` (default `12`)
- `BOT_TELEGRAM_ML_REPORT_HOURS` (default `6`, set `0` to disable periodic ML Telegram report)
- `BOT_TELEGRAM_ML_REPORT_MIN_TRADES` (default `15`)
- `BOT_RISK_VOLATILITY_FLOOR_MULT` (default `0.45`)
- `BOT_RISK_VOLATILITY_CAP_MULT` (default `1.20`)
- `BOT_RISK_REGIME_ADAPT_STRENGTH` (default `0.35`)
- `BOT_RISK_REGIME_MIN_SAMPLES` (default `12`)
- `TELEGRAM_BOT_TOKEN` (required for Telegram notifications)
- `TELEGRAM_CHAT_ID` (required for Telegram notifications)
- `PROXY_URL` (required by `telegram_notifier.py` to forward messages)
- `HL_PRIVATE_KEY` (required for live mirror)
- `HL_ACCOUNT_ADDRESS` (optional)

## Telegram notifications

- Entry alert: sent when a paper position opens
- Exit alert: sent when TP/SL closes a position
- Midnight summary: sent once per day at `00:00 UTC`
- Readiness alert: sent when profitability gate is reached and bot is ready to request live approval

Summary includes last-24h trades, win rate, PnL, and overall cumulative stats.

ML progress update (periodic, configurable) includes rolling Brier, rolling expectancy, drawdown, and per-coin Brier.

## Hugging Face diagnostics + phone workflow

1. Keep state and report under `/data` (already default in `Dockerfile`).
2. Set Telegram secrets in your Space variables:
   - `TELEGRAM_BOT_TOKEN`
   - `TELEGRAM_CHAT_ID`
   - `PROXY_URL`
3. Optionally tune ML push cadence:
   - `BOT_TELEGRAM_ML_REPORT_HOURS=6`
   - `BOT_TELEGRAM_ML_REPORT_MIN_TRADES=15`
4. View live JSON diagnostics in a phone browser:
   - `https://<your-space>.hf.space/status`
   - `https://<your-space>.hf.space/status/full`
5. Trigger one-off diagnostics message from Space shell:

```bash
python ml_diagnostics.py --state-file /data/learning_state.joblib --status-url http://127.0.0.1:7860/status/full --send-telegram
```

## How the ML learns

At a high level, this bot uses online learning so it improves continuously while paper trading:

1. For `HYPE`, it builds a feature vector from latest candles:
   - short-horizon returns (`ret_1`, `ret_3`, `ret_8`)
   - trend/momentum (`macd`, scaled `rsi`)
   - volatility and activity (`atr14`, `vol_z`)
2. `SGDClassifier(loss="log_loss")` predicts probability of a profitable long setup.
3. Entry logic maps probability to actions:
   - `p_long >= threshold` -> long
   - `p_long <= 1 - threshold` -> short
   - otherwise hold
   - when model is cold, bootstrap mode uses weak momentum direction to generate first labels
   - optional exploration (`--exploration-rate`) continues collecting data even during neutral model states
4. When a trade closes (TP/SL), supervision is direction-aware for a long-probability model:
   - long trade win -> label `1`
   - long trade loss -> label `0`
   - short trade win -> label `0`
   - short trade loss -> label `1`
5. The model is updated immediately using `partial_fit(...)` on that single labeled example.
6. The confidence threshold adapts from recent realized win rate (last 30 outcomes), becoming stricter or looser.
7. Learned state is persisted to `learning_state.joblib` and reloaded on restart.
8. Open paper positions and captured entry features are also persisted, so trades crossing restarts still train the model on close.

Additional adaptive controls for safer compounding:

- volatility/regime-aware sizing scales effective `risk_per_trade` down in high/extreme volatility and up modestly in calm conditions
- regime-performance adaptation nudges risk up/down only after enough same-regime samples exist
- drift monitoring tracks feature-distribution shifts and reports a `feature_drift_score` in `/status` and `/status/full`
- calibration/error monitoring now includes rolling calibration error and directional edge metrics

Additional safety controls now reduce repeated losing phases:

- model-driven entries only activate after a minimum sample count per coin
- optional safety pause halts new entries when recent expectancy is poor and drawdown is elevated

So each closed paper trade directly trains the next decision, and training survives restarts.

## ML diagnostics

`ml_diagnostics.py` helps answer whether the model signal is actually improving.

It reports:

- overall/per-coin/per-side win rate and expectancy
- directional sanity checks:
  - long winners should have higher `p_long` than long losers
  - short winners should have lower `p_long` than short losers
- direction-aware Brier score (lower is better)
- optional runtime snapshot from `/status/full` including rolling Brier/expectancy/drawdown
- rolling calibration error, directional edge, and feature drift score

If advisor mode is enabled, `/status/full` includes `advisor` status and counters (requests/errors/blocked signals).

This is useful to catch label/specification issues where the model keeps repeating failing trade patterns.

## Notes

- The consistency gate currently requires:
  - at least 30 paper trades
  - win rate >= 58%
  - profit factor >= 1.25
- State persistence file is configurable with `--state-file`
- Runtime report file is configurable with `--report-file`
- Live approval can be controlled with:
  - `--require-live-approval / --no-require-live-approval`
  - `--live-approval-mode either|both` (default `either`)
  - `--live-approval-file` (default `allow_live_trading.flag`)
- Startup live order test can be controlled with:
  - `--live-startup-test / --no-live-startup-test`
  - `--live-startup-test-coin` (default `HYPE`)
  - `--live-startup-test-notional` (default `12`)