AI Market Maker: Agentic Trading System for Crypto Hedge Funds

Overview | Quick Start | Docs | Contributing | License

Overview

AI-Market-Maker is an open-source, hedge-fund-style trading stack for crypto. It combines specialist AI trading agents (acting as trading desks), a LangGraph orchestration layer, a hard Risk Guard veto before any execution, and quant-grade discipline including centralized policy, benchmarks against buy-and-hold, and full traceability.

Designed to feel like a small professional trading firm — not just another bot.

Key Features

• Multi-agent workflow with clear desk responsibilities
• Strict Risk Guard that can veto any trade
• Quant-style backtesting with built-in benchmarks (excess return vs buy-and-hold)
• Unified agent interface + governance layer
• OpenClaw-ready packaging (SKILL.md + manifest.json + dedicated runners)
• Paper trading on Binance Testnet + rich local backtester; Hyperliquid adapter (dry-run) via OMS layer
• Modern web dashboard for telemetry and traces
• Clean configuration (JSON policy + env for secrets only)

---

Goals

Current (Trading Mode)
Fetch real-time data, generate signals through specialist agents, run portfolio logic, apply Risk Guard veto, and execute on Binance Testnet.

Near-term
Full position lifecycle, multi-asset portfolio management, configurable leverage, and improved long/short handling.

Longer-term
Deeper agentic capabilities, better OpenClaw integration, and support for additional execution venues and data sources.

---

Why This Project Stands Out

• Real risk governance — Risk Guard has final veto power, not just logging.
• Quant discipline — Every backtest includes clear benchmarks. No hand-waving.
• Standardized agents — All agents follow the same Input → Process → Output → Feedback contract.
• Transparency — Full traces, reasoning logs, and event ledger.
• Extensibility — Built with LangGraph, clean personas, and OpenClaw skill packaging.

System Architecture

The workflow mimics a small hedge fund:

1. Research Desks — Market Scan, Technical Analysis, Statistical Alpha, Sentiment
2. Alpha Generation — Signal synthesis and thesis building
3. Portfolio Management — Risk-weighted allocation and trade sizing
4. Risk Guard — Final safety layer (can veto everything)
5. Execution — Only proceeds if Risk Guard approves

See docs/langgraph-workflow.md for the complete graph state, nodes, edges and routing logic.

---

Quick Start

# 1. Clone the repo
git clone https://github.com/olaxbt/ai-market-maker.git
cd ai-market-maker

# 2. Install dependencies
pip install uv

# 3. Install TA-Lib first (see installation options in Prerequisites section)
# Example using Conda (recommended for OpenClaw environments):
# wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
# bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda
# source $HOME/miniconda/bin/activate
# conda install -y ta-lib -c conda-forge

# 4. Install Python dependencies
uv sync --extra dev
uv run pre-commit install

# 3. Set up environment
cp .env.example .env
# Edit .env with your API keys (Binance Testnet + OpenAI recommended)
#
# Required for the Docker stack:
#   DATABASE_URL=postgresql+psycopg://aimm:aimm@db:5432/aimm
#   AIMM_AUTH_SECRET=<long-random-secret>

# 4. Run the platform stack (recommended): DB + API + worker + web
# Requires Docker Desktop / docker compose.
#
docker compose -f docker-compose.prod.yml up --build -d

# 5. Run migrations (first time, and after schema changes)
docker compose -f docker-compose.prod.yml run --rm api alembic upgrade head

# 6. Open the dashboard
# http://localhost:3000/leaderboard   (results + signals)
# http://localhost:3000/console       (nexus console)
# http://localhost:3000/get-started   (copy/paste setup guide)
# http://localhost:3000/tools         (tool browser)

Open http://localhost:3000 to view the dashboard.

Note: first boot may show an empty Leaderboard/Signals until you run a backtest (Nexus → Research) or publish provider results/signals.

For CLI-only trading mode:

uv run python src/main.py

---

Hosted Leaderboard (recommended public deployment)

If you want a public site where people can: - view Leaderboard results + Signals - publish results from their own local runs (provider keys)

Run the leaderboard stack (DB + API, optional Web UI):

# API + DB (leaderboard endpoints)
docker compose -f docker-compose.leaderboard.yml up -d --build

# Optional: include the web-v2 portal UI (service `portal`; avoids clobbering Next `web` if you merge this file with prod compose)
docker compose -f docker-compose.leaderboard.yml --profile web up -d --build

This keeps the public deployment lightweight and focused on evaluation, while users run the full agentic system locally.

---

How to evaluate this repo (developer checklist)

• Start with the product surface
• Open /leaderboard to see how results/signals are presented.
• Open /get-started for local setup commands.
• Open /tools to browse callable platform endpoints.
• Run a quick backtest
• Use Nexus → Research (or call POST /backtests/quick) and confirm:
  • equity + trades ledgers exist under .runs/backtests/<run_id>/
  • results can be published to the leaderboard (see /leadpage/external_result)
• Inspect a run
• Fetch GET /runs/latest/payload?soft=1 and inspect topology/traces/message log.

Setup Details

Prerequisites

• Python 3.11+
• uv
• TA-Lib (C library + Python wrapper) - see installation options below
• Binance Testnet API keys (for paper trading)
• OpenAI API key (optional, enables LLM nodes)
• (Optional) Nexus Skills API access

TA-Lib Installation Options

Option 1: Conda (Recommended)

# Install Miniconda if not already installed
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda
source $HOME/miniconda/bin/activate
conda install -y ta-lib -c conda-forge

Option 2: System Package Manager

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y ta-lib

# macOS (Homebrew)
brew install ta-lib

# Then install Python wrapper
pip install ta-lib

Option 3: Source Compilation

wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
tar -xzf ta-lib-0.4.0-src.tar.gz
cd ta-lib/
./configure --prefix=/usr/local
make
sudo make install
pip install ta-lib

Note for OpenClaw Users: If running in OpenClaw environment without sudo privileges, use Option 1 (Conda) as shown in the CI workflow.

Configuration Philosophy

• Policy & universe → config/policy.default.json and config/app.default.json (single source of truth)
• Secrets → only in .env

Detailed docs: - docs/configuration.md - docs/policy-schema.md - docs/run-modes.md

Testing

# Default unit tests (no network)
uv run pytest -q

# Full agentic E2E tests
uv run pytest -q tests/test_agentic_trading_e2e.py tests/test_tier0_consensus.py

---

Agents (Desks)

• Market Scan — New listings, momentum, universe coverage
• Technical TA Engine — Pattern recognition, MACD, indicators
• Statistical Alpha Engine — Factor and cross-sectional signals
• Sentiment & Narrative — News, retail hype, whale behavior
• Risk Management — Position sizing, volatility-based limits
• Portfolio Management — Multi-asset allocation and proposal generation
• Risk Guard — Hard veto layer before execution

All agents follow a standardized interface defined in src/agents/base_agent.py.

---

Backtesting & Research Expectations

Every backtest automatically includes: - Performance metrics (Sharpe, Sortino, Profit Factor, etc.) - Benchmark vs. buy-and-hold (spot move + equity curve) - Excess return calculation - Full trade ledger and forced risk exits - Multi-asset portfolio analysis

Important: A single profitable backtest is not proof of edge. Always validate across multiple regimes and out-of-sample periods.

Running Backtests

Run these from the repository root (the directory that contains pyproject.toml), after uv sync --extra dev (or uv sync).

# Using the OpenClaw runner (same cwd requirement)
uv run python openclaw/scripts/claw_runner.py --backtest

# With custom parameters
uv run python openclaw/scripts/claw_runner.py --backtest --symbols "BTC/USDT,ETH/USDT,SOL/USDT" --steps 100

# Direct multi-symbol demo (public OHLCV via CCXT; no API keys required)
# Quote --symbols in zsh/fish. NEXUS_DISABLE + LLM off avoid slow/failing network and LLM calls.
NEXUS_DISABLE=1 AI_MARKET_MAKER_USE_LLM=0 \
  uv run python -m backtest.run_demo \
    --symbols 'BTC/USDT,ETH/USDT,SOL/USDT' \
    --steps 100 \
    --online \
    --exchange binance

If you see ModuleNotFoundError: No module named 'backtest', you are not in the repo root or dependencies are not installed (uv sync). If your .env sets AIMM_STRATEGY_PRESET, it overrides config/app.default.json strategy defaults; unset it to use shipped app.default.json presets.

Example Backtest Results

The default configuration (using multiple symbols and conservative risk parameters) typically produces results like:

Trade count: 17
Total return: 14.95%
Excess return vs BTC buy & hold: +30.25%
Sharpe ratio: 1.79
Maximum drawdown: 11.84%
Win rate: 62.5%

These results reflect: - Multi-asset diversification (BTC, ETH, SOL) - Conservative position sizing and risk limits - Automated benchmark comparison - Full trade transparency and risk event logging

---

Futu OpenD (HK / US Stock Data)

The stack includes a Futu OpenD adapter for fetching real-time HK and US stock data and placing simulated (paper) orders.

Prerequisites

• Futu OpenD must be running locally or on a reachable host. Download from Futu OpenAPI and start the gateway on your local machine: bash chmod +x OpenD ./OpenD OpenD exposes port 11111 (quote) and 11112 (trade) by default.

Configuration

# .env (all have sensible defaults if unset)
FUTU_OPEND_HOST=127.0.0.1       # OpenD host
FUTU_OPEND_QUOTE_PORT=11111     # Quote API port
FUTU_OPEND_TRADE_PORT=11112     # Trade API port
FUTU_DRY_RUN=0                  # 1 = parse only, never send real orders (safe default)
# FUTU_UNLOCK_PWD=              # Required for order placement

Test the connection

python -c "
from futu import OpenQuoteContext
ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
ret, data = ctx.get_stock_quote('HK.00700')
print('OK' if ret == 0 else 'FAIL', data)
ctx.close()
"

Web Dashboard

Open the Futu dashboard at /futu (Nexus nav → Futu tab) after starting the web UI. - Select HK/US tickers from the configured universe. - View OHLCV candlestick charts (interval: 1h / 1d / 1w). - Place simulated buy/sell orders (paper trades). - Falls back to synthetic mock data when OpenD is not available.

---

Web UI

A Next.js dashboard is included for viewing: - Live agent traces and reasoning - Backtest results - Topology visualization - Prompt editing (where applicable) - Futu stock data and charts

Run with:

cd web && npm install && npm run dev

---

Project Structure

ai-market-maker/
├── src/                    # Core Python logic
│   ├── agents/             # Individual trading desks
│   ├── tools/              # Exchange, TA, sentiment tools
│   ├── backtest/           # Backtesting engine
│   └── api/                # FastAPI endpoints
├── web/                    # Next.js dashboard
├── openclaw/               # OpenClaw skill definitions
├── config/                 # Default policy and app config
├── docs/                   # Detailed documentation
├── tests/                  # Test suite
└── .env.example

OpenClaw Integration

This project includes complete OpenClaw support with dedicated tooling for agentic trading workflows.

Skill Package

``` openclaw/ ├── SKILL.md # Skill documentation ├── manifest.json # OpenClaw manifest ├── scripts/ # Dedicated runners │ ├── claw_runner.py