Skip to main content

FAQ & Troubleshooting

Installation & Setup​

Q: Which Python version is required?​

Python 3.11 or higher is required. LangGraph and some dependencies use features not available in earlier versions.

python --version    # should show 3.11+

Q: Can I use pip instead of uv?​

Yes, but uv is strongly recommended for consistent dependency resolution. If using pip:

pip install -r requirements.txt    # if a requirements.txt is provided
# or
pip install -e .

Q: How do I install on Windows?​

Quant Flow is tested on Linux and macOS. Windows should work via WSL2 (Windows Subsystem for Linux). Native Windows is not officially supported.

Configuration​

Q: What format should symbols be in?​

Use simple asset symbols — not trading pair format:

# ✅ Correct
trading:
  symbols: [BTC, ETH, SOL]

# ❌ Wrong
trading:
  symbols: [BTC/USDT, ETH-PERP]

Hyperliquid uses simple asset names internally.

Q: Which LLM should I use?​

For trading decisions, use a model that:

  • Supports reliable JSON output (structured outputs)
  • Has low latency (< 5s response time recommended)
  • Is cost-effective at scale

Recommended options:

ModelProviderConfig client_typeNotes
deepseek-ai/deepseek-v3.2NVIDIA NIMlangchain_nvidiaGood balance of speed/quality
gpt-4o-miniOpenAIopenaiFast and cheap
gpt-4oOpenAIopenaiHigher quality, higher cost
gemini-1.5-flashGooglegoogleFast, generous free tier

Q: How do I switch between testnet and mainnet?​

Set HYPERLIQUID_TESTNET in .env:

HYPERLIQUID_TESTNET=true    # testnet
HYPERLIQUID_TESTNET=false   # mainnet (real funds)

Errors & Issues​

PermissionError: Permission denied: '/app/logs/...'​

The logs/ directory has incorrect permissions. Run:

bash init-deployment.sh

This script creates and sets permissions on logs/, data/, and backtest_results/.

Cannot increase position when open interest is at cap​

The asset has reached Hyperliquid's open interest limit. Solutions:

  1. Switch to a different trading pair
  2. Wait for OI to decrease naturally
  3. Trade smaller size (may still fail if cap is per-user)

Leverage exceeds maximum allowed​

Different assets have different maximum leverage on Hyperliquid. For example, some altcoins may have a max of 5× while BTC/ETH support 50×.

Fix: Reduce max_leverage in config.yaml:

trading:
  max_leverage: 5    # lower this value

API wallet can query balance but cannot place orders​

Your API wallet needs to be authorized on the main Hyperliquid interface:

  1. Open app.hyperliquid.xyz
  2. Connect your main wallet (not the API wallet)
  3. Go to Settings → API Wallets
  4. Add your API wallet address and authorize it

ModuleNotFoundError: No module named 'langchain_...'​

Dependencies are not installed. Run:

uv sync

LLM returns invalid JSON​

The LLM occasionally returns malformed JSON for the ExecutionPlan. The ExecutionAgent handles this with retries. If it persists:

  • Lower temperature to 0.1
  • Use a model with better structured output support (GPT-4o, DeepSeek V3)
  • Check if your model supports function calling / JSON mode

Trading Behavior​

Q: Why is the bot holding (not trading)?​

Common reasons:

  1. Validation blocked the trade — check logs for BLOCK decisions from DecisionValidator
  2. Account protection triggered — check if daily loss or drawdown limit was hit
  3. Confidence too low — the LLM returned a confidence below the threshold for the current regime
  4. Market state — decision_validator avoids certain market states (e.g., UNCERTAIN)

Check the logs:

tail -f logs/main.log | grep -i "block\|hold\|skip\|protection"

Q: Can I run multiple symbols simultaneously?​

Yes. List all symbols in trading.symbols:

trading:
  symbols: [BTC, ETH, SOL]

Each symbol runs with an independent agent and context. They share the same LLM client but have separate conversation histories and experience databases.

Q: How does the bot handle internet outages?​

If the Hyperliquid API is unreachable:

  • The current decision cycle fails and is retried on the next scheduler tick
  • Existing open positions remain open (the bot cannot cancel or close them while offline)
  • Market monitor stops alerting (no price data)
warning

Ensure your hosting environment has reliable internet. Consider using a VPS in a data center rather than a home network.

Q: Can I run both perpetual agent and grid simultaneously?​

Yes, use Docker with RUN_MODE=all:

# docker-compose.yml
environment:
  - RUN_MODE=all

Both strategies run under supervisord and log to separate files (logs/main.log, logs/grid.log).

Risk & Safety​

Q: Is there a maximum loss protection?​

Yes — account_protection:

account_protection:
  enabled: true
  max_drawdown_pct: 0.10    # stop trading if account drops 10% from peak
  max_daily_loss_pct: 0.05  # stop trading if daily loss hits 5%
  max_position_hours: 48    # force-close any position held > 48 hours
warning

Never disable account_protection without understanding the consequences. A runaway LLM or API error could otherwise accumulate unlimited losses.

Q: What happens if the stop-loss order fails?​

HyperliquidClient has a critical fallback:

If placing a stop-loss fails after an order is already open, the system immediately attempts to close the position via market order — up to 3 retries.

This prevents running an open position with no downside protection.

Q: Should I use testnet before mainnet?​

Yes, always. Set HYPERLIQUID_TESTNET=true and run for at least 24–48 hours to verify:

  • Correct order placement
  • Stop-loss and take-profit behavior
  • Account protection triggers
  • Log output is sensible

Only switch to mainnet (HYPERLIQUID_TESTNET=false) after successful testnet validation.

Getting Help​