tossinvest-skill

Toss Securities Open API

概要

このスキルを使って、Toss Securities Open API を利用するアプリケーションを構築または運用できます。同梱のリファレンスには公式の OpenAPI ソースが保持されており、scripts/tossinvest.py は認証、マーケットデータ、口座データ、注文履歴、注文情報、およびユーザーから委任された自律的な注文変更を行う決定論的な CLI を提供します。

ソースの選択

• 同梱の公式リファレンスは 2026-09-08（OpenAPI 1.2.14）に更新されています。これはスナップショットです。今後の API 変更については、公式ソースを再度確認してください。
• 新たに追加された REST API、更新された注文ルール、WebSocket のルーティングについては、references/current-api.md を読んでください。CLI は request を通じて新しい REST エンドポイントをサポートしますが、WebSocket クライアントは実装していません。
• 正確なリアルタイム購読およびメッセージのスキーマについては、references/asyncapi.json を読んでください。
• タスクの振り分け、エンドポイントグループ、安全ルール、レート制限、一般的なワークフローについては、references/workflows.md を読んでください。
• 正確なリクエストパラメーター、スキーマ、列挙値、例、レスポンスエンベロープが必要な場合は、references/openapi.json を読んでください。
• 公式のクイックスタート、レート制限モデル、エラーモデルについては、references/official-overview.md を読んでください。
• API ごと、およびモデルごとの公式 Markdown ページを探すには、references/api-reference-index.md を読んでください。

認証情報

OAuth クライアント ID として TOSS_API_KEY を、OAuth クライアントシークレットとして TOSS_SECRET_KEY を使用してください。次のエイリアスも、存在する場合は受け付けます：TOSSINVEST_CLIENT_ID、TOSS_CLIENT_ID、TOSSINVEST_CLIENT_SECRET、TOSS_CLIENT_SECRET。同梱の CLI は、まずプロセスの環境変数を読み取り、その後 ~/.zshrc、~/.zprofile、または ~/.profile にある単純な代入文をフォールバックとして読み取ります。

シェルの認証情報を変更した後は、呼び出し元のプロセスで再読み込みするか、新しいシェルを起動してください。継承された環境変数は、シェルファイルからのフォールバックより優先されます。invalid_client が発生した場合は、設定したクライアント ID／シークレットを確認してください。403 が発生した場合は、WTS Open API の許可 IP リストを確認してください。認証エラーの診断目的でトークンを繰り返し再発行しないでください。

シークレットは決して表示しないでください。外部ツールで使うためにユーザーが明示的に必要としている場合を除き、アクセストークン全体の表示も避けてください。scripts/tossinvest.py token は、デフォルトでトークンを伏せて表示します。

CLI クイックスタート

スキルのディレクトリから実行してください：

python3 scripts/tossinvest.py list-endpoints
python3 scripts/tossinvest.py token
python3 scripts/tossinvest.py stocks --symbols 005930,AAPL
python3 scripts/tossinvest.py prices --symbols 005930,AAPL
python3 scripts/tossinvest.py accounts

口座、資産、注文履歴、注文情報の各 API には口座シーケンスが必要です：

python3 scripts/tossinvest.py holdings --account 1
python3 scripts/tossinvest.py buying-power --account 1 --currency KRW
python3 scripts/tossinvest.py orders --account 1 --status OPEN

簡単に使えるように、TOSSINVEST_ACCOUNT、TOSS_ACCOUNT、または TOSS_ACCOUNT_SEQ を設定すると、--account を省略できます。

取引操作

create-order、modify-order、cancel-order、および request による条件付き注文の作成／変更／キャンセルは、実際の金融取引に影響する操作として扱ってください。条件付き注文は、エージェントが実行中でなくても後から取引を発生させる可能性があります。その動作と有効期限についても、許可の範囲に含まれている必要があります。

• ユーザーが自然言語で自律取引を委任した場合、その指示が有効な間は、繰り返しの買い、売り、変更、キャンセル操作を実行する許可があるものとして扱ってください。委任された実行中に、注文ごとの再確認を求めないでください。
• 現在の口座状態、市場の取引時間、買付余力、売却可能数量、警告、手数料、価格、板情報、約定、ローソク足を使って、実際の変更操作を判断してください。
• 実際に変更を行う直前にドライランを実施し、正確なリクエスト本文を検証してください。そのうえで、委任された目的と現在の市場データに引き続き合致する場合は、同じ操作を自律的に実行してください。
• 実際に変更を行った後は、注文状況を確認し、適切であれば委任されたループを続けてください。待機、変更、キャンセル、後続注文の発注を行うか、簡潔な報告をして停止してください。
• 実際の注文変更には、--execute と --yes の両方が必要です。
• 注文の作成には --client-order-id の使用を推奨します。--allow-no-client-order-id も指定しない限り、CLI はこれを指定しない実際の create-order 呼び出しをブロックします。

ドライランの例：

python3 scripts/tossinvest.py create-order --account 1 --symbol 005930 --side BUY --order-type LIMIT --quantity 1 --price 70000 --client-order-id test-001

実際の注文執行の例：

python3 scripts/tossinvest.py create-order --account 1 --symbol 005930 --side BUY --order-type LIMIT --quantity 1 --price 70000 --client-order-id test-001 --execute --yes

レスポンス処理

認証不要のリクエストが成功した場合は、共通の JSON エンベロープで result を含むレスポンスが返されます。OAuth トークンのレスポンスは OAuth2 の形式を使用します。エラーが発生した場合は、HTTP ステータス、X-Request-Id（referenceId、x-amz-cf-id、または従来の cf-ray を代替として使用）、Toss のエラーコード／メッセージ／データ、レート制限ヘッダーを記録してください。

CLI は、次の 2 つの失敗モードを自動的に処理します。

• キャッシュされたトークンで 401 が返された場合：トークンを 1 回再発行し、再試行します。クライアントごとに有効なアクセストークンは 1 つだけなので、別のプロセスがトークンを発行すると、キャッシュは通知なしに無効になります。
• 429 が返された場合：--max-retries の回数（デフォルトは 2、または TOSSINVEST_MAX_RETRIES）まで再試行し、ジッターを加えて Retry-After または X-RateLimit-Reset の時間だけ待機します。無効にするには --max-retries 0 を指定します。

CLI を使用せずに API を呼び出す場合も、同じ動作を実装してください。list-endpoints は各エンドポイントの rateLimitGroup を報告します。グループごとにループの実行頻度を調整し、X-RateLimit-Remaining が 0 になる前に確認してください。

CLI は gzip レスポンスをデコードします。注文結果が不確かな場合は、再試行する前に注文状態を確認し、10 分の有効期間内は同じボディと clientOrderId を保持してください。結果を照合できない場合は、処理を中止してください。