Omnitrade

English | 简体中文

OmniTrade: LLM-Driven Crypto Futures Arena

11 competing strategies · 4 close-path taxonomy · atomic three-way state · real-time dashboard

News  ·  Try in 2 Min  ·  Features  ·  Strategies  ·  vs Hand-rolled  ·  Get Started  ·  Architecture  ·  API  ·  Sponsor  ·  License

---

📢 Project Status

OmniTrade is actively developed. The architecture, API surface, and strategies all evolve in response to operator feedback — issues and feature requests are very welcome and treated as first-class signal.

If anything breaks, feels off, or you'd like to see a new strategy / data source / dashboard panel, please [open an issue][issues] or a pull request — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [SECURITY.md](SECURITY.md) for vulnerability reports (private channel only). Star the repo if you'd like to follow along.

[issues]: https://github.com/gong1414/omnitrade/issues

---

⚠️ Risk Disclaimer — please read before running

OmniTrade automates real trades on cryptocurrency exchanges. Crypto derivatives are high-leverage instruments and can cost you the entire balance of an account in a single bad cycle. This project is research software released under the MIT license, with no warranty of any kind. The maintainers are not financial advisors and accept no liability for any losses incurred from running it.

By using this software you accept that:

• You are responsible for every trade it places. The agent will open,

size, and close positions autonomously. Treat its decisions as your own.

• Start on testnet. GATE_USE_TESTNET=true and OKX_USE_TESTNET=true

are the defaults. Run for weeks on testnet before flipping either flag.

• Start small on mainnet. When you do go live, begin with a balance

you would be willing to lose entirely. The HITL gate (HITL_OPEN_SIZE_THRESHOLD_USD, default $10 000) is a safety net, not a substitute for setting your own position-size limits.

• Lock down your exchange API keys. Set them to "trade only, no

withdraw" on Gate.io / OKX. Enable 2FA on the exchange account.

• Monitor it. The dashboard exposes every cycle's reasoning,

positions, and gates. Read it. The G5 fault-phrase scanner flags obvious problems automatically; subtler issues are still your call.

• You bear full regulatory risk. Algorithmic trading of crypto

derivatives may be restricted or prohibited in your jurisdiction — verify your local rules before running this software.

If you can't accept those terms, stop here.

---

📰 News

• 2026-04-26 🎉 Open-source release v0.1.0 — Agno cutover (Stages A–E) + T1–T10 hardening all green. Full release notes at v0.1.0.
• 2026-04-26 🛡️ OSS quality batch — Dependabot + CodeQL security scanning, branch protection on main, GitHub Pages live at docs, full ADR collection under [docs/adr/](docs/adr/).
• 2026-04-26 📚 Quickstart + FAQ — git clone → first cycle in HITLOPENSIZETHRESHOLDUSD` (default $10 000) via SSE — operator approves on the dashboard |

| LLM reasoning is forgotten between sessions | T10 trade-journal RAG ingests every decision into PgVector; subsequent cycles see semantically relevant prior decisions in their system prompt | | No visibility into "did the agent really use its tools?" | OpenTelemetry traces (T4) — one span per Agent.arun / model call / tool call, served via AgentOS GET /traces | | Multi-framework drift (LangChain + LiteLLM + LangGraph + mcp2py) | One framework — Agno 2.x. CI's Acceptance 4 enforces zero legacy imports |

---

✨ Key Features

🎯 Strategy Arena

• 11 named strategies across 3 risk profiles • 2 prompt branches: minimal (autopilot / dual-signal) vs full "World-class Trader" • Per-strategy leverage bands, trailing ladder, partial-profit stages • Multi-agent modes: arena-tribunal (3-expert jury) & arena-raider-squad (4-expert team)

🛡️ Close-Path Classifier

• Pure classifier: closepathclassifier.py • 10-s monitors: trailing-stop, stop-loss, partial-profit • AI closes via closeposition / partialclose tools • Three-way state written atomically on every close

🔌 Exchange Client

• ccxt unified adapter; testnet default • REST: ticker, OHLCV, order book, open interest, funding • Real-time dashboard via Server-Sent Events (single transport) • Order lifecycle: open, close, partial close, cancel

🧪 Characterization Gate

• 22 hand-curated decision contracts • VCR cassettes synthesised deterministically • Decision-equivalent replay ≥ 0.95 pass-rate • Every close-path bucket ≥ 0.95, drift ≤ 0.05

---

🎯 Strategies

11 strategies, each a concrete configuration of leverage band → trailing ladder → partial-profit stages → stop-loss override → system-prompt branch. Quick names: arena-guardian / arena-steward / arena-raider / arena-raider-squad / arena-scalper / arena-swingsmith / arena-strider / arena-rebate-hunter / arena-autopilot / arena-tribunal / arena-dual-signal.

Click to expand the full 11-strategy table

| # | Enum value | Profile | Prompt branch | Code-level protection | Frozen fixtures | |---|---|---|---|---|---| | 1 | arena-guardian | capital-preservation | full | off | case_06, case_19 | | 2 | arena-steward | balanced default | full | off | case_05, case_11, case_18 | | 3 | arena-raider | high-leverage single-agent | full | off | case_07 | | 4 | arena-raider-squad | multi-agent attack team (4 experts) | team | off | case_16 | | 5 | arena-scalper | 5-minute intraday | full | off | case_04, case_08, case_09, case_17 | | 6 | arena-swingsmith | multi-day swing | full | on (auto-close) | case_01-03, case_10, case_22 | | 7 | arena-strider | slow trend follower | full | off | case_20 | | 8 | arena-rebate-hunter | high-frequency rebate arbitrage | full | on | case_12 | | 9 | arena-autopilot | fully autonomous LLM | minimal | on + AI override | case_13, case_14 | | 10 | arena-tribunal | 3-expert jury consensus | jury | off | case_21 | | 11 | arena-dual-signal | registry fallback (unknown → dual-signal) | minimal | off | case_15 |

Full parameter tables: [docs/STRATEGIES.md](./docs/STRATEGIES.md).

---

🛡️ Close-Path Taxonomy

Four mutually-exclusive close paths plus a none bucket. Monitors own the first three; the think-node owns ai_decision.

| Path | Driven by | Writes | |---|---|---| | stop_loss | stop_loss_monitor (10 s) | trades(type=close), agent_decisions(trigger=stop_loss), delete positions | | trailing_stop | trailing_stop_monitor (10 s, when enable_code_level_protection) | trades, agent_decisions, delete positions | | partial_profit | partial_profit_monitor (10 s) | partial trades, atomic 3-way UPDATE positions, agent_decisions | | ai_decision | close_position / partial_close tools (trading loop) | trades, atomic three-way UPDATE positions | | none | — | open-only or hold snapshots |

Full rules + truth table: [apps/backend/src/omnitrade/domain/services/close_path_classifier.py](./apps/backend/src/omnitrade/domain/services/closepathclassifier.py).

---

🚀 Get Started

Path A · Docker (zero setup)

cp apps/backend/.env.example .env
# edit .env — set LLM_API_KEY (DeepSeek), GATE_API_KEY / OKX_API_KEY, leave testnet flags ON
docker compose up -d
# `db-init` runs `alembic upgrade head` automatically and the backend
# waits on `service_completed_successfully` before starting.

Verify the cycle is running end-to-end:

curl -X POST http://localhost:8000/api/v1/cycle/trigger          # should return {"status":"ok"} in ≤60s
curl -s 'http://localhost:8000/api/v1/decisions?limit=1' | jq    # last decision JSON

| URL | Surface | |---|---| | http://localhost:3000/dashboard | Next.js dashboard | | http://localhost:8000/docs | FastAPI interactive docs | | http://localhost:8000/sse/stream | Server-Sent Events feed (decision / position / run-paused) |

Path B · Local (Python 3.11 + Node 20)

# Backend
cd apps/backend
uv sync --all-extras
uv run alembic upgrade head
uv run uvicorn omnitrade.api.app:create_app --factory --reload

# Frontend (separate terminal)
cd apps/frontend
npm install
npm run dev

Path C · Production

cp .env.production.example .env.production
# fill secrets — NEVER commit .env.production
docker compose -f docker-compose.prod.yml up -d

Full release checklist (smoke tests, observability, rollback plan): [docs/RELEASECHECKLIST.md](./docs/RELEASECHECKLIST.md).

Prerequisites

• LLM API key — DeepSeek (default deepseek-reasoner; switch to deepseek-v4-pro / -flash via AGNO_LLM_MODEL), driven directly by Agno's DeepSeek model class
• Exchange credentials — Gate.io or OKX; testnet recommended
• Python 3.11+ with uv for Path B
• Docker + Docker Compose for Paths A / C

---

🧠 Environment

All config is env-driven. Two essentials and the rest are documented inline:

• LLM_API_KEY — your DeepSeek / OpenAI / OpenRouter key
• GATE_API_KEY + GATE_API_SECRET — exchange credentials (testnet default)

Full reference (40+ variables) lives in [apps/backend/.env.example](./apps/backend/.env.example) with documenting comments per row.

Click for the most-asked variables (defaults shown)

| Variable | Default | Description | |---|---|---| | TRADING_STRATEGY | arena-autopilot | one of 11 strategies | | TRADING_INTERVAL_MINUTES | 20 | cron for the main trading loop | | MAX_LEVERAGE | 25 | hard cap per position | | MAX_POSITIONS | 5 | concurrent open positions | | MAX_HOLDING_HOURS | 36 | force-close after this many hours | | EXTREME_STOP_LOSS_PERCENT | -30 | hard floor — force-close below this PnL % | | EXCHANGE | gate | gate or okx | | GATE_USE_TESTNET / OKX_USE_TESTNET | true | testnet default — live trading requires false | | LLM_PROVIDER | deepseek | Agno DeepSeek provider key | | LLM_MODEL_NAME | deepseek/deepseek-v3.2-exp | any OpenAI-compatible model | | MULTI_AGENT_ENABLED | false | enable arena-raider-squad / arena-tribunal dispatch | | FEE_REBATE_PERCENT | 20 | shown as rebateAmount in /api/account | | HITL_OPEN_SIZE_THRESHOLD_USD | 10000 | T9 — opens above this pause for operator approval | | EMBEDDER_PROVIDER | fastembed | fastembed (local, default) or openai | | OTEL_TRACING_ENABLED | true | T4 — OpenTelemetry span emission |

Recommended LLMs (model-choice cheat sheet)

OmniTrade is a tool-calling-heavy agent — open/close/partial decisions all flow through OpenAI-style tool calls. Model choice directly decides whether the agent uses its tools or fabricates decisions.

| Tier | Examples | When to use | |---|---|---| | Best | anthropic/claude-sonnet-4.6, openai/gpt-5.4, google/gemini-3.1-pro | Multi-agent swarms (arena-raider-squad, arena-tribunal), long-running research | | Sweet spot (default) | deepseek/deepseek-v3.2-exp, x-ai/grok-4, z-ai/glm-5, moonshotai/kimi-k2, qwen3-max | Daily driver — reliable tool-calling at ~1/10 the cost | | Avoid | *-nano, *-flash-lite, small distilled variants | Tool-calling is unreliable; agent will "answer from memory" instead of querying markets |

---

🏛️ Architecture

Classic DDD 4-layer (domain / application / infrastructure / api) + a dedicated agents/ module that's the only place allowed to import Agno. Five async loops drive everything: one trading cycle (AgentOS-scheduled) plus four 10-second monitors that own the position-protection paths.

Deep-dive with full mermaid diagrams + scheduler topology + three-way state invariant: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) ([中文](./docs/ARCHITECTURE_ZH.md)).

Click for layer + scheduler diagrams

flowchart TD
    api[apiFastAPI + middleware + DI]
    app[applicationservices, monitors, orchestrators]
    dom[(domainentities, protocols, pure services)]
    infra[infrastructureSQLAlchemy, ccxt, Agno DeepSeek, sqlite-vec]
    agents[agentsAgno Agent + MultiMCPTools + Team]

    api --> app
    app --> dom
    app --> agents
    infra --> dom
    agents --> dom

    classDef dom fill:#fef3c7,stroke:#f59e0b
    class dom dom

Five async loops, all driven by a single injected Clock protocol:

flowchart LR
    L1[trading_loopAgentOS scheduler */TRADING_INTERVAL] --> DB[(Postgres + pgvector)]
    L2[account_recordercron */ACCOUNT_INTERVAL] --> DB
    L3[trailing_stop10 s] --> DB
    L4[stop_loss10 s] --> DB
    L5[partial_profit10 s atomic 3-way UPDATE] --> DB
    style L5 stroke:#dc2626,stroke-width:3px

---

🌐 API Reference

Interactive Swagger docs: http://localhost:8000/docs (renders the live spec). Every public route is read-only except POST /api/v1/cycle/trigger, POST /api/v1/runs/{id}/{confirm,reject} (T9 HITL), and POST /api/actions/close-all (password-gated emergency).

Click for the full endpoint table

uv run uvicorn omnitrade.api.app:create_app --factory
# or: docker compose exec backend ...

| Method | Endpoint | Description | |---|---|---| | GET | /api/health · /api/ready | liveness / readiness probes | | GET | /api/account | balance + rolling 24 h rebate trace | | GET | /api/positions | open positions with three-way state | | GET | /api/trades | trade history | | GET | /api/decisions | agent decision audit log | | GET | /api/history | account-value time series | | GET | /api/stats | Sharpe, drawdown, strategy breakdown | | GET | /api/prices | cached tickers | | GET | /api/strategy · /api/config | active strategy + runtime knobs | | GET | /api/rebate | 24 h rebate summary | | GET | /api/logs | in-memory log buffer (tailable) | | POST | /api/actions/close-all | emergency close-all (guarded) | | POST | /api/v1/cycle/trigger | trigger one trading cycle synchronously | | POST | /api/v1/runs/{run_id}/confirm · /reject | T9 HITL approve / reject a paused large open | | GET | /sse/stream | Server-Sent Events feed (decision_update, position_update, run_paused, orchestrator_error, …) | | GET | /traces | AgentOS-served OTel span tree per cycle (T4) |

The same routes are also reachable under the /api/v1/* prefix; the unprefixed /api/* surface is the Phase-8 legacy mount and is kept for the dashboard's existing fetch URLs.

---

🗂️ Project Structure

Two apps in a monorepo: apps/backend/ (Python 3.11 / FastAPI / Agno) and apps/frontend/ (Next.js 14). Shared infra in docker-compose.yml. Strategy + architecture deep-dives under docs/.

Click for the full directory tree

omnitrade/
├── apps/
│   ├── backend/                      # Python 3.11 + FastAPI + SQLAlchemy 2.0
│   │   ├── src/omnitrade/
│   │   │   ├── domain/               # entities, protocols, pure services
│   │   │   ├── application/          # services, 5 monitors, multi-agent
│   │   │   ├── infrastructure/       # SQLAlchemy, ccxt, Agno DeepSeek, SSE
│   │   │   ├── agents/               # Agno Agent + MultiMCPTools, prompts
│   │   │   └── api/                  # FastAPI routers + middleware
│   │   ├── alembic/                  # migrations
│   │   └── tests/                    # structured output + integration tests
│   └── frontend/

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gong1414](https://github.com/gong1414)
- **Source:** [gong1414/omnitrade](https://github.com/gong1414/omnitrade)
- **License:** MIT
- **Homepage:** https://github.com/gong1414/omnitrade

Install and usage instructions live in the source repository linked above.