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”
• 策略运行：

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. 1. Install this skill via ClawHub (if not installed yet):

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

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

1. 3. Create virtual environment (recommended):

1. 4. Install package:

1. 5. Configure credentials:

依赖项

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

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

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

Module Map

• - Account: INLINECODE22

• - Quote: INLINECODE26

• - Trade: INLINECODE39

• - Strategy Runtime: INLINECODE44

• - Strategy Helpers: INLINECODE46

Standard Workflow

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

CODEBLOCK5

Account Usage

Preflight

CODEBLOCK7

Quote Usage

Basic Info / Market State

Snapshot (no subscription needed)

K-Line

Ticker

Subscription & Callbacks

Unified Stream Startup

Strategy Helpers

Trade Usage

CODEBLOCK15

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

CODEBLOCK16

4.4 Agent Execution Steps

User: “Start a range strategy for Tencent, buy below 540, sell above 550.”

Agent:

1. 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 &
   

1. 5. Record PID and log path.
2. 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:
CODEBLOCK18

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 INLINECODE107
• Run PYTHONPATH=src python -m preflight_check first and follow its suggestions

Configuration

• - Config file: INLINECODE109
• Required fields:

• - Password handling:

• - Account cache: json/account_info.json (auto‑generated after get_account_info)

📜 License

This skill is licensed under MIT-0 (MIT No Attribution).