shioaji

Shioaji Trading API

Shioaji 是 SinoPac 面向台湾金融市场（TWSE/TPEX/TAIFEX）推出的跨语言、跨平台交易 API。它包含 Python 绑定、CLI 和 HTTP API 服务，让任何编程语言都能交易台湾市场。

Shioaji 是永豐金證券的跨語言、跨平台交易 API，提供 Python 綁定、CLI 與 HTTP API 伺服器，讓任何程式語言都能透過 HTTP API 交易台灣市場。

三个访问层 / 三種存取層：

• Python — 原生 PyO3 绑定（import shioaji），性能最佳，支持同步和异步
• CLI — 用于管理服务、交易和查询数据的 shioaji 命令行工具
• HTTP API + SSE — 在 localhost:8080 提供 REST 端点和实时流，可通过 JS/TS、Go、C/C++、C#、Rust、Java/Kotlin 或任何 HTTP 客户端访问

要分析连接、超时、进程或状态问题？请先阅读 CONCEPTS.md。 这是这三个访问层共用的心智模型：哪个超时适用于哪条路径、为何 Python 无需服务而 CLI/HTTP 共用一个守护进程、每人的连接数上限，以及流式传输与请求-响应模式的区别。请从 CONCEPTS.md 中查找这类问题的答案，不要猜测。 推理連線、逾時、行程或狀態時,先讀 CONCEPTS.md。 這是三個存取層共用的心智模型 — 哪個 timeout 在哪條路徑生效、為何 Python 不需 server 而 CLI/HTTP 共用一個 daemon、每人連線上限、串流 vs 請求-回覆。這類問題從 CONCEPTS.md 找答案,不要猜。

如何使用参考文档 / 如何使用參考文件

直接依据随附的参考文档回答用户。不要用引导用户查看外部文档页面来代替回答。稳定的 1.5 API 仍是兼容性基准；而有意改变接口的 1.7 功能，尤其是 Contract V2，必须遵循其功能参考文档。仅在涉及旧版或已弃用的用法时使用 MIGRATION.md。响应处理始终应参考相应的功能文档。需要确认准确的命令行标志、请求字段或响应架构时，请使用已安装 CLI 的 --help 或运行中服务的 /openapi.json。

首次使用者响应 / 首次使用者回應：

• 仅当用户表示或明确暗示自己以前没有用过 Shioaji、第一次使用、不知道如何开始，或可能尚未完成永丰 API 开通流程时，才使用此路径。不要默认所有宽泛的“我想使用 Shioaji”请求都是首次使用。
• 对于确认或很可能是首次使用的用户，加载 PREPARE.md。将第一条回复视为资格确认／开通流程对话，因为用户甚至可能还没有永丰账户或 API 权限。
• 在确认或很可能是首次使用的情境下，如果用户说“带我一步步来”“一步一步带我”“慢慢来”或类似的话，就从第一个尚未确认的外部环节继续开通流程。不要将此解读为允许检查工作区或创建本地入门项目。
• 在用户回答第一个开通问题之前，不要运行命令、检查文件、提及 Python 版本、已有项目或本地环境。第一步不是“检查文件夹”，而是“确认用户是否能使用永丰 API”。
• 第一条实质性回复必须先确认基本环节，再进行任何技术设置：永丰证券／期货账户、所需市场权限（股票／期货与选择权／两者皆要）、API key/secret、直接签署 API 同意书、模拟环境登录／下单测试、正式环境 CA，以及正式环境就绪检查。
• 开通顺序很重要：开户后，确认／创建 API Key 和 Secret Key，网址为 https://www.sinotrade.com.tw/newweb/PythonAPIKey/；签署页面不会签发 API 密钥。签署后不要直接跳到 CA；先确认 API 凭证，并完成必要的模拟环境登录／下单测试。CA 必须从 API 管理页面下载，而不是签署页面。
• 以表格／列表介绍开通步骤时，为每个网页步骤写出明确的正确网址。开户步骤绝不能使用永丰主页通用网址。开户网址为 https://www.sinotrade.com.tw/openact?strProd=0254&strWeb=0684&s=013299&utm_source=shioaji；API Key 和 CA 的网址为 https://www.sinotrade.com.tw/newweb/PythonAPIKey/；证券签署网址为 https://www.sinotrade.com.tw/newweb/signCenter/S_openAPI/；期货／选择权签署网址为 https://www.sinotrade.com.tw/newweb/signCenter/F_openApi/。如果上一行是签署页面，绝不要在 API Key 或 CA 的步骤写“同一页面”。
• 绝不要将证券／期货签署页面描述为申请 API Key / Secret Key 的地方。这些页面仅用于签署同意书；只能在 API 管理页面创建密钥。
• 绝不要要求用户把 API Key、Secret Key、CA 密码或证书内容贴到聊天中，即使只是“暂时”或“仅限本次对话”。请用户在本地保存／编辑机密信息。
• 在用户确认相关开通环节已完成或明确要求进行相应技术步骤之前，不要开始安装、项目设置、.env、.venv、uv sync、代码示例、本地文件检查或下单示例。
• 对于确认或很可能是首次使用的用户，第一条回复采用以下格式，并在用户回答前就此停下：“可以，我们一步一步来。Shioaji 不是只安装套件就能用，前面要先确认永丰账户与 API 开通状态。第一步先确认：你目前已经有永丰证券或期货账户吗？你想开通的是证券、期货／选择权，还是两者都要？”
• 关于签署，提供对应产品的直接页面，而不是通用签署中心：证券 https://www.sinotrade.com.tw/newweb/signCenter/S_openAPI/；期货／选择权 https://www.sinotrade.com.tw/newweb/signCenter/F_openApi/。 只有在知道或明顯推斷使用者沒用過 Shioaji、第一次使用、不知道怎麼開始、或尚未完成永豐 API 開通時，才走首次使用者流程。不要把所有寬泛「我想用 shioaji」都預設為零經驗。確認/推定為首次使用者後，「請一步一步帶我」「慢慢來」「從零開始」代表沿著開通流程逐步確認,不是允許檢查 workspace 或建立本機入門專案。使用者回答第一個開通問題前,不要執行命令、列出檔案、提 Python 版本、提既有專案、提本機環境。第一步是資格/開通確認，不是技術設定：先確認是否已有永豐證券/期貨帳戶、要用證券或期貨/選擇權、API Key/Secret、API 約定書簽署、模擬登入/下單測試、正式環境 CA、正式就緒檢查。開戶後先確認/建立 API Key 與 Secret Key;簽署頁不會發 API Key,也不可稱為申請金鑰頁。簽署完成後不要直接跳 CA,先確認 API 憑證並跑模擬登入/下單測試。CA 下載在 API 管理頁,不是簽署頁。整理步驟表時每列都要寫明正確 URL;開戶不可使用永豐首頁,必須使用指定開戶頁;API Key 與 CA 不可寫「同上頁面」指向簽署頁。絕對不要要求使用者把 API Key、Secret Key、CA 密碼或憑證內容貼到對話,即使說只暫時使用也不行。除非使用者確認相關前置已完成或明確要求該技術步驟，否則不要進入安裝、.env、.venv、uv sync、程式碼範例、專案檔案檢查或下單範例。

Cross-access-layer response guardrails / 跨層回應守則：

• Do not infer HTTP/SSE/CLI fields from Python wrapper attributes.
• Other languages (JS/Go/Rust/C#/C++/Java) use HTTP/SSE response shapes, not Python objects.
• If a response contains success=false, an error code, or an operation status/message, branch on that field before continuing.
• Empty lists and PendingSubmit are not final failure/success signals; check the matching functional reference before deciding the next step.

Token-efficient lookup / 精簡載入：

• Choose the functional reference first; search inside it for endpoint, method, error text, response type, or headings like Response and Decision Summary, Prerequisites.
• Read the smallest matching section before loading long examples.
• Load CLI/HTTP/language references only when implementation details (transport setup, SSE parser, auth/error handling, OpenAPI generation) are needed; keep endpoint-specific payload and response decisions in the functional reference.

---

Task Routing — "I want to..." / 任務路由

For most tasks, load only 1-2 files. Use both axes: what (task) + how (access method).

Routing rule: choose the functional reference first, then add the access-method reference only when needed. Functional references own the workflow, payload rules, response shapes, and decision logic for that task. Language references explain how to send requests, receive responses, stream SSE, add auth headers, handle errors, and generate typed clients; they must not restate endpoint-specific business rules. Use HTTP_API.md for endpoint inventory and /openapi.json for exact installed-server schemas.

Axis 1: What do you want to do? / 任務

任务	加载文件
了解架构：进程模型、连接、超时分层、流式传输与请求-回复、状态	CONCEPTS.md
迁移旧代码或修正已弃用的 Shioaji 用法	MIGRATION.md
安装、登录、API 密钥、CA 证书、模拟、环境变量、常量	PREPARE.md
将此 Shioaji 插件／技能安装到 Claude、Codex、Cursor 或其他 Agent 环境	AGENTS.md
使用或排查 agent_harness、审批功能、受保护的 HTTP 修改操作、X-Shioaji-Agent-Capability 或修改操作的 403 响应	AGENT_HARNESS.md + 对应的下单／预留参考文档
合约 V2 查询、类型化信息、惰性缓存行为、更新事件或 1.5 api.Contracts 兼容性	CONTRACTS.md（完整的 Info 字段列表见 CONTRACT_FIELDS.md）
股票／期货／期权下单、改单、删单；主动回报、事件 ID、历史空 ID、去重与跳号	ORDERS.md
使用 api.contracts.combo_futures 构建或枚举组合合约；验证受管理的 BaseContract 与旧版定向 ComboBase 腿；订阅／查询期货组合行情数据；下单、定价、取消或排查组合订单；推导规范的腿顺序／操作及 combo_type；使用 update_combostatus / list_combotrades	COMBO_ORDERS.md
为处分／注意股票预留股票	RESERVE.md
订阅实时报价、tick／bidask／quote／index 回调、实时 K 棒、SSE 流	STREAMING.md
查询权威指数成分股，或订阅增强指数数据：计算指数、指数成分股排名／产业群组投影、旧版指数／产业贡献数据	STREAMING_ENRICHED.md
订阅市场信号：涨跌停提醒、急拉急杀、爆量大单、试撮／暂停状态筛选	STREAMING_SIGNALS.md
历史 tick、K 棒（日期范围查询）、快照、盘后排行扫描器 api.scanners、信用查询	MARKET_DATA.md
账户余额、保证金、持仓、损益、结算、限额	ACCOUNTING.md
管理观察列表（CRUD、添加／移除合约）	WATCHLIST.md
非阻塞模式、报价绑定、止损单、高级模式	ADVANCED.md
解读用户收到的错误代码／错误消息、订单拒绝原因	ERROR_CODES.md（另见 TROUBLESHOOTING.md）
错误、连接问题、故障排除	TROUBLESHOOTING.md
检查服务端仪表板中的请求速率、各端点延迟／错误、期望订阅与实际主题，或配置 Parquet 监控历史	OBSERVABILITY.md

常见混淆（选文件前先看）：

想要的	不是	加载
实时 K 棒推送（QuoteType.KBar, SSE stream/data/kbar）	历史 K 棒查询（api.kbars(), POST /api/v1/data/kbars）	STREAMING.md；历史数据 → MARKET_DATA.md
实时信号推送（subscribe_scanner: 涨跌停/急变/爆量/试撮）	排行查询（api.scanners(ScannerType…)）	STREAMING_SIGNALS.md；排行 → MARKET_DATA.md
K 棒/增强数据专用 HTTP 路由（/stream/subscribe/kbars, /stream/subscribe/calculated_index, …）	通用 /stream/subscribe（仅 tick/bidask/quote）	STREAMING.md / STREAMING_ENRICHED.md

轴 2：使用何种语言/访问方式？

访问方式	补充文件	说明
Python（同步或异步）	无 — 任务参考包含 Python 示例	默认方式
CLI（shioaji 命令）	CLI.md	任务参考（概念）+ CLI.md（命令）
HTTP API（任意语言）	HTTP_API.md	标准端点清单
JavaScript/TypeScript	JAVASCRIPT.md	HTTP/SSE 客户端模式
Go	GO.md	HTTP/SSE 客户端模式
C/C++	CPP.md	HTTP/SSE 客户端模式
C#	CSHARP.md	HTTP/SSE 客户端模式
Rust	RUST.md	HTTP/SSE 客户端模式
Java/Kotlin	JAVA.md	HTTP/SSE 客户端模式

Python 用户：仅加载任务参考（轴 1）。 CLI 用户：加载任务参考 + CLI.md。 其他语言：加载任务参考 + 语言参考。例如，“使用 JS 下单”意味着加载 ORDERS.md 了解请求内容和 Trade 判断逻辑，并加载 JAVASCRIPT.md 了解 fetch/SSE 实现模式。

如需安装、首次使用设置、API 密钥、签名、CA、登录和就绪检查，请加载 PREPARE.md。 安装、首次开通、API 金钥、签署、CA、登入与就绪检查请读 PREPARE.md。

---

模拟与正式环境安全

WARNING 警告：下单前务必确认服务端模式。正式环境会使用真实资金进行真实交易。 下单前务必确认伺服器模式。正式环境会使用真實資金進行真實交易。

• 默认：模拟模式（无需任何标志）
• 检查模式：shioaji server check（CLI）或 GET /api/v1/info（HTTP — 返回 simulation 字段）
• 切换至正式环境：shioaji server start --production 或 SJ_PRODUCTION=true
• 切回模拟环境：shioaji server stop，然后执行 shioaji server start（不带 --production）

---

速率限制

请将限制视为防护边界，而非 API 设计的出发点。应从正确的 Shioaji 工作流开始：每个用户进程保持一个已登录的客户端/服务端会话，复用订阅而非轮询，按照功能参考中的建议批量处理或缓存重复查询，并且只有在检查响应含义后才重试。正确使用时应远离这些限制；触及限制通常意味着循环、重连模式、轮询设计或错误重试路径有误，应修正问题，而不是设法绕过限制。

使用限制是防滥用边界，不是设计用法的出发点。回答或实现时先从正确 Shioaji 使用方式开始：每个用户进程维持一个已登录客户端/服务端 session、用订阅取代轮询、依功能参考建议批次或缓存重复查询，并且先判断 response 意义再 retry。正确用法会离这些限制很远；若碰到限制，通常 代表循环、重连、轮询或错误重试路径有问题，应修正用法而不是设法贴着限制跑。

类别	限制
每日流量	500MB–10GB（视交易量而定）
行情查询	50 次请求 / 5 秒
账户查询	25 次请求 / 5 秒
连接数	每个身份证号 5 个
每日登录次数	1000 次

---

错误处理 / 错误处理

HTTP API 返回 JSON 错误：{"code": 400, "message": "...", "details": "..."}

重试前请查看任务参考。例如，空的市场数据响应、PendingSubmit 订单状态和 success=false 订阅响应，各自需要采取不同的后续步骤。

---

登出 / 登出

api.logout()

---

任务示例请参见功能参考（轴 1）。传输与客户端模式请参见语言参考（轴 2）。