English Version:
A trading bot skill based on Futu OpenAPI that enables natural language trading. This skill encapsulates Futu's market quote and order execution APIs, allowing agents to perform real-time trading operations through simple commands or scripts. Perfect for implementing natural language trading strategies and automated workflows.
Important: Always use the encapsulated functions provided in this skill (e.g., submit_order, get_market_snapshot). Never call Futu SDK functions directly (ctx.place_order, ctx.get_market_snapshot), as this will bypass connection management, parameter validation, and error handling, leading to unpredictable failures and resource leaks.
Note to agent: When the user expresses any of these intents, you should use the encapsulated functions provided in this skill (e.g., get_account_info, get_market_snapshot, submit_order, etc.). Never call Futu SDK functions directly – always go through the skill's API.
Quick Start / 快速开始
Prerequisites / 前提条件:
Ensure Futu OpenD is running and HK quote entitlement is available.
确保富途OpenD正在运行且拥有港股行情权限。
When running inside a restricted agent sandbox (for example OpenClaw/Codex exec), prefer host / elevated mode.
The Futu Python SDK may access local OpenD resources during import, including the user log directory under ~/.com.futunn.FutuOpenD/Log, so restricted sandboxes may fail before business functions are called.
Run preflight_check first to verify config, OpenD connectivity, and sandbox/runtime readiness.
Call get_account_info() and select target account (get acc_id).
Pull quote/snapshot for the target symbol (default HK use case: HK.00700).
For real trading, call unlock_trade(...) (password from config or input).
Submit or manage orders with explicit acc_id and trd_env.
After real operation, call lock_trade() if needed.
Connection Lifecycle
Pull-style quote functions such as get_market_snapshot, get_stock_basicinfo, get_market_state, get_cur_kline, request_history_kline, and get_rt_ticker now close their quote context automatically after returning.
Trade functions such as submit_order, modify_order, and cancel_all_orders now close their trade/quote contexts automatically after returning.
Account functions such as get_account_info, unlock_trade, and lock_trade now close their contexts automatically after returning.
Subscription/callback flows keep the quote context open on purpose. For subscribe, unsubscribe, unsubscribe_all, query_subscription, set_quote_callback, and set_orderbook_callback, call close_quote_service() explicitly when you are done with the session.
Canonical Imports
python
# Always use these import paths – do not import from futu directly
from preflight_check import run_preflight
from strategy import (
StrategyState, TradeGuard, in_trading_window,
trading_window_status, cooldown_elapsed, holding_timeout_exceeded
)
from strategy_runtime import run_strategy
from account_manager import get_account_info, unlock_trade, lock_trade
from quote_service import (
get_stock_basicinfo, get_market_state, get_market_snapshot,
get_cur_kline, request_history_kline, get_rt_ticker,
subscribe, unsubscribe, unsubscribe_all, query_subscription,
set_quote_callback, set_orderbook_callback,
start_quote_stream, start_orderbook_stream
)
from trade_service import submit_order, modify_order, cancel_order, cancel_all_orders
Account Usage
Preflight
python
preflight = run_preflight()
if not preflight["success"]:
print(preflight)
raise SystemExit("Preflight failed")
python
# Get list of accounts
info = get_account_info()
if info['success']:
accounts = info['accounts']
print(accounts)
# Unlock trade (uses password from config or provided)
unlock_trade() # will prompt for password if not configured
# Or with explicit password:
# unlock_trade(password="your_password")
# Lock trade
lock_trade()
state = StrategyState()
guard = TradeGuard()
if in_trading_window(start_time="09:30", end_time="16:00"):
with guard.locked():
pass
Trade Usage
python
# Submit an order
result = submit_order(
code="HK.00700",
side="BUY",
qty=200,
acc_id=6017237, # from get_account_info
trd_env="SIMULATE", # or "REAL"
price=150, # required for LIMIT order
order_type="NORMAL",
)
# Modify order (change price/quantity)
modify_order(
op="NORMAL",
order_id="123456789",
trd_env="SIMULATE",
price=151,
qty=200,
acc_id=6017237
)
# Cancel a single order
cancel_order(order_id="123456789", trd_env="SIMULATE", acc_id=6017237)
# Cancel all orders
cancel_all_orders(trd_env="SIMULATE", acc_id=6017237)
Running a Background Trading Strategy (Using System Tools)
This skill does not manage long-running processes internally. Instead, you (the agent) should use system tools (e.g., exec, write, kill) to run strategy scripts in the background. This keeps the skill simple and leverages the platform's process management.
4.1 Workflow for Background Strategies
Run preflight first with PYTHONPATH=src python -m preflight_check.
If preflight reports sandbox/log-directory restrictions, rerun in host / elevated mode before using quote/trade functions.
Generate a Python script based on user's natural language request, using the encapsulated functions from this skill (e.g., start_quote_stream, submit_order, run_strategy).
Save the script to a temporary file (using the write tool or similar).
Launch the script as a background process using the exec tool, redirecting output to a log file.
Record the process ID (PID) and log file path for future monitoring.
Monitor/stop using system tools (ps, kill, cat).
4.2 Natural Language Triggers
User Request
Agent Action
“Start a strategy to monitor Tencent, buy below 540, sell above 550”
Generate script → save → launch with exec → return PID and log path
When generating a strategy script, use the following template. It handles signals, logging, and state persistence correctly.
python
#!/usr/bin/env python3
import sys
import time
import json
import os
import signal
import logging
from pathlib import Path
# If you installed the skill with `pip install -e .`, you can import modules directly.
# Only use sys.path/PYTHONPATH hacks when you didn't install the package.
from trade_service import submit_order
from quote_service import get_market_snapshot
# ===== Strategy parameters – fill by agent =====
# Replace these placeholders with your own strategy settings.
SYMBOL = "HK.00700"
ACC_ID = 0 # fill from get_account_info()
TRD_ENV = "SIMULATE" # default to SIMULATE; use REAL only with explicit confirmation
QTY = 0 # position sizing / order quantity
LOG_FILE = Path("strategy.log")
PID_FILE = Path("strategy.pid")
# ===============================================
logging.basicConfig(
filename=LOG_FILE,
level=logging.INFO,
format='%(asctime)s - %(levelname)s - %(message)s'
)
# Handle termination signals
def handle_exit(signum, frame):
logging.info("Received signal, stopping strategy")
sys.exit(0)
signal.signal(signal.SIGTERM, handle_exit)
signal.signal(signal.SIGINT, handle_exit)
# Write PID file
with open(PID_FILE, "w") as f:
f.write(str(os.getpid()))
logging.info(f"Strategy started: {SYMBOL}")
try:
while True:
snap = get_market_snapshot([SYMBOL])
if not snap["success"]:
logging.error(f"Quote failed: {snap['message']}")
time.sleep(60)
continue
price = snap["data"][0]["last_price"]
logging.info(f"Current price: {price}")
# --- Insert your strategy logic here ---
# Decide whether to trade based on your own signals/logic, then call submit_order(...).
time.sleep(60) # check every minute
except Exception as e:
logging.exception("Strategy crashed")
finally:
if PID_FILE.exists():
PID_FILE.unlink()
4.4 Agent Execution Steps
User: “Start a range strategy for Tencent, buy below 540, sell above 550.”
Agent:
Get account ID via get_account_info().
Generate script using the template above, filling in parameters.
Save script to a file, e.g., range_00700.py, using write tool.
Launch background process using exec:
bash
cd /path/to/workspace
nohup .venv/bin/python range_00700.py > strategy.out 2>&1 &
(Capture the PID from output.)
Record PID and log path.
Reply: “Strategy started. PID: 12345, log file: strategy_00700.log. You can check status or stop it anytime.”
4.5 Check Status
User: “How is my strategy doing?”
Agent:
Read last lines of log: tail -n 20 strategy_00700.log.
Check if process still running: ps -p 12345.
Summarize: “Strategy is running, last price was 542.5 at 10:30.”
4.6 Stop Strategy
User: “Stop my strategy.”
Agent:
Send SIGTERM: kill 12345.
Verify process ended, clean up PID file if needed.
Reply: “Strategy stopped.”
Error Handling
All functions return a dictionary with at least success (bool) and message (str).
On success, additional fields like data or order_id may be present.
Always check success first before using other fields.
Example:
python
result = submit_order(...)
if result["success"]:
print(f"Order ID: {result['order_id']}")
else:
print(f"Error: {result['message']}")
If OpenD connection fails, recheck:
OpenD is running (check port 11111 with lsof -i :11111)
Host/port in config.json matches OpenD
Account has necessary permissions
If the skill fails before quote/trade functions are even called, recheck:
Whether the current agent/tool is running in a restricted sandbox
Whether you should rerun in host / elevated mode
Whether the runtime can access the local Futu OpenD log directory under ~/.com.futunn.FutuOpenD/Log
Run PYTHONPATH=src python -m preflight_check first and follow its suggestions
Configuration
Config file: json/config.json
Required fields:
futu_api.host (default: 127.0.0.1)
futu_api.port (default: 11111)
futu_api.security_firm (e.g., FUTUSECURITIES)
Password handling:
Prefer trade_password_md5 (32‑char lowercase MD5)
Fallback to trade_password (will be MD5‑ed at runtime)
Account cache: json/account_info.json (auto‑generated after get_account_info)
📜 License
This skill is licensed under MIT-0 (MIT No Attribution).
