Production-Grade Agent Runtime for Crypto Trading Research & Execution
中文文档 · English Summary · Documentation · API · User Manual · Developer Guide
HyperTrade is a self-hosted Agent runtime that connects LLM-powered reasoning with governed access to crypto market data, strategy backtesting, paper trading, and risk-gated Testnet execution. It provides a unified environment for systematic trading research — from natural language exploration to evidence-backed strategy iteration.
| Domain | Capability |
|---|---|
| Market Intelligence | Real-time OKX SWAP data, multi-source indicators, global market regime classification |
| Strategy Research | Backtrader backtests, multi-variant experiments, evidence library with automatic gating |
| Paper Trading | Full lifecycle simulation with pause/resume/close/reset controls |
| Testnet Execution | Approval-gated OKX Testnet orders with risk checks (mainnet blocked in V1) |
| BitPro Integration | MCP adapter for strategy lifecycle, backtest diagnostics, and paper monitoring |
| Knowledge Systems | RAG retrieval over docs/knowledge with pgvector, audited Memory persistence |
| Governance | Policy-enforced tool registry, approval gates, idempotency, deterministic evals |
Disclaimer: Nothing in this repository constitutes investment advice. Mainnet live order execution is blocked in V1.
┌─────────────────────────────────────────────────────────────────────┐
│ Client Layer │
│ CLI (ht) · Web Console (/harness) · REST/SSE API · External Agents │
├─────────────────────────────────────────────────────────────────────┤
│ Agent Runtime │
│ Graph Kernel · Provider Router · Tool Executor │
├─────────────────────────────────────────────────────────────────────┤
│ Governance Layer │
│ ToolRegistry · Risk Policy · Approval Gates · Audit Trace │
├─────────────────────────────────────────────────────────────────────┤
│ Service Layer │
│ Market · RAG · Memory · Strategy · Backtest · World Model │
├─────────────────────────────────────────────────────────────────────┤
│ Data Layer │
│ PostgreSQL/pgvector · OKX API · BitPro MCP · Alpha Vantage │
└─────────────────────────────────────────────────────────────────────┘
| Layer | Technologies |
|---|---|
| Runtime | Python 3.12+, FastAPI, SQLAlchemy, Alembic |
| Agent Engine | Graph-based kernel, provider routing, policy-enforced tool execution |
| Frontend | React 18, TypeScript 5, Vite, TanStack Query, Recharts |
| Database | PostgreSQL 14+ with pgvector (or SQLite for development) |
| LLM Providers | Vide Coding (opus-4.6), DeepSeek, OpenAI, Codex, OpenRouter, Qwen |
| Backtesting | Backtrader |
| Infrastructure | Docker Compose, Nginx, GitHub Actions CI/CD |
| Capability | Description | Status |
|---|---|---|
| Natural Language | Free-form prompts routed to LLM planner with automatic tool selection | Production |
| Tool Calling | Registry-based execution with scope, approval, and idempotency enforcement | Production |
| Market Intelligence | OKX SWAP tickers, candles, funding, OI, relative strength indicators | Production |
| Global Market | Cross-asset regime classification (equities, volatility, FX, rates) | Production |
| RAG | pgvector-backed citation search over knowledge documents | Production |
| Memory | Audited observations with tags, confidence scoring, and importance weighting | Production |
| Strategy Research | Backtrader backtests, multi-variant experiments, evidence library | Production |
| BitPro Integration | MCP adapter for strategy lifecycle, backtest diagnostics, paper monitoring | Production |
| Paper Trading | Simulated execution with full lifecycle controls | Production |
| Testnet Execution | Approval-gated OKX Testnet orders with risk validation | Production |
| Monitoring & Alerts | Read-only monitors for paper strategies, connector health, library freshness | Production |
| Evaluation Suite | Deterministic evals for tool choice, RAG, Memory, risk, report quality | Production |
| World Model | Portfolio state tracking and defensive action scheduling | Experimental |
- Python 3.12+ with
uvpackage manager - Node.js 18+ with
pnpm - API key for at least one chat provider (Vide Coding, DeepSeek, OpenAI, etc.)
- PostgreSQL 14+ with pgvector (recommended) or SQLite for development
git clone git@github.com:Shadowell/HyperTrade.git
cd HyperTrade
cp .env.example .env
# Edit .env with your API keysBackend (API server):
uv run uvicorn hypertrade.main:app --app-dir backend/src --host 0.0.0.0 --port 3334Frontend (Web console):
npm exec --yes pnpm@10 -- -C frontend install
npm exec --yes pnpm@10 -- -C frontend devCLI (command-line interface):
uv run ht --local| Service | URL |
|---|---|
| Web Console | http://localhost:3333/harness |
| API Docs (Swagger) | http://localhost:3334/docs |
| Health Check | http://localhost:3334/api/health |
docker compose up -d postgres
export DATABASE_URL="postgresql://hypertrade:hypertrade@localhost:5432/hypertrade"
uv run alembic upgrade head# Natural language queries
uv run hypertrade --local ask "看下目前市场的热度怎么样"
# Structured commands
/price ETH
/candles BTC 1H 120
/compare ETH SOL BTC
/global-market # Cross-asset regime snapshot/research 研究ETH趋势突破策略 # Create research record
/backtest # Run Backtrader backtest
/experiment 不同参数动量策略 # Multi-variant experiment
/strategy library momentum_v1 # Query aggregated evidence# Query backtest performance
查看 BitPro 回测收益大于100%的策略有哪些
# Inspect backtest details
查看 BitPro 回测 result 196 的权益曲线和交易证据
# Monitor live paper strategies
监控 BitPro 所有运行中的模拟盘策略，列出异常和数据缺口/paper # Status overview
/paper pause BTC # Pause a strategy
/paper resume # Resume all
/paper close # Close positions
/paper reset # Reset simulation/live intent ETH buy 0.01 reason="API smoke test"
/live intents # List pending intents
/live approve loi_abc123 # Approve for execution
/live execute loi_abc123 # Submit to OKX Testnet/rag 风控 # Semantic search over knowledge base
/memory search tag:strategy # Query audited memory# Streaming agent run
curl -N -X POST http://localhost:3334/api/agent/runs/stream \
-H "Content-Type: application/json" \
-d '{"prompt":"请做行情归纳"}'
# RAG search
curl "http://localhost:3334/api/rag/search?query=风控&limit=5"
# Memory query
curl "http://localhost:3334/api/memory?query=市场&limit=10"
# Market snapshot
curl http://localhost:3334/api/global-market/snapshot| Document | Description |
|---|---|
| API Reference | Complete REST/SSE API documentation |
| User Manual | Operator guide for all surfaces (CLI, Web, API) |
| Developer Guide | Extending HyperTrade with tools, providers, connectors |
| Documentation Index | Full documentation map |
| Architecture Docs | System design and module documentation (20+ docs) |
| Product Spec | Vision, scope, and roadmap |
| Knowledge Base | Operator guides and best practices |
| Runbooks | Deployment, monitoring, incident response |
Chinese translations available for all primary documents.
./scripts/check.sh # Full suite: tests, lint, type-check
uv run pytest tests/ -v # Run specific testsPython:
uv run ruff format . # Auto-format
uv run ruff check . # Lint
uv run mypy backend/src # Type-checkFrontend:
npm exec --yes pnpm@10 -- -C frontend lint
npm exec --yes pnpm@10 -- -C frontend formatDeterministic evals guard against regressions across tool choice, RAG citations, Memory behavior, risk refusal, BitPro source-of-truth usage, and report quality.
uv run ht --local /evals
curl http://localhost:3334/api/evals/statusAutomated deployment via GitHub Actions to a self-hosted runner on push to main.
# Manual deployment
ssh hypertrade-server
sudo -u hypertrade /opt/hypertrade/deploy/deploy.sh
# Post-deploy verification
curl -fsS http://localhost:3334/api/health
hypertrade ask "看下ETH行情"See Runbooks for detailed deployment and monitoring procedures.
- Secrets: API keys, tokens, and credentials managed via environment variables; never committed
- BitPro Boundary: All BitPro access through stable MCP/API contracts only
- Audit Trail: Every tool execution logged with timestamp, payload, and provenance
- Idempotency: Write operations require idempotency keys
- Approval Gates: Human-in-the-loop for Testnet orders and destructive operations
- Testnet First: Mainnet live execution blocked in V1
| Initiative | Status |
|---|---|
| World Model — portfolio state and defensive actions | In Progress |
| Global Market — cross-asset regime classification | Production |
| Vide Coding (opus-4.6) provider | Production |
| Enhanced output formatting | Complete |
- Multi-Agent collaboration patterns
- Custom strategy DSL
- Multi-exchange support (Binance, Bybit)
- Advanced risk modeling (VaR, CVaR)
- Mainnet execution framework (pending governance)
- Review active sprint scope in
docs/contracts/ - Keep changes within contract scope
- Run
./scripts/check.shbefore committing - Commit to
main(no feature branches in current workflow) - Push triggers automatic CI/CD deployment
See Developer Guide for detailed contribution guidelines.
Built with these excellent projects and services:
OKX API · Backtrader · FastAPI · LangGraph · React · Vite · pgvector · Alembic