nautilus-trader

# Nautilus Trader Skill Comprehensive assistance with NautilusTrader development. Includes complete Hyperliquid mainnet integration with SDK patch for live trading. --- ## Overview This skill covers: - Strategy development with NautilusTrader - Backtesting using the Parquet data catalog - Live trading deployment on Hyperliquid mainnet - SDK patch for Hyperliquid price precision requirements ### When to Use - Building trading strategies with NautilusTrader - Running backtests with historical data - Deploying strategies to Hyperliquid mainnet - Debugging NautilusTrader adapter issues - Working with multi-timeframe (MTF) indicators --- ## Prerequisites ### Core Dependencies ```bash # NautilusTrader (backtesting + live trading framework) pip install nautilus_trader # Hyperliquid SDK (for live trading patch) pip install hyperliquid-python-sdk eth-account python-dotenv # Data handling pip install pandas numpy ``` ### Verify Installation ```python import nautilus_trader print(f"Nautilus Trader: {nautilus_trader.__version__}") # Tested with v1.222.0 ``` ### Environment Variables Create a `.env` file for Hyperliquid credentials: ```bash HYPERLIQUID_PK=your_private_key_without_0x_prefix HYPERLIQUID_VAULT=0xYourVaultAddressHere ``` --- ## Quick Start ### 1. Apply the Hyperliquid Patch (for live trading) ```python # CRITICAL: Import patch BEFORE Nautilus Trader import hyperliquid_patch # Then import Nautilus normally from nautilus_trader.adapters.hyperliquid import HYPERLIQUID from nautilus_trader.live.node import TradingNode ``` ### 2. Basic Strategy Template ```python from nautilus_trader.trading.strategy import Strategy from nautilus_trader.config import StrategyConfig from nautilus_trader.model.data import Bar, BarType from nautilus_trader.model.enums import OrderSide, TimeInForce from nautilus_trader.model.identifiers import InstrumentId from decimal import Decimal class MyStrategyConfig(StrategyConfig): instrument_id: str bar_type: str trade_size: Decimal = Decimal("0.1") class MyStrategy(Strategy): def __init__(self, config: MyStrategyConfig): super().__init__(config) self.instrument_id = InstrumentId.from_str(config.instrument_id) self.bar_type = BarType.from_str(config.bar_type) self.trade_size = config.trade_size def on_start(self): self.instrument = self.cache.instrument(self.instrument_id) self.subscribe_bars(self.bar_type) def on_bar(self, bar: Bar): # Your strategy logic here pass def on_stop(self): self.close_all_positions(self.instrument_id) ``` --- ## Strategy Development ### Heiken Ashi Indicator ```python from nautilus_trader.indicators.base.indicator import Indicator from nautilus_trader.model.data import Bar class HeikenAshi(Indicator): """Heiken Ashi candle smoothing indicator.""" def __init__(self): super().__init__([]) self.ha_open = 0.0 self.ha_close = 0.0 self.ha_high = 0.0 self.ha_low = 0.0 self._prev_ha_open = None self._prev_ha_close = None self.initialized = False def handle_bar(self, bar: Bar) -> None: o, h, l, c = float(bar.open), float(bar.high), float(bar.low), float(bar.close) self.ha_close = (o + h + l + c) / 4 if self._prev_ha_open is None: self.ha_open = (o + c) / 2 else: self.ha_open = (self._prev_ha_open + self._prev_ha_close) / 2 self.ha_high = max(h, self.ha_open, self.ha_close) self.ha_low = min(l, self.ha_open, self.ha_close) self._prev_ha_open = self.ha_open self._prev_ha_close = self.ha_close self.initialized = True @property def is_bullish(self) -> bool: return self.ha_close > self.ha_open @property def is_bearish(self) -> bool: return self.ha_close < self.ha_open def reset(self) -> None: self._prev_ha_open = None self._prev_ha_close = None self.initialized = False ``` ### Multi-Timeframe EMA Strategy See `references/hyperliquid.md` for complete MTF EMA + Heiken Ashi strategy implementation. Key concepts: - HTF (Higher Timeframe): Determines trend direction via EMA crossover - LTF (Lower Timeframe): Entry timing via Heiken Ashi confirmation - Entry: HA color change in trend direction - Exit: HA color reversal --- ## Backtesting ### Engine Setup ```python from nautilus_trader.backtest.engine import BacktestEngine, BacktestEngineConfig from nautilus_trader.model.currencies import USD from nautilus_trader.model.enums import AccountType, OmsType from nautilus_trader.model.identifiers import Venue from nautilus_trader.model.objects import Money from nautilus_trader.persistence.catalog import ParquetDataCatalog from decimal import Decimal def run_backtest(): config = BacktestEngineConfig( trader_id="BACKTESTER-001", logging_level="INFO", ) engine = BacktestEngine(config=config) # Add venue engine.add_venue( venue=Venue("HYPERLIQUID"), oms_type=OmsType.NETTING, account_type=AccountType.MARGIN, base_currency=USD, starting_balances=[Money(100_000, USD)], ) # Load data from catalog catalog = ParquetDataCatalog("./data_catalog") instruments = catalog.instruments() for instrument in instruments: engine.add_instrument(instrument) bars = catalog.bars() engine.add_data(bars) # Add strategy strategy = MyStrategy(config=MyStrategyConfig( instrument_id="SOL-USD.HYPERLIQUID", bar_type="SOL-USD.HYPERLIQUID-5-MINUTE-LAST-EXTERNAL", trade_size=Decimal("1.0"), )) engine.add_strategy(strategy) # Run engine.run() # Results print(engine.trader.generate_account_report(Venue("HYPERLIQUID"))) print(engine.trader.generate_order_fills_report()) print(engine.trader.generate_positions_report()) engine.dispose() ``` ### Data Catalog See `references/backtesting.md` and `references/data.md` for detailed catalog operations: - `ParquetDataCatalog` - Query and manage Parquet data files - `BarDataWrangler` - Convert pandas DataFrames to Nautilus Bar objects - `write_data()` - Persist data to catalog - `query()` - Retrieve data with time filters --- ## Live Trading on Hyperliquid ### Node Configuration ```python import os from dotenv import load_dotenv load_dotenv() # CRITICAL: Apply patch BEFORE Nautilus imports import hyperliquid_patch from nautilus_trader.adapters.hyperliquid import ( HYPERLIQUID, HyperliquidDataClientConfig, HyperliquidExecClientConfig, ) from nautilus_trader.live.node import TradingNode, TradingNodeConfig from nautilus_trader.config import LiveDataEngineConfig, LiveExecEngineConfig def main(): node_config = TradingNodeConfig( trader_id="LIVE-001", data_engine=LiveDataEngineConfig(), exec_engine=LiveExecEngineConfig(), ) node = TradingNode(config=node_config) data_config = HyperliquidDataClientConfig( wallet_address=os.getenv("HYPERLIQUID_VAULT"), is_testnet=False, ) exec_config = HyperliquidExecClientConfig( wallet_address=os.getenv("HYPERLIQUID_VAULT"), private_key=os.getenv("HYPERLIQUID_PK"), is_testnet=False, ) node.build() # Add your strategy strategy = MyStrategy(config=my_config) node.trader.add_strategy(strategy) node.run() if __name__ == "__main__": main() ``` ### Set Leverage (One-Time Setup) ```python from hyperliquid.exchange import Exchange from hyperliquid.utils import constants from eth_account import Account import os private_key = os.getenv("HYPERLIQUID_PK") if not private_key.startswith("0x"): private_key = "0x" + private_key account = Account.from_key(private_key) exchange = Exchange(account, constants.MAINNET_API_URL) # Set 10x leverage for SOL (cross margin) exchange.update_leverage(10, "SOL", is_cross=True) ``` ### Network Latency For best performance, deploy on AWS ap-northeast-1 (Tokyo): - Ping to Hyperliquid CloudFront: ~1ms - API latency: ~28ms --- ## Hyperliquid SDK Patch ### The Problem Nautilus Trader v1.222.0 has bugs in the Hyperliquid adapter: 1. Rust HTTP client serialization causes type mismatches 2. Price precision exceeds Hyperliquid's 5 significant figure limit ### The Solution Bypass the buggy adapter using the official Hyperliquid Python SDK. The patch file is located at `references/hyperliquid_patch.py`. ### Price Precision Rules Hyperliquid requires maximum 5 significant figures for all prices: | Price | Valid? | Sig Figs | |-----------|--------|----------| | $139.05 | Yes | 5 | | $139.054 | No | 6 | | $1.2345 | Yes | 5 | | $1.23456 | No | 6 | | $12345 | Yes | 5 | | $123456 | No | 6 | ### Usage ```python # CRITICAL: Import patch BEFORE any Nautilus imports import hyperliquid_patch # Then import Nautilus normally from nautilus_trader.adapters.hyperliquid import HYPERLIQUID ``` The patch auto-applies on import and handles: - Price formatting to 5 significant figures - Rounding up for buys, down for sells (ensures fills) - SDK-based order submission bypassing Rust client ### Verified Working Tested on Hyperliquid Mainnet 2025-01-12: ``` SELL 0.72 SOL @ $143.38 - FILLED BUY 0.71 SOL @ $143.39 - FILLED ``` --- ## Configuration ### File Structure ``` your_trading_project/ ├── .env # Credentials (gitignored) ├── hyperliquid_patch.py # SDK patch for live trading ├── heiken_ashi.py # Heiken Ashi indicator ├── my_strategy.py # Strategy implementation ├── backtest.py # Backtest runner ├── live.py # Live trading runner └── data_catalog/ # Parquet data for backtesting ``` ### Bar Type Format ``` {symbol}.{venue}-{step}-{aggregation}-{price_type}-{source} Examples: SOL-USD.HYPERLIQUID-1-HOUR-LAST-EXTERNAL SOL-USD.HYPERLIQUID-5-MINUTE-LAST-EXTERNAL BTC-USD.HYPERLIQUID-15-MINUTE-LAST-EXTERNAL ``` --- ## Troubleshooting ### Order Rejected: Invalid Price Ensure prices have max 5 significant figures. Use the `format_price_5_sigfigs()` function from the patch. ### Connection Error 1. Check `.env` has correct `HYPERLIQUID_PK` and `HYPERLIQUID_VAULT` 2. Verify private key format (with or without `0x` prefix) 3. Confirm vault address is correct ### Patch Not Applied Ensure `import hyperliquid_patch` comes BEFORE any Nautilus imports. ### Missing Data in Backtest 1. Verify data catalog path exists 2. Check instrument IDs match between data and strategy config 3. Ensure bar types are correctly formatted ### Position Not Closing Check that `reduce_only=True` is set on exit orders for netting accounts. --- ## Reference Files Detailed documentation is available in `references/`: | File | Description | |------|-------------| | `hyperliquid.md` | Complete Hyperliquid integration guide | | `hyperliquid_patch.py` | SDK patch source code | | `strategies.md` | Strategy patterns and examples | | `backtesting.md` | Data catalog and backtest API | | `data.md` | Data handling and wrangling | | `getting_started.md` | NautilusTrader fundamentals | | `concepts.md` | Core concepts and architecture | | `api.md` | Full API reference | Use `view` to read specific reference files when detailed information is needed.