ValueCell-ai · hazeone · Nov 3, 2025 · Nov 3, 2025 · Nov 3, 2025 · Nov 3, 2025
diff --git a/.env.example b/.env.example
@@ -68,6 +68,19 @@ OPENAI_COMPATIBLE_BASE_URL=
 # You can set this to any valid email address.
 SEC_EMAIL=
 
+# ============================================
+# Auto Trading Agent Configurations
+# ============================================
+# OKX exchange API.
+OKX_NETWORK=paper
+OKX_API_KEY=
+OKX_API_SECRET=
+OKX_API_PASSPHRASE=
+OKX_ALLOW_LIVE_TRADING=false
+OKX_MARGIN_MODE=cash
+OKX_USE_SERVER_TIME=false
+
+
 
 # ============================================
 # Third-Party Agent Configurations
@@ -82,4 +95,4 @@ FINNHUB_API_KEY=
 # Additional Configurations
 # ============================================
 # Optional: Set your https://xueqiu.com/ token if YFinance data fetching becomes unstable.
-# XUEQIU_TOKEN=
+# XUEQIU_TOKEN=
diff --git a/README.md b/README.md
@@ -83,6 +83,7 @@ Welcome to join our Discord community to share feedback and issues you encounter
 - **Multiple LLM Providers**: Support OpenRouter, SiliconFlow, Google and OpenAI 
 - **Popular Market Data**: Cover US market, Crypto market, Hong Kong market, China market and more
 - **Multi-Agent Framework Compatible**: Support Langchain, Agno by A2A Protocol for research and development integration
+- **Exchange Connectivity**: Optional live routing to OKX with built-in guardrails
 
 # Quick Start
 
@@ -156,6 +157,12 @@ If it has been a long time since the last update, you can delete the database fi
 
 Once the application is running, you can explore the web interface to interact with ValueCell's features and capabilities.
 
+## Live Trading (OKX Preview)
+
+- Set `AUTO_TRADING_EXCHANGE=okx` and populate the required `OKX_*` credentials in `.env` (see [Configuration Guide](docs/CONFIGURATION_GUIDE.md) and [OKX Setup](docs/OKX_SETUP.md)).
+- Start the stack with `./start.sh` after configuring the environment.
+- Keep `OKX_ALLOW_LIVE_TRADING=false` until strategies pass paper trading validation and stakeholders approve mainnet deployment.
+
 ---
 
 **Note**: Ensure all prerequisites are installed and environment variables are properly configured before running the application.

diff --git a/docs/CONFIGURATION_GUIDE.md b/docs/CONFIGURATION_GUIDE.md
@@ -21,12 +21,12 @@ This hierarchy allows you to:
 
 ValueCell supports multiple LLM providers. Choose at least one:
 
-| Provider | Sign Up |
-|----------|---------|
-| **OpenRouter** | [openrouter.ai](https://openrouter.ai/) |
-| **SiliconFlow** | [siliconflow.cn](https://www.siliconflow.cn/) |
-| **Google** | [ai.google.dev](https://ai.google.dev/) |
-| **OpenAI** | [platform.openai.com](https://platform.openai.com/) |
+| Provider        | Sign Up                                             |
+| --------------- | --------------------------------------------------- |
+| **OpenRouter**  | [openrouter.ai](https://openrouter.ai/)             |
+| **SiliconFlow** | [siliconflow.cn](https://www.siliconflow.cn/)       |
+| **Google**      | [ai.google.dev](https://ai.google.dev/)             |
+| **OpenAI**      | [platform.openai.com](https://platform.openai.com/) |
 
 ### Step 2: Configure .env File
 
@@ -485,11 +485,23 @@ models:
 
 ### Pattern 3: Development vs Production
 
-```bash
-# .env.development
-OPENROUTER_API_KEY=sk-or-v1-dev-xxxxx
-APP_ENVIRONMENT=development
+### OKX Trading
+
+| Variable                 | Default | Description                                                        |
+| ------------------------ | ------- | ------------------------------------------------------------------ |
+| `OKX_NETWORK`            | `paper` | Choose `paper` for demo trading or `mainnet` for live environment. |
+| `OKX_API_KEY`            | —       | OKX API key generated from the OKX console.                        |
+| `OKX_API_SECRET`         | —       | API secret corresponding to the key.                               |
+| `OKX_API_PASSPHRASE`     | —       | Passphrase set when creating the OKX API key.                      |
+| `OKX_ALLOW_LIVE_TRADING` | `false` | Must be `true` before routing orders to the mainnet environment.   |
+| `OKX_MARGIN_MODE`        | `cash`  | Trading mode passed to OKX (`cash`, `cross`, `isolated`).          |
+| `OKX_USE_SERVER_TIME`    | `false` | Enable to sync with OKX server time for order stamping.            |
 
+> [!IMPORTANT]
+> Keep `OKX_ALLOW_LIVE_TRADING=false` until strategies are validated on the OKX paper environment. Treat API secrets as production credentials and store them in a secure vault.
+
+## Troubleshooting
+```bash
 # .env.production  
 OPENROUTER_API_KEY=sk-or-v1-prod-xxxxx
 SILICONFLOW_API_KEY=sk-prod-xxxxx

diff --git a/docs/OKX_SETUP.md b/docs/OKX_SETUP.md
@@ -0,0 +1,50 @@
+# OKX Setup Guide
+
+Use this checklist to enable the Auto Trading agent to route spot orders through OKX. Start with the paper environment before touching mainnet funds.
+
+## 1. Create API Credentials
+- Log in to the OKX console → *API* → *Create V5 API key*.
+- Enable **Trade** permission. Withdrawals are not required for trading.
+- Record the **API Key**, **Secret Key**, and **Passphrase** immediately; you will not be able to view the secret again.
+- For paper trading, toggle the **Demo trading** switch when generating the key (or set `flag=0` by using the paper environment).
+
+## 2. Configure Environment Variables
+Add the following entries to `.env` (or export them before launching):
+
+```bash
+AUTO_TRADING_EXCHANGE=okx
+OKX_NETWORK=paper            # change to mainnet after validation
+OKX_API_KEY=your_api_key
+OKX_API_SECRET=your_secret
+OKX_API_PASSPHRASE=your_passphrase
+OKX_ALLOW_LIVE_TRADING=false
+OKX_MARGIN_MODE=cash         # use cross / isolated for margin derivatives
+OKX_USE_SERVER_TIME=false    # set true if you see timestamp drift errors
+```
+
+## 3. Launch the Stack
+- Install dependencies: `uv sync --group dev` and `bun install --cwd frontend` (first run only).
+- Start services with paper overrides:
+
+  ```bash
+  ./start.sh --exchange okx --network paper
+  ```
+
+- This propagates the environment into `python/scripts/launch.py`, ensuring the Auto Trading agent connects with paper credentials.
+
+## 4. Validate Paper Trading
+1. Trigger the Auto Trading agent via the UI (http://localhost:1420) or CLI and request trades such as “Trade BTC-USD with 5000 USD on OKX”.
+2. Watch the logs under `logs/<timestamp>/AutoTradingAgent.log` for entries like `exchange=okx` and `status=filled`.
+3. Open https://www.okx.com/paper/account/trade to confirm the orders appear in the simulated environment.
+4. Run the OKX unit tests locally: `uv run python -m pytest valuecell/agents/auto_trading_agent/tests/test_okx_exchange.py`.
+
+## 5. Promote to Mainnet (Optional and High Risk)
+- Flip `OKX_NETWORK=mainnet` and `OKX_ALLOW_LIVE_TRADING=true` only after paper validation and formal approval.
+- Restart with `./start.sh --exchange okx --network mainnet --allow-live-trading`.
+- Monitor fills and balances continuously; revert the toggle if behaviour is unexpected.
+
+## 6. Safety Best Practices
+- Store secrets in a vault (1Password, AWS Secrets Manager, etc.) and inject them at runtime instead of committing to disk.
+- Rotate keys periodically and whenever you suspect compromise.
+- Set conservative order sizes (`risk_per_trade`) and verify instrument availability (`BTC-USDT`, `ETH-USDT`, etc.) before relying on automation.
+- Archive trading logs for audit purposes and switch the system back to paper mode when not actively monitoring.
diff --git a/python/README.md b/python/README.md
@@ -55,3 +55,19 @@ uv venv --python 3.12 && uv sync && uv pip list
 
 - Python >= 3.12
 - Dependencies managed via `pyproject.toml`
+
+## OKX Trading (Preview)
+
+Add OKX credentials to `.env` (or export them before launch):
+
+```bash
+AUTO_TRADING_EXCHANGE=okx
+OKX_NETWORK=paper          # switch to mainnet only after validation
+OKX_API_KEY=...
+OKX_API_SECRET=...
+OKX_API_PASSPHRASE=...
+OKX_ALLOW_LIVE_TRADING=false
+OKX_MARGIN_MODE=cash       # or cross / isolated
+```
+
+Launch with `./start.sh --exchange okx --network paper` to route the Auto Trading agent through OKX. Flip `OKX_ALLOW_LIVE_TRADING=true` only when you're ready for real execution.
diff --git a/python/pyproject.toml b/python/pyproject.toml
@@ -9,6 +9,7 @@ description = "ValueCell is a community-driven, multi-agent platform for financi
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
+    "python-okx>=0.4.0",
     "pytz>=2023.3",
     "python-dateutil>=2.8.2",
     "fastapi>=0.104.0",

diff --git a/python/scripts/launch.py b/python/scripts/launch.py
@@ -49,6 +49,17 @@
 PYTHON_DIR_STR = PYTHON_DIR.as_posix()
 ENV_PATH_STR = ENV_PATH.as_posix()
 
+AUTO_TRADING_ENV_OVERRIDES = {
+    "AUTO_TRADING_EXCHANGE": os.getenv("AUTO_TRADING_EXCHANGE"),
+}
+AUTO_TRADING_ENV_PREFIX = " ".join(
+    f"{key}={value}"
+    for key, value in AUTO_TRADING_ENV_OVERRIDES.items()
+    if value not in (None, "")
+)
+if AUTO_TRADING_ENV_PREFIX:
+    AUTO_TRADING_ENV_PREFIX = f"{AUTO_TRADING_ENV_PREFIX} "
+
 # Mapping from agent name to launch command
 MAP_NAME_COMMAND: Dict[str, str] = {}
 for name, analyst in MAP_NAME_ANALYST.items():
@@ -62,7 +73,7 @@
     f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.research_agent"
 )
 MAP_NAME_COMMAND[AUTO_TRADING_AGENT_NAME] = (
-    f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.auto_trading_agent"
+    f"{AUTO_TRADING_ENV_PREFIX}uv run --env-file {ENV_PATH_STR} -m valuecell.agents.auto_trading_agent"
 )
 MAP_NAME_COMMAND[NEWS_AGENT_NAME] = (
     f"uv run --env-file {ENV_PATH_STR} -m valuecell.agents.news_agent"