Content
# Helix Trader
A locally self-hosted **cryptocurrency market trading strategy** bot control and monitoring tool. Supports web, CLI, and agents like Codex/Claude for natural language invocation.
> Not investment advice. Trading cryptocurrency derivatives carries the risk of loss. It is recommended to verify on the testnet first and manage API keys and account security yourself.
> Trading is always executed on the user's local machine; this repository does not hold keys or run trades.
## Features
- Launch a local trading bot supporting trend-following and breakout momentum strategies
- Use CLI or MCP to query status, preview configurations, and start/stop the bot via natural language
- Defaults to testnet; live trading requires explicit local activation and user confirmation
- Optional web console for viewing status and trades
## Repository Structure
- `backend/`: FastAPI backend and Agent MCP/CLI (executed on the user's local machine)
- `frontend/`: Next.js console (optional)
- `docs/`: Beginner's guide, parameter explanations, and local launch instructions
- `examples/mcp/`: Local MCP configuration examples (skill plugins do not include this; see the directory README)
## Quick Start
New users follow the 10–15 minute guide: [docs/GETTING_STARTED_AGENT.md](docs/GETTING_STARTED_AGENT.md).
Recommended one-click initialization when downloading the repository:
```bash
bash scripts/setup_backend.sh
# Then edit backend/.env locally (JWT_SECRET, HELIX_USERNAME/PASSWORD, etc.)
```
Manual equivalent steps (use **Python 3.10+**, recommended 3.12; avoid macOS's default 3.9 `python3`):
```bash
cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env locally, do not submit real keys to the repository or public channels
# Fill in at least HELIX_USERNAME / HELIX_PASSWORD (or use ADMIN_*)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
Open another terminal:
```bash
cd backend
source .venv/bin/activate
python -m app.agent doctor
python -m app.agent login # Caches token to backend/.helix-agent-token
python -m app.agent mode # New processes can continue using cached login state
python -m app.agent strategies
python -m app.agent preview \
--strategy trend_following_core \
--exchange okx \
--symbol BTC/USDT:USDT \
--testnet
# Exit local login state: python -m app.agent logout
```
Saving exchange keys is a **two-step process**: fill in `.env` as the input source and then call to save and write to the backend database (otherwise, `mode` remains `not_configured`):
```bash
# 1) Recommended: edit backend/.env, fill in HELIX_EXCHANGE_API_KEY / HELIX_EXCHANGE_API_SECRET
# OKX also requires HELIX_EXCHANGE_PASSPHRASE, see docs/OKX_CREDENTIALS.md
# 2) Write to backend:
python -m app.agent save-credentials --exchange okx --testnet --confirm-save-credentials
# Or interactively input locally (skipping .env), avoid entering shell history
python -m app.agent save-credentials --exchange okx --testnet --prompt --confirm-save-credentials
# Or in a trusted private agent session, provide keys explicitly and let the agent call save_exchange_credentials
```
Launch MCP server:
```bash
cd backend
source .venv/bin/activate
python -m app.agent mcp
```
MCP setup instructions: [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
Configuration examples: [examples/mcp/](examples/mcp/).
## Common User Queries (Examples)
```text
Help me start this bot
```
```text
How do I start? Use the testnet first
```
```text
Help me start the bot, preview the configuration; just recommend one strategy
```
```text
Is this a simulation or live trading?
```
The agent should automatically complete the initial configuration and network probing; then inquire about the exchange (OKX/Binance), recommend a trend strategy, preview the configuration, and confirm before starting.
Key protection is a hard rule for the agent; no user reminder is needed. After successful initial configuration, it should actively ask if the user wants to start the local web console (see [docs/OPERATIONS.md](docs/OPERATIONS.md)).
## Agent Capabilities
| Capability | Description |
|------------|--------------|
| `doctor` | Check if the local environment is ready (does not echo keys) |
| `login` / `logout` | Login and cache token / clear local login state |
| `get_runtime_mode` | Determine if the current mode is testnet, live trading, or not configured, data from `/api/bot/status.use_testnet` |
| `list_strategies` / `explain_parameters` | View strategies and parameter explanations |
| `preview_bot_config` | Preview configuration before starting, no orders placed |
| `start_bot` | Start the bot; defaults to testnet |
| `get_bot_status` / `get_recent_trades` | View status and recent trades |
| `stop_bot` | Stop the bot; may require additional confirmation for simultaneous liquidation |
Detailed rules: [README_AGENT.md](README_AGENT.md)
Quick start for new users: [docs/GETTING_STARTED_AGENT.md](docs/GETTING_STARTED_AGENT.md)
Agent playbook: [docs/AGENT_PLAYBOOK.md](docs/AGENT_PLAYBOOK.md)
OKX credentials: [docs/OKX_CREDENTIALS.md](docs/OKX_CREDENTIALS.md)
MCP setup: [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
Troubleshooting: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
Parameter explanations: [docs/parameters.md](docs/parameters.md)
Security requirements: [SECURITY.md](SECURITY.md)
Local operations: [docs/OPERATIONS.md](docs/OPERATIONS.md)
## Security Highlights
- API key, secret, passphrase, and token should be placed in local environment variables or `.env`
- If the user explicitly chooses, keys can also be provided directly in a trusted private agent session; the tool will not echo complete keys
- Do not post keys in chat, GitHub issues, public posts, or any platform introductions
- Enabling live trading requires:
1. Local environment variable `HELIX_ALLOW_LIVE_TRADING=true`
2. Tool parameter `confirm_live_trading=true`
3. Explicit user confirmation
## Usage Instructions
- The user must deploy the backend locally; keys and trading accounts are managed by the user
- To confirm if the current mode is testnet or live trading, run `python -m app.agent mode`, do not rely on memory
- Switching from testnet to live trading: stop the bot, save live trading credentials, preview the configuration, and then confirm to start
- Complete `doctor` and configuration preview before considering starting the bot
- Optional web console instructions see [docs/OPERATIONS.md](docs/OPERATIONS.md)
