Hyperliquid Cross-Exchange Arbitrage Bot (TypeScript)

A TypeScript-based cross-exchange arbitrage monitoring bot for perpetual futures.
It tracks real-time spreads between Hyperliquid and centralized exchanges (including Bybit, with extensible connectors for Binance and OKX), then surfaces actionable opportunities through configurable alerts and analytics.

SEO Keywords

hyperliquid arbitrage bot, hyperliquid trading bot, crypto arbitrage typescript, hyperliquid bybit arbitrage, cross exchange arbitrage, perpetual futures arbitrage, funding rate arbitrage, typescript trading bot, hyperliquid websocket bot, defi cefi arbitrage

Features

• Real-time spread monitoring across perpetual exchanges
• Funding-aware opportunity scoring (optional)
• Configurable spread thresholds, cooldowns, and filters
• Alert pipeline ready for social/webhook integrations
• Structured logging and type-safe configuration
• TypeScript-first architecture for maintainability and safety

Bot Overview

What this bot does

This project is a real-time arbitrage detection and monitoring system, not a guaranteed profit engine.
It continuously compares bid/ask prices across exchanges and flags potential long/short opportunities when spread and risk filters pass.

How arbitrage is detected

1. Ingest market data
   Subscribe to exchange streams and normalize symbols/order book snapshots.
2. Compute spread

   Spread % = ((BestSell - BestBuy) / BestBuy) * 100
   

3. Apply filters
   Fees, slippage, liquidity checks, and optional funding adjustments.
4. Publish signal
   Emit ranked opportunities and send alerts when thresholds are met.

Typical directional logic

• If Price_Hyperliquid > Price_Bybit: buy on Bybit, sell on Hyperliquid
• If Price_Bybit > Price_Hyperliquid: buy on Hyperliquid, sell on Bybit

Note: Real execution quality depends on latency, fees, funding windows, depth, and exchange constraints.

Supported Exchanges

Exchange	Market Type
Hyperliquid	Perpetual DEX
Bybit	USDT Perpetual Futures
Binance*	USDT-M Perpetual Futures
OKX*	Perpetual Swaps

* Optional/extendable based on connector configuration.

Installation

1) Clone repository

git clone https://github.com/xatxay/arbitrage
cd arbitrage

2) Install dependencies

npm install

3) Configure environment

Create .env from your template and add exchange credentials:

# Hyperliquid
HYPERLIQUID_WS_URL=wss://api.hyperliquid.xyz/ws
HYPERLIQUID_WALLET_ADDRESS=0x...
HYPERLIQUID_PRIVATE_KEY=0x...

# Bybit
BYBIT_INSTRUMENT_API_URL=https://api.bybit.com/v5/market/instruments-info?category=linear
BYBIT_WS_URL=wss://stream.bybit.com/v5/public/linear
BYBIT_API_KEY=
BYBIT_API_SECRET=

# Arbitrage settings
SPREAD_THRESHOLD_PERCENT=5
RESET_TWEETED_SYMBOLS_EVERY_MINUTES=60

# Optional: Twitter alerting
TWITTER_ENABLED=false
CONSUMER_KEY=
CONSUMER_SECRET=
ACCESS_TOKEN=
TOKEN_SECRET=

Environment Variables Reference

Variable	Required	Description	Example
HYPERLIQUID_WS_URL	Yes	Hyperliquid public websocket endpoint used for allMids market stream.	wss://api.hyperliquid.xyz/ws
HYPERLIQUID_WALLET_ADDRESS	Recommended	Wallet address for Hyperliquid account operations. Required for signed trading/execution flows.	0xabc123...
HYPERLIQUID_PRIVATE_KEY	Recommended	Private key paired with the wallet address. Keep secret and never commit it.	0xdeadbeef...
BYBIT_INSTRUMENT_API_URL	Yes	Bybit REST endpoint to fetch tradable linear symbols.	https://api.bybit.com/v5/market/instruments-info?category=linear
BYBIT_WS_URL	Yes	Bybit public websocket endpoint for real-time kline stream.	wss://stream.bybit.com/v5/public/linear
BYBIT_API_KEY	Optional	Bybit API key for authenticated endpoints (not required for current public-price monitor).	your_key
BYBIT_API_SECRET	Optional	Secret paired with BYBIT_API_KEY.	your_secret
SPREAD_THRESHOLD_PERCENT	Yes	Minimum spread percentage needed before an opportunity alert is emitted.	5
RESET_TWEETED_SYMBOLS_EVERY_MINUTES	Yes	Cooldown window for clearing duplicate-alert symbol cache.	60
TWITTER_ENABLED	Optional	Enable/disable Twitter posting. If false, alerts are logged to console only.	false
CONSUMER_KEY	Required if TWITTER_ENABLED=true	Twitter/X API app key.	...
CONSUMER_SECRET	Required if TWITTER_ENABLED=true	Twitter/X API app secret.	...
ACCESS_TOKEN	Required if TWITTER_ENABLED=true	Twitter/X user access token.	...
TOKEN_SECRET	Required if TWITTER_ENABLED=true	Twitter/X user token secret.	...

Security Notes

• Never commit .env or private keys to Git.
• Use a dedicated low-privilege key for bot operations.
• Rotate keys immediately if exposed.
• For production, prefer secret managers over plain local .env files.

Usage

Run the bot in monitoring mode:

npm run dev

Common workflows:

• Start live monitor/dashboard
• Track top spread opportunities by pair
• Trigger alerts for opportunities over threshold
• Export historical spread data for analysis/backtesting

Why TypeScript

• Strong typing for safer exchange integrations
• Better maintainability for multi-exchange connectors
• Excellent ecosystem for WebSocket/data tooling
• Easier collaboration and long-term project growth

Roadmap

• Add deeper connector support for Binance/OKX
• Expand backtesting and session-based analytics
• Improve alert channels (Telegram/Discord/email)
• Add execution simulator and risk controls
• Enhance observability (metrics, tracing, health checks)

Contributing

Contributions are welcome.

git checkout -b feature/my-feature
git commit -m "feat: add my feature"
git push origin feature/my-feature

Then open a Pull Request.

Contact

For support or collaboration:

Telegram: @lorine93s