# Omnitrade > OmniTrade: LLM-driven crypto futures arena — 11 competing strategies on Agno + AgentOS, atomic three-way state, real-time SSE dashboard. - **Type:** MCP server - **Install:** `agentstack add mcp-gong1414-omnitrade` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [gong1414](https://agentstack.voostack.com/s/gong1414) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [gong1414](https://github.com/gong1414) - **Source:** https://github.com/gong1414/omnitrade - **Website:** https://github.com/gong1414/omnitrade ## Install ```sh agentstack add mcp-gong1414-omnitrade ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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](https://github.com/gong1414/omnitrade/releases/tag/v0.1.0). - **2026-04-26** 🛡️ **OSS quality batch** — Dependabot + CodeQL security scanning, branch protection on main, GitHub Pages live at [docs](https://gong1414.github.io/omnitrade/), full ADR collection under [`docs/adr/`](docs/adr/). - **2026-04-26** 📚 **Quickstart + FAQ** — `git clone → first cycle in `HITL_OPEN_SIZE_THRESHOLD_USD` (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: close_path_classifier.py • 10-s monitors: trailing-stop, stop-loss, partial-profit • AI closes via close_position / partial_close 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/close_path_classifier.py). --- ## 🚀 Get Started ### Path A · Docker (zero setup) ```bash 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: ```bash 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) ```bash # 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 ```bash 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](./docs/RELEASE_CHECKLIST.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`](https://github.com/astral-sh/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 ```mermaid 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: ```mermaid 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 ```bash 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-gong1414-omnitrade - Seller: https://agentstack.voostack.com/s/gong1414 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.