Skip to content

Walkthrough

This walkthrough explains the core flow and safe first steps.

1) Install and configure

Follow the installation guide to install and create .env and cc-liquid-config.yaml.

uv tool install cc-liquid
cc-liquit init

Tip: enable tab autocompletion for a smoother CLI experience

cc-liquid completion install

2) Confirm profile/config/data

cc-liquid config
See configuration for defaults and overrides: Configuration → Data

Set your data source in cc-liquid-config.yaml or via --set data.source=[crowdcent|numerai]:

  • crowdcent: latest consolidated metamodel from CrowdCent
  • numerai: Numerai Crypto metamodel
  • local: your own parquet/csv file

3) Inspect account and positions

cc-liquid account

This shows your current portfolio state:

account

Warning

Errors on this step are most often due to incrorrectly configured/loaded private keys. You may need to ensure your .env is loaded by running: 

export $(grep -v '^#' .env | xargs)

This command reads your .env file, filters out comments, and exports the variables. You'll need to run it in each new terminal session.

4) Plan and execute rebalancing

cc-liquid rebalance

The CLI will display a detailed plan showing:

  • Current vs target positions
  • Required trades to rebalance
  • Portfolio metrics and leverage

rebalance plan

After reviewing the plan, you'll be prompted to confirm execution. To skip the confirmation prompt:

cc-liquid rebalance --skip-confirm

You can adjust parameters on the fly:

cc-liquid rebalance --set portfolio.num_long=12 --set portfolio.num_short=8 --set portfolio.target_leverage=2.0

How rebalancing works

  1. Load predictions

    • Downloads latest metamodel from CrowdCent/Numerai (or loads local file)
    • Keeps most recent prediction per asset

  2. Select assets

    • Top num_long assets for long positions (highest predictions)
    • Bottom num_short assets for short positions (lowest predictions)
    • Filters to only assets tradeable on Hyperliquid

  3. Size positions

    • Equal-weight: (account_value × target_leverage) / total_positions
    • Warns if position sizes fall below min_trade_value

  4. Generate trades

    • Calculates delta between current and target positions
    • Rounds sizes to exchange precision (sz_decimals)
    • Marks trades below minimum as "skipped"

  5. Execute orders

    • Places market orders with configured slippage_tolerance
    • Reports fills, failures, and actual slippage

After execution completes:

execution summary

Flatten (close all positions)

cc-liquid close-all

In the event you want to return your entire portfolio/vault to cash, close-all plans and executes trades to close all trades to 0 notional value. Add --skip-confirm to skip confirmation messages.

5) Continuous mode (autopilot)

Schedules execution at portfolio.rebalancing.at_time every every_n_days. See Autopilot & Scheduling for details.

cc-liquid run --skip-confirm   # executes automatically on schedule

Dashboard/monitor view:

dashboard

Safety notes

  • Leverage increases liquidation risk; start with 1.0x
  • Ensure execution.min_trade_value and slippage are appropriate
  • Use Hyperliquid testnet first (--set is_testnet=true)