{"id":37080752,"url":"https://github.com/crowdcent/cc-liquid","last_synced_at":"2026-01-14T09:48:13.155Z","repository":{"id":309769894,"uuid":"1037472391","full_name":"crowdcent/cc-liquid","owner":"crowdcent","description":"Open source reference implementation for a simple, metamodel-based Hyperliquid portfolio rebalancer","archived":false,"fork":false,"pushed_at":"2025-12-10T16:34:34.000Z","size":2517,"stargazers_count":11,"open_issues_count":5,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-04T17:35:49.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crowdcent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-13T16:14:07.000Z","updated_at":"2025-12-10T16:34:14.000Z","dependencies_parsed_at":"2025-12-14T02:12:57.312Z","dependency_job_id":null,"html_url":"https://github.com/crowdcent/cc-liquid","commit_stats":null,"previous_names":["crowdcent/cc-liquid"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/crowdcent/cc-liquid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdcent%2Fcc-liquid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdcent%2Fcc-liquid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdcent%2Fcc-liquid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdcent%2Fcc-liquid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crowdcent","download_url":"https://codeload.github.com/crowdcent/cc-liquid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdcent%2Fcc-liquid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28416120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T09:48:12.405Z","updated_at":"2026-01-14T09:48:13.148Z","avatar_url":"https://github.com/crowdcent.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-liquid\n\n\u003e ⚠️ **PRE-ALPHA SOFTWARE - USE AT YOUR OWN RISK** ⚠️\n\u003e \n\u003e This is PRE-ALPHA software provided as a reference implementation only. By using this software, you acknowledge:\n\u003e - Risk of COMPLETE LOSS of funds - CrowdCent makes NO WARRANTIES and assumes NO LIABILITY\n\u003e - Software is provided \"AS IS\" without any guarantees\n\u003e - You must comply with all Hyperliquid terms of service\n\u003e - We do NOT endorse any vaults, strategies, or implementations using this tool\n\n## Overview\n\ncc-liquid is a simple metamodel-based rebalancer for Hyperliquid that:\n- Downloads metamodel predictions from CrowdCent or Numerai\n- Identifies top long and bottom short opportunities\n- Rebalances your Hyperliquid portfolio based on predictions\n- Manages position sizing and risk automatically based on portfolio configurations\n\nRead the docs: [documentation](https://crowdcent.github.io/cc-liquid)\n\n![dashboard](docs/images/dashboard.svg)\n\n## Installation\n\n```bash\n# Install globally\nuv tool install cc-liquid\n\n# With Numerai support\nuv tool install cc-liquid[numerai]\n\n# Or run without installing\nuvx cc-liquid --help\n\n# Optional: Enable shell completion\ncc-liquid completion install\n```\n\n## Quick Start\n\n```bash\ncc-liquid init        # Interactive setup wizard (recommended for new users)\n```\n\nThe wizard guides you through:\n- Choosing testnet (recommended) or mainnet\n- Selecting data source (CrowdCent/Numerai/local)\n- Entering API keys securely\n- Setting portfolio parameters\n- Auto-configuring for safety\n\n## Configuration\n\n### Secrets (.env only - never commit)\n\n```env\n# API Keys\nCROWDCENT_API_KEY=...\n\n# Signer private keys (owner key or approved agent wallet keys)\nHYPERLIQUID_PRIVATE_KEY=0x...\nHYPER_AGENT_KEY_PERSONAL=0x...\nHYPER_AGENT_KEY_VAULT=0x...\n```\n\nGet your keys from:\n- CrowdCent: `https://crowdcent.com/profile`\n- Hyperliquid: `https://app.hyperliquid.xyz/API`\n\n### Settings (cc-liquid-config.yaml)\n\n```yaml\nprofiles:\n  default:\n    owner: 0xYourMain           # Main owner address (never the API/Agent wallet)\n    vault: null                 # null for personal, or vault address\n    signer_env: HYPERLIQUID_PRIVATE_KEY  # ENV var name (not the key itself)\n\n  my-vault:\n    owner: 0xYourMain           # optional, informational\n    vault: 0xVaultAddress\n    signer_env: HYPER_AGENT_KEY_VAULT\n\nactive_profile: default\n\ndata:\n  source: crowdcent             # crowdcent, numerai, or local\n  path: predictions.parquet\n\nportfolio:\n  num_long: 10\n  num_short: 10\n  target_leverage: 1.0          # 1.0 = no leverage, 2.0 = 2x, etc.\n  stop_loss:\n    sides: none                 # \"none\", \"both\", \"long_only\", \"short_only\"\n    pct: 0.17                   # 17% from entry price\n    slippage: 0.05              # 5% slippage tolerance\n  rebalancing:\n    every_n_days: 10\n    at_time: \"18:15\"\n\nexecution:\n  slippage_tolerance: 0.005     # Market orders: aggressive pricing (default)\n  limit_price_offset: 0.0       # Limit orders: passive offset (0.0 = exact mid)\n  min_trade_value: 10.0\n  order_type: market            # \"market\" or \"limit\"\n  time_in_force: Ioc            # \"Ioc\", \"Gtc\", or \"Alo\"\n```\n\n**Profile Management:**\n```bash\ncc-liquid profile list\ncc-liquid profile show\ncc-liquid profile use \u003cname\u003e\n```\n\n**Agent Wallets (Recommended for automation):**\n- Use separate agent keys per bot for nonce isolation\n- Approve agent in Hyperliquid UI, then add private key to `.env`\n- Never use agent address for Info queries (use owner/vault)\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Account info\ncc-liquid account\n\n# Download predictions\ncc-liquid download-crowdcent -o predictions.parquet\ncc-liquid download-numerai -o predictions.parquet\n\n# Rebalance portfolio\ncc-liquid rebalance\n\n# View open orders\ncc-liquid orders\n\n# Cancel open orders\ncc-liquid cancel-orders                  # Cancel all\ncc-liquid cancel-orders --coin BTC       # Cancel specific coin\n\n# Apply stop losses to positions\ncc-liquid apply-stops                    # Apply to configured sides\ncc-liquid apply-stops --set portfolio.stop_loss.sides=both  # Override\n\n# View trade history\ncc-liquid history --days 7               # Last 7 days\ncc-liquid history --start 2025-01-01     # Date range\n\n# Continuous rebalancing (WARNING: auto-executes)\ncc-liquid run --skip-confirm\n```\n\n### Configuration Overrides\n\nUse `--set` to override any config value at runtime:\n\n```bash\n# Data source (auto-applies column mappings)\n--set data.source=numerai      # → date, symbol, meta_model columns\n--set data.source=crowdcent    # → release_date, id columns\n--set data.path=custom.parquet\n\n# Portfolio\n--set portfolio.num_long=15\n--set portfolio.num_short=8\n--set portfolio.target_leverage=2.0\n\n# Stop Loss\n--set portfolio.stop_loss.sides=both        # Enable on both sides\n--set portfolio.stop_loss.pct=0.15          # 15% from entry\n--set portfolio.stop_loss.slippage=0.05     # 5% slippage tolerance\n\n# Execution\n--set execution.slippage_tolerance=0.01      # Market order aggressiveness\n--set execution.limit_price_offset=0.003     # Limit order passive offset (0 = mid)\n--set execution.order_type=limit             # market or limit\n--set execution.time_in_force=Gtc            # Ioc, Gtc, or Alo\n\n# Environment\n--set is_testnet=true\n```\n\nExample combinations:\n```bash\ncc-liquid rebalance --set data.source=numerai --set portfolio.num_long=20 --set portfolio.target_leverage=2.0\n```\n\n### Order Types \u0026 Execution\n\n**Order Types:**\n- `market` - Uses `slippage_tolerance` to price away from mid for aggressive fills (default: 0.005)\n- `limit` - Uses `limit_price_offset` to price at or inside mid for passive maker orders (default: 0.0 = exact mid)\n\n**Pricing Behavior:**\n- `slippage_tolerance`: Market orders - buy ABOVE mid, sell BELOW mid (worse price, guaranteed fill)\n- `limit_price_offset`: Limit orders - buy BELOW mid, sell ABOVE mid (better price, may not fill)\n  - 0.0 = exact mid (default, current behavior)\n  - 0.002 = 0.2% inside mid (passive maker)\n  - 0.005 = 0.5% inside mid (more aggressive passive)\n\n**Time-in-Force (TIF):**\n- `Ioc` (Immediate or Cancel) - Fills what it can immediately, cancels rest. No orders stay on book. (default)\n- `Gtc` (Good til Canceled) - Orders stay on book until filled or manually canceled\n- `Alo` (Add Liquidity Only) - Only posts to book, never takes liquidity\n\n**Order Status:**\n- **Filled** - Order executed immediately ✅\n- **Resting** - Order posted to book and waiting (Gtc/Alo only) ✅\n- **Failed** - Order rejected or not filled ❌\n\n```bash\n# Use limit orders at exact mid (default)\ncc-liquid rebalance --set execution.order_type=limit --set execution.time_in_force=Gtc\n\n# Use limit orders with passive offset (inside mid)\ncc-liquid rebalance --set execution.order_type=limit --set execution.time_in_force=Gtc --set execution.limit_price_offset=0.002\n\n# Note: limit orders with Ioc (default TIF) may not fill if priced at or inside mid\n# Recommended to use Gtc or Alo with limit orders\n\n# Check what's on the book\ncc-liquid orders\n\n# Cancel orders before rebalancing\ncc-liquid rebalance --cancel-open-orders\n```\n\n**Managing Open Orders with Gtc:**\n\nWhen using `Gtc`, unfilled orders stay on the book and may conflict with rebalancing:\n\n```bash\n# Option 1: Auto-cancel before rebalancing\ncc-liquid rebalance --cancel-open-orders\n\n# Option 2: Manual management\ncc-liquid orders                    # Check open orders\ncc-liquid cancel-orders             # Cancel all\ncc-liquid rebalance                 # Will prompt if orders found\n\n# Option 3: Cancel specific coins\ncc-liquid cancel-orders --coin BTC\n```\n\n**Batch Execution:**\n- All orders are submitted in a single batch for efficiency\n- Reduces network latency and improves throughput\n- Better execution coordination across multiple trades\n\n## How It Works\n\n1. **Download Metamodel**: Fetches consolidated predictions from CrowdCent or Numerai\n2. **Select Assets**: Identifies top N longs and bottom N shorts based on 10-day predictions\n3. **Calculate Positions**: Determines target sizes based on account value and leverage\n4. **Generate Trades**: Calculates required trades from current to target positions\n5. **Execute Orders**: Submits orders in batch with configured order type and time-in-force\n   - Properly handles size precision (szDecimals) and price precision (tick size)\n   - Distinguishes between filled orders and resting orders (for Gtc/Alo)\n\n## Backtesting \u0026 Optimization\n\ncc-liquid includes backtesting and optimization tools to test strategies on historical data:\n\n```bash\ncc-liquid analyze                    # Run backtest with current config\ncc-liquid optimize                   # Find optimal parameters via grid search\n```\n\n\u003e ⚠️ **BACKTESTING DISCLAIMER** ⚠️\n\u003e \n\u003e **Past performance does not predict future results.** Backtesting has inherent limitations:\n\u003e - Results are hypothetical and may not reflect real trading conditions\n\u003e - Optimized parameters are prone to overfitting\n\u003e - Market conditions, liquidity, and execution costs change over time\n\u003e - Always validate with out-of-sample data and paper trading before live deployment\n\u003e \n\u003e See [full documentation](https://crowdcent.github.io/cc-liquid/backtesting/) for details.\n\n## Future Enhancements\n\n- Neutralize to known risk factors\n- Unequal-weight position sizing\n- Advanced portfolio optimization\n\n## License\n\nMIT License - See LICENSE file for details","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdcent%2Fcc-liquid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowdcent%2Fcc-liquid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdcent%2Fcc-liquid/lists"}