Hyperliquid grid trading bot

Repository: github.com/NoFxAi-OS/hyperliquid-trading-bot

A configurable grid strategy runner for Hyperliquid. It places layered buy and sell orders around a price range and supports basic risk rules (stop loss, take profit, drawdown limits, and rebalancing). The main implementation is TypeScript on Node.js; a legacy Python tree remains for reference and scripts.

Risk. Trading digital assets and derivatives is risky. This repository is for education and research. You can lose your capital. Use Hyperliquid testnet and small size until you understand the behavior. The authors and contributors are not providing financial or legal advice.

What you need

| Requirement | Notes | |-------------|--------| | Node.js 20.19 or newer | Required for the main bot (package.json → engines). | | A Hyperliquid wallet (private key) | For testnet: use a dedicated key; fund via testnet faucet or your preferred source. | | git | To clone the repository. |

Optional: uv if you use the Python examples under learning_examples/ or src/run_bot.py.

Install and run (main bot)

Follow these steps in order.

1. Clone and install dependencies

git clone 
cd hyperliquid-trading-bot
npm install

2. Environment file

cp .env.example .env

Edit .env and set at least:

• Testnet: HYPERLIQUID_TESTNET_PRIVATE_KEY, HYPERLIQUID_TESTNET=true, and the testnet URL variables if you use the defaults from .env.example.
• Mainnet (real funds): use the mainnet private key variable and HYPERLIQUID_TESTNET=false as described in .env.example. Double-check YAML exchange.testnet: false for live trading.

Never commit .env or share your private key.

3. Bot configuration

Configs live in bots/*.yaml. The sample btc_conservative.yaml is a conservative grid profile. Set active: true on the file you want the auto-discovery runner to pick (only one should be active: true if you rely on auto-discovery), or pass an explicit path when starting (see below).

4. Validate, then start

npm run validate
npm start

| Command | Purpose | |--------|---------| | npm start | Runs the bot using the first active: true config under bots/. | | npm run validate | Checks that a selected YAML is structurally valid (no private key required for this step). | | npx tsx ts/src/runBot.ts path/to/config.yaml | Runs with an explicit config file. | | npm test | Runs automated tests (e.g. grid math). |

On Ctrl+C, the engine attempts to cancel open orders; review logs for your environment.

How configuration fits together

• .env – Private keys, testnet flag, and API base URLs. See .env.example for all options and comments.
• bots/.yaml – Strategy name, exchange (e.g. Hyperliquid, testnet on/off), account allocation, grid (symbol, levels, range), risk_management, and monitoring.log_level.

The TypeScript