cc-liquid 0.1.8a8

cc-liquid - open source reference implementation for a simple, metamodel-based Hyperliquid portfolio rebalancer

cc-liquid

⚠️ 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

Overview

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

Installation

# 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 install

Quick Start

cc-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

Configuration

Secrets (.env only - never commit)

# 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

Settings (cc-liquid-config.yaml)

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)

Usage

Basic Commands

# 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-confirm

Configuration Overrides

Use --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=true

Example combinations:

cc-liquid rebalance --set data.source=numerai --set portfolio.num_long=20 --set portfolio.target_leverage=2.0

Order Types & Execution

Order Types:

• market - Uses slippage_tolerance to price away from mid for aggressive fills (default: 0.005)
• limit - Uses limit_price_offset to 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 canceled
• Alo (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-orders

Managing 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 BTC

Batch Execution:

• All orders are submitted in a single batch for efficiency
• Reduces network latency and improves throughput
• Better execution coordination across multiple trades

How It Works

1. Download Metamodel: Fetches consolidated predictions from CrowdCent or Numerai
2. Select Assets: Identifies top N longs and bottom N shorts based on 10-day predictions
3. Calculate Positions: Determines target sizes based on account value and leverage
4. Generate Trades: Calculates required trades from current to target positions
5. 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)

Backtesting & Optimization

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.

Future Enhancements

• Neutralize to known risk factors
• Unequal-weight position sizing
• Advanced portfolio optimization

License

MIT License - See LICENSE file for details