shioaji

Shioaji Trading API

Shioaji は、台湾の金融市場（TWSE/TPEX/TAIFEX）向けの SinoPac のクロス言語・クロスプラットフォーム取引 API です。Python バインディング、CLI、HTTP API サーバーを備え、あらゆるプログラミング言語から台湾市場で取引できます。

3 つのアクセスレイヤー：

• Python — パフォーマンスを最大限に高めるネイティブ PyO3 バインディング（import shioaji）。同期・非同期に対応
• CLI — サーバー管理、取引、データ照会を行うコマンドラインツール shioaji
• HTTP API + SSE — localhost:8080 で利用できる REST エンドポイントとリアルタイムストリーミング。JS/TS、Go、C/C++、C#、Rust、Java/Kotlin、その他あらゆる HTTP クライアントからアクセス可能

接続、タイムアウト、プロセス、状態について考える場合は、まず CONCEPTS.md をお読みください。 これは、3 つのレイヤーが共通して前提とするメンタルモデルです。どの経路でどのタイムアウトが適用されるか、Python ではサーバーが不要なのに CLI/HTTP では 1 つのデーモンを共有する理由、ユーザーごとの接続上限、ストリーミングとリクエスト・リプライについて説明しています。推測するのではなく、こうした疑問への答えは CONCEPTS.md から得てください。 接続、タイムアウト、プロセス、状態について考える場合は、まず CONCEPTS.md をお読みください。 これは、3 つのアクセスレイヤーが共通して前提とするメンタルモデルです。どのタイムアウトがどの経路に適用されるか、Python ではサーバーが不要なのに CLI/HTTP では同じデーモンを共有する理由、ユーザーごとの接続上限、ストリーミングとリクエスト・リプライについて説明しています。推測するのではなく、こうした疑問への答えは CONCEPTS.md から得てください。

参照ドキュメントの使い方

同梱されている参照ドキュメントをもとに、ユーザーに直接回答してください。回答の代わりに、外部ドキュメントのページへ誘導しないでください。安定版の 1.5 API は引き続き互換性の基準となります。一方、特に Contract V2 など、インターフェースが意図的に変更される 1.7 の機能については、対応する機能別リファレンスに従ってください。レガシーまたは非推奨の用法については、MIGRATION.md のみを参照してください。レスポンスの処理については、必ず対応する機能別リファレンスを参照してください。正確なコマンドフラグ、リクエストフィールド、レスポンススキーマの確認が必要な場合は、インストール済みの CLI の --help または実行中のサーバーの /openapi.json を使用してください。

初めて利用するユーザーへの回答：

• ユーザーがShioajiを使ったことがない、初めて使う、始め方がわからない、またはSinoPac APIのオンボーディングが完了していない可能性があると明言した場合、あるいはそれが明らかに示唆されている場合にのみ、この手順を使用します。「Shioajiを使いたい」という広い意味のリクエストを、常にデフォルトで初回利用と判断しないでください。
• 初回利用であることが確実、またはその可能性が高いユーザーには、PREPARE.mdを読み込みます。SinoPacの口座もAPIアクセス権もまだない可能性があるため、最初の応答は利用資格とオンボーディングについて確認する会話にします。
• 初回利用であることが確実、またはその可能性が高い状況で、ユーザーが「順を追って説明して」「ステップごとに」「一步一步帶我」「慢慢來」などと述べた場合、最初に未確認の外部手続きからオンボーディングを続けます。それを、ワークスペースを調べたり、ローカルのスタータープロジェクトを作成したりする許可だと解釈しないでください。
• ユーザーが最初のオンボーディングの質問に答える前に、コマンドを実行したり、ファイルを調べたり、Pythonのバージョンに触れたり、既存のプロジェクトに言及したり、ローカル環境について話したりしてはいけません。最初のステップは「フォルダーを確認する」ことではなく、「ユーザーがSinoPac APIを開いて利用できるか確認する」ことです。
• 最初の実質的な応答では、技術的なセットアップに進む前に、基本的な条件を確認する必要があります。SinoPacの証券／先物口座、希望する市場へのアクセス（株式／先物・オプション／両方）、API Key／Secret Key、APIの直接契約への署名、シミュレーションでのログイン／注文テスト、本番環境用のCA、本番環境への準備状況の確認です。
• オンボーディングの順序は重要です。口座開設後、https://www.sinotrade.com.tw/newweb/PythonAPIKey/でAPI KeyとSecret Keyを確認または作成します。署名ページではAPIキーは発行されません。署名後、すぐにCAの手続きに進まず、まずAPI認証情報を確認し、必要なシミュレーションでのログイン／注文テストを実施します。CAのダウンロード先は署名ページではなくAPI管理ページです。
• オンボーディングの手順を表やリストで示す場合、各ウェブ上の手続きについて正しいURLを明記します。口座開設用URLとしてSinoPacの汎用ホームページを使ってはいけません。口座開設は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、コード例、プロジェクトファイルの確認、注文例に進まないでください。

アクセスレイヤーをまたぐ回答のガードレール：

• Python ラッパーの属性から HTTP／SSE／CLI のフィールドを推測しないでください。
• 他の言語（JS／Go／Rust／C#／C++／Java）では、Python オブジェクトではなく、HTTP／SSE のレスポンス形式を使用します。
• レスポンスに success=false、エラーコード、または操作のステータス／メッセージが含まれる場合は、先にそのフィールドに基づいて分岐してから続行してください。
• 空のリストや PendingSubmit は、最終的な失敗／成功を示すものではありません。次の手順を決める前に、対応する機能リファレンスを確認してください。

トークン効率のよい参照：

• まず機能リファレンスを選び、その中でエンドポイント、メソッド、エラーテキスト、レスポンスタイプ、または Response and Decision Summary、Prerequisites などの見出しを検索してください。
• 長い例を読み込む前に、該当箇所の最小限のセクションを読んでください。
• CLI／HTTP／言語別リファレンスを読み込むのは、実装の詳細（トランスポート設定、SSE パーサー、認証／エラー処理、OpenAPI の生成）が必要な場合に限ってください。エンドポイント固有のペイロードとレスポンスの判断には、機能リファレンスを使用してください。

---

タスクのルーティング — 「〜したい」場合

ほとんどのタスクでは、1～2 個のファイルだけを読み込んでください。何をするか（タスク）と、どのようにアクセスするか（アクセス方法）の両方の軸を使ってください。

ルーティングのルール：まず機能リファレンスを選び、必要な場合に限ってアクセス方法のリファレンスを追加してください。機能リファレンスには、そのタスクのワークフロー、ペイロードのルール、レスポンス形式、判断ロジックが記載されています。言語別リファレンスには、リクエストの送信、レスポンスの受信、SSE のストリーミング、認証ヘッダーの追加、エラー処理、型付きクライアントの生成方法が記載されています。エンドポイント固有のビジネスルールを重複して記載してはいけません。エンドポイント一覧には HTTP_API.md を使用し、インストール済みサーバーの正確なスキーマには /openapi.json を使用してください。

軸 1：何をしたいですか？／タスク

タスク	読み込むファイル
アーキテクチャを理解する：プロセスモデル、接続、タイムアウトの階層、ストリーミングとリクエスト／リプライの違い、状態	CONCEPTS.md
レガシーコードを移行する、または非推奨の Shioaji の書き方を修正する	MIGRATION.md
インストール、ログイン、API キー、CA 証明書、シミュレーション、環境変数、定数	PREPARE.md
この Shioaji プラグイン／スキルを Claude、Codex、Cursor、その他のエージェント環境にインストールする	AGENTS.md
agent_harness、承認機能、保護された HTTP の変更操作、X-Shioaji-Agent-Capability、変更操作の 403 応答を使用またはトラブルシューティングする	AGENT_HARNESS.md + 対応する注文／予約のリファレンス
Contract V2 の検索、型付き情報、遅延キャッシュの動作、更新イベント、または 1.5 の api.Contracts 互換性	CONTRACTS.md（全 Info フィールド一覧は CONTRACT_FIELDS.md を参照）
注文、コールバック／HTTP SSE、イベント ID、過去データの空の ID、重複排除とシーケンス番号の欠落／株式／先物／オプションの発注、訂正、取消；プッシュ通知、イベント ID、過去データの空の ID、重複排除と番号の欠落	ORDERS.md
api.contracts.combo_futures でコンボ契約を構築または列挙する；管理対象の BaseContract とレガシーの方向指定 ComboBase レッグを検証する；先物コンボの市場データを購読／照会する；コンボ注文を発注、価格設定、取消、トラブルシューティングする；正規のレッグ順序／アクションと combo_type を導出する；update_combostatus／list_combotrades を使用する	COMBO_ORDERS.md
処分／注意銘柄の株式を予約する	RESERVE.md
リアルタイム相場、ティック／買い気配・売り気配／相場／指数コールバック、リアルタイム K バー 即時K棒、SSE ストリームを購読する	STREAMING.md
信頼できる指数構成銘柄を照会する、または付加情報付き指数データ 即時加值資料を購読する：計算済み指数 自算指數、指数構成銘柄ランキング／グループ投影 成分股排行與產業群組投影、従来の指数／業種寄与度	STREAMING_ENRICHED.md
市場シグナル 市場訊號を購読する：値幅制限アラート 漲跌停訊號、急激な値動き 急拉急殺、出来高急増・大口取引 爆量大單、試合せ／取引停止ステータスのフィルター 試撮／暫停	STREAMING_SIGNALS.md
過去のティック、K バー（日付範囲指定の過去 K バー検索 歷史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（ティック／板情報／気配値のみ）	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 で注文を出す」場合は、ペイロードと Trade の判断ロジックについて ORDERS.md を、fetch／SSE の実装パターンについて JAVASCRIPT.md を読み込みます。

インストール、初回セットアップ、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 ワークフローに従います。ユーザーのプロセスごとにログイン済みのクライアント／サーバーセッションを 1 つ維持し、ポーリングの代わりにサブスクリプションを再利用し、機能別リファレンスの推奨に従って繰り返しの照会をまとめるかキャッシュし、レスポンスの意味を確認してから再試行します。正しく使用していれば、これらの制限に達することはほとんどありません。制限に達する場合は通常、ループ、再接続のパターン、ポーリング設計、またはエラー時の再試行処理に問題があるため、制限を回避するのではなく修正してください。

使用制限は不正利用を防ぐための境界であり、設計の出発点ではありません。回答や実装では、まず正しい Shioaji の使い方に従います。ユーザーのプロセスごとにログイン済みのクライアント／サーバーセッションを 1 つ維持し、ポーリングの代わりにサブスクリプションを使い、機能別リファレンスの推奨に従って繰り返しの照会をまとめるかキャッシュし、レスポンスの意味を判断してから再試行します。正しく使用していれば、これらの制限から大きく離れた状態を保てます。制限に達する場合は通常、ループ、再接続、ポーリング、またはエラー時の再試行処理に問題があるため、制限ぎりぎりで運用するのではなく、使い方を修正してください。

カテゴリ	制限
1 日あたりのトラフィック	500MB–10GB（取引量に基づく）
気配値の照会	50 リクエスト / 5 秒
口座情報の照会	25 リクエスト / 5 秒
接続数	1 人 ID あたり 5
1 日あたりのログイン回数	1000 回

---

エラー処理

HTTP API は JSON 形式のエラーを返します：{"code": 400, "message": "...", "details": "..."}

再試行する前に、タスクのリファレンスを確認してください。たとえば、空のマーケットデータ応答、PendingSubmit の注文ステータス、success=false のサブスクリプション応答では、それぞれ異なる次の手順が必要です。

---

ログアウト

api.logout()

---

タスクの例については、機能リファレンス（軸 1）をご覧ください。トランスポートとクライアントのパターンについては、言語リファレンス（軸 2）をご覧ください。