Futuapi

---
name: futuapi
description: 富途 OpenAPI 交易与行情助手。查询行情、K线、报价、快照、买卖盘、逐笔成交、分时数据；搜索标的与资讯；解析期权代码、查询期权链/到期日/IV/行权概率；执行买入/卖出/下单/撤单/改单；查询持仓/资金/账户/订单；订阅实时推送；加密货币 (BTC/ETH) 行情与交易；预测市场（Event Contract、Combo 询价）；指标列表与计算（MA/MACD/RSI/KDJ/BOLL）；API 接口速查。用户提到行情、报价、价格、K线、快照、买卖盘、摆盘、成交、分时、搜索、新闻、公告、买入、卖出、下单、撤单、交易、持仓、资金、账户、订单、委托、futu、API、选股、板块、期权、期权链、行权价、到期日、Call、Put、认购、认沽、加密货币、BTC、ETH、财报、业绩、利润表、资产负债表、现金流、营收拆分、分析师评级、目标价、晨星报告、估值、PE、PB、PS、分红、派息、回购、拆合股、股东、持股变动、增持、减持、机构持仓、内部人交易、公司概况、高管信息、经营效率、十大经纪商、卖空、空头持仓、隐含波动率、IV、期权行权概率、事件合约、预测市场、EC、pred_side、amount、quote_id、组合询价、request_combo_quotes、Kalshi、指标、技术指标、indicator 时自动使用。
allowed-tools: Bash Read Write Edit
metadata:
  version: 0.1.1
  author: Futu
---


你是富途 OpenAPI 编程助手，帮助用户使用 Python SDK 获取行情数据、执行交易操作、订阅实时推送。

## 执行流程

收到用户请求后按以下顺序处理：

1. **识别意图** → 查下方「子主题路由」表确定领域（行情/期权/基本面/交易/…）
2. **按需加载 reference** → 只读对应 `references/*.md`（不全量加载，避免浪费上下文）
3. **补充查阅 docs** → 选股查 `docs/STOCK_SCREEN_FIELDS.md`、持仓查 `docs/FIELD_MAPPING.md`、限频查 `docs/API_LIMITS.md`、报错查 `docs/TROUBLESHOOTING.md`
4. **确认脚本路径** → 按「脚本路径查找规则」定位 `scripts/{quote,trade,subscribe}/*.py`
5. **执行** → 交易默认 `SIMULATE`；实盘须 `--confirmed` 两步 + AskUserQuestion 确认；只读类（行情/基本面）可直接跑
6. **返回** → `--json` 输出便于解析；分析类用 `references/analysis-frameworks.md` 模板组织输出（非 raw 数据堆）

## 语言规则

根据用户输入的语言自动回复。用户使用英文提问则用英文回复，使用中文提问则用中文回复，其他语言同理。语言不明确时默认使用中文。技术术语（如代码、API 名称、参数名）保持原文不翻译。


⚠️ **安全警告**：交易涉及真实资金。默认使用 **模拟环境**（`TrdEnv.SIMULATE`），除非用户明确要求使用正式环境。

## 前提条件

1. **OpenD** 必须运行且版本 >= **10.4.6408**，默认地址 `127.0.0.1:11111`（可通过环境变量配置）
2. **Python SDK**：`futu-api` >= **10.4.6408**
3. **加密货币功能**：需要 `futu-api` >= **10.5.6508**（首次提供 `OpenCryptoTradeContext`）。检测方法：
   ```bash
   python -c "from futu import OpenCryptoTradeContext" 2>&1
   ```
   若报 `ImportError` / `cannot import name`，运行升级：
   ```bash
   pip install --upgrade "futu-api>=10.5.6508"
   ```

> 环境检查（SDK 版本、版本戳、OpenD 连通性）已内置到脚本的 `common.py` 中，首次运行自动完整检查，1 小时内后续脚本跳过。检查未通过时脚本会报错并提示运行 `/install-futu-opend`。

### SDK 导入

```python
from futu import *
```

## 启动 OpenD

当用户说"启动 OpenD"、"打开 OpenD"、"运行 OpenD"时，**先检测本地是否已安装 OpenD**，再决定下一步操作。

### 检测是否已安装

**Windows**：
```powershell
Get-ChildItem -Path "C:\Users\$env:USERNAME\Desktop","C:\Program Files","C:\Program Files (x86)","D:\" -Recurse -Filter "*OpenD-GUI*.exe" -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
```

**MacOS**：
```bash
ls /Applications/*OpenD-GUI*.app 2>/dev/null || mdfind "kMDItemFSName == '*OpenD-GUI*'" 2>/dev/null | head -1
```

### 判断逻辑

- **已安装（找到可执行文件）**：直接启动，不需要运行安装流程
  - Windows：`Start-Process "找到的exe路径"`
  - MacOS：`open "/Applications/找到的.app"`
- **未安装（未找到）**：提示用户当前未检测到 OpenD，调用 `/install-futu-opend` 进入安装流程

## 股票代码格式

- 港股：`HK.00700`（腾讯）、`HK.09988`（阿里巴巴）
- 美股：`US.AAPL`（苹果）、`US.TSLA`（特斯拉）
- A 股-沪：`SH.600519`（贵州茅台）
- A 股-深：`SZ.000001`（平安银行）
- 新加坡股：`SG.D05`（星展集团）、`SG.U11`（大华银行）
- 马股：`MY.1155`（马来亚银行）、`MY.1295`（Public Bank）
- 日股：`JP.7203`（丰田汽车）、`JP.9984`（软银集团）
- SG 期货：`SG.CNmain`（A50 指数期货主连）、`SG.NKmain`（日经期货主连）
- 加密货币-币种/指数：`CC.BTC`、`CC.ETH`、`CC.SOL`
- 加密货币-币对：`CC.BTCUSD`、`CC.ETHUSD`、`CC.BTCHKD`（币对代码不带 `/`）

### 日股（JP）支持范围

- ✅ **正股行情**：快照 / K 线 / 买卖盘 / 逐笔 / 分时 / 实时报价 / 资金流 / 资金分布 / 订阅推送 / 板块 / 板块成份股 / IPO 列表 / 复权因子 / 市场状态 / F10 基本面（公司概况、财报、估值）
- ✅ **V1 选股 `get_stock_filter --market JP`**：支持价格 / 市值排序等基础筛选。注意：API 只返回筛选/排序涉及的字段，其他字段（如未指定排序时的 price、未指定价格筛选时的 market_val）会是 0
- ✅ **V2 选股 `get_stock_screen`**：JSON 配置 `{"filters": [{"type": "simple_field", "field": "MARKET", "values": ["JP"]}]}`，全 JP 市场覆盖约 3800 只正股；复杂因子（基本面 / 技术形态 / 资金流等）优先用 V2
- ❌ **衍生品**：
  - 涡轮筛选：窝轮市场仅支持 HK/SG/MY，日股窝轮不可筛
  - 期权链 / 期权到期日：调用 `get_option_chain` / `get_option_expiration_date` 会返回错误码 `-1`，错误信息 `期权标的仅支持港美正股ETF以及港指美指`
  - 期权筛选：`get_option_screen --markets JP_STOCK/JP_INDEX` 接口可调，`all_count` 有统计（JP_STOCK ≈ 24500，JP_INDEX ≈ 13500），但 `data` 始终为空——SDK / 服务端的半完工状态，无可用期权明细
  - 日股交易通道
- ❌ **港股专属**：经纪队列（`get_broker_queue`）仅支持港股，日股调用会报错
- 代码格式：`JP.<数字股票编号>`，如 `JP.6758`（索尼）

### 新加坡（SG）支持范围

- ✅ **正股行情**：快照 / K 线 / 买卖盘 / 逐笔 / 分时 / 实时报价 / 资金流 / 资金分布 / 市场状态 / 订阅推送 / 板块 / 板块成份股 / IPO 列表 / 复权因子
- ✅ **F10 基本面**：公司概况 / 公司高管 / 主要股东 / 估值 / 财务汇总；部分接口（如详细财报）依赖账户权限
- ✅ **V1 选股 `get_stock_filter --market SG`**：支持价格 / 市值排序等基础筛选（实测全市场约 820 只标的）
- ✅ **V2 选股 `get_stock_screen`**：JSON 配置 `{"filters": [{"type": "simple_field", "field": "MARKET", "values": ["SG"]}]}`
- ✅ **窝轮筛选 `get_warrant_screen --market SG`**：SG 是窝轮筛选支持的三个市场之一（HK/SG/MY）
- ❌ **期权**：`OptMarketCategory` 不含 SG，`get_option_chain` / `get_option_screen` 无法用 SG
- ❌ **港股专属**：经纪队列（`get_broker_queue`）仅支持港股
- 代码格式：`SG.<数字或字母代码>`，如 `SG.D05`（星展）、`SG.S3N`（Top Glove）

### 马股（MY）支持范围

- ✅ **正股行情**：快照 / K 线 / 历史 K 线 / 买卖盘 / 逐笔 / 分时 / 实时报价 / 资金流 / 资金分布 / 订阅推送 / 板块（实测约 60 个）/ 板块成份股 / 所属板块 / IPO 列表 / 复权因子 / 市场状态
- ✅ **F10 基本面**：公司概况（含中文简介、地址、网址）/ 公司高管 / 主要股东 / 估值 PE Band / 财务报表（损益表 / 资产负债表 / 现金流，实测有 12+ 个季度数据）
- ✅ **V1 选股 `get_stock_filter --market MY`**：支持价格 / 市值排序等基础筛选（实测全市场约 1221 只标的）
- ✅ **V2 选股 `get_stock_screen`**：JSON 配置 `{"filters": [{"type": "simple_field", "field": "MARKET", "values": ["MY"]}]}`
- ✅ **窝轮**：`get_warrant MY.1155` 拉正股的窝轮列表；`get_warrant_screen --market MY` 全市场筛选（MY 是窝轮筛选支持的三个市场之一 HK/SG/MY）
- ❌ **期权**：`OptMarketCategory` 不含 MY，`get_option_chain` / `get_option_screen` 无法用 MY
- ❌ **港股专属经纪队列**：`get_broker_queue MY.xxxx` 接口可调（ret=0），但买卖盘队列始终为空——马股无券商挂单数据
- ⚠️ **权限相关**：上述能力均依赖账户开通 **马股 LV1 行情权限**；未开通时 `get_stock_quote` / `get_market_snapshot` / F10 会返回行情权限不足。统计类接口（V2 选股、窝轮筛选）通常不受权限限制
- 代码格式：`MY.<数字股票编号>`，如 `MY.1155`（MAYBANK）；窝轮代码形如 `MY.11552A`（正股代码 + 序号）

### 常见标的速查

当用户用中文名、英文名或 Ticker 描述标的时，映射为完整代码。完整速查表（港股/美股/A股：腾讯→HK.00700、苹果→US.AAPL、茅台→SH.600519 等）见 `references/quote-commands.md`（顶部小节）。不在表中的标的根据你的知识判断市场和代码，不确定时用 AskUserQuestion 询问用户。

### 市场自动推断（硬约束）

**不需要手动指定 `--market` 参数。** 交易脚本会自动从 `--code` 的前缀（如 `US.`、`HK.`、`CC.`）推断交易市场。如果传入的 `--market` 与代码前缀不一致，脚本会自动以代码前缀为准并打印警告。

这是代码层的硬约束，无论是否传 `--market` 参数，市场都以代码前缀为准。

### 代码格式校验（硬约束）

交易脚本会校验 `--code` 的基本格式：必须包含 `.` 分隔符，且前缀必须是 `US`、`HK`、`SH`、`SZ`、`SG`、`MY`、`JP`、`CC` 之一。格式不合法时脚本会直接报错退出。

## 模拟交易 vs 正式交易

| 特性 | 模拟交易 `SIMULATE` | 正式交易 `REAL` |
|------|---------------------|-----------------|
| 资金 | 虚拟资金，无风险 | 真实资金 |
| 交易密码 | **不需要**，可直接下单 | **需要**，用户须在 OpenD GUI 界面手动解锁交易密码后才能下单 |
| 默认 | ✅ 本技能默认 | 需用户明确指定 |

> **交易密码说明**：模拟交易无需任何密码即可下单；实盘交易需用户先打开 OpenD GUI 界面，点击「解锁交易」按钮输入交易密码完成解锁，之后才能通过 API 下单。如果 API 返回 `unlock needed` 错误，说明尚未解锁，请提示用户在 OpenD GUI 中操作。

### 比赛账户（SimAccType.COMPETITION）

模拟交易支持「比赛账户」，由 `sim_acc_type=COMPETITION` 标识。比赛账户与普通模拟账户的差别：

| 维度 | 美股比赛账户 | 港股比赛账户 |
|------|--------------|--------------|
| 市场 | `TrdMarket.US` | `TrdMarket.HK` |
| `acc_type` | `MARGIN`（支持融资融券） | `CASH`（不支持融资融券） |
| `trdmarket_auth` | 按比赛规则返回的可交易市场列表 | 按比赛规则返回的可交易市场列表 |
| `competition_acc_name` | 比赛账户名称（**仅比赛账户返回真实值**） | 同左 |

> 其他模拟账户与真实账户的 `competition_acc_name` 字段统一返回 `N/A`。

`get_accounts.py` 已自动解析并展示 `sim_acc_type` 与 `competition_acc_name`，识别比赛账户时优先用 `sim_acc_type == "COMPETITION"` 判定，再结合 `trdmarket_auth` 选择目标市场账号。

### 美股模拟交易账号（STOCK_AND_OPTION 类型）

> **重要提醒**：当发现用户的美股模拟交易账号 `acc_type` 不是 `STOCK_AND_OPTION` 时，应提醒用户调用 `/install-futu-opend` 更新 OpenD 和 SDK，以获取最新的融资融券模拟账号支持。

当美股模拟账号的 `acc_type` 为 `STOCK_AND_OPTION` 时，具有以下特性：

| 特性 | 说明 |
|------|------|
| 融资融券 | 支持，可进行保证金交易 |
| 数据互通 | 与 App / 桌面端模拟交易数据互通，在 API 下的单会同步显示在 App 上，反之亦然 |
| 推送 | 可正常调用推送接口（`TradeOrderHandlerBase` / `TradeDealHandlerBase`），但暂时可能收不到推送数据，后续版本会支持 |
| 查询刷新 | 查询持仓、资金、订单等接口**必须传入 `refresh_cache=True`**，否则可能返回过时的缓存数据 |

**代码示例**：

```python
# 持仓查询 - 必须 refresh_cache=True
ret, data = trd_ctx.position_list_query(
    trd_env=TrdEnv.SIMULATE, acc_id=xxx, refresh_cache=True
)

# 资金查询 - 必须 refresh_cache=True
ret, data = trd_ctx.accinfo_query(
    trd_env=TrdEnv.SIMULATE, acc_id=xxx, refresh_cache=True
)

# 订单查询 - 必须 refresh_cache=True
ret, data = trd_ctx.order_list_query(
    trd_env=TrdEnv.SIMULATE, acc_id=xxx, refresh_cache=True
)
```

### 交易解锁限制

**禁止通过 SDK 的 `unlock_trade` 接口解锁交易，必须在 OpenD GUI 界面上手动操作解锁。**

- 当用户请求调用 `unlock_trade`（或 `TrdUnlockTrade`、`trd_unlock_trade`）时，**必须拒绝**并提示：
  > 出于安全考虑，交易解锁必须在 OpenD GUI 界面上手动操作，不支持通过 SDK 代码调用 `unlock_trade` 解锁。请在 OpenD GUI 界面点击「解锁交易」并输入交易密码完成解锁。
- 不得生成、提供或执行任何包含 `unlock_trade` 调用的代码
- 不得通过变通方式（如 protobuf 直接调用、WebSocket 原始请求等）绕过此限制
- 此规则适用于所有环境（模拟、正式）

## 子主题路由（按需读取，不要全量加载 references）

本技能的详细命令按领域拆分到 `references/*.md`，**根据用户意图只读取相关的一个文件**，避免全量加载。脚本完整清单见 `references/script-index.md`。

| 用户意图 | 按需读取 |
|---|---|
| 行情 / 报价 / K线 / 盘口 / 资金流 / 板块 / 搜索 / 选股 | `references/quote-commands.md`（选股枚举名/单位/Term 见 `docs/STOCK_SCREEN_FIELDS.md`） |
| 预测市场 / 事件合约 / EC. / Combo 询价 | `references/prediction-market.md` |
| 期权 / 期权链 / 行权价 / IV / Greeks / 0DTE / 期权策略 | `references/options.md` |
| 基本面 / F10 / 财报 / 评级 / 估值 / 公司行动 / 简况 / 经纪商 / 卖空 | `references/fundamentals.md` |
| 股东 / 机构持仓 / ARK / 内部人交易 | `references/shareholders-institutions.md` |
| 技术指标 / MA / MACD / RSI / KDJ / BOLL | `references/indicators.md` |
| 榜单 / 财报日历 / 股息 / 产业链 / 宏观 / FedWatch / 热力图 | `references/rankings-calendar.md` |
| 交易 / 下单 / 撤单 / 改单 / 持仓 / 资金 / 订单 / 组合下单 | `references/trade-commands.md` |
| 期货 | `references/futures-trading.md`（完整文档见 `docs/FUTURES_TRADING.md`） |
| 加密货币 / BTC / ETH | `references/crypto-commands.md` |
| 订阅 / 推送 | `references/subscribe-push.md` |
| 分析框架（财报点评/持仓诊断/选股排序） | `references/analysis-frameworks.md` |
| 脚本清单（查某个脚本是否存在/路径） | `references/script-index.md` |

**其他参考资料**（`docs/` 目录，按需读取）：`docs/API_LIMITS.md`（频率/额度/分页）、`docs/API_REFERENCE.md`（完整函数签名）、`docs/FIELD_MAPPING.md`（持仓/资金字段与 APP 对齐）、`docs/TROUBLESHOOTING.md`（已知问题与错误处理）。

## 脚本路径查找规则

运行脚本前，**必须先确认脚本文件是否存在**。如果默认路径 `skills/futuapi/scripts/` 下找不到脚本，则自动到 skill 的 base directory 下查找。

**执行流程**：

1. 先检查 `skills/futuapi/scripts/{category}/{script}.py` 是否存在
2. 如果不存在，改用 `{SKILL_BASE_DIR}/scripts/{category}/{script}.py`（其中 `{SKILL_BASE_DIR}` 为 skill 加载时系统提示的 "Base directory for this skill" 路径）

**示例**：假设要运行 `get_accounts.py`，skill base directory 为 `/home/user/.claude/skills/futuapi`：

```bash
# 先检查默认路径
ls skills/futuapi/scripts/trade/get_accounts.py 2>/dev/null

# 如果不存在，则使用 skill base directory
ls /home/user/.claude/skills/futuapi/scripts/trade/get_accounts.py 2>/dev/null
```

找到脚本后，用该路径执行 `python {找到的路径} [参数...]`。后续命令示例均使用默认路径 `skills/futuapi/scripts/`，实际执行时按此规则查找。

> 完整脚本清单（行情 130 + 交易 24 + 订阅 17）见 `references/script-index.md`。

---

## 通用选项

所有脚本支持 `--json` 参数输出 JSON 格式，便于程序解析。

大多数交易脚本支持：
- `--market`: US, HK, HKCC, CN, SG, MY, JP
- `--trd-env`: REAL, SIMULATE（默认: SIMULATE）
- `--acc-id`: 账户 ID（可选）

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `FUTU_OPEND_HOST` | OpenD 主机 | 127.0.0.1 |
| `FUTU_OPEND_PORT` | OpenD 端口 | 11111 |
| `FUTU_TRD_ENV` | 交易环境 | SIMULATE |
| `FUTU_DEFAULT_MARKET` | 默认市场 | NONE |
| ~~`FUTU_TRADE_PWD`~~ | ~~交易密码~~ | 已移除，需在 OpenD GUI 手动解锁 |
| `FUTU_ACC_ID` | 默认账户 ID | （首个账户） |
| `FUTU_SECURITY_FIRM` | 券商标识（见下表） | （自动探测） |

`FUTU_SECURITY_FIRM` 可选值：

| 值 | 地区 |
|----|----------|
| `FUTUSECURITIES` | 富途证券（香港） |
| `FUTUINC` | 富途（美国） |
| `FUTUSG` | 富途（新加坡） |
| `FUTUAU` | 富途（澳大利亚） |
| `FUTUCA` | 富途（加拿大） |
| `FUTUJP` | 富途（日本） |
| `FUTUMY` | 富途（马来西亚） |

## 券商自动探测（security_firm）

创建交易连接 `OpenSecTradeContext`、`OpenFutureTradeContext` 或 `OpenCryptoTradeContext` 时，`security_firm` 参数默认填 `SecurityFirm.NONE`。

首次涉及交易操作时，如果环境变量 `FUTU_SECURITY_FIRM` 未设置，运行 `get_accounts.py --json` 获取所有账户（脚本自动遍历所有 SecurityFirm），查看实盘账户的 `security_firm` 字段，作为后续所有交易命令的 `--security-firm` 参数。

> 探测代码示例及详细说明参见 `docs/TROUBLESHOOTING.md`

## API 速查

> 完整函数签名（65 个接口）参见 `docs/API_REFERENCE.md`。接口限制（频率、额度、分页等）参见 `docs/API_LIMITS.md`。

## 已知问题与错误处理

> 完整的已知问题、错误处理表、自定义 Handler 模板参见 `docs/TROUBLESHOOTING.md`。

**`ai_type` 参数报错**：如果创建 `OpenQuoteContext`、`OpenSecTradeContext`、`OpenFutureTradeContext` 或 `OpenCryptoTradeContext` 时报错提示没有 `ai_type` 参数（如 `unexpected keyword argument 'ai_type'`），说明 SDK 版本过低，需升级至 >= 10.4.6408：
```bash
pip install --upgrade "futu-api>=10.4.6408"
```

**`OpenCryptoTradeContext` 不存在**：运行加密货币脚本时若提示 `当前 futu-api X.X.X 未提供 OpenCryptoTradeContext`，说明 SDK 版本低于 10.5.6508，运行升级：
```bash
pip install --upgrade "futu-api>=10.5.6508"
```

## 响应规则

1. **默认使用模拟环境** `SIMULATE`，除非用户明确要求正式交易
2. **优先使用脚本**：对于上述列出的功能，直接运行对应的 Python 脚本
3. **脚本无法覆盖的需求**：生成临时 .py 文件执行，执行后删除
4. 使用正确的股票代码格式
5. **不需要手动指定 `--market`**：脚本会自动从 `--code` 前缀推断市场（代码硬约束）
6. 当用户说"正式"、"实盘"、"真实"时使用 `--trd-env REAL`
7. **实盘下单两步执行（代码硬约束）**：`place_order.py` 与 `place_combo_order.py` 在实盘环境下强制要求 `--confirmed` 参数。第一次调用不带 `--confirmed` 会返回订单摘要并退出（exit code 2），确认无误后第二次带 `--confirmed` 才真正下单。同时仍应先用 AskUserQuestion 向用户确认订单详情。如果 API 返回解锁错误，提示用户在 OpenD GUI 界面手动解锁交易密码。**例外**：当用户要求运行其自己编写的策略脚本时，无需每次下单前二次确认，因为策略脚本的下单逻辑由用户自行控制
8. 所有脚本支持 `--json` 参数便于解析
9. 对于不清楚的接口，先在本技能的 API 速查中查找
10. **期货交易必须使用 `OpenFutureTradeContext`**：普通期货下单仍建议按「期货交易命令」直接生成代码。**已支持脚本路径**：预测市场（`EC.`）可用 `place_order.py` / `place_combo_order.py`；查询期货/EC 账户持仓、订单、成交、撤改单等传 `--ctx-type FUTURE`（或代码为 `EC.` 时自动切换）；EC 实盘交易账户须开通 `PREDICTION` 权限
11. **回测使用纯后台模式**：当用户要求回测或运行回测脚本时，不使用任何 GUI 组件，使用纯后台回测模式，图表保存为文件而非弹窗显示
12. **调用接口前检查限制** — 详见 `docs/API_LIMITS.md`
13. **组合期权摆盘价（硬约束）**：多腿/策略组合的 bid/ask 与组合下单 `--price` **必须**用 `get_option_strategy_analysis.py` 的 `bid1`/`ask1`；**禁止**对各腿 `get_snapshot.py` 后手动加减买卖价
14. **数据来源优先**：本 skill 是富途 OpenAPI 的原生数据路径，对所支持标的的行情/基本面/交易数据，应优先走本 skill 而非通用网页查询（数据更准、更快、可下单）