A Python package for monitoring trades and orders on Hyperliquid DEX in real-time. This package allows you to track specific addresses and receive notifications when trades are executed or orders are placed/cancelled.
- Real-time monitoring of trades and orders
- Support for multiple addresses
- Optional SQLite database storage
- Callback system for custom notifications
- Clean shutdown handling
- Proper trade type definitions using dataclasses
poetry add hyperliquid-monitorpip install hyperliquid-monitorHere's a basic example that monitors an address and prints trades to the console:
from hyperliquid_monitor import HyperliquidMonitor
from hyperliquid_monitor.types import Trade
from datetime import datetime
def print_trade(trade: Trade):
"""Print trade information to console with colors"""
timestamp = trade.timestamp.strftime('%Y-%m-%d %H:%M:%S')
# Color codes
GREEN = '\033[92m'
RED = '\033[91m'
BLUE = '\033[94m'
RESET = '\033[0m'
# Choose color based on trade type and side
color = GREEN if trade.side == "BUY" else RED
print(f"\n{BLUE}[{timestamp}]{RESET} New {trade.trade_type}:")
print(f"Address: {trade.address}")
print(f"Coin: {trade.coin}")
print(f"{color}Side: {trade.side}{RESET}")
print(f"Size: {trade.size}")
print(f"Price: {trade.price}")
if trade.trade_type == "FILL":
print(f"Direction: {trade.direction}")
if trade.closed_pnl:
pnl_color = GREEN if trade.closed_pnl > 0 else RED
print(f"PnL: {pnl_color}{trade.closed_pnl:.2f}{RESET}")
print(f"Hash: {trade.tx_hash}")
def main():
# List of addresses to monitor
addresses = [
"0x010461C14e146ac35Fe42271BDC1134EE31C703a" # Example address
]
# Create monitor with console notifications and optional database
monitor = HyperliquidMonitor(
addresses=addresses,
db_path="trades.db", # Optional: remove to disable database
callback=print_trade
)
try:
print("Starting monitor... Press Ctrl+C to exit")
monitor.start()
except KeyboardInterrupt:
monitor.stop()
if __name__ == "__main__":
main()The Trade object contains the following information:
@dataclass
class Trade:
timestamp: datetime # When the trade occurred
address: str # The address that made the trade
coin: str # The traded coin/token
side: Literal["BUY", "SELL"] # Trade side
size: float # Trade size
price: float # Trade price
trade_type: Literal["FILL", "ORDER_PLACED", "ORDER_CANCELLED"]
direction: Optional[str] = None # e.g., "Open Long", "Close Short"
tx_hash: Optional[str] = None # Transaction hash for fills
fee: Optional[float] = None # Trading fee
fee_token: Optional[str] = None # Fee token (e.g., "USDC")
start_position: Optional[float] = None # Position size before trade
closed_pnl: Optional[float] = None # Realized PnL for closing trades
order_id: Optional[int] = None # Order ID for ordersIf you provide a db_path, trades will be stored in an SQLite database with two tables:
- timestamp: When the trade occurred
- address: Trader's address
- coin: Traded asset
- side: BUY/SELL
- size: Trade size
- price: Trade price
- direction: Trade direction
- tx_hash: Transaction hash
- fee: Trading fee
- fee_token: Fee token
- start_position: Position before trade
- closed_pnl: Realized PnL
- timestamp: When the order was placed/cancelled
- address: Trader's address
- coin: Asset
- action: placed/cancelled
- side: BUY/SELL
- size: Order size
- price: Order price
- order_id: Unique order ID
The monitor supports different modes of operation for recording trades:
# Records to database and sends notifications via callback
monitor = HyperliquidMonitor(
addresses=addresses,
db_path="trades.db",
callback=print_trade
)# Only records to database, no notifications
monitor = HyperliquidMonitor(
addresses=addresses,
db_path="trades.db",
silent=True # Suppresses all notifications and console output
)# Only sends notifications, no database recording
monitor = HyperliquidMonitor(
addresses=addresses,
callback=print_trade
)The silent mode is particularly useful for:
- Background monitoring and data collection
- Reducing system resource usage
- Running multiple monitors concurrently
- Long-term trade data accumulation
- Server-side deployments where notifications aren't needed
Note: Silent mode requires a database path to be specified since it's meant for data recording.
- Clone the repository:
git clone https://github.com/your-username/hyperliquid-monitor.git
cd hyperliquid-monitor- Install poetry if you haven't already:
curl -sSL https://install.python-poetry.org | python3 -- Install dependencies:
poetry installThe package includes a comprehensive test suite using pytest. To run the tests:
# Run all tests
poetry run pytest
# Run with coverage report
poetry run pytest --cov
# Run specific test file
poetry run pytest tests/test_monitor.py
# Run tests with output
poetry run pytest -vTests are organized in the following structure:
tests/
├── __init__.py
├── conftest.py # Shared fixtures
├── test_monitor.py # Monitor tests
├── test_database.py # Database tests
└── test_types.py # Type validation tests
Key test areas:
- Monitor functionality (subscriptions, event handling)
- Database operations (storage, retrieval)
- Type validation (trade object validation)
- Event processing (fills, orders)
Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:
- Add tests for any new functionality
- Update documentation as needed
- Follow the existing code style
- Run the test suite before submitting
This project is licensed under the MIT License - see the LICENSE file for details.
Built on top of the official Hyperliquid Python SDK