Overview | Quick Start | Docs | Contributing | License
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.
- Multi-agent workflow with clear desk responsibilities
- Strict Risk Guard that can veto any trade
- Quant-style backtesting with built-in benchmarks; agentic LLM required (
OPENAI_API_KEYorATLASCLOUD_API_KEY) - Pinned historical
data/— daily OHLCV, funding, FRED / DefiLlama / Fear & Greed, news dailies, sha256 manifest so--csv-onlyreruns match - 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: deploy JSON for strategy, policy/app JSON for defaults,
.envfor secrets only
Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud's new coding plan promotion for more budget-friendly API access: https://www.atlascloud.ai/console/coding-plan
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.
- Real risk governance — Risk Guard has final veto power, not just logging.
- Quant discipline — Every backtest includes clear benchmarks. No hand-waving.
- Reproducible tape — Pinned
data/(OHLCV, funding, macro, news) withMANIFEST.jsonhashes; bar-aligned, no live Nexus in backtest. - Standardized agents — All agents follow the same
Input → Process → Output → Feedbackcontract. - Transparency — Full traces, reasoning logs, and event ledger.
- Extensibility — Built with LangGraph, clean personas, and OpenClaw skill packaging.
Rough flow (LangGraph):
- Market scan + Tier-0 desks — enabled desks from deploy JSON (TA, macro, pattern, …)
- Risk + desk debate — risk context; optional
desk_debate_llm(off in shipped presets) - Signal arbitrator — static
agents.*.weightmath first; optional desk CoT (llm_enabled) then optionalarbitrator_llmoverlay → BUY/SELL/HOLD - Portfolio — proposal → Risk Guard veto → execute
Weights/thresholds: docs/weighted-arbitrator.md. Graph notes: docs/langgraph-workflow.md.
# 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
# 5. Set up environment
cp .env.example .env
# Edit .env — set OPENAI_API_KEY or ATLASCLOUD_API_KEY (required for LLM calls)
# AIMM_API_KEY / AIMM_AUTH_SECRET / POSTGRES_PASSWORD: leave empty to generate, or set your own
# Strategy (desks, weights, LLM overlays) lives in config/deploy.active.json
# 6. Run the platform stack: DB + migrate + API + worker + web
# Requires Docker Desktop. Futu OpenD optional (`--profile with-futu`).
#
docker compose up --build -d
# 7. Open the dashboard
# http://localhost:3000/console?view=research
# http://localhost:3000/leaderboard
# http://localhost:3000/get-startedOpen http://127.0.0.1:3000 to view the dashboard (bound to localhost by default).
Migrations run automatically on first docker compose up (service migrate).
Compose Postgres listens on 5433 (new volume; old 5432 data is left untouched).
If AIMM_API_KEY / AIMM_AUTH_SECRET / POSTGRES_PASSWORD are set in .env, those values are used. If you left them empty, first boot writes unique values into .secrets/ (gitignored) and reuses them. Direct calls to :8001 need x-api-key; the dashboard proxies through Next.js with that key.
First boot may show an empty Leaderboard until you run a backtest (Nexus → Research) or publish results.
For CLI-only trading mode:
uv run python src/main.pyAgentic path needs a key (no silent fallback). Either:
OPENAI_API_KEY=...
# optional: OPENAI_BASE_URL / OPENAI_MODELor, if OPENAI_API_KEY is unset:
ATLASCLOUD_API_KEY=...
ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1
ATLASCLOUD_MODEL=deepseek-ai/deepseek-v4-proCoding plan: https://www.atlascloud.ai/console/coding-plan — more env notes in docs/configuration.md.
If you want a lightweight public API for published results/signals (no full Nexus UI):
docker compose -f docker-compose.leaderboard.yml up -d --buildFor the full local portal (Research backtests + console), use plain docker compose up --build -d instead.
- Start with the product surface
- Put
OPENAI_API_KEYorATLASCLOUD_API_KEYin.env, then open/console?view=research. - Open
/get-startedfor local setup commands. - Open
/toolsto browse callable platform endpoints.
- Put
- Run a quick backtest
- Use Nexus → Research (or call
POST /backtests/quick) and confirm:- equity + trades ledgers exist under
.runs/backtests/<run_id>/
- equity + trades ledgers exist under
- Use Nexus → Research (or call
- Inspect a run
- Fetch
GET /runs/latest/payload?soft=1and inspect topology/traces/message log.
- Fetch
- Python 3.11+
- uv
- TA-Lib (C library + Python wrapper) - see installation options below
- Binance Testnet API keys (for paper trading)
- LLM API key for agentic mode (
OPENAI_API_KEYorATLASCLOUD_API_KEY) - (Optional) Nexus Skills API access
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-forgeOption 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-libOption 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-libNote for OpenClaw Users: If running in OpenClaw environment without sudo privileges, use Option 1 (Conda) as shown in the CI workflow.
- Strategy →
config/deploy.active.json(desks, weights, LLM overlays, gates). Seedocs/agentic-config.md - Policy & universe →
config/policy.default.jsonandconfig/app.default.json - Historical tape →
data/+data/MANIFEST.json(not live APIs) - Secrets / ops →
.envonly (no arbitrator-mode or LLM-agent env flags)
Detailed docs:
# 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- Tier-0 —
monetary_sentinel,news_narrative_miner,pattern_recognition_bot,statistical_alpha_engine,technical_ta_engine,retail_hype_tracker,pro_bias_analyst,whale_behavior_analyst,liquidity_order_flow - Market scan, risk, desk debate — universe + risk context before arbitration
- Signal arbitrator — weighted math on static JSON weights; optional desk CoT +
arbitrator_llmoverlay →trade_intent - Portfolio — proposal / execute
- Risk Guard — hard veto before execution
Default research combo (g49 in config/deploy.active.json): TA×0.35 CoT, news×0.20 CoT, macro×0.20, pattern×0.15, stat×0.10. Personas in docs/personas/; interface in src/agents/base_agent.py.
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.
data/ ships in the repo so a clone can run --csv-only without fetching APIs or leaking look-ahead (today’s news on 2022 bars). Hashes live in data/MANIFEST.json. Layers:
| Layer | Path | Used for |
|---|---|---|
| Daily OHLCV (19 USDT pairs) | data/ohlcv/ |
TA / pattern desks, fills, buy-and-hold |
| Perp funding | data/derivatives/ |
Statistical / funding context |
| FRED (VIX, fed funds, 10y, DXY) | data/macro/fred_daily.csv |
monetary_sentinel |
| DefiLlama TVL / stables (lag-1) | data/macro/defillama_liquidity_daily.csv |
monetary_sentinel |
| Fear & Greed | data/macro/fear_greed_daily.csv |
monetary_sentinel |
| CryptoVision daily news | data/news_sentiment/ |
News desk in backtest |
Details: docs/backtest-data.md.
Run these from the repository root (the directory that contains pyproject.toml), after uv sync --extra dev (or uv sync). Requires an LLM key (OPENAI_API_KEY / LLM_API_KEY or ATLASCLOUD_API_KEY). LLM path dependence means re-runs are not bit-identical.
# Offline CSV backtest — uses pinned data/ (no prefetch)
NEXUS_DISABLE=1 uv run python -m backtest run \
--deploy config/deploy.active.json \
--symbols 'BTC/USDT,ETH/USDT,SOL/USDT' \
--steps 180 \
--csv-only \
--timeframe 1d \
--ticker BTC/USDTOptional: uv run python -m backtest.bootstrap_showcase only if you need to refresh local CSVs. Day-to-day research should hit data/ as shipped.
Watch stderr for the per-bar transcript; stdout ends with JSON metrics;
HTML report at .runs/backtests/<run_id>/backtest_report.html.
TA warmup (default, recommended): --steps 180 fetches 230 daily bars (50 warmup + 180 eval).
Warmup bars feed RSI/MACD/ADX context only — no LLM calls, no trades. Metrics and benchmark use
the 180 eval bars only (summary.json → eval_bars, ta_warmup_bars). Override via
config/app.default.json backtest.min_warmup_bars (default 50).
Use --no-warmup only for fast A/B compares (indicators cold-start on bar 1; not for production reporting).
Unique setups ranked by scored-book mean return (identical clone prints dropped). Default is rank 1 (config/deploy.active.json).
| Rank | Deploy | Mean | Sharpe | Windows + |
|---|---|---|---|---|
| 1 | deploy.active.json (g49) |
+8.15% | 1.71 | 2/2 |
| 2 | deploy.easy_short.json |
+6.48% | 1.66 | 2/2 |
| 3 | deploy.tight_sl.json |
+6.04% | 1.50 | 2/2 |
| 4 | deploy.tp8.json |
+5.82% | 1.43 | 2/2 |
| 5 | deploy.lev15.json |
+5.52% | 1.17 | 2/2 |
| 6 | deploy.stat_cot.json |
+5.03% | 1.43 | 1/2 |
| 7 | deploy.news_flow.json |
+4.13% | 1.02 | 2/2 |
| 8 | deploy.swing_sharpe.json |
+4.13% | 0.87 | 2/2 |
| 9 | deploy.ta_heavy.json |
+3.53% | 0.78 | 1/2 |
| 10 | deploy.sharpe_focus.json |
+3.46% | 0.68 | 1/2 |
swing_sharpe is the only one also green on the locked 3-window release suite (2021 H2 / 2022 H1 / 2025 H1: +2.58 / +11.10 / +0.59, mean +4.76%). Small trade sample. Not a live-edge claim. deploy.ohlcv_only.json is CI wiring only.
Research helpers (period sweep, preset compare) live under out/scripts/ (gitignored scratch).
Tuning for paper / research (agentic framework aligned):
| Knob | Recommendation | Why |
|---|---|---|
| Desk combo | Rank-1 g49 in config/deploy.active.json |
Highest scored-book mean (+8.15% / 1.71) |
| Horizon | --steps 180 daily (50 warmup + 180 eval) |
Enough bars for TA + a later OOS window |
| Period lock | --until a pinned date |
Pin eval end date when CSV grows |
| Data | Pinned data/ + --csv-only |
Same tape as the catalog; see data/MANIFEST.json |
| OHLCV context | AIMM_BACKTEST_OHLCV_NEXUS=0 |
OHLCV-only desk; defers live Nexus |
| Nexus desks | Enable in deploy JSON when you have historical feeds | See docs/backtest-data.md |
| Symbols | BTC + ETH + SOL | Multi-asset book; transcript defaults to --ticker only |
| Transcript | AIMM_BACKTEST_TERMINAL_ALL_SYMBOLS=1 optional |
Show all three symbols per bar (verbose) |
| Stress test | --steps 365 separately |
Full-year bear-market eval; report PF even if < 1 |
# Desk list + LLM flags come from config/deploy.active.json
NEXUS_DISABLE=1 AIMM_BACKTEST_LLM_MAX_STEPS=200 \
uv run python -m backtest run \
--deploy config/deploy.active.json \
--symbols 'BTC/USDT,ETH/USDT,SOL/USDT' --steps 180 --until 2026-07-12 --online --timeframe 1d --ticker BTC/USDTIf you see ModuleNotFoundError: No module named 'backtest', you are not in the repo root or dependencies are not installed (uv sync).
AIMM_STRATEGY_PRESET / AIMM_DESK_STRATEGY_PRESET are optional TA/research overlays, not LLM strategy flags. Desk LLM and arbitrator overlays come from deploy JSON.
Each bar invokes the full LangGraph workflow with LLM-active desks:
| Piece | Behavior |
|---|---|
| Fusion | Weighted math on static agents.*.weight (not retuned each bar) |
| Desk LLM | execution.use_llm_synthesis + agents.*.llm_enabled → infer_agent |
| Arbitrator LLM | execution.arbitrator_llm overlay after math (falls back to math on failure) |
| Portfolio | Always llm_portfolio_proposal / llm_portfolio_execute (no rule-based fallback) |
| OHLCV context | Market scan + Tier-0 math feed prompts; monetary_sentinel can use OHLCV-derived macro (AIMM_BACKTEST_OHLCV_NEXUS=1). Showcase commands use =0. |
| No fallback layer | Graph trade_intent only — no HOLD→BUY/SELL override |
| Fill model | Signal on completed bars; fill at bar open; TP/SL at bar close |
| Terminal output | Per-bar desk CoT on stderr (on by default in backtest; disable with AIMM_BACKTEST_TERMINAL_LOG=0) |
| Audit receipts | tier0_summary in iterations (on by default in backtest; disable with AIMM_BACKTEST_VERBOSE_RECEIPTS=0) |
Strategy knobs: config/deploy.active.json — see docs/agentic-config.md.
Comparison with TradingAgents
Both are LangGraph multi-agent research scaffolds. Differences that matter for this repo:
| TradingAgents | AIMM (this repo) | |
|---|---|---|
| Asset class | Equities (Yahoo) | Crypto perps (Binance OHLCV) |
| Backtest model | Date-grid propagate() vs next-bar close |
Bar-by-bar perp simulator (margin, funding, multi-symbol) |
| Agent fusion | Bull/bear debate → trader → risk → PM | Weighted desk convergence + TA-led gates |
| Artifacts | Decision log, checkpoints | summary.json, trades/equity JSONL, HTML report, quality gates |
| Terminal UX | Per-date analyst reports in CLI | Per-bar desk CoT + BUY/SELL/HOLD summary on stderr |
Like TradingAgents, results vary with model and window — report benchmark, sample size, and profit factor honestly.
Re-run after setting your LLM key — results depend on provider and model. Prefer pinned data/ over a live window:
NEXUS_DISABLE=1 uv run python -m backtest run \
--deploy config/deploy.active.json \
--symbols 'BTC/USDT,ETH/USDT,SOL/USDT' \
--steps 180 --csv-only --timeframe 1d --ticker BTC/USDTReport: .runs/backtests/<run_id>/backtest_report.html
Local parameter sweep (requires LLM key; compares presets via deploy_config in src/backtest/run_agentic_sweep.py):
NEXUS_DISABLE=1 uv run python -m backtest.run_agentic_sweep --showcaseReports: .runs/evaluations/sweep_<id>/sweep_report.md
See also: docs/weighted-arbitrator.md for threshold and alignment-gating details.
The stack includes a Futu OpenD adapter for fetching real-time HK and US stock data and placing simulated (paper) orders.
- Futu OpenD must be running locally or on a reachable host.
Download from Futu OpenAPI and start the
gateway on your local machine:
OpenD exposes port 11111 (quote) and 11112 (trade) by default.
chmod +x OpenD ./OpenD
# .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 placementpython -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()
"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.
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 devai-market-maker/
├── src/ # Core Python logic
│ ├── agents/ # Individual trading desks
│ ├── tools/ # Exchange, TA, sentiment tools
│ ├── backtest/ # Backtesting engine
│ ├── llm/ # LLM clients (OpenAI-compatible / Atlas)
│ └── api/ # FastAPI endpoints
├── web/ # Next.js dashboard
├── openclaw/ # OpenClaw skill definitions
├── config/ # deploy.*.json (strategy) + policy/app defaults
├── data/ # pinned OHLCV, funding, macro, news + MANIFEST.json
├── assets/ # Branding
├── docs/ # Detailed documentation
├── tests/ # Test suite
└── .env.example
This project includes complete OpenClaw support with dedicated tooling for agentic trading workflows.
openclaw/
├── SKILL.md # Skill documentation
├── manifest.json # OpenClaw manifest
├── scripts/ # Dedicated runners
│ ├── claw_runner.py # Main entry point
│ └── verify_installation.sh # Dependency checker
└── examples/ # Usage examples
# From OpenClaw
claw install https://github.com/olaxbt/ai-market-maker
# Or locally
claw skill install ./openclaw- Dedicated runner with automatic environment setup
- Installation verification script
- Pre-configured for OpenClaw environments
- Full compatibility with Claw skill system
- Multi-language documentation support (English, Korean)
- Complete examples for different usage scenarios
- Optimized default arbitrator weights (offline-tuned); see Backtesting
You can run this service as part of the OlaXBT Nexus stack and settle usage directly on BNB Chain (BSC / BNB Smart Chain).
Fund your Nexus-connected wallet with BNB or supported stablecoins on BNB Chain, then buy credits through the Nexus interface; all metered usage is settled on BNB Chain with low fees, and can later be expanded to opBNB or Greenfield–aligned workflows.
This lets agents and trading tools consume data and actions through Nexus while keeping payments and accounting native to the BNB Chain ecosystem.
We welcome contributions! Please read CONTRIBUTING.md first.
Growth is driven by issues and pull requests. See the open issues for current priorities.
GNU Affero General Public License v3.0 — see LICENSE. If you modify this software and run it as a network service, AGPL obligations (including source offer to users) may apply; read the license carefully.
Built with LangGraph • FastAPI • Next.js • TA-Lib
Ready to experiment with serious agentic trading infrastructure.