hyperliquid-trading-bot

# Hyperliquid Trading Bot

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A configurable grid strategy runner for [Hyperliquid](https://hyperliquid.xyz) DEX. Places layered buy/sell orders around a price range and enforces risk rules (stop loss, take profit, drawdown limits, rebalancing). Primary stack is **TypeScript on Node.js 20.19+**; a legacy Python tree exists for reference and learning examples.

---

## Installation

```bash
git clone https://github.com/PolyPulse-Analytics/hyperliquid-trading-bot.git
cd hyperliquid-trading-bot
npm install
```

### Requirements

- Node.js **20.19+**
- A Hyperliquid wallet private key (use a dedicated testnet key to start)
- `git`

Optional for Python examples: [uv](https://github.com/astral-sh/uv)

---

## Environment Setup

```bash
cp .env.example .env
```

Edit `.env` — minimum required keys:

```env
# Testnet (recommended to start)
HYPERLIQUID_TESTNET_PRIVATE_KEY=0xYOUR_TESTNET_PRIVATE_KEY_HERE
HYPERLIQUID_TESTNET=true

# Mainnet (real funds — set carefully)
# HYPERLIQUID_MAINNET_PRIVATE_KEY=0xYOUR_MAINNET_PRIVATE_KEY_HERE
# HYPERLIQUID_TESTNET=false
```

**Never commit `.env` or share your private key.**

---

## Key Commands

| Command | Purpose |
|---|---|
| `npm start` | Run bot using first `active: true` config in `bots/` |
| `npm run validate` | Validate YAML config structure (no private key needed) |
| `npm test` | Run automated tests (grid math, etc.) |
| `npx tsc --noEmit` | TypeScript type check |
| `npx tsx ts/src/runBot.ts path/to/config.yaml` | Run with explicit config file |

### Explicit config path (recommended for multi-bot setups)

```bash
npx tsx ts/src/runBot.ts bots/btc_conservative.yaml
```

### Graceful shutdown

Press **Ctrl+C** — the engine attempts to cancel all open orders before exiting. Always review logs to confirm cancellation.

---

## Bot Configuration (YAML)

Config files live in `bots/*.yaml`. Only one file should have `active: true` when using auto-discovery via `npm start`.

### Full annotated example

```yaml
name: "btc_grid_testnet"
active: true

exchange:
  type: "hyperliquid"
  testnet: true          # Set false for mainnet — also set HYPERLIQUID_TESTNET=false in .env

account:
  max_allocation_pct: 10.0   # Max % of account balance to allocate to this grid

grid:
  symbol: "BTC"              # Hyperliquid market symbol
  levels: 10                 # Number of buy/sell levels on each side
  price_range:
    mode: "auto"             # "auto" or "manual"
    auto:
      range_pct: 5.0         # Spread ±5% from current price
    # manual:
    #   lower: 90000
    #   upper: 100000

risk_management:
  stop_loss_enabled: false
  stop_loss_pct: 8.0         # Trigger if price drops X% from entry

  take_profit_enabled: false
  take_profit_pct: 15.0      # Trigger if price rises X% from entry

  max_drawdown_pct: 15.0     # Max allowed drawdown before halting
  max_position_size_pct: 40.0 # Max position as % of allocated capital

  rebalance:
    price_move_threshold_pct: 12.0  # Rebalance grid if price moves outside this %

monitoring:
  log_level: "INFO"          # DEBUG, INFO, WARN, ERROR
```

### Manual price range example

```yaml
grid:
  symbol: "ETH"
  levels: 8
  price_range:
    mode: "manual"
    manual:
      lower: 3000
      upper: 3600
```

---

## Common Patterns

### Running multiple bots with different configs

Do not use `active: true` — call each explicitly:

```bash
# Terminal 1
npx tsx ts/src/runBot.ts bots/btc_conservative.yaml

# Terminal 2
npx tsx ts/src/runBot.ts bots/eth_aggressive.yaml
```

### Validate before running (CI/pre-flight)

```bash
npm run validate && npm start
```

### Testnet workflow before going live

1. Set `HYPERLIQUID_TESTNET=true` in `.env`
2. Set `exchange.testnet: true` in your YAML
3. Fund via [Hyperliquid testnet faucet](https://faucet.chainstack.com/hyperliquid-testnet-faucet)
4. Run `npm run validate` then `npm start`
5. Watch logs — verify orders appear in testnet UI
6. Only then flip both flags to `false` for mainnet

---

## Python Learning Examples

```bash
# Install Python deps
uv sync

# Validate Python bot config
uv run src/run_bot.py --validate

# Run Python bot (legacy)
uv run src/run_bot.py

# Educational scripts
uv run learning_examples/01_websockets/realtime_prices.py
uv run learning_examples/02_market_data/get_all_prices.py
uv run learning_examples/04_trading/place_limit_order.py
```

### Python: Fetch real-time prices via WebSocket

```python
# learning_examples/01_websockets/realtime_prices.py pattern
import asyncio
from hyperliquid.websocket_manager import WebsocketManager

async def on_message(msg):
    print(msg)

async def main():
    ws = WebsocketManager(base_url="https://api.hyperliquid-testnet.xyz")
    await ws.subscribe({"type": "allMids"}, on_message)
    await asyncio.sleep(30)

asyncio.run(main())
```

### Python: Place a limit order (testnet)

```python
# learning_examples/04_trading/place_limit_order.py pattern
import os
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
import eth_account

private_key = os.environ["HYPERLIQUID_TESTNET_PRIVATE_KEY"]
account = eth_account.Account.from_key(private_key)

exchange = Exchange(account, constants.TESTNET_API_URL)

# Place a limit buy for 0.001 BTC at $90,000
result = exchange.order(
    "BTC",
    is_buy=True,
    sz=0.001,
    limit_px=90000,
    order_type={"limit": {"tif": "Gtc"}},
)
print(result)
```

---

## Troubleshooting

### Bot exits immediately without placing orders

- Run `npm run validate` first — check for YAML syntax errors
- Confirm `active: true` is set (or pass config path explicitly)
- Verify `HYPERLIQUID_TESTNET` in `.env` matches `exchange.testnet` in YAML

### Orders placed but immediately cancelled

- Testnet account may have insufficient balance — refund via faucet
- `max_allocation_pct` may be too low for minimum order sizes on the symbol

### TypeScript compilation errors

```bash
npx tsc --noEmit
```

Check Node.js version — must be **20.19+**:

```bash
node --version
```

### Python `uv` not found

```bash
pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Private key errors / authentication failures

- Confirm the key in `.env` matches the funded testnet wallet
- Key must include `0x` prefix
- Never use a mainnet key on testnet configs — keep separate keys

### Grid not rebalancing when price moves

Check `risk_management.rebalance.price_move_threshold_pct` — default is `12.0`. Lower it if you want more frequent rebalancing (increases gas/fees).

---

## Project Structure

```
hyperliquid-trading-bot/
├── bots/                    # YAML strategy configs
│   └── btc_conservative.yaml
├── ts/src/
│   └── runBot.ts            # Main TypeScript entrypoint
├── src/
│   └── run_bot.py           # Legacy Python entrypoint
├── learning_examples/       # Educational Python scripts
│   ├── 01_websockets/
│   ├── 02_market_data/
│   └── 04_trading/
├── .env.example             # Environment variable template
├── package.json
└── pyproject.toml
```

---

## Risk Reminder

- Always start on **testnet** with a dedicated key
- Use `max_allocation_pct` to limit exposure
- Enable `max_drawdown_pct` as a safety net before enabling stop loss/take profit
- Review open orders in the Hyperliquid UI after every bot restart
- This software is provided "as is" — you are responsible for your capital