⚠️ PRE-ALPHA SOFTWARE - USE AT YOUR OWN RISK⚠️ This is PRE-ALPHA software provided as a reference implementation only. By using this software, you acknowledge:
- Risk of COMPLETE LOSS of funds - CrowdCent makes NO WARRANTIES and assumes NO LIABILITY
- Software is provided "AS IS" without any guarantees
- You must comply with all Hyperliquid terms of service
- We do NOT endorse any vaults, strategies, or implementations using this tool
cc-liquid is a simple metamodel-based rebalancer for Hyperliquid that:
- Downloads metamodel predictions from CrowdCent or Numerai
- Identifies top long and bottom short opportunities
- Rebalances your Hyperliquid portfolio based on predictions
- Manages position sizing and risk automatically based on portfolio configurations
Read the docs: documentation
# Install globally
uv tool install cc-liquid
# With Numerai support
uv tool install cc-liquid[numerai]
# Or run without installing
uvx cc-liquid --help
# Optional: Enable shell completion
cc-liquid completion installcc-liquid init # Interactive setup wizard (recommended for new users)The wizard guides you through:
- Choosing testnet (recommended) or mainnet
- Selecting data source (CrowdCent/Numerai/local)
- Entering API keys securely
- Setting portfolio parameters
- Auto-configuring for safety
# API Keys
CROWDCENT_API_KEY=...
# Signer private keys (owner key or approved agent wallet keys)
HYPERLIQUID_PRIVATE_KEY=0x...
HYPER_AGENT_KEY_PERSONAL=0x...
HYPER_AGENT_KEY_VAULT=0x...Get your keys from:
- CrowdCent:
https://crowdcent.com/profile - Hyperliquid:
https://app.hyperliquid.xyz/API
profiles:
default:
owner: 0xYourMain # Main owner address (never the API/Agent wallet)
vault: null # null for personal, or vault address
signer_env: HYPERLIQUID_PRIVATE_KEY # ENV var name (not the key itself)
my-vault:
owner: 0xYourMain # optional, informational
vault: 0xVaultAddress
signer_env: HYPER_AGENT_KEY_VAULT
active_profile: default
data:
source: crowdcent # crowdcent, numerai, or local
path: predictions.parquet
portfolio:
num_long: 10
num_short: 10
target_leverage: 1.0 # 1.0 = no leverage, 2.0 = 2x, etc.
stop_loss:
sides: none # "none", "both", "long_only", "short_only"
pct: 0.17 # 17% from entry price
slippage: 0.05 # 5% slippage tolerance
rebalancing:
every_n_days: 10
at_time: "18:15"
execution:
slippage_tolerance: 0.005 # Market orders: aggressive pricing (default)
limit_price_offset: 0.0 # Limit orders: passive offset (0.0 = exact mid)
min_trade_value: 10.0
order_type: market # "market" or "limit"
time_in_force: Ioc # "Ioc", "Gtc", or "Alo"Profile Management:
cc-liquid profile list
cc-liquid profile show
cc-liquid profile use <name>Agent Wallets (Recommended for automation):
- Use separate agent keys per bot for nonce isolation
- Approve agent in Hyperliquid UI, then add private key to
.env - Never use agent address for Info queries (use owner/vault)
# Account info
cc-liquid account
# Download predictions
cc-liquid download-crowdcent -o predictions.parquet
cc-liquid download-numerai -o predictions.parquet
# Rebalance portfolio
cc-liquid rebalance
# View open orders
cc-liquid orders
# Cancel open orders
cc-liquid cancel-orders # Cancel all
cc-liquid cancel-orders --coin BTC # Cancel specific coin
# Apply stop losses to positions
cc-liquid apply-stops # Apply to configured sides
cc-liquid apply-stops --set portfolio.stop_loss.sides=both # Override
# View trade history
cc-liquid history --days 7 # Last 7 days
cc-liquid history --start 2025-01-01 # Date range
# Continuous rebalancing (WARNING: auto-executes)
cc-liquid run --skip-confirmUse --set to override any config value at runtime:
# Data source (auto-applies column mappings)
--set data.source=numerai # → date, symbol, meta_model columns
--set data.source=crowdcent # → release_date, id columns
--set data.path=custom.parquet
# Portfolio
--set portfolio.num_long=15
--set portfolio.num_short=8
--set portfolio.target_leverage=2.0
# Stop Loss
--set portfolio.stop_loss.sides=both # Enable on both sides
--set portfolio.stop_loss.pct=0.15 # 15% from entry
--set portfolio.stop_loss.slippage=0.05 # 5% slippage tolerance
# Execution
--set execution.slippage_tolerance=0.01 # Market order aggressiveness
--set execution.limit_price_offset=0.003 # Limit order passive offset (0 = mid)
--set execution.order_type=limit # market or limit
--set execution.time_in_force=Gtc # Ioc, Gtc, or Alo
# Environment
--set is_testnet=trueExample combinations:
cc-liquid rebalance --set data.source=numerai --set portfolio.num_long=20 --set portfolio.target_leverage=2.0Order Types:
market- Usesslippage_toleranceto price away from mid for aggressive fills (default: 0.005)limit- Useslimit_price_offsetto price at or inside mid for passive maker orders (default: 0.0 = exact mid)
Pricing Behavior:
slippage_tolerance: Market orders - buy ABOVE mid, sell BELOW mid (worse price, guaranteed fill)limit_price_offset: Limit orders - buy BELOW mid, sell ABOVE mid (better price, may not fill)- 0.0 = exact mid (default, current behavior)
- 0.002 = 0.2% inside mid (passive maker)
- 0.005 = 0.5% inside mid (more aggressive passive)
Time-in-Force (TIF):
Ioc(Immediate or Cancel) - Fills what it can immediately, cancels rest. No orders stay on book. (default)Gtc(Good til Canceled) - Orders stay on book until filled or manually canceledAlo(Add Liquidity Only) - Only posts to book, never takes liquidity
Order Status:
- Filled - Order executed immediately ✅
- Resting - Order posted to book and waiting (Gtc/Alo only) ✅
- Failed - Order rejected or not filled ❌
# Use limit orders at exact mid (default)
cc-liquid rebalance --set execution.order_type=limit --set execution.time_in_force=Gtc
# Use limit orders with passive offset (inside mid)
cc-liquid rebalance --set execution.order_type=limit --set execution.time_in_force=Gtc --set execution.limit_price_offset=0.002
# Note: limit orders with Ioc (default TIF) may not fill if priced at or inside mid
# Recommended to use Gtc or Alo with limit orders
# Check what's on the book
cc-liquid orders
# Cancel orders before rebalancing
cc-liquid rebalance --cancel-open-ordersManaging Open Orders with Gtc:
When using Gtc, unfilled orders stay on the book and may conflict with rebalancing:
# Option 1: Auto-cancel before rebalancing
cc-liquid rebalance --cancel-open-orders
# Option 2: Manual management
cc-liquid orders # Check open orders
cc-liquid cancel-orders # Cancel all
cc-liquid rebalance # Will prompt if orders found
# Option 3: Cancel specific coins
cc-liquid cancel-orders --coin BTCBatch Execution:
- All orders are submitted in a single batch for efficiency
- Reduces network latency and improves throughput
- Better execution coordination across multiple trades
- Download Metamodel: Fetches consolidated predictions from CrowdCent or Numerai
- Select Assets: Identifies top N longs and bottom N shorts based on 10-day predictions
- Calculate Positions: Determines target sizes based on account value and leverage
- Generate Trades: Calculates required trades from current to target positions
- Execute Orders: Submits orders in batch with configured order type and time-in-force
- Properly handles size precision (szDecimals) and price precision (tick size)
- Distinguishes between filled orders and resting orders (for Gtc/Alo)
cc-liquid includes backtesting and optimization tools to test strategies on historical data:
cc-liquid analyze # Run backtest with current config
cc-liquid optimize # Find optimal parameters via grid search
⚠️ BACKTESTING DISCLAIMER⚠️ Past performance does not predict future results. Backtesting has inherent limitations:
- Results are hypothetical and may not reflect real trading conditions
- Optimized parameters are prone to overfitting
- Market conditions, liquidity, and execution costs change over time
- Always validate with out-of-sample data and paper trading before live deployment
See full documentation for details.
- Neutralize to known risk factors
- Unequal-weight position sizing
- Advanced portfolio optimization
MIT License - See LICENSE file for details