[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79345":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":38,"readmeContent":39,"aiSummary":40,"trendingCount":16,"starSnapshotCount":16,"syncStatus":14,"lastSyncTime":41,"discoverSource":42},79345,"hyperliquid-trading-bot","Novaquant-labs\u002Fhyperliquid-trading-bot","Novaquant-labs","hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot, hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot, hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot, hyperliquid trading bot, perp trading bot, hyperliquid profitable trading bot,","https:\u002F\u002Fgithub.com\u002FNovaquant-labs\u002Fhyperliquid-trading-bot",null,"Python",214,2158,2,1,0,196,10,"Apache License 2.0",false,"main",[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"algo-trading","automated-trading","crypto-bot","cryptocurrency","decentralized-finance","derivatives","dex","hyperliquid","perp-trading-bot","perpetual-futures","perpetual-trading","profitable-trading","testnet-trading","trading-bot","typescript","2026-06-12 02:03:50","# 🤖 Hyperliquid Grid Trading Bot\n\n**An intelligent grid trading strategy runner for Hyperliquid — automate layered orders with built-in risk management.**\n\n[![GitHub](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub-Novaquant--labs-blue?logo=github)](https:\u002F\u002Fgithub.com\u002FNovaquant-labs\u002Fhyperliquid-trading-bot)\n[![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNode.js-20.19+-green)](https:\u002F\u002Fnodejs.org\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-gray)](LICENSE)\n\n---\n\n## 🎯 What This Bot Does\n\nThis bot **automatically places layered buy and sell orders** around your target price range on Hyperliquid. Think of it as a smart assistant that:\n\n✅ Places multiple orders at different price levels (your \"grid\")  \n✅ Automatically rebalances when the market moves  \n✅ Protects your capital with stop-loss, take-profit, and drawdown limits  \n✅ Logs everything for transparency and debugging  \n✅ Runs 24\u002F7 on testnet or mainnet (your choice)\n\n**Perfect for:** Volatile markets, range-bound trading, automated income generation, and hands-off position management.\n\n---\n\n## ⚠️ Risk Warning\n\n**Trading derivatives is risky.** You can lose your entire investment. This bot is for **education and research only**. \n\n🔴 **Before you start:**\n- Start on **testnet** with fake funds\n- Keep position sizes **small** while learning\n- Always understand the strategy before running it\n- Never share your private keys or `.env` file\n- Read `bots\u002Fbtc_conservative.yaml` to understand risk settings\n\n**The authors provide no financial or legal advice. You are fully responsible for your trading decisions.**\n\n---\n\n## 📋 Prerequisites\n\nYou'll need just **three things**:\n\n| What | Why | Link |\n|-----|-----|------|\n| **Node.js 20.19+** | Runs the bot engine | [Download Node.js](https:\u002F\u002Fnodejs.org\u002F) |\n| **Hyperliquid Wallet** | Holds your trading funds | [Create wallet](https:\u002F\u002Fhyperliquid.xyz) |\n| **Git** | Clones this repository | [Get Git](https:\u002F\u002Fgit-scm.com\u002F) |\n\n**Optional:** [uv](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv) if you want to play with Python learning examples.\n\n---\n\n## 🚀 Quick Start (5 Minutes)\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FNovaquant-labs\u002Fhyperliquid-trading-bot.git\ncd hyperliquid-trading-bot\nnpm install\n```\n\n### Step 2: Set Up Your Environment\n\n```bash\ncp .env.example .env\n```\n\nThen edit `.env` and add your wallet's private key:\n\n**For testnet (recommended first):**\n```env\nHYPERLIQUID_TESTNET=true\nHYPERLIQUID_TESTNET_PRIVATE_KEY=your_testnet_private_key_here\n```\n\n**For mainnet (real money):**\n```env\nHYPERLIQUID_TESTNET=false\nHYPERLIQUID_MAINNET_PRIVATE_KEY=your_mainnet_private_key_here\n```\n\n> 🔒 **Never commit `.env` to Git.** It's already in `.gitignore` — keep it that way.\n\n### Step 3: Configure Your Strategy\n\nThe bot comes with a sample config: `bots\u002Fbtc_conservative.yaml`\n\nTo use it, make sure it has `active: true`:\n\n```yaml\nname: \"my_first_grid\"\nactive: true           # ← Set this to true\n\nexchange:\n  type: \"hyperliquid\"\n  testnet: true        # Change to false for mainnet\n\naccount:\n  max_allocation_pct: 10.0  # Risk only 10% of your account\n\ngrid:\n  symbol: \"BTC\"\n  levels: 10           # 10 buy\u002Fsell orders per side\n  price_range:\n    mode: \"auto\"\n    auto:\n      range_pct: 5.0   # Grid spans ±5% around current price\n```\n\n### Step 4: Validate & Run\n\n```bash\nnpm run validate      # Quick check for config errors\nnpm start             # 🤖 Bot is now trading!\n```\n\nPress **Ctrl+C** to stop. The bot will cancel all open orders.\n\n---\n\n## 📖 Understanding Your Configuration\n\nAll bot settings live in **one YAML file** under `bots\u002F`.\n\n### Basic Structure\n\n```yaml\nname: \"my_bot_name\"           # What to call this strategy\nactive: true                  # true = bot will auto-start, false = skip\n\nexchange:\n  type: \"hyperliquid\"         # Only option for now\n  testnet: true               # true = testnet, false = mainnet\n\naccount:\n  max_allocation_pct: 10.0    # Max % of wallet to use (safety limit)\n\ngrid:\n  symbol: \"BTC\"               # Trading pair: BTC, ETH, SOL, etc.\n  levels: 10                  # Number of orders on each side\n  price_range:\n    mode: \"auto\"              # Can be \"auto\" or \"manual\"\n    auto:\n      range_pct: 5.0          # Grid covers ±5% from current price\n\nrisk_management:\n  stop_loss_enabled: false\n  stop_loss_pct: 10.0\n  take_profit_enabled: false\n  take_profit_pct: 20.0\n  max_drawdown_pct: 15.0      # Pause if down 15%\n  rebalance:\n    price_move_threshold_pct: 12.0\n\nmonitoring:\n  log_level: \"INFO\"           # INFO, DEBUG, WARN, ERROR\n```\n\n### Key Settings Explained\n\n**`grid.levels`** — How many buy orders below and sell orders above your center price  \n→ More levels = thinner spreads, more orders to manage\n\n**`price_range.auto.range_pct`** — How wide your grid spans  \n→ 5% = grid from -5% to +5% of current price\n\n**`max_allocation_pct`** — % of your wallet the bot can use  \n→ 10% = max risk is 10% of your total funds\n\n**`max_drawdown_pct`** — Bot pauses if losses hit this threshold  \n→ 15% = shut down if down $15 per $100 in the account\n\n---\n\n## 🎓 Common Configurations\n\n### 🛡️ Conservative (Low Risk, Slow Profit)\n```yaml\ngrid:\n  levels: 15\n  price_range:\n    auto:\n      range_pct: 2.0\naccount:\n  max_allocation_pct: 5.0\nrisk_management:\n  max_drawdown_pct: 10.0\n```\n\n### ⚡ Aggressive (Higher Risk, Faster Profit)\n```yaml\ngrid:\n  levels: 5\n  price_range:\n    auto:\n      range_pct: 10.0\naccount:\n  max_allocation_pct: 25.0\nrisk_management:\n  max_drawdown_pct: 25.0\n```\n\n### 💰 Balanced (Medium Risk)\n```yaml\ngrid:\n  levels: 10\n  price_range:\n    auto:\n      range_pct: 5.0\naccount:\n  max_allocation_pct: 15.0\nrisk_management:\n  max_drawdown_pct: 15.0\n```\n\n---\n\n## 🛠️ Commands & Tools\n\n| Command | What It Does |\n|---------|-------------|\n| `npm start` | Run bot with first active config |\n| `npm run validate` | Check config syntax (no keys needed) |\n| `npx tsx ts\u002Fsrc\u002FrunBot.ts bots\u002Fmy_config.yaml` | Run specific config |\n| `npm test` | Run automated tests |\n| `npm run debug` | Start with verbose logging |\n\n---\n\n## 🔄 How It Works (Under the Hood)\n\n```\n┌─────────────────────────────────────────────────────┐\n│ 1. Bot Starts                                       │\n│    Reads your .env (private key) + YAML config     │\n└──────────────────┬──────────────────────────────────┘\n                   ↓\n┌─────────────────────────────────────────────────────┐\n│ 2. Places Grid Orders                               │\n│    Puts buy orders below + sell orders above        │\n│    e.g., BTC at $43k, $42.9k, $42.8k (buy side)    │\n│             $44k, $44.1k, $44.2k (sell side)       │\n└──────────────────┬──────────────────────────────────┘\n                   ↓\n┌─────────────────────────────────────────────────────┐\n│ 3. Monitor & Manage                                 │\n│    Watch for fills, check risk limits, rebalance   │\n│    Logs every action for transparency              │\n└──────────────────┬──────────────────────────────────┘\n                   ↓\n┌─────────────────────────────────────────────────────┐\n│ 4. Loop Until Stopped                               │\n│    Repeat every few seconds (configurable)          │\n└─────────────────────────────────────────────────────┘\n```\n\n---\n\n## 📊 Real Example Walkthrough\n\nLet's say BTC is trading at **$43,000**:\n\n**Your Config:**\n- `levels: 5` (5 buy, 5 sell orders)\n- `range_pct: 4.0` (±4% = $41,280 to $44,720)\n\n**Bot Creates This Grid:**\n\n```\nSELL Orders (Above Price)     BUY Orders (Below Price)\n─────────────────────────     ──────────────────────\nLimit $44,720 (±4%)           Limit $41,280 (±4%)\nLimit $44,344                 Limit $41,656\nLimit $43,968 (←Mid)          Limit $42,032 (←Mid)\nLimit $43,592                 Limit $42,408\nLimit $43,216                 Limit $42,784\n```\n\nWhen price rises to $44,000 → sells execute → profit locked.  \nWhen price drops to $42,000 → buys execute → averaging down.  \nRinse and repeat.\n\n---\n\n## 🐍 Python Examples (Educational)\n\nWant to learn the API? Check out the learning examples:\n\n```bash\n# Install Python deps\nuv sync\n\n# Run examples\nuv run learning_examples\u002F01_websockets\u002Frealtime_prices.py\nuv run learning_examples\u002F02_market_data\u002Fget_all_prices.py\nuv run learning_examples\u002F04_trading\u002Fplace_limit_order.py\n```\n\nAlso see the legacy Python bot:\n```bash\nuv run src\u002Frun_bot.py --validate\nuv run src\u002Frun_bot.py\n```\n\n---\n\n## ❓ FAQ\n\n### Q: Can I run multiple bots at once?\n**A:** Not in auto-discovery mode (only one `active: true`). To run multiple, launch them separately with explicit config paths:\n```bash\nnpx tsx ts\u002Fsrc\u002FrunBot.ts bots\u002Fbtc_grid.yaml &\nnpx tsx ts\u002Fsrc\u002FrunBot.ts bots\u002Feth_grid.yaml &\n```\n\n### Q: What's the minimum position size?\n**A:** Depends on Hyperliquid's rules. Start with the testnet to find out—no real money lost if wrong.\n\n### Q: Does the bot work 24\u002F7?\n**A:** Yes, as long as your server\u002Fmachine stays on. Consider cloud hosting (AWS, DigitalOcean) for always-on trading.\n\n### Q: How often does it check & rebalance?\n**A:** Every few seconds (configurable). Check logs to see the exact interval.\n\n### Q: Can I edit the config while the bot is running?\n**A:** No. Stop the bot (Ctrl+C), edit the YAML, then restart.\n\n### Q: What if my key is exposed?\n**A:** Immediately revoke it in your Hyperliquid wallet settings and generate a new one. Never re-use a compromised key.\n\n---\n\n## 🐛 Troubleshooting\n\n### Bot won't start\n```bash\nnpm run validate\n# Check for YAML syntax errors\n# Verify .env file exists and has HYPERLIQUID_TESTNET_PRIVATE_KEY\n```\n\n### Orders aren't filling\n- Check market liquidity (sparse market = wider spreads needed)\n- Verify `price_range.range_pct` is wide enough\n- Ensure your account has enough collateral\n- Look at logs: `npm run debug`\n\n### \"Invalid private key\" error\n- Double-check `.env` for typos\n- Verify you're using the **correct** key for testnet\u002Fmainnet\n- Make sure the key is **hex-encoded** (no spaces)\n\n### Bot stops unexpectedly\n- Check logs for error messages\n- Verify your API rate limits aren't exceeded\n- Ensure the bot account still has collateral\n\n### High slippage \u002F orders not optimal\n- Reduce `grid.levels` (fewer, thicker orders)\n- Increase `price_range.range_pct` (wider bands)\n- Trade more liquid pairs (BTC, ETH)\n\n---\n\n## 💡 Tips for Success\n\n✅ **Start small** — Test on testnet with tiny amounts first  \n✅ **Log everything** — Keep detailed records of all trades  \n✅ **Monitor trends** — Grids work best in range-bound markets  \n✅ **Set realistic limits** — 15% drawdown > 5% of actual risk  \n✅ **Adjust gradually** — Change one setting at a time  \n✅ **Read the docs** — Hyperliquid has nuances; understand them  \n✅ **Use alerts** — Set up bot notifications (email, Telegram, Discord)\n\n---\n\n## 🔧 Advanced: Custom Configs\n\nNeed more control? Edit `bots\u002Fyour_config.yaml` with all available options:\n\n```yaml\ngrid:\n  price_range:\n    mode: \"manual\"           # Instead of auto\n    manual:\n      lower_bound: 40000\n      upper_bound: 50000\n\nrisk_management:\n  stop_loss_enabled: true\n  stop_loss_pct: 8.0\n  take_profit_enabled: true\n  take_profit_pct: 15.0\n  max_position_size_pct: 40.0\n  rebalance:\n    enabled: true\n    price_move_threshold_pct: 12.0\n\nmonitoring:\n  log_level: \"DEBUG\"         # Verbose logging\n```\n\n---\n\n## 📚 Development & Contributing\n\n### Local Development\n```bash\n# Typecheck\nnpx tsc --noEmit\n\n# Run tests\nnpm test\n\n# Run with debug logging\nnpm run debug\n```\n\n### Contributing\nSee `AGENTS.md` \u002F `CLAUDE.md` for code style and conventions.\n\n### Publishing (Maintainers)\nUse `scripts\u002Fpublish-to-polypulse.ps1` to push to GitHub (requires `GITHUB_TOKEN`).\n\n---\n\n## ⚖️ License & Disclaimer\n\n**This software is provided \"as is,\" without any warranty.** You are fully responsible for:\n- Securing your private keys and API credentials\n- Compliance with exchange rules and local laws\n- Any financial losses from using this bot\n- Ensuring your strategy aligns with your risk tolerance\n\nRead the full license in the repository.\n\n---\n\n## 🤝 Get Help\n\n- 📖 **Docs:** Check `README.md` and `bots\u002Fbtc_conservative.yaml`\n- 🐛 **Issues:** Report bugs on [GitHub Issues](https:\u002F\u002Fgithub.com\u002FNovaquant-labs\u002Fhyperliquid-trading-bot\u002Fissues)\n- 💬 **Discussions:** Join the community for questions\n- 📧 **Security:** Report vulnerabilities privately to maintainers\n\n---\n\n## 🎉 Next Steps\n\n1. **Clone the repo** → `git clone ...`\n2. **Set up `.env`** → Add your testnet key\n3. **Run on testnet** → `npm start`\n4. **Monitor logs** → Verify orders are placed correctly\n5. **Tweak the config** → Experiment with different settings\n6. **Graduate to mainnet** (optional) → When confident, switch to real funds\n\n**Happy trading!** 🚀\n\n---\n\n*Last Updated: May 2026 | Maintained by Novaquant-labs*","Novaquant-labs\u002Fhyperliquid-trading-bot 是一个针对Hyperliquid平台的网格交易机器人，能够自动在目标价格区间内放置多层买卖订单。其核心功能包括智能订单分层、市场变动时自动再平衡、内置的风险管理（如止损、止盈和最大回撤限制）以及详细的日志记录，支持24\u002F7不间断运行于测试网或主网。该项目采用Python编写，并提供了易于配置的策略文件。适用于波动性较大的市场环境下的范围交易、自动化收益生成及免手动干预的位置管理场景。对于希望通过算法交易提高效率同时控制风险的加密货币投资者来说，这是一个值得尝试的工具。","2026-06-01 03:48:17","CREATED_QUERY"]