{"id":47623058,"url":"https://github.com/keitaj/hyperliquid-bot","last_synced_at":"2026-04-25T12:03:11.329Z","repository":{"id":307807273,"uuid":"1030747737","full_name":"keitaj/hyperliquid-bot","owner":"keitaj","description":"Automated trading bot for Hyperliquid DEX with 7 strategies (MA, RSI, Bollinger, MACD, Grid, Breakout, Market Making) and HIP-3 multi-DEX support","archived":false,"fork":false,"pushed_at":"2026-04-21T22:13:22.000Z","size":736,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-22T00:03:17.122Z","etag":null,"topics":["algorithmic-trading","blockchain","cryptocurrency","defi","dex","hip-3","hyperliquid","hyperliquid-api","hyperliquid-trading-bot","market-making","perpetuals","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keitaj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-02T08:31:41.000Z","updated_at":"2026-04-21T22:11:26.000Z","dependencies_parsed_at":"2026-04-22T00:01:18.427Z","dependency_job_id":null,"html_url":"https://github.com/keitaj/hyperliquid-bot","commit_stats":null,"previous_names":["keitaj/hyperliquid-bot"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/keitaj/hyperliquid-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keitaj%2Fhyperliquid-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keitaj%2Fhyperliquid-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keitaj%2Fhyperliquid-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keitaj%2Fhyperliquid-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keitaj","download_url":"https://codeload.github.com/keitaj/hyperliquid-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keitaj%2Fhyperliquid-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32261127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithmic-trading","blockchain","cryptocurrency","defi","dex","hip-3","hyperliquid","hyperliquid-api","hyperliquid-trading-bot","market-making","perpetuals","python","python3"],"created_at":"2026-04-01T22:26:22.911Z","updated_at":"2026-04-25T12:03:11.278Z","avatar_url":"https://github.com/keitaj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyperliquid Trading Bot\n\n[![Test](https://github.com/keitaj/hyperliquid-bot/actions/workflows/test.yml/badge.svg)](https://github.com/keitaj/hyperliquid-bot/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Release](https://img.shields.io/github/v/release/keitaj/hyperliquid-bot)](https://github.com/keitaj/hyperliquid-bot/releases)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)\n\n**English** | [日本語](README_ja.md)\n\nAutomated trading bot for Hyperliquid DEX with **HIP-3 multi-DEX support** (trade.xyz, Felix, Markets by Kinetiq, Based, and more).\n\n## ⚠️ Important Disclaimer\n\n**This software is for educational and informational purposes only.**\n\nThe author assumes no responsibility for any financial losses resulting from the use of this software. Cryptocurrency trading involves significant risks. Before engaging in actual trading, please ensure the following:\n\n- Understand and thoroughly test the code\n- Verify operation with small amounts or on testnet\n- Use at your own risk\n- Consult with experts before making investment decisions\n\nPlease refer to the [LICENSE](./LICENSE) file for detailed disclaimer.\n\n---\n\n## 📋 Table of Contents\n\n- [Setup](#setup)\n- [Usage](#usage)\n  - [Docker Usage (Recommended)](#-docker-usage-recommended)\n  - [Python Usage](#-python-usage)\n- [HIP-3 Multi-DEX Trading](#hip-3-multi-dex-trading)\n- [Trading Strategies](#trading-strategies)\n- [Risk Guardrails](#risk-guardrails)\n- [Features](#features)\n- [Technical Documentation](#technical-documentation)\n- [File Structure](#file-structure)\n- [Parameter Reference (for AI agents)](#parameter-reference-for-ai-agents)\n\n## Setup\n\n### Create Environment File\n\n```bash\ncp .env.example .env\n```\n\n### API Key Configuration\n\nEdit the `.env` file and configure the following information:\n\n**Configuration Items:**\n- `HYPERLIQUID_ACCOUNT_ADDRESS`: Your main wallet address (the address that holds your funds)\n- `HYPERLIQUID_PRIVATE_KEY`: Private key for signing transactions\n- `USE_TESTNET`: Set to `true` to use testnet\n\n### Method 1: Direct Private Key Usage\nSet your wallet's private key directly.\n\n### Method 2: API Wallet Usage (Recommended)\nFor a more secure approach, visit [https://app.hyperliquid.xyz/API](https://app.hyperliquid.xyz/API) to generate an API wallet.\n\nSet `HYPERLIQUID_ACCOUNT_ADDRESS` to your main wallet address and `HYPERLIQUID_PRIVATE_KEY` to the API wallet's private key. The API wallet is used only for signing transactions — no fund transfer to the API wallet is required.\n\n## Usage\n\n### 🐳 Docker Usage (Recommended)\n\n#### Prerequisites\n```bash\n# Create environment file\ncp .env.example .env\n# Edit .env file to set API keys\n```\n\n#### Basic Usage\n```bash\n# Use latest stable version\ndocker run --env-file .env ghcr.io/keitaj/hyperliquid-bot:latest\n\n# Run with specific strategy and parameters\ndocker run --env-file .env ghcr.io/keitaj/hyperliquid-bot:latest \\\n  python3 bot.py --strategy rsi --rsi-period 21 --oversold-threshold 25\n\n# Run with specific trading coins\ndocker run --env-file .env ghcr.io/keitaj/hyperliquid-bot:latest \\\n  python3 bot.py --strategy macd --coins BTC ETH\n\n# Daemon execution (continuous background operation)\ndocker run -d --name hyperliquid-bot --env-file .env \\\n  -v $(pwd)/logs:/app/logs ghcr.io/keitaj/hyperliquid-bot:latest\ndocker logs -f hyperliquid-bot\n\n# Check balance\ndocker run --rm --env-file .env ghcr.io/keitaj/hyperliquid-bot:latest \\\n  python3 check_balance.py\n```\n\n#### Available Image Tags\n- `latest` - Latest stable version\n- `v0.3.0` - Specific version\n\n### 🐍 Python Usage\n\n#### Install Dependencies\n```bash\npip3 install .\n```\n\n#### Basic Usage\n```bash\n# Start with default strategy (Simple MA)\npython3 bot.py\n\n# Start with specific strategy\npython3 bot.py --strategy rsi\n\n# Specify trading coins\npython3 bot.py --strategy macd --coins BTC ETH\n\n# Show help\npython3 bot.py --help\n```\n\n#### Parameter Customization\n\n**Common Parameters**\n```bash\n# Change position size and profit/loss settings\npython3 bot.py --position-size-usd 200 --take-profit-percent 10 --stop-loss-percent 3\n```\n\n**Strategy-Specific Parameters**\n```bash\n# Simple MA Strategy\npython3 bot.py --strategy simple_ma --fast-ma-period 5 --slow-ma-period 20\n\n# RSI Strategy\npython3 bot.py --strategy rsi --rsi-period 21 --oversold-threshold 25 --overbought-threshold 75\n\n# Bollinger Bands Strategy\npython3 bot.py --strategy bollinger_bands --bb-period 25 --std-dev 2.5\n\n# MACD Strategy\npython3 bot.py --strategy macd --fast-ema 10 --slow-ema 20 --signal-ema 7\n\n# Grid Trading Strategy\npython3 bot.py --strategy grid_trading --grid-levels 15 --grid-spacing-pct 0.3 --position-size-per-grid 30\n\n# Breakout Strategy\npython3 bot.py --strategy breakout --lookback-period 30 --volume-multiplier 2.0 --atr-period 20\n\n# Market Making Strategy\npython3 bot.py --strategy market_making --spread-bps 10 --order-size-usd 100 --maker-only --taker-fallback-age 60\n\n# Market Making with BBO mode (place orders at best bid/ask)\npython3 bot.py --strategy market_making --bbo-mode --bbo-offset-bps 0.5\n```\n\n**Risk Guardrail Parameters**\n```bash\n# Configure risk limits\npython3 bot.py --strategy rsi \\\n  --max-position-pct 0.1 \\\n  --max-margin-usage 0.7 \\\n  --daily-loss-limit 500 \\\n  --per-trade-stop-loss 0.05 \\\n  --max-open-positions 3 \\\n  --risk-level yellow\n```\n\n#### Balance \u0026 Position Check\n```bash\npython3 check_balance.py\n```\n\nExample output:\n```\n==================================================\n🏦 HYPERLIQUID ACCOUNT BALANCE\n==================================================\n📦 Spot (USDC/USDH):\n   USDC    $1,000.00\n   USDH    $0.00\n📊 Perps:           $299.00\n📈 Position Value:   $500.00\n\n==================================================\n📋 POSITIONS\n==================================================\nBTC          | LONG  | Size:   0.0050 | Entry: $100000.00 | PnL: 🟢$   5.00\nxyz:AAPL     | SHORT | Size:   1.0000 | Entry: $  250.00 | PnL: 🔴$  -2.50\n--------------------------------------------------\nTOTAL        |       |                |                 | PnL: 🟢$   2.50\n==================================================\n```\n\n---\n\n## HIP-3 Multi-DEX Trading\n\n[HIP-3](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-3-builder-deployed-perpetuals) is Hyperliquid's standard for builder-deployed perpetuals DEXes. All HIP-3 DEXes share the same underlying Hyperliquid L1 infrastructure and API, differing only in their listed assets and oracle configurations.\n\n### Supported Platforms\n\n| Platform | DEX Name | Asset Types |\n|---|---|---|\n| Standard Hyperliquid | (none) | Crypto perps (BTC, ETH, SOL...) |\n| [trade.xyz](https://trade.xyz) | `xyz` | Equity \u0026 commodity perps (AAPL, GOLD, CL...) |\n| [Felix](https://trade.usefelix.xyz) | `flx` | Equity \u0026 commodity perps |\n| [Markets by Kinetiq](https://markets.xyz) | `km` | Various (collateral: USDH) |\n| [Based](https://basedapp.xyz) | (none) | Standard HL frontend — use `ENABLE_STANDARD_HL=true` |\n| [Ventuals](https://app.ventuals.com) | `vntl` | — |\n| [HyENA](https://app.hyena.trade) | `hyna` | — |\n| [dreamcash](https://trade.dreamcash.xyz) | `cash` | — |\n\n\u003e **Note**: DEX names are assigned on-chain. Run `{\"type\": \"perpDexs\"}` against the Hyperliquid API to see the current full list.\n\n### Configuration\n\nAdd the following to your `.env` file:\n\n```bash\n# Comma-separated HIP-3 DEX names to trade on\nTRADING_DEXES=xyz,flx\n\n# Set to false to trade only on HIP-3 DEXes (disable standard HL perps)\nENABLE_STANDARD_HL=true\n\n# Per-DEX coin lists (optional — defaults to all available coins on that DEX)\nXYZ_COINS=XYZ100,XYZ200\nFLX_COINS=NVDA,AAPL,WTI\n```\n\n### HIP-3 Command-Line Options\n\n```bash\n# Trade only on trade.xyz with RSI strategy\npython3 bot.py --strategy rsi --dex xyz --no-hl\n\n# Trade Felix equity perps (NVDA, AAPL) + standard HL BTC/ETH simultaneously\nFLX_COINS=NVDA,AAPL python3 bot.py --strategy simple_ma --coins BTC ETH --dex flx\n\n# Trade across all configured DEXes (set TRADING_DEXES in .env)\npython3 bot.py --strategy macd\n```\n\n| Flag | Description |\n|---|---|\n| `--dex DEX [DEX ...]` | HIP-3 DEX names to trade (overrides `TRADING_DEXES` env var) |\n| `--no-hl` | Disable standard Hyperliquid perps, trade only HIP-3 DEXes |\n| `--enable-ws` | Enable WebSocket feed for real-time L2 book updates (reduces REST API calls) |\n\n### How HIP-3 Works Internally\n\nHIP-3 assets use a special integer asset ID scheme:\n\n```\nasset_id = 100000 + (perp_dex_index × 10000) + index_in_meta\n```\n\nFor example, if `xyz` is the 2nd DEX (index 1) and `XYZ100` is its first asset (index 0):\n```\nasset_id = 100000 + (1 × 10000) + 0 = 110000\n```\n\nThe bot handles this automatically at startup:\n1. Calls `perpDexs` API to discover all registered DEXes and their indices\n2. Calls `meta` for each configured DEX to get its asset list\n3. Computes asset IDs and injects them into the SDK's lookup table\n4. Represents HIP-3 coins as `\"dex:coin\"` strings (e.g. `\"xyz:XYZ100\"`, `\"flx:NVDA\"`)\n\n---\n\n## Features\n\n- **Market Data**: Real-time price, order book, and candlestick data retrieval\n- **Order Management**: Limit and market order placement and cancellation\n- **Risk Management**: Leverage limits, maximum drawdown, daily loss limits\n- **Multiple Strategies**: Choose from 7 different trading strategies\n- **Risk Guardrails**: Configurable margin limits, daily loss limits, per-trade stop loss, and dynamic risk levels\n- **Startup Validation**: Strategy parameters validated at startup with all errors reported at once\n- **Structured Logging**: JSON output mode for log aggregation tools (`LOG_FORMAT=json`)\n- **HIP-3 Multi-DEX**: Trade across Hyperliquid, trade.xyz, Felix, and other HIP-3 DEXes simultaneously\n\n## Trading Strategies\n\n| # | Strategy | Description |\n|---|---|---|\n| 1 | `simple_ma` | Moving average crossover — buy on golden cross, sell on death cross |\n| 2 | `rsi` | RSI overbought/oversold — buy when RSI \u003c 30, sell when RSI \u003e 70 |\n| 3 | `bollinger_bands` | Bollinger Bands bounce and volatility breakout |\n| 4 | `macd` | MACD/signal crossover with divergence detection |\n| 5 | `grid_trading` | Grid orders at regular intervals in ranging markets |\n| 6 | `breakout` | Support/resistance breakout with volume and ATR confirmation |\n| 7 | `market_making` | Symmetric buy/sell limits around mid price for spread capture |\n\nThe `market_making` strategy uses **progressive close pricing**: as a position ages, the take-profit price is tightened from full spread → breakeven (at 50% of max age) → small loss (at 75%), reducing costly taker force-closes. The loss tolerance is configurable via `--aggressive-loss-bps` (default: 1 bps). During the force-close phase, `--force-close-max-loss-bps` enables progressive loss acceptance that scales from `aggressive-loss-bps` to the configured maximum as the position approaches the taker deadline.\n\n**BBO mode** (`--bbo-mode`): Places orders at the best bid/ask instead of `mid ± spread_bps`. On Hyperliquid, market spreads are typically 0.1–2 bps, so even `SPREAD_BPS=5` places orders 4–5 bps away from BBO, resulting in low fill rates. BBO mode improves fill rates by tracking the current best prices. Use `--bbo-offset-bps N` to place orders N bps behind BBO (default: 0 = at BBO). Falls back to `mid ± spread_bps` when BBO is unavailable.\n\n**Per-coin overrides** (`--coin-offset-overrides`, `--coin-spread-overrides`): Override BBO offset or spread per coin. Format: `\"SP500:0.5,MSFT:3\"`. Supports both bare names and DEX-prefixed names (`xyz:SP500:0.5`). Unspecified coins use the global default.\n\n**Quiet hours** (`--quiet-hours-utc`): Stop or widen quoting during specific UTC hours (e.g., `\"17\"` or `\"17,18\"`). Default: stop quoting entirely. With `--quiet-hours-spread-multiplier N`, widens spread by Nx instead. Positions are still managed during quiet hours.\n\n**Spread schedule** (`--spread-schedule`): Per-hour spread multiplier for time-of-day spread control. Format: `\"HOUR:MULT,...\"` (e.g., `\"0:1.5,3:2.0,14:1.5\"`). Hours not in the schedule use multiplier 1.0 (no change). Multiplier 0 triggers full-stop mode (same as quiet hours). Coexists with quiet hours — quiet hours full-stop takes priority; otherwise multipliers stack.\n\n**WebSocket guards** (require `--enable-ws`):\n- `--bbo-guard-threshold-bps`: Cancel stale entry orders when BBO moves (default: 2.0)\n- `--imbalance-guard-threshold`: Cancel one side when L2 book is skewed (0–1, default: 0)\n- `--close-refresh-threshold-bps`: Refresh close orders on BBO change to improve maker fill rate (default: 0 = disabled)\n\n**Adverse selection logging** (`--enable-adverse-selection-log`): Measures mid-price movement 5s/30s/60s after each fill, logging per-coin summaries every 300s. Observation only — no trading impact.\n\n**Dynamic offset** (`--dynamic-offset`): Auto-adjusts per-coin BBO offset based on adverse selection severity from the tracker. Coins with higher adverse selection get wider offsets; favorable coins get tighter offsets. Requires `--enable-ws` and `--enable-adverse-selection-log`. Manual `--coin-offset-overrides` serve as the baseline; dynamic adjustment adds/subtracts from it.\n\nAll parameters are configurable via CLI flags with sensible defaults.\nRun `python3 bot.py --help` for the full list, or see [Parameter Reference](#parameter-reference-for-ai-agents) below.\n\n## Risk Guardrails\n\nConfigurable risk management via environment variables or CLI flags (CLI takes precedence).\n\n| Env Var | CLI Flag | Default | Description |\n|---|---|---|---|\n| `MAX_POSITION_PCT` | `--max-position-pct` | 0.2 | Max single position as % of account |\n| `MAX_MARGIN_USAGE` | `--max-margin-usage` | 0.8 | Stop new orders above this margin ratio |\n| `FORCE_CLOSE_MARGIN` | `--force-close-margin` | — | Force close ALL positions above this ratio |\n| `DAILY_LOSS_LIMIT` | `--daily-loss-limit` | — | Absolute $ daily loss to auto-stop bot |\n| `PER_TRADE_STOP_LOSS` | `--per-trade-stop-loss` | — | Cut losing trades at this % (e.g., 0.05 = 5%) |\n| `MAX_OPEN_POSITIONS` | `--max-open-positions` | 5 | Max concurrent open positions |\n| `COOLDOWN_AFTER_STOP` | `--cooldown-after-stop` | 3600 | Seconds to wait after emergency stop |\n| `RISK_LEVEL` | `--risk-level` | green | `green` (100%), `yellow` (50%), `red` (pause), `black` (close all) |\n| `METRICS_CACHE_TTL` | — | 2.0 | Seconds to cache risk metrics before re-fetching (recommend 10+ for 6+ coins) |\n| `META_CACHE_TTL` | — | 3600 | Seconds to cache asset metadata (sz_decimals) |\n| `MIDS_CACHE_TTL` | — | 5.0 | Seconds to cache mid prices in order manager |\n\n### Margin Validation\n\nMinimum order values and margin multipliers used during startup validation. Override via environment variables if Hyperliquid changes its requirements.\n\n| Env Var | Default | Description |\n|---|---|---|\n| `MIN_ORDER_VALUE_DEFAULT` | 50 | Default minimum order value in USD |\n| `MIN_ORDER_VALUE_BTC` | 100 | Minimum order value for BTC |\n| `MIN_ORDER_VALUE_ETH` | 100 | Minimum order value for ETH |\n| `MIN_ORDER_VALUE_{COIN}` | — | Minimum order value for any coin (e.g. `MIN_ORDER_VALUE_SOL=80`) |\n| `INITIAL_MARGIN_MULTIPLIER` | 3.0 | Margin multiplier for initial orders |\n| `MARGIN_SAFETY_BUFFER` | 1.5 | Safety buffer on margin calculations |\n\n### Rate Limiter\n\nHyperliquid allows 1,200 weight/minute (~20 req/sec). The rate limiter is configurable via environment variables:\n\n| Env Var | Default | Description |\n|---|---|---|\n| `RATE_LIMIT_RPS` | 5.0 | Requests per second (max 20) |\n| `RATE_LIMIT_BURST` | 8 | Burst limit (max 20) |\n| `RATE_LIMIT_BACKOFF` | 2.0 | Backoff multiplier on rate limit errors |\n| `RATE_LIMIT_MAX_BACKOFF` | 30.0 | Maximum backoff seconds |\n\n### Logging\n\n| Env Var | Default | Description |\n|---|---|---|\n| `LOG_FORMAT` | `text` | Log output format: `text` (human-readable) or `json` (structured, one JSON object per line) |\n| `LOG_LEVEL` | `INFO` | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |\n\nJSON mode is useful for log aggregation tools (Datadog, CloudWatch, Loki, etc.). Example:\n\n```bash\nLOG_FORMAT=json LOG_LEVEL=DEBUG python3 bot.py --strategy rsi\n```\n\n## Technical Documentation\n\nFor more detailed technical information, please refer to the following documents:\n\n- [Timeframes and Parameters Details](./docs/technical-notes/timeframes.md) - Explanation of timeframes and parameter units for each strategy\n- [Docker Release Process](./docs/docker-release.md) - About automatic Docker image releases\n\n## File Structure\n\n- `bot.py`: Main bot class\n- `config.py`: Configuration management\n- `market_data.py`: Market data retrieval\n- `order_manager.py`: Order management\n- `risk_manager.py`: Risk management\n- `rate_limiter.py`: API rate limiting\n- `log_config.py`: Logging setup (text / JSON structured output)\n- `coin_utils.py`: Shared HIP-3 coin notation helpers\n- `account_utils.py`: Account balance helpers (Portfolio Margin)\n- `hip3/`: HIP-3 multi-DEX support\n  - `dex_registry.py`: DEX discovery and asset ID resolution\n  - `multi_dex_market_data.py`: DEX-aware market data\n  - `multi_dex_order_manager.py`: DEX-aware order management\n- `strategies/`: Trading strategies\n  - `base_strategy.py`: Base strategy class\n  - `simple_ma_strategy.py`: Moving average strategy\n  - `rsi_strategy.py`: RSI strategy\n  - `bollinger_bands_strategy.py`: Bollinger Bands strategy\n  - `macd_strategy.py`: MACD strategy\n  - `grid_trading_strategy.py`: Grid trading strategy\n  - `breakout_strategy.py`: Breakout strategy\n  - `market_making_strategy.py`: Market making strategy\n  - `mm_order_tracker.py`: MM order tracking and stale order management\n  - `mm_position_closer.py`: MM position close and take-profit management\n- `validation/`: Pre-trade validation\n  - `margin_validator.py`: Margin and configuration validation\n  - `strategy_validator.py`: Strategy parameter validation\n- `docs/`: Documentation\n  - `technical-notes/`: Technical detail documents\n\n## Notes\n\n- Before using in production, always test on testnet first\n- Keep your private keys secure\n- Set risk management parameters carefully\n- HIP-3 DEXes may charge higher fees than standard Hyperliquid (typically 2x, with 50% going to the DEX deployer)\n- HIP-3 DEXes currently support isolated margin only (cross-margin not available)\n\n---\n\n## Parameter Reference (for AI agents)\n\n\u003e This section is formatted for machine consumption. All CLI flags, config keys, and default values per strategy are listed below as structured YAML. CLI flags use `--kebab-case`, config dict keys use `snake_case`. Config merging: `default_configs[strategy]` is the base; CLI overrides are merged on top.\n\n```yaml\nsystem:\n  main_loop_interval: 10          # --main-loop-interval  (seconds)\n  market_order_slippage: 0.01     # --market-order-slippage  (0.01 = 1%)\n\nstrategies:\n  simple_ma:\n    candle_interval: \"5m\"         # --candle-interval\n    fast_ma_period: 10            # --fast-ma-period\n    slow_ma_period: 30            # --slow-ma-period\n    position_size_usd: 100        # --position-size-usd\n    max_positions: 3              # --max-positions\n    take_profit_percent: 5        # --take-profit-percent\n    stop_loss_percent: 2          # --stop-loss-percent\n\n  rsi:\n    candle_interval: \"15m\"\n    rsi_period: 14                # --rsi-period\n    oversold_threshold: 30        # --oversold-threshold\n    overbought_threshold: 70      # --overbought-threshold\n    rsi_extreme_low: 25           # --rsi-extreme-low  (RSI below this → size × extreme multiplier)\n    rsi_moderate_low: 35          # --rsi-moderate-low  (RSI below this → size × moderate multiplier)\n    size_multiplier_extreme: 1.5  # --size-multiplier-extreme\n    size_multiplier_moderate: 1.2 # --size-multiplier-moderate\n    position_size_usd: 100\n    max_positions: 3\n    take_profit_percent: 5\n    stop_loss_percent: 2\n\n  bollinger_bands:\n    candle_interval: \"15m\"\n    bb_period: 20                         # --bb-period\n    std_dev: 2                            # --std-dev\n    squeeze_threshold: 0.02               # --squeeze-threshold\n    volatility_expansion_threshold: 1.5   # --volatility-expansion-threshold\n    high_band_width_threshold: 0.05       # --high-band-width-threshold  (band_width \u003e this → size × high multiplier)\n    high_band_width_multiplier: 0.8       # --high-band-width-multiplier\n    low_band_width_threshold: 0.02        # --low-band-width-threshold  (band_width \u003c this → size × low multiplier)\n    low_band_width_multiplier: 1.2        # --low-band-width-multiplier\n    position_size_usd: 100\n    max_positions: 3\n    take_profit_percent: 5\n    stop_loss_percent: 2\n\n  macd:\n    candle_interval: \"15m\"\n    fast_ema: 12                  # --fast-ema\n    slow_ema: 26                  # --slow-ema\n    signal_ema: 9                 # --signal-ema\n    divergence_lookback: 20       # --divergence-lookback\n    histogram_strength_high: 0.5  # --histogram-strength-high  (histogram% \u003e this → size × high multiplier)\n    histogram_strength_low: 0.1   # --histogram-strength-low  (histogram% \u003c this → size × low multiplier)\n    histogram_multiplier_high: 1.3 # --histogram-multiplier-high\n    histogram_multiplier_low: 0.7  # --histogram-multiplier-low\n    position_size_usd: 100\n    max_positions: 3\n    take_profit_percent: 5\n    stop_loss_percent: 2\n\n  grid_trading:\n    candle_interval: \"15m\"\n    grid_levels: 10                   # --grid-levels\n    grid_spacing_pct: 0.5             # --grid-spacing-pct\n    position_size_per_grid: 50        # --position-size-per-grid\n    range_period: 100                 # --range-period\n    range_pct_threshold: 10           # --range-pct-threshold  (range% \u003c this → ranging market)\n    volatility_threshold: 0.15        # --volatility-threshold  (vol \u003c this → ranging market)\n    grid_recalc_bars: 20              # --grid-recalc-bars\n    grid_saturation_threshold: 0.7    # --grid-saturation-threshold  (fill ratio \u003e this → size × 0.5)\n    grid_boundary_margin_low: 0.98    # --grid-boundary-margin-low\n    grid_boundary_margin_high: 1.02   # --grid-boundary-margin-high\n    account_cap_pct: 0.05             # --account-cap-pct\n    max_positions: 5\n    take_profit_percent: 2\n    stop_loss_percent: 5\n\n  breakout:\n    candle_interval: \"15m\"\n    lookback_period: 20                    # --lookback-period\n    volume_multiplier: 1.5                 # --volume-multiplier\n    breakout_confirmation_bars: 2          # --breakout-confirmation-bars\n    atr_period: 14                         # --atr-period\n    pivot_window: 5                        # --pivot-window\n    avg_volume_lookback: 20                # --avg-volume-lookback\n    stop_loss_atr_multiplier: 1.5          # --stop-loss-atr-multiplier\n    position_stop_loss_atr_multiplier: 2.0 # --position-stop-loss-atr-multiplier\n    strong_breakout_multiplier: 1.5        # --strong-breakout-multiplier\n    high_atr_threshold: 3.0               # --high-atr-threshold  (ATR% \u003e this → size × high multiplier)\n    low_atr_threshold: 1.0                # --low-atr-threshold  (ATR% \u003c this → size × low multiplier)\n    high_atr_multiplier: 0.7              # --high-atr-multiplier\n    low_atr_multiplier: 1.3               # --low-atr-multiplier\n    position_size_usd: 100\n    max_positions: 3\n    take_profit_percent: 7\n    stop_loss_percent: 3\n\n  market_making:\n    spread_bps: 5                      # --spread-bps\n    order_size_usd: 50                 # --order-size-usd\n    max_open_orders: 4                 # --max-open-orders\n    refresh_interval_seconds: 30       # --refresh-interval\n    close_immediately: true            # --no-close-immediately  (flag inverts this)\n    max_position_age_seconds: 120      # --max-position-age\n    maker_only: false                  # --maker-only\n    taker_fallback_age_seconds: null   # --taker-fallback-age  (seconds after max-position-age to fall back to taker; null = never)\n    aggressive_loss_bps: 1.0           # --aggressive-loss-bps (max loss in bps accepted to avoid taker close; 0 = breakeven only)\n    force_close_max_loss_bps: 0        # --force-close-max-loss-bps (progressive loss in force-close phase; 0 = disabled)\n    close_spread_bps: null             # --close-spread-bps  (close order spread; null = same as spread_bps)\n    close_breakeven_pct: 0.50          # --close-breakeven-pct  (fraction of max_age for breakeven tier transition)\n    close_aggressive_pct: 0.75         # --close-aggressive-pct  (fraction of max_age for aggressive tier transition)\n    bbo_mode: false                    # --bbo-mode  (place orders at best bid/ask instead of mid ± spread)\n    bbo_offset_bps: 0                  # --bbo-offset-bps  (bps behind BBO; 0 = at BBO)\n    inventory_skew_bps: 0              # --inventory-skew-bps (skew per unit of inventory; 0 = disabled)\n    coin_offset_overrides: \"\"          # --coin-offset-overrides  (per-coin BBO offset: \"SP500:0.5,MSFT:3\")\n    coin_spread_overrides: \"\"          # --coin-spread-overrides  (per-coin spread: \"SP500:8,XYZ100:15\")\n    dynamic_offset_enabled: false      # --dynamic-offset  (auto-adjust offset from adverse selection tracker)\n    dynamic_offset_sensitivity: 0.5    # --dynamic-offset-sensitivity  (offset widening per 1bps adverse)\n    dynamic_offset_tighten_rate: 0.25  # --dynamic-offset-tighten-rate  (offset tightening for favorable fills)\n    dynamic_offset_max_addition: 3.0   # --dynamic-offset-max-add  (max offset addition in bps)\n    dynamic_offset_max_reduction: 1.0  # --dynamic-offset-max-reduce  (max offset reduction in bps)\n    dynamic_offset_floor: 0.5          # --dynamic-offset-floor  (minimum offset bps)\n    dynamic_offset_min_fills: 5        # --dynamic-offset-min-fills  (min fills before adjustment activates)\n    microprice_skew_enabled: false     # --microprice-skew  (asymmetric offset based on micro-price skew)\n    microprice_skew_multiplier: 1.0    # --microprice-skew-multiplier  (skew scaling factor)\n    microprice_max_skew_bps: 2.0       # --microprice-max-skew-bps  (max offset adjustment from skew)\n    spread_schedule: \"\"                # --spread-schedule  (per-hour spread multiplier: \"14:1.5,15:1.5,3:2.0\")\n    quiet_hours_utc: \"\"                # --quiet-hours-utc  (UTC hours to stop/reduce quoting: \"17\" or \"17,18\")\n    quiet_hours_spread_multiplier: 0   # --quiet-hours-spread-multiplier  (0 = stop, \u003e0 = widen spread by Nx)\n    vol_adjust_enabled: false          # --vol-adjust  (enable volatility-adjusted BBO offset)\n    vol_adjust_multiplier: 2.0         # --vol-adjust-multiplier  (offset += multiplier × avg_move_bps)\n    vol_adjust_max_offset: 50          # --vol-adjust-max-offset  (max offset bps after vol adjustment)\n    account_cap_pct: 0.05              # --account-cap-pct\n    max_positions: 3\n    take_profit_percent: 1\n    stop_loss_percent: 2\n\nrisk_guardrails:\n  max_position_pct: 0.2           # --max-position-pct  / env MAX_POSITION_PCT\n  max_margin_usage: 0.8           # --max-margin-usage  / env MAX_MARGIN_USAGE\n  force_close_margin: null        # --force-close-margin  / env FORCE_CLOSE_MARGIN\n  daily_loss_limit: null          # --daily-loss-limit  / env DAILY_LOSS_LIMIT\n  per_trade_stop_loss: null       # --per-trade-stop-loss  / env PER_TRADE_STOP_LOSS\n  max_open_positions: 5           # --max-open-positions  / env MAX_OPEN_POSITIONS\n  cooldown_after_stop: 3600       # --cooldown-after-stop  / env COOLDOWN_AFTER_STOP\n  risk_level: \"green\"             # --risk-level  / env RISK_LEVEL  (green|yellow|red|black)\n  metrics_cache_ttl: 2.0          # env METRICS_CACHE_TTL  (seconds; recommend 10+ for 6+ coins)\n  meta_cache_ttl: 3600            # env META_CACHE_TTL  (seconds; asset metadata cache)\n  mids_cache_ttl: 5.0             # env MIDS_CACHE_TTL  (seconds; mid price cache)\n\nmargin_validation:\n  min_order_value_default: 50     # env MIN_ORDER_VALUE_DEFAULT\n  min_order_value_btc: 100        # env MIN_ORDER_VALUE_BTC\n  min_order_value_eth: 100        # env MIN_ORDER_VALUE_ETH\n  initial_margin_multiplier: 3.0  # env INITIAL_MARGIN_MULTIPLIER\n  margin_safety_buffer: 1.5       # env MARGIN_SAFETY_BUFFER\n\nlogging:\n  log_format: \"text\"              # env LOG_FORMAT  (text|json)\n  log_level: \"INFO\"               # env LOG_LEVEL  (DEBUG|INFO|WARNING|ERROR|CRITICAL)\n\nhip3:\n  env:\n    TRADING_DEXES: \"\"             # Comma-separated DEX names (e.g. \"xyz,flx\")\n    ENABLE_STANDARD_HL: \"true\"    # Trade standard HL perps alongside HIP-3\n    \"{DEX}_COINS\": \"\"             # Per-DEX coin list (e.g. XYZ_COINS=XYZ100,XYZ200)\n  cli:\n    --dex: []                     # HIP-3 DEX names (overrides TRADING_DEXES)\n    --no-hl: false                # Disable standard HL perps\n    --enable-ws: false            # Enable WebSocket L2 book feed + WS guards\n\nws_guards:                         # All require --enable-ws\n  bbo_guard_threshold_bps: 2.0     # --bbo-guard-threshold-bps  (cancel entry orders on BBO change; 0 = disabled)\n  imbalance_guard_threshold: 0     # --imbalance-guard-threshold  (cancel one side on L2 skew; 0 = disabled)\n  imbalance_guard_depth: 5         # --imbalance-guard-depth  (L2 levels for imbalance calc)\n  close_refresh_threshold_bps: 0   # --close-refresh-threshold-bps  (refresh close orders on BBO change; 0 = disabled)\n  velocity_guard_enabled: false    # --velocity-guard  (cancel one side on sustained BBO direction; disabled by default)\n  velocity_consecutive: 3          # --velocity-consecutive  (consecutive same-direction moves to trigger)\n  velocity_min_move_bps: 1.0       # --velocity-min-move-bps  (min cumulative move in bps to trigger)\n  enable_adverse_selection_log: false  # --enable-adverse-selection-log  (post-fill mid tracking)\n  adverse_selection_log_interval: 300  # --adverse-selection-log-interval  (summary log interval in seconds)\n\nconfig_merge_order: \"default_configs[strategy] ← CLI overrides (only non-null)\"\npriority: \"CLI flag \u003e env var \u003e default_configs \u003e strategy constructor fallback\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeitaj%2Fhyperliquid-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeitaj%2Fhyperliquid-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeitaj%2Fhyperliquid-bot/lists"}