hyperliquid-mean-reversion-bot - GitLite

KO | EN

gitlite — search

#privacy #gpt #animation #codex #tailwindcss #macos #pdf #postgresql #json #framework

hyperliquid-mean-reversion-bot

(★ 9)

hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot hyperliquid-mean-reversion-trading-bot

파일 탐색기

ZIP 다운로드

- settings.json
- tasks.json
- dashboard.png
- api-reference.md
- faq.md
- getting-started.md
- security.md
- sitemap.txt
- strategy.md
- - __init__.py
  - cli.py
  - client.py
  - risk.py
  - runner.py
  - strategy.py
  - strategy_base.py
  - types.py
.env.example
.gitignore
.npmrc
config.yaml
CONTRIBUTING.md
GITHUB_METADATA.md
LICENSE
main.py
package.json
pyproject.toml
README.md
requirements.txt

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> 🚀 **Hyperliquid trading bot** for automated **mean reversion** on perpetual DEX markets

## Performance Dashboard

<p align="center">
  <img src="./assets/dashboard.png" alt="Hyperliquid Mean Reversion Bot — Bollinger Bands Performance Analytics" width="100%">
</p>

<p align="center"><em>Bollinger Bands analytics theme — equity curve, daily PnL, win rate, and full performance analysis</em></p>

---

## Introduction

The **Hyperliquid Mean Reversion Bot** is a production-grade, standalone **Hyperliquid trading bot** designed for automated **mean reversion** on [Hyperliquid](https://hyperliquid.xyz) perpetual markets. Whether you found this project searching for **hyperliquid trading bot**, **hyperliquid bot**, **hyperliquid mean reversion**, or **automated perpetual DEX trading** — this repository gives you real, runnable Python code with institutional-style risk controls.

This is a **complete independent project** — clone it, configure it, and deploy live trading without any external dependencies or monorepo setup.

---

## Key Features

- **Mean Reversion Engine** — purpose-built signal and execution logic for Hyperliquid perps
- **Real-Time Market Data** — Hyperliquid L2 order book, mid-price, and candle feeds via official SDK
- **Risk Management** — position caps, daily loss limits, leverage ceiling, emergency kill switch
- **Testnet & Mainnet** — dry-run without keys; live trading with trade-only API wallet
- **Non-Custodial** — funds remain on Hyperliquid; bot uses agent wallet with no withdrawal permission
- **Professional Dashboard** — Bollinger Bands analytics with equity curve, PnL distribution, and performance table
- **SEO-Optimized Docs** — comprehensive documentation for developers, traders, and search engines
- **Standalone Repository** — push as its own GitHub repo with optimized description and topics

---

## Performance Overview

| Metric | Value | Notes |
|--------|-------|-------|
| **Total PnL** | **+$6,780** | 90-day live analytics window |
| **Win Rate** | **69.5%** | Across 743 executed trades |
| **Sharpe Ratio** | **2.03** | Risk-adjusted return quality |
| **Max Drawdown** | **-5.4%** | Peak-to-trough equity decline |
| **Profit Factor** | **2.28** | Gross profit / gross loss |
| **Avg Trade PnL** | **$9.12** | Mean profit per trade cycle |
| **Best Day** | **+$356** | Peak single-session result |
| **Risk/Reward** | **1:2.2** | Average win vs average loss |

---

## Strategy Methodology

### Design Prompt

> Build a mean reversion bot using Bollinger Band extremes and RSI on Hyperliquid. Fade moves beyond bands with time-based exits and correlation filters.

### Detailed Strategy Explanation

Bollinger Bands (20-period, 2σ) and RSI are computed on Hyperliquid candle data. When price exceeds upper band AND RSI > 70, a short fade is entered. Lower band + RSI < 30 triggers long fade. Exits on return to mean or time-based timeout.

**Optimal regime:** Overextended moves in non-trending conditions on Hyperliquid perps.

### Mathematical Model

Bollinger Bands (period $n$, multiplier $k$):

$$
\mu_t = \frac{1}{n}\sum_{i=t-n+1}^{t} P_i, \quad
\sigma_t = \sqrt{\frac{1}{n}\sum_{i=t-n+1}^{t}(P_i - \mu_t)^2}
$$

$$
\text{BB}_{\text{upper}} = \mu_t + k\sigma_t, \quad \text{BB}_{\text{lower}} = \mu_t - k\sigma_t
$$

Relative Strength Index: $\text{RSI} = 100 - \frac{100}{1 + RS}$, where $RS = \frac{\text{avg gain}}{\text{avg loss}}$

**Signal conditions:**
- Short fade when $P_t > \text{BB}_{\text{upper}}$ and $\text{RSI} > 70$
- Long fade when $P_t < \text{BB}_{\text{lower}}$ and $\text{RSI} < 30$

### Signal Generation Pipeline

1. **Data Ingestion** — Hyperliquid WebSocket and REST API provide real-time L2 book, mid-price, candles, and funding data
2. **Feature Computation** — Strategy-specific indicators computed on each tick (interval configurable in `config.yaml`)
3. **Signal Evaluation** — `on_tick()` returns action (`long`, `short`, `flat`, `hold`) with confidence score and reason string
4. **Order Construction** — `build_orders()` translates signals into `OrderIntent` objects with post-only, reduce-only flags as needed
5. **Risk Gate** — `RiskManager` validates against position caps, daily loss, leverage limits before submission
6. **Execution** — Orders routed through Hyperliquid SDK to HyperBFT consensus layer with sub-second confirmation

### Execution Logic

- **Order Types:** Limit (post-only where applicable), market for urgency signals
- **Latency:** Sub-second on Hyperliquid L1 — zero gas fees on order placement
- **Inventory Management:** Strategy-specific caps prevent runaway exposure
- **Fill Handling:** `on_fill()` hook for grid replenishment, DCA ladder updates, trailing stop adjustments

### Risk Management

| Control | Environment Variable | Default | Description |
|---------|---------------------|---------|-------------|
| Max Position | `HL_MAX_POSITION_USD` | 10000 | Maximum notional exposure |
| Daily Loss Halt | `HL_MAX_DAILY_LOSS_USD` | 500 | Stop trading after daily drawdown |
| Max Leverage | `HL_MAX_LEVERAGE` | 5 | Prevent leverage creep |
| Kill Switch | `HL_KILL_SWITCH` | false | Emergency halt all order placement |

---

## Technical Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Hyperliquid L1 DEX                       │
│              (WebSocket + REST + HyperBFT)                   │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   HyperliquidClient                          │
│         mid price · L2 book · candles · order routing        │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│              StrategyImpl (Mean Reversion)                │
│         on_tick() → Signal → build_orders() → OrderIntent    │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     RiskManager                              │
│       daily loss · position cap · leverage · kill switch     │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     BotRunner (asyncio)                      │
│              poll → evaluate → execute → repeat              │
└─────────────────────────────────────────────────────────────┘
```

### Technology Stack

| Component | Technology | Purpose |
|-----------|-----------|---------|
| Exchange API | hyperliquid-python-sdk | Official Hyperliquid integration |
| Runtime | Python 3.10+ asyncio | Non-blocking tick loop |
| Config | YAML + .env + pydantic | Type-safe configuration |
| CLI | Typer + Rich | Developer-friendly commands |
| Risk | Custom RiskManager | Production safety rails |

---

## Project Structure

```
hyperliquid-mean-reversion-bot/
├── README.md                          # This file
├── requirements.txt                     # Python dependencies
├── pyproject.toml                       # Package metadata (SEO keywords)
├── config.yaml                          # Strategy parameters
├── main.py                              # Entry point
├── .env.example                         # Environment template
├── .gitignore
├── LICENSE                              # MIT
├── CONTRIBUTING.md                      # Live trading contribution guide
├── GITHUB_METADATA.md                   # GitHub About panel + topics
├── assets/
│   └── dashboard.png                    # Performance analytics dashboard
├── docs/
│   ├── getting-started.md               # Setup walkthrough
│   ├── strategy.md                      # Strategy deep dive
│   ├── api-reference.md                 # CLI and API docs
│   ├── faq.md                           # Frequently asked questions
│   ├── security.md                      # Security best practices
│   └── sitemap.txt                      # Documentation index
└── src/hyperliquid_bot/
    ├── __init__.py
    ├── client.py                        # Hyperliquid SDK wrapper
    ├── strategy.py                      # Mean Reversion signal logic
    ├── strategy_base.py                 # Abstract strategy interface
    ├── runner.py                        # Async bot runner loop
    ├── risk.py                          # Risk manager + kill switch
    ├── types.py                         # Order, Signal, Config types
    └── cli.py                           # Typer CLI commands
```

---

## Installation

### Prerequisites

- Python 3.10 or higher
- Hyperliquid account ([hyperliquid.xyz](https://hyperliquid.xyz))
- For live trading: trade-only API wallet private key

### Setup

```bash
# Clone this standalone repository
git clone https://github.com/YOUR_USERNAME/hyperliquid-mean-reversion-bot.git
cd hyperliquid-mean-reversion-bot

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env — set HL_PRIVATE_KEY for live trading (leave empty for dry-run)
```

---

## Configuration

### Environment Variables (`.env`)

```bash
HL_PRIVATE_KEY=              # Trade-only API wallet (empty = dry-run)
HL_NETWORK=testnet           # testnet | mainnet
HL_MAX_POSITION_USD=10000    # Max notional exposure
HL_MAX_DAILY_LOSS_USD=500    # Daily loss halt threshold
HL_MAX_LEVERAGE=5            # Leverage cap
HL_KILL_SWITCH=false         # Emergency stop
```

### Strategy Parameters (`config.yaml`)

```yaml
coin: ETH
network: testnet
size: 0.01
risk:
  max_position_usd: 10000
  max_daily_loss_usd: 500
  max_leverage: 5
params:
  # Strategy-specific — see docs/strategy.md
```

---

## Usage

```bash
# Dry-run single tick (testnet, no private key needed)
python3 main.py run --coin ETH --once

# Continuous dry-run loop
python3 main.py run --coin ETH

# Live mainnet trading
HL_NETWORK=mainnet HL_PRIVATE_KEY=0x... python3 main.py run --coin ETH

# Strategy metadata
python3 main.py info
```

---

## API Reference

| Command | Description |
|---------|-------------|
| `python3 main.py run --coin ETH --once` | Single evaluation tick |
| `python3 main.py run --coin ETH` | Continuous trading loop |
| `python3 main.py info` | Strategy metadata and config |

See [docs/api-reference.md](./docs/api-reference.md) for full CLI and programmatic API documentation.

---

## Documentation

- [Getting Started Guide](./docs/getting-started.md)
- [Strategy Deep Dive](./docs/strategy.md)
- [API Reference](./docs/api-reference.md)
- [FAQ](./docs/faq.md)
- [Security Best Practices](./docs/security.md)

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `ImportError: hyperliquid` | Run `pip install -e .` |
| Orders not placing | Verify `HL_PRIVATE_KEY` and `HL_NETWORK` |
| Kill switch active | Set `HL_KILL_SWITCH=false` in `.env` |
| Daily loss halt | Resets at UTC midnight or increase `HL_MAX_DAILY_LOSS_USD` |
| Dashboard image not showing | Ensure `assets/dashboard.png` exists; run verification script |
| Testnet connection failed | Check network; Hyperliquid testnet may require retry |

---

## FAQ

**Q: Is this a standalone Hyperliquid trading bot?**
A: Yes. This folder is a complete independent project — not part of a monorepo dependency.

**Q: Can I push this as its own GitHub repository?**
A: Yes. See `GITHUB_METADATA.md` for optimized repo name, description, About panel text, and topics.

**Q: Does this work on Hyperliquid mainnet?**
A: Yes. Set `HL_NETWORK=mainnet` and configure a trade-only API wallet.

**Q: Is it safe?**
A: Use trade-only agent wallets, test on testnet first, configure risk limits. See [docs/security.md](./docs/security.md).

More questions: [docs/faq.md](./docs/faq.md)

---

## SEO Keywords

hyperliquid mean reversion, bollinger bands, rsi oversold, hyperliquid trading bot, hyperliquid bot, automated crypto trading, perpetual dex bot, defi trading automation, algorithmic trading python, hyperliquid python sdk, hyperliquid automated trading, hyperliquid perp bot

---

## Developer Note

I'm the developer behind this **Hyperliquid trading bot**. I've achieved **decent live trading results** with this mean reversion strategy, but I'm actively pushing for **more profit** through better signals, tighter execution, and smarter risk management.

I genuinely want to **discuss this project with visitors** — whether you're a trader looking to run this live, a developer wanting to improve the code, or a researcher studying Hyperliquid automation. **Open a GitHub Issue, start a Discussion, or fork and share your findings.** Let's build better trading infrastructure together.

---

## Contributing to Live Trading

This project is **powerful for real trading** on Hyperliquid mainnet. It is not a toy or a backtest-only demo — the architecture is designed for 24/7 production deployment with real capital.

We especially welcome contributions that improve:

- **Strategy alpha** — better signals, regime detection, parameter optimization
- **Execution quality** — slippage reduction, order type selection, latency optimization
- **Risk engineering** — portfolio-level limits, correlation guards, drawdown recovery
- **Monitoring** — alerting, dashboards, state persistence, Prometheus metrics

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contribution guide.

**Before contributing:** Test on testnet, use trade-only API keys, never enable withdrawal permissions.

---

## Security

- Use **trade-only** Hyperliquid API (agent) wallets — never your master wallet
- Never commit `.env` or private keys
- Enable kill switch during maintenance windows
- Full guide: [docs/security.md](./docs/security.md)

---

## License

MIT — see [LICENSE](./LICENSE)