Skip to main content

Local Deployment

Running locally is ideal for development, backtesting, and testing configuration changes without Docker overhead.

Prerequisites​

  • Python 3.11 or higher
  • uv package manager (recommended) — or pip

Install uv​

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup​

1. Clone and Enter the Repository​

git clone https://github.com/web3spreads/quant-flow
cd quant-flow

2. Install Dependencies​

# Install all runtime dependencies
uv sync

# Install with development dependencies (for testing, linting)
uv sync --group dev

3. Configure Environment​

cp .env.example .env

Edit .env:

# LLM API Keys (use at least one)
OPENAI_API_KEY=sk-...
CLOUDFLARE_ACCOUNT_ID=...       # optional: Cloudflare Workers AI
CLOUDFLARE_API_TOKEN=...        # optional
GOOGLE_API_KEY=...              # optional: Gemini
NVIDIA_API_KEY=nvapi-...        # optional: NVIDIA NIM

# Hyperliquid
HYPERLIQUID_PRIVATE_KEY=0x...
HYPERLIQUID_TESTNET=true        # strongly recommended for local testing

4. Configure Trading​

cp config.yaml.example config.yaml

Minimal local config:

llm:
  client_type: openai
  model: gpt-4o-mini
  temperature: 0.2

trading:
  symbols: [BTC]
  max_trade_amount: 10    # keep small for testing
  max_leverage: 2

scheduler:
  interval_minutes: 5

Running the Strategies​

Perpetual Futures Agent​

uv run python main.py

With explicit config and env file:

uv run python main.py --config config.yaml --env .env

Grid Trading​

cp config.grid.yaml.example config.grid.yaml
# Edit config.grid.yaml

uv run python grid_main.py --config config.grid.yaml --env-file .env

Running Tests​

# Run all tests
uv run pytest tests/

# Run a specific test file
uv run pytest tests/test_agents_langgraph.py -v

# Run with coverage
uv run pytest tests/ --cov=src

# Run backtests (no live trading)
uv run python backtest.py --symbol BTC --strategy single \
  --start-date 2024-01-01 --end-date 2024-12-01

Syntax Checking​

# Check a specific module
uv run python -m py_compile src/trading/client.py

# Check all source files
find src -name "*.py" | xargs uv run python -m py_compile

Adding Dependencies​

# Add a runtime dependency
uv add requests

# Add a dev-only dependency
uv add --group dev pytest-mock

Log Output​

When running locally, logs are printed to stdout and also written to logs/:

tail -f logs/main.log    # perpetual agent
tail -f logs/grid.log    # grid trading

Testnet vs Mainnet​

Always Start on Testnet

Set HYPERLIQUID_TESTNET=true in .env during development. Testnet uses the same interface as mainnet but with no real funds.

Switch to mainnet only after you've validated your configuration:

HYPERLIQUID_TESTNET=false

Troubleshooting​

IssueFix
ModuleNotFoundErrorRun uv sync to reinstall dependencies
PermissionError on logs/mkdir -p logs && chmod 755 logs
Cannot connect to HyperliquidCheck HYPERLIQUID_TESTNET and network connectivity
API wallet can't tradeAuthorize the API wallet address on the main Hyperliquid wallet page

Next Steps​