Futu Trade Bot Skills 📈

🎯 Overview / 概述

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.

中文版本: 基于富途牛牛API接口的交易机器人技能，帮助用户用自然语言进行交易。本技能已将富途牛牛的行情报价、下单交易等功能做了完整封装，可供智能助手随时调用。建议通过命令行或脚本来实现自然语言的策略生成和交易执行。

重要提示：请始终使用本技能提供的封装函数（如 submit_order、get_market_snapshot）。切勿直接调用富途SDK的原始函数（例如 ctx.place_order），否则会绕过连接管理、参数校验和错误处理，导致不可预料的失败和资源泄漏。

When to Use This Skill / 使用场景

Use this skill when the user asks in natural language, for example:

• 账户相关：“查一下我的账户余额”、“解锁交易”、“锁定账户”、“看看我有哪些账户”
• 行情查询：“腾讯现在多少钱？”、“查一下港交所的实时报价”、“帮我看看美团今天的K线图”
• 数据拉取：“获取腾讯的历史K线数据”、“拉取最近10笔成交”
• 订阅与回调：“实时监控腾讯的报价”、“给我推送腾讯的逐笔成交”
• 下单交易：“帮我买100股腾讯，限价350”、“卖出200股阿里”、“撤单”、“把订单价格改到355”
• 策略运行：
  • “帮我写一个区间策略，监控腾讯，低于540买入，高于550卖出”
  • “启动这个策略”
  • “我的策略跑得怎么样了？”
  • “停止我的策略”

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.
• 如果在受限的 agent 沙箱中运行（例如 OpenClaw/Codex exec），优先使用 host / elevated 模式。
• 富途 Python SDK 在导入阶段就可能访问本机 OpenD 相关资源，包括 ~/.com.futunn.FutuOpenD/Log 下的日志目录；因此受限沙箱可能会在业务函数执行前就失败。

Setup Steps / 安装步骤:

1. Install this skill via ClawHub (if not installed yet):

   clawhub install futu-trading-bot
   

2. Enter the skill folder (default OpenClaw workspace path):

   cd ~/.openclaw/workspace/skills/futu-trading-bot
   

   If you installed to a different location, cd into that folder instead.

3. Create virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate
   

4. Install package:

   pip install -e .
   

5. Configure credentials:

   cp json/config_example.json json/config.json
   # Edit json/config.json with your Futu credentials
   # 编辑json/config.json填写你的富途账户信息
   

依赖项

本技能通过 pip install -e . 自动安装以下核心 Python 包：

• futu-api（富途 SDK）
• pydantic（数据校验）

更多依赖请以 pyproject.toml / requirements.txt 为准。

Module Map

• Account: account_manager
  • get_account_info()
  • unlock_trade(password=None, password_md5=None)
  • lock_trade()
• Quote: quote_service
  • Stage 1: get_stock_basicinfo, get_market_state
  • Stage 2: subscribe, unsubscribe, unsubscribe_all, query_subscription, callbacks
  • Stage 3: get_market_snapshot, get_cur_kline, request_history_kline, get_rt_ticker
  • Stage 4: start_quote_stream, start_orderbook_stream
• Trade: trade_service
  • submit_order, modify_order, cancel_order, cancel_all_orders
• Strategy Runtime: strategy_runtime
  • run_strategy
• Strategy Helpers: strategy
  • in-memory state
  • trade guard / lock
  • trading window and cooldown helpers

Standard Workflow

1. Run preflight_check first to verify config, OpenD connectivity, and sandbox/runtime readiness.
2. Call get_account_info() and select target account (get acc_id).
3. Pull quote/snapshot for the target symbol (default HK use case: HK.00700).
4. For real trading, call unlock_trade(...) (password from config or input).
5. Submit or manage orders with explicit acc_id and trd_env.
6. 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

# 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

preflight = run_preflight()
if not preflight["success"]:
    print(preflight)
    raise SystemExit("Preflight failed")

# 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()

Quote Usage

Basic Info / Market State

get_stock_basicinfo(market="HK", sec_type="STOCK", code_list=["HK.00700"])
get_market_state(["HK.00700"])

Snapshot (no subscription needed)

snap = get_market_snapshot(["HK.00700"])
if snap['success']:
    price = snap['data'][0]['last_price']

K-Line

# Current K-line (requires subscription, will auto-subscribe if needed)
kline = get_cur_kline(code="HK.00700", num=5, ktype="K_DAY", autype="QFQ")

# Historical K-line
hist = request_history_kline(
    code="HK.00700",
    start="2026-02-20",
    end="2026-03-06",
    ktype="K_DAY"
)

Ticker

tickers = get_rt_ticker(code="HK.00700", num=10)

Subscription & Callbacks

def on_quote(payload):
    print(payload)

set_quote_callback(on_quote)
subscribe(["HK.00700"], ["QUOTE"], is_first_push=True, subscribe_push=True)
query_subscription()
unsubscribe(["HK.00700"], ["QUOTE"])
unsubscribe_all()
close_quote_service()

Unified Stream Startup

def on_quote(payload):
    print(payload)

start_quote_stream(["HK.00700"], on_quote)

Strategy Helpers

state = StrategyState()
guard = TradeGuard()

if in_trading_window(start_time="09:30", end_time="16:00"):
    with guard.locked():
        pass

Trade Usage

# 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

1. Run preflight first with PYTHONPATH=src python -m preflight_check.
2. If preflight reports sandbox/log-directory restrictions, rerun in host / elevated mode before using quote/trade functions.
3. 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).
4. Save the script to a temporary file (using the write tool or similar).
5. Launch the script as a background process using the exec tool, redirecting output to a log file.
6. Record the process ID (PID) and log file path for future monitoring.
7. Monitor/stop using system tools (ps, kill, cat).

4.2 Natural Language Triggers

4.3 Script Template (for Agent Reference)

When generating a strategy script, use the following template. It handles signals, logging, and state persistence correctly.

#!/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:

1. Get account ID via get_account_info().
2. Generate script using the template above, filling in parameters.
3. Save script to a file, e.g., range_00700.py, using write tool.
4. Launch background process using exec:

   cd /path/to/workspace
   nohup .venv/bin/python range_00700.py > strategy.out 2>&1 &
   

   (Capture the PID from output.)
5. Record PID and log path.
6. 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:

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).

Copyright © 2026 jeffersonling1217-png