{"id":31917895,"url":"https://github.com/chainstacklabs/hyperliquid-trading-bot","last_synced_at":"2025-10-13T20:51:12.680Z","repository":{"id":312666600,"uuid":"1039917398","full_name":"chainstacklabs/hyperliquid-trading-bot","owner":"chainstacklabs","description":"Trading bot for Hyperliquid DEX","archived":false,"fork":false,"pushed_at":"2025-10-05T08:55:58.000Z","size":298,"stargazers_count":23,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-05T10:32:54.695Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chainstacklabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-18T07:20:38.000Z","updated_at":"2025-10-05T08:56:02.000Z","dependencies_parsed_at":"2025-09-01T09:55:04.274Z","dependency_job_id":"f4e62309-333c-456e-b45d-3d2db5ac6f38","html_url":"https://github.com/chainstacklabs/hyperliquid-trading-bot","commit_stats":null,"previous_names":["chainstacklabs/hyperliquid-trading-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chainstacklabs/hyperliquid-trading-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-trading-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-trading-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-trading-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-trading-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chainstacklabs","download_url":"https://codeload.github.com/chainstacklabs/hyperliquid-trading-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-trading-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016924,"owners_count":26085913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-10-13T20:51:11.266Z","updated_at":"2025-10-13T20:51:12.674Z","avatar_url":"https://github.com/chainstacklabs.png","language":"Python","readme":"## Extensible grid trading bot for [Hyperliquid DEX](https://hyperliquid.xyz)\n\n\u003e ⚠️ This software is for educational and research purposes. Trading cryptocurrencies involves substantial risk of loss. Never trade with funds you cannot afford to lose. Always thoroughly test strategies on testnet before live deployment.\n\nThis project is under active development. Feel free to submit questions, suggestions, and issues through GitHub.\n\nYou're welcome to use the best docs on Hyperliquid API via [Chainstack Developer Portal MCP server](https://docs.chainstack.com/docs/developer-portal-mcp-server).\n\n## 🚀 Quick start\n\n### **Prerequisites**\n- [uv package manager](https://github.com/astral-sh/uv)\n- Hyperliquid testnet account with testnet funds (see [Chainstack Hyperliquid faucet](https://faucet.chainstack.com/hyperliquid-testnet-faucet))\n\n### **Installation**\n\n```bash\n# Clone the repository\ngit clone https://github.com/chainstacklabs/hyperliquid-trading-bot\ncd hyperliquid-trading-bot\n\n# Install dependencies using uv\nuv sync\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your Hyperliquid testnet private key\n```\n\n### **Configuration**\n\nCreate your environment file:\n```bash\n# .env\nHYPERLIQUID_TESTNET_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE\nHYPERLIQUID_TESTNET=true\n```\n\nThe bot comes with a pre-configured conservative BTC grid strategy in `bots/btc_conservative.yaml`. Review and adjust parameters as needed.\n\n### **Running the bot**\n\n```bash\n# Auto-discover and run the first active configuration\nuv run src/run_bot.py\n\n# Validate configuration before running\nuv run src/run_bot.py --validate\n\n# Run specific configuration\nuv run src/run_bot.py bots/btc_conservative.yaml\n```\n\n## ⚙️ Configuration\n\nBot configurations use YAML format with comprehensive parameter documentation:\n\n```yaml\n# Conservative BTC Grid Strategy\nname: \"btc_conservative_clean\"\nactive: true  # Enable/disable this strategy\n\naccount:\n  max_allocation_pct: 10.0  # Use only 10% of account balance\n\ngrid:\n  symbol: \"BTC\"\n  levels: 10               # Number of grid levels\n  price_range:\n    mode: \"auto\"           # Auto-calculate from current price\n    auto:\n      range_pct: 5.0      # ±5% price range (conservative)\n\nrisk_management:\n  # Exit Strategies\n  stop_loss_enabled: false      # Auto-close positions on loss threshold\n  stop_loss_pct: 8.0           # Loss % before closing (1-20%)\n  take_profit_enabled: false   # Auto-close positions on profit threshold\n  take_profit_pct: 25.0        # Profit % before closing (5-100%)\n  \n  # Account Protection\n  max_drawdown_pct: 15.0       # Stop trading on account drawdown % (5-50%)\n  max_position_size_pct: 40.0  # Max position as % of account (10-100%)\n  \n  # Grid Rebalancing\n  rebalance:\n    price_move_threshold_pct: 12.0  # Rebalance trigger\n\nmonitoring:\n  log_level: \"INFO\"       # DEBUG/INFO/WARNING/ERROR\n```\n\n## 📚 Learning examples\n\nMaster the Hyperliquid API with standalone educational scripts:\n\n```bash\n# Authentication and connection\nuv run learning_examples/01_authentication/basic_connection.py\n\n# Market data and pricing\nuv run learning_examples/02_market_data/get_all_prices.py\nuv run learning_examples/02_market_data/get_market_metadata.py\n\n# Account information\nuv run learning_examples/03_account_info/get_user_state.py\nuv run learning_examples/03_account_info/get_open_orders.py\n\n# Trading operations\nuv run learning_examples/04_trading/place_limit_order.py\nuv run learning_examples/04_trading/cancel_orders.py\n\n# Real-time data\nuv run learning_examples/05_websockets/realtime_prices.py\n```\n\n## 🛡️ Exit strategies\n\nThe bot includes automated risk management and position exit features:\n\n**Position-level exits:**\n- **Stop loss**: Automatically close positions when loss exceeds configured percentage (1-20%)\n- **Take profit**: Automatically close positions when profit exceeds configured percentage (5-100%)\n\n**Account-level protection:**\n- **Max drawdown**: Stop all trading when account-level losses exceed threshold (5-50%)\n- **Position size limits**: Prevent individual positions from exceeding percentage of account (10-100%)\n\n**Operational exits:**\n- **Grid rebalancing**: Cancel orders and recreate grid when price moves outside range\n- **Graceful shutdown**: Cancel pending orders on bot termination (positions preserved by default)\n\nAll exit strategies are configurable per bot and disabled by default for safety.\n\n## 🔧 Development\n\n### **Package management**\nThis project uses [uv](https://github.com/astral-sh/uv) for fast, reliable dependency management:\n\n```bash\nuv sync              # Install/sync dependencies\nuv add \u003cpackage\u003e     # Add new dependencies\nuv run \u003ccommand\u003e     # Run commands in virtual environment\n```\n\n### **Testing**\nAll components are tested against Hyperliquid testnet:\n\n```bash\n# Test learning examples\nuv run learning_examples/04_trading/place_limit_order.py\n\n# Validate bot configuration\nuv run src/run_bot.py --validate\n\n# Run bot in testnet mode (default)\nuv run src/run_bot.py\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainstacklabs%2Fhyperliquid-trading-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainstacklabs%2Fhyperliquid-trading-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainstacklabs%2Fhyperliquid-trading-bot/lists"}