Skip to content

cryptole0/Hyperliquid-Copy-Trading-Bot

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

154 Commits
scripts
scripts
 
 
src
src
 
 
.env.example
.env.example
 
 
.eslintrc.js
.eslintrc.js
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

Hyperliquid Copy Trading Bot

Overview

A production-grade copy trading bot built in TypeScript (Node.js) that mirrors trades from a target Hyperliquid wallet in real-time. It listens for fills/trades, copies opens, reduces, and closes positions while applying configurable risk parameters, supports dry-run and testnet modes, and offers safety/resilience features.

Features

Core Functionality

  • Real-time copying: Monitors a target wallet (public or vault address) for new fills/trades via WebSocket subscriptions, and mirrors opens, reduces, closes of positions immediately.
  • Smart risk management & sizing:
    • Position size = (ourAccountEquity / targetWalletEquity) * targetPositionSize * SIZE_MULTIPLIER
    • Configurable multiplier (e.g. 0.5×, 1×, 2×)
    • Minimum notional check (skip if too small) — Hyperliquid requires ~$10 per order
    • Maximum position size cap (as % of our equity)
    • Match leverage, but cap at MAX_LEVERAGE
    • Blocked assets support (skip certain assets)
    • Limit on max concurrent open trades

Safety & Resilience

  • Dry-run / simulation mode: Log actions without placing real orders
  • Testnet support: Toggleable via config
  • Graceful reconnects: Automatic WebSocket reconnection on disconnect with exponential backoff
  • Rate limiting: Respects API limits with extra safety layer
  • Error handling & retries: Automatic retry logic for failed orders

Configuration & Validation

  • .env + zod schema for strong typed config
  • Required: PRIVATE_KEY, TARGET_WALLET, TESTNET (boolean)
  • Optional: SIZE_MULTIPLIER, MAX_LEVERAGE, BLOCKED_ASSETS (array), DRY_RUN, LOG_LEVEL

Architecture & Code Quality

  • Modern TypeScript (ESM, strict mode)
  • Modular structure: separate modules for config, SDK init, monitoring, execution, logger, types, etc.
  • Async/await, concurrency where necessary
  • Comprehensive logging (info, warn, error) with timestamps via winston
  • Full type safety using SDK types
  • CLI script (e.g. npm start)
  • Comments & notes on Hyperliquid specifics (e.g. no trailing zeros in size/price, GTC orders, etc.)

Bonus Features

  • Telegram notifications: Optional notifications when trades are copied (via node-telegram-bot-api)
  • Basic PnL tracking: Compare our account vs target
  • Health checks: Periodically verify our positions (every 5 minutes by default)

Tech Stack & Dependencies

  • Node.js (ESM), TypeScript with strict enabled
  • SDK: @nktkas/hyperliquid (preferred community SDK)
  • Other libs:
    • dotenv - Environment variable management
    • zod - Config schema validation
    • winston - Logging
    • ethers - Wallet management
    • ws - WebSocket support
    • Optional: node-telegram-bot-api - Telegram notifications

Project Structure

hyperliquid-copy-bot/
├── package.json
├── tsconfig.json
├── .env.example
├── README.md
├── src/
│   ├── index.ts                 # Main entry point
│   ├── config.ts                # Configuration with zod validation
│   ├── hyperliquidClient.ts    # Hyperliquid SDK wrapper
│   ├── copyTrader.ts            # Core copy trading logic
│   ├── logger.ts                # Winston logger setup
│   ├── types.ts                 # TypeScript type definitions
│   ├── utils/
│   │   ├── risk.ts              # Risk management utilities
│   │   └── healthCheck.ts       # Health check utility
│   └── notifications/
│       └── telegram.ts          # Telegram notification service
└── logs/                        # Log files (auto-created)

Setup & Installation

Prerequisites

  • Node.js 18+ (ESM support)
  • npm or yarn
  • Hyperliquid account (testnet or mainnet)

Installation Steps

  1. Clone the repository

    git clone <repository-url>
cd hyperliquid-copy-bot

  2. Install dependencies

    npm install

  3. Configure environment variables

    cp .env.example .env

    Edit .env and fill in your values:

    PRIVATE_KEY=0xYourPrivateKeyHere
TARGET_WALLET=0xTargetWalletAddressHere
TESTNET=true
SIZE_MULTIPLIER=1.0
MAX_LEVERAGE=20
DRY_RUN=true

  4. Build TypeScript (optional, can run directly with tsx)

    npm run build

  5. Start the bot

    npm start

Configuration

Required Environment Variables

Variable Description Example
PRIVATE_KEY Your wallet private key (0x prefix) 0x1234...
TARGET_WALLET Target wallet address to copy 0x5678...
TESTNET Use testnet (true/false) true

Optional Environment Variables

Variable Description Default
SIZE_MULTIPLIER Position size multiplier 1.0
MAX_LEVERAGE Maximum leverage cap 20
MAX_POSITION_SIZE_PERCENT Max position size as % of equity 50
MIN_NOTIONAL Minimum order size in USD 10
MAX_CONCURRENT_TRADES Max concurrent open positions 10
BLOCKED_ASSETS Comma-separated blocked assets ``
DRY_RUN Simulation mode (true/false) false
LOG_LEVEL Logging level (error/warn/info/debug) info
TELEGRAM_BOT_TOKEN Telegram bot token (optional) -
TELEGRAM_CHAT_ID Telegram chat ID (optional) -
HEALTH_CHECK_INTERVAL Health check interval in minutes 5

Usage

Basic Usage

  1. Testnet Testing (Recommended first)

    TESTNET=true
DRY_RUN=true

    This allows you to test the bot without risking real funds.

  2. Production Mode

    TESTNET=false
DRY_RUN=false

How It Works

  1. Initialization: Bot loads config, initializes Hyperliquid client, connects to your wallet
  2. Monitoring: Subscribes to target wallet fills via WebSocket
  3. On Fill Event:
    • Determines if it's opening, reducing, or closing a position
    • Fetches our and target wallet equity
    • Calculates position size: (ourEquity / targetEquity) * targetSize * multiplier
    • Applies risk checks (min notional, max size, blocked assets, leverage cap)
    • Executes trade (or logs in dry-run mode)
  4. Health Checks: Periodically compares our positions vs target positions
  5. Notifications: Sends Telegram notifications (if configured)

Position Sizing Example

If:

  • Target wallet equity: $10,000
  • Our wallet equity: $5,000
  • Target opens $1,000 position
  • SIZE_MULTIPLIER: 1.0

Then our position size = (5000 / 10000) * 1000 * 1.0 = $500

Risk Management

The bot includes multiple safety layers:

  1. Minimum Notional: Skips trades below $10 (Hyperliquid requirement)
  2. Maximum Position Size: Caps position at configured % of equity
  3. Leverage Cap: Limits leverage to MAX_LEVERAGE
  4. Blocked Assets: Skips copying certain coins
  5. Max Concurrent Trades: Limits number of open positions
  6. Dry-Run Mode: Test without placing real orders

Hyperliquid SDK References

SDK Compatibility Note

Options:

  1. @nktkas/hyperliquid (preferred) - Community SDK

  2. nomeida/hyperliquid (alternative) - Another community SDK

    • Check npm for availability

  3. Direct API calls - If no SDK is available, implement direct HTTP/WebSocket calls

If SDK import fails: The code includes error handling and will guide you. You may need to:

Important Hyperliquid Notes

  • No trailing zeros: Size and price must not have trailing zeros (e.g., "1.5" not "1.50")
  • GTC orders: Orders are Good Till Cancel by default
  • Minimum notional: ~$10 minimum per order
  • Leverage: Must be set per coin before placing orders

Logging & Monitoring

Log Files

  • logs/combined.log - All logs
  • logs/error.log - Error logs only

Log Levels

  • error - Errors only
  • warn - Warnings and errors
  • info - Info, warnings, and errors (default)
  • debug - Verbose logging

Key Events Logged

  • Subscription start/stop
  • Detected fill events
  • Trade opened/reduced/closed
  • Skipped trades (due to filters)
  • Errors & retries
  • Health check results

Telegram Notifications

The bot includes comprehensive Telegram notifications for real-time updates on trading activity, errors, and system status.

Features

  • Trade Notifications: Real-time alerts when trades are copied (success/failure)
  • Startup/Shutdown Alerts: Notifications when bot starts or stops
  • Error Notifications: Critical errors sent immediately with context
  • Health Check Alerts: Warnings when position drift is detected
  • Summary Reports: Optional daily/weekly trading statistics
  • Markdown Formatting: Beautiful, readable messages with formatting

Notification Types

  1. Trade Copied - Sent when a trade is executed

    • Shows target trade details (coin, side, size, price)
    • Shows our trade details (side, size, leverage, order type)
    • Success/failure status with order ID or error message

  2. Startup Notification - Sent when bot starts

    • Shows configuration summary
    • Testnet/dry-run status
    • Target wallet info

  3. Shutdown Notification - Sent when bot stops gracefully

  4. Error Notifications - Sent for critical errors

    • Error message and stack trace (in debug mode)
    • Context information

  5. Health Check Alerts - Sent when position drift detected

    • Account equity comparison
    • Position drift details
    • Warning indicators

  6. Summary Reports - Optional statistics

    • Total trades copied
    • Success rate
    • Active positions
    • PnL (if available)

Setup Telegram Notifications

  1. Create a Telegram Bot:

    • Open Telegram and search for @BotFather
    • Send /newbot command
    • Follow instructions to create your bot
    • Copy the bot token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

  2. Get Your Chat ID:

    • Start a conversation with your bot
    • Send any message to the bot
    • Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
    • Look for "chat":{"id":123456789} - that's your chat ID

  3. Configure in .env:

    TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=123456789

  4. Restart the bot - Notifications will be enabled automatically

Example Notifications

Trade Copied:

✅ Trade Copied

Target Trade:
• Coin: `BTC`
• Direction: Open Long
• Size: `0.1`
• Price: `50000`

Our Trade:
📈 Side: Long
• Size: `0.05`
• Leverage: `10x`
• Reduce Only: No
• Order Type: Market

Status: Success
• Order ID: `12345`

Time: 1/19/2026, 2:00:00 PM

Health Check Alert: ``

Account Status: • Our Equity: $5000.00 • Target Equity: $10000.00 • Our Positions: 2 • Target Positions: 2

• BTC: Our 0.05 vs Target 0.1 (Diff: 0.05)

Checked: 1/19/2026, 2:00:00 PM


### Disabling Notifications

To disable Telegram notifications, simply remove or comment out the `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` from your `.env` file.

## Health Checks

The bot periodically checks positions:

- Compares our positions vs target positions
- Detects drift (size differences)
- Logs warnings if significant drift detected
- Default interval: 5 minutes (configurable)

## Troubleshooting

### Common Issues

1. **"Failed to import Hyperliquid SDK"**
   - Run: `npm install @nktkas/hyperliquid`
   - If package doesn't exist, check alternative SDKs or use official API

2. **"Cannot connect to Hyperliquid account"**
   - Verify `PRIVATE_KEY` is correct
   - Check network connectivity
   - Ensure testnet/mainnet matches your account

3. **"WebSocket disconnected"**
   - Bot will auto-reconnect with exponential backoff
   - Check network stability
   - Verify target wallet address is correct

4. **"Trade execution failed"**
   - Check account balance
   - Verify minimum notional requirements
   - Check if asset is blocked
   - Review leverage limits

### Debug Mode

Enable debug logging:
```env
LOG_LEVEL=debug

Risks & Disclaimers

⚠️ IMPORTANT WARNINGS:

  • High Risk: Trading derivatives involves significant risk of loss
  • Leverage Risk: Leverage amplifies both gains and losses
  • Capital Loss: You may lose your entire capital
  • No Warranty: This software is provided "as is" without warranty
  • Educational Purpose: This is for educational purposes only
  • Test First: Always test on testnet before using real funds
  • Private Key Security: Never share your private key. Store securely.

Development

Building

npm run build

Development Mode

npm run dev

Code Structure

  • Modular design: Each component in separate file
  • Type safety: Full TypeScript types throughout
  • Error handling: Comprehensive try-catch blocks
  • Logging: Structured logging at all levels

Contributing

Contributions welcome! Please ensure:

  • TypeScript strict mode compliance
  • All tests pass
  • Code is well-documented
  • Follow existing code style

License

MIT License — free to use, modify, but no warranty.

Support

For issues, questions, or contributions:

  1. Check existing GitHub issues
  2. Review Hyperliquid documentation
  3. Test on testnet first
  4. Enable debug logging for troubleshooting

Getting Started with Testnet

  1. Visit https://app.hyperliquid-testnet.xyz/drip
  2. Get testnet tokens from faucet
  3. Set TESTNET=true in .env
  4. Set DRY_RUN=true for initial testing
  5. Start bot: npm start

CLI Commands

npm start          # Start the bot
npm run build      # Build TypeScript
npm run dev        # Development mode with watch

Example .env File

# Required
PRIVATE_KEY=0xYourPrivateKeyHere
TARGET_WALLET=0xTargetWalletAddressHere
TESTNET=true

# Position Sizing & Risk Management
SIZE_MULTIPLIER=1.0
MAX_LEVERAGE=20
MAX_POSITION_SIZE_PERCENT=50
MIN_NOTIONAL=10
MAX_CONCURRENT_TRADES=10

# Asset Filtering
BLOCKED_ASSETS=BTC,ETH

# Safety Features
DRY_RUN=true
LOG_LEVEL=info

# Optional: Telegram Notifications
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

# Optional: Health Check Interval (minutes)
HEALTH_CHECK_INTERVAL=5

About

Hyperliquid Copy Trading Bot

Topics

trading-strategies trading-algorithms tradingbot hyperliquid

Resources

Readme
Activity

Stars

77 stars

Watchers

1 watching

Forks

61 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages