English | 简体中文

OmniTrade

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

Python FastAPI Next.js Agno License
Strategies Close Paths Fixtures Tests Exchanges
GitHub stars GitHub forks GitHub issues GitHub release last commit Codecov OpenSSF Scorecard

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

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 or a pull request — see CONTRIBUTING.md for the workflow and SECURITY.md for vulnerability reports (private channel only). Star the repo if you'd like to follow along.

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.

• 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/.
• 2026年04月26日 📚 Quickstart + FAQ — git clone → first cycle in <5 min walkthrough at docs/QUICKSTART.md, 11 common errors covered in docs/FAQ.md.
• 2026年04月26日 🤖 T10 — Trade-journal RAG — every cycle's structured reasoning is now ingested into ai.trade_journal (PgVector hybrid search) and auto-injected as context into subsequent cycles. Default embedder is local BAAI/bge-small-en-v1.5 (no API key needed).
• 2026年04月26日 🛑 T9 — HITL large-open gate — opens above HITL_OPEN_SIZE_THRESHOLD_USD (default 10ドル 000) pause via SSE and require operator approval through the dashboard banner.
• 2026年04月26日 🔭 T4 — OpenTelemetry tracing — every Agno run / model call / tool call emits a span via OpenInference's AgnoInstrumentor; visit GET /traces for the per-cycle span tree.

The shortest path from git clone to "the agent is trading on Gate.io testnet", in one paste-able block:

git clone https://github.com/gong1414/omnitrade.git && cd omnitrade && \
 cp apps/backend/.env.example .env && \
 echo "Edit .env now: set LLM_API_KEY (DeepSeek), GATE_API_KEY, GATE_API_SECRET" && \
 docker compose up -d && \
 curl -X POST http://localhost:8000/api/v1/cycle/trigger

Then open http://localhost:3000/dashboard. Full walkthrough at docs/QUICKSTART.md; common errors at docs/FAQ.md.

OmniTrade is an autonomous crypto-futures trading arena where 11 LLM-driven strategies compete for PnL on Gate.io or OKX perpetuals. Point it at a testnet, pick a strategy, and watch the agent reason about markets, size positions, and manage risk — with every decision verifiable via a structured output contract test suite.

• 11 named strategies — from arena-guardian (capital-preservation) through arena-raider-squad (multi-agent attack team) to arena-autopilot (fully autonomous LLM)
• 4-path close-path taxonomy — stop_loss, trailing_stop, partial_profit, ai_decision, plus none; enforced by a pure classifier and three 10-second monitors
• Atomic three-way state contract — cumulative_close_pct, stop_loss, trailing_peak_pnl_pct land in a single SQL UPDATE so the stop-loss monitor can never read a torn write
• Testnet by default — GATE_USE_TESTNET=true / OKX_USE_TESTNET=true out of the box; live trading requires explicit override
• Characterization gate — 22 frozen fixtures replay deterministically at ≥ 0.95 Decision-equivalent pass rate
• Real-time dashboard — Next.js 14 App Router + SWR + Server-Sent Events (EventSource) with exponential-backoff reconnect

• LLM agent researchers who want a non-toy benchmark — real exchange API, structured tool-calling under cost pressure, multi-agent coordination on a single PnL-driven loop.
• Quant tinkerers who treat "AI manages crypto futures" as a hobby project and want a complete stack to play with rather than building from scratch.
• Operators on testnet who want to study how an LLM behaves on real market data over weeks, before considering any mainnet exposure.
• Tooling/MCP authors who want a working example of MultiMCPTools driving 15 tools (9 trading + 6 crypto-data) under Agno.

OmniTrade is not for: people who want a turnkey money printer, traders looking for a copy-trade signal service, or anyone who can't afford to lose every dollar in the account.

• Paper-trade an LLM for weeks on Gate.io / OKX testnet, then read every cycle's reasoning to develop intuition for what the model actually understands.
• Compare strategies — run the same market window through arena-guardian vs arena-raider vs arena-tribunal and see how different prompt branches handle the same setup.
• Test new MCP tools — drop a new FastMCP server in infrastructure/mcp/, register it via MultiMCPTools, and watch the agent discover and call it.
• Stress-test agent reliability — the T7 ReliabilityEval lane and T8 AccuracyEval lane catch regressions in tool-calling fidelity (the "did the agent actually use its tools or fabricate the answer?" axis).
• Run a personal account on mainnet — only after weeks of testnet plus your own conviction. Treat it as a colleague who needs supervision, not an autopilot.

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.

Full parameter tables: docs/STRATEGIES.md.

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

Full rules + truth table: apps/backend/src/omnitrade/domain/services/close_path_classifier.py.

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

# 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

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/RELEASE_CHECKLIST.md.

• 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

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 with documenting comments per row.

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 (中文).

flowchart TD
 api[api<br/>FastAPI + middleware + DI]
 app[application<br/>services, monitors, orchestrators]
 dom[(domain<br/>entities, protocols, pure services)]
 infra[infrastructure<br/>SQLAlchemy, ccxt, Agno DeepSeek, sqlite-vec]
 agents[agents<br/>Agno Agent + MultiMCPTools + Team]
 api --> app
 app --> dom
 app --> agents
 infra --> dom
 agents --> dom
 classDef dom fill:#fef3c7,stroke:#f59e0b
 class dom dom

flowchart LR
 L1[trading_loop<br/>AgentOS scheduler */TRADING_INTERVAL] --> DB[(Postgres + pgvector)]
 L2[account_recorder<br/>cron */ACCOUNT_INTERVAL] --> DB
 L3[trailing_stop<br/>10 s] --> DB
 L4[stop_loss<br/>10 s] --> DB
 L5[partial_profit<br/>10 s atomic 3-way UPDATE] --> DB
 style L5 stroke:#dc2626,stroke-width:3px

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).

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

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/.

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/ # Next.js 14 + SWR + Server-Sent Events
├── tests/fixtures/frozen/ # 22 hand-curated decision contracts
├── docs/ # architecture, strategies, release, ADRs
├── assets/ # logo + social preview + sponsor QR
├── scripts/ # ops + drift-detection probes
└── docker-compose.yml # postgres + pgvector + db-init + backend + frontend

Issues and PRs welcome. Please:

1. Run uv run pytest inside apps/backend — the 702-test suite must stay green, and the 22 frozen fixtures must replay at ≥ 0.95.
2. The Agno cutover (Stages A–E, see docs/AGNO_MIGRATION_TRACKER.md) removed every LangGraph / LangChain / LiteLLM / mcp2py / WebSocket consumer — keep them out of new code.
3. Respect the three-way state atomicity — any code path that writes a position's cumulative_close_pct, stop_loss, or trailing_peak_pnl_pct must go through PositionRepository.apply_three_way_state.
4. Keep new dependencies within the allow-list (MIT / Apache-2.0 / BSD / ISC / MPL-2.0). See docs/LICENSE_INVENTORY.md.

OmniTrade is a solo / volunteer-maintained open-source project. If it saves you time or makes you money on testnet (and eventually mainnet), a small tip is genuinely appreciated — it pays for LLM API credits, server time, and the occasional tank of caffeine.

USDT (Tron · TRC20)

TMDnFG8KBxNvkgNgqkr9PhL2keNczjSGdS

⚠️ Network warning: This is a TRON (TRC20) address. Sending USDT (or anything else) on a different network — Ethereum / ERC20, BSC / BEP20, Polygon, Arbitrum, Solana, etc. — will result in lost funds with no recovery. Verify your wallet is set to Tron before sending. Always copy-paste the address; a single character changed is a different wallet.

No expectation, no obligation, no donor list, no tax-deductible guarantees — just a way for people who want to say thanks. If you'd prefer to support via GitHub Sponsors / Open Collective once those are set up, open an issue to nudge.

Star History Chart

MIT — see LICENSE.

Testnet is the default and the recommended mode. Live trading on mainnet carries a real risk of total loss of funds. The maintainers are not financial advisors; nothing in this repository constitutes financial advice. Use at your own risk.

OmniTrade is built on ~30 open-source projects — full stack from agent runtime (Agno + FastMCP + OpenInference) to backend (FastAPI + SQLAlchemy + Postgres + pgvector + ccxt) to frontend (Next.js + React + Tailwind + Recharts) to tooling (uv + Ruff + pytest + Playwright). Huge thanks to all the maintainers — please go star their repos.

If we missed your project, please open an issue and we'll add you in.