fyers-trading

FYERS Trading API v3

公式の FYERS Developer API v3（https://api-t1.fyers.in）上で 戦略、自動化、バックテスト を構築する開発者を支援します。動作する Python（fyers-apiv3 SDK）または生の REST コードを生成し、OAuth を正しく接続し、以下の実際の資金に関する安全ルールを遵守します。

対象範囲に関する注意。 このスキルは公開開発者 API（api-t1.fyers.in + fyers-apiv3 SDK + WebSockets）を対象としています。FIA チャットアシスタントプロキシ（fia.fyers.in）ではありません。コードは自由に生成してください。FIA の「コードを書かない／注文しない」ルールはここでは適用されません。

安全ルール（変更不可 — 実際の資金）

1. シークレットは環境変数のみを経由します。 app_id、secret_id、access_token、PIN を生成コードにハードコードしたり、コミットしたりしないでください。env / .env から読み取ります。
2. デフォルトでドライラン。 注文を出すコードは、デフォルトで DRY_RUN=True（または --dry-run）モードにして、送信する代わりにペイロードをログに記録する必要があります。本番の発注には、ユーザー自身が設定する明示的で明白なオプトインフラグが必要です。
3. すべての注文の前に、シンボルをマスターに対して検証してください。 手で構築したシンボルから注文を出したり、変更したり、組み立てたりしないでください。まず毎日のシンボルマスター（scripts/fyers_symbols.py / validate_symbol()）に存在することを確認してください。これは qty を照合するためのロットサイズも提供します。検証されていないシンボルは、本番でコード -300 により失敗します。fyers_client.place_order() はデフォルトでこれを強制します。
4. 本番移行前に確認を取ってください。 実際の注文を出したり、変更したり、キャンセルしたりするものを実行する前に、それが何をするのかを明確に述べ、ユーザーに確認を取ってください。
5. レート制限を尊重してください： 10 req/秒、200 req/分、100,000 req/日。注文操作は ≤10/秒（HTTP 429 → Retry-After を尊重）。1 分あたりの上限を 1 日に 3 回を超えて破ると、その日は終日ブロックされます。
6. ライブティックには WebSocket を使用してください。 /quotes へのポーリングループは決して使用しないでください。
7. トークンは毎日失効します。 401 / コード -8/-15/-16/-17 は再ログインを意味し、リトライではありません。

本番移行のための二重ゲートルール（ルール 2 とルール 4 を詳述するもので、置き換えるものではありません）。 デフォルトの会話型実行モードでは、あなた（エージェント）はドライランの注文コードを自分で実行し、実際にログに記録されたペイロードをチャットに表示できます。ただし、本番 の注文パスを自分で呼び出せるのは、両方のゲートが成立する場合のみです：(a) コード／スクリプト自体が、ユーザー自身が設定する明示的なオプトインを必要とする（例：ファイル／CLI 内の --live、DRY_RUN=False — これはルール 2 に従い存在する必要があり、あなたはユーザーの代わりに設定しません）、かつ (b) その特定のアクションについて、チャットでユーザーから平易な言葉で入力された確認を得ている（ルール 4 に従う）。どちらのゲートも他方を代替しません — チャット確認なしのフラグ、またはフラグなしのチャット確認だけでは、本番実行には十分ではありません。

デフォルトモード：会話型実行

FYERS の戦略／データ／注文タスクのデフォルト動作：プロジェクトフォルダ内で、スクリプトを実際にその都度実行してください — コードを生成して渡すだけにしないでください。 小さな増分で開発します：戦略の小さな一部分を書き込み／編集する → プロジェクトフォルダから Bash 経由で実際に実行する → 実際の出力をチャットに表示する → ユーザーに反応／方向転換してもらう → 繰り返す。各部分を途中で実行することなく、「完成した」戦略を一度に出すことは決してしないでください。これは認証のセットアップ（以下）、データの取得、シグナルの計算、ドライラン注文、バックテスト（「戦略成果物の慣例」を参照）に適用されます。実行するものはすべて、プロジェクトフォルダ内の実在する永続ファイルでなければなりません（そのセクションを参照） — インライン／使い捨てのスニペットは決して使用しないでください。

オプトアウト： ユーザーが明示的にコードのみを求めたり、何も実行しないように言ったりした場合（例：「コードだけくれ」、「実行しないで」）、実行せずにファイルを生成する方針にフォールバックします — このスキルの以前の動作と同様です。

ステップ 0 — 環境のセットアップ (初回のみ)

ユーザーがスキルの「セットアップ」を求めた場合、またはプロジェクトの venv がまだ存在しない場合は、何よりも先に venv を作成し、ストラテジーコードの依存関係をインストールします:

python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

パッケージのインストールに失敗しても、そこで止めないでください — 残りをインストールし、失敗したものだけを単独で再試行し、ストラテジー生成に進む前に解決してください。デフォルトのパッケージ一覧とそれぞれの目的を含む詳細は、references/setup.md にあります。

ステップ 1 — 認証 (最初に、会話形式で行います)

デフォルトの会話形式実行モードでは、ユーザーにスクリプトを案内するだけでなく、チャットでユーザーと一緒に認証を行います。これはプロジェクトフォルダで行ってください:

1. 有効なトークンを自分で確認します。次を実行してください:

   python scripts/fyers_login.py --check   # prints OK if cached token is valid
   

2. トークンが存在しないか 401 であり、.env がまだ存在しない場合、自分でひな形を作成します: プロジェクトフォルダに .env を作成し、.env.example と同じキー (FYERS_APP_ID、FYERS_SECRET_ID、FYERS_REDIRECT_URI、およびリフレッシュトークンフローが必要な場合のみ FYERS_PIN) を用意しますが、値は空白にします — シークレットの値をファイルに書き込んではならず、ユーザーにシークレットの値をチャットに貼り付けるよう求めてはいけません。次に、ユーザー自身で .env を開いて値を入力するよう依頼し、他のことを行う前にユーザーの明示的な確認 (例: 「完了」/「入力しました」) を待ってください。推測して続行しないでください。
3. 確認が取れたら、OAuth フローを自分で実行します:

   python scripts/fyers_login.py           # opens auth URL, exchanges code, caches token
   

   出力された認証 URL をチャットでユーザーに伝え、ユーザーにログインしてもらい、auth_code (または完全なリダイレクト URL) をコピーして返してもらい、同じスクリプト実行内で交換を完了します。
4. 成功を自分で確認します — python scripts/fyers_client.py profile を実行し、実際の結果をチャットで報告します (動作するはずだと主張しないでください)。

これにより、日次の access_token が ~/.fyers/token.json にキャッシュされます。内部のフローは次のとおりです: generate-authcode → ユーザーがログイン → auth_code → appIdHash = SHA256("app_id:secret_id") → validate-authcode → access_token。会話形式のデフォルトを希望しないユーザー向けのスタンドアロン/手動パスを含む詳細は、references/auth.md にあります。

ステップ 2 — タスクのルーティング

ユーザーの要望…	読み込むリファレンス	使用するもの
スキル、venv、依存関係のセットアップ / インストール	references/setup.md	—
ログイン / トークン / OAuth / リフレッシュ	references/auth.md	scripts/fyers_login.py
気配値、板情報、ヒストリカル、市場ステータス	references/market-data.md	scripts/fyers_client.py
オプションチェーン、ギリシャ指標、IV、PCR、限月選択、ATM/ITM/OTM、マックスペイン	references/market-data.md	scripts/fyers_client.py + scripts/option_chain.py
注文の新規 / 変更 / キャンセル / GTT / スマート注文、ポジション	references/orders.md	scripts/fyers_client.py
シンボル文字列 (eq/fut/opt)、銘柄名 → 正確なシンボルの検索、ロット/ティック/限月	references/symbols.md	scripts/fyers_symbols.py
ライブストリーミング (データ / 注文 / TBT ソケット)	references/websocket.md	—
ヒストリカルローソク足からのストラテジーのバックテスト	references/backtesting.md	scripts/example_strategy.py
テクニカル指標 (RSI、MACD、ボリンジャー、ATR など)	references/indicators.md	scripts/indicators.py
バックテストのパフォーマンスの可視化 / レポート (ティアシート、シャープレシオ、ドローダウン、月次リターン)	references/quantstats.md	scripts/quantstats_report.py
任意のエンドポイントパス / ペイロード / 列挙コード	references/endpoints.md	—
レート制限、エラーコード、リトライ	references/rate-limits.md	—

リファレンスはオンデマンドで読んでください — 最初にすべてを読み込まないでください。endpoints.md はパス/フィールド/列挙コードの完全なカタログであり、その他はタスクに焦点を当てたものです。

ステップ 3 — 作成、検証、報告

• scripts/fyers_client.py の再利用を優先してください(キャッシュされたトークンを読み込み、 Authorization: app_id:access_token ヘッダーを追加し、安全性/レート制限のロジックをラップします)。
• コードを作成したら、インポート/コンパイルが通ることを検証し(python -m py_compile <file>)、 トークンが存在する場合はデータのみのパスを実際の API に対して実行してください。決して 実際の注文 コードを「テスト」のために実行しないでください — ドライランを使用してください。
• enum コードを正確に 把握してください(注文の type 1/2/3/4、side 1/-1、productType、セグメント/ 取引所 ID)。これらは references/endpoints.md に記載されています。推測しないでください。

ストラテジー成果物の規約

ストラテジー、ボット、または自動化(単発のクエリを超えるもの)を構築する場合、 単一のスクリプトではなく自己完結型のフォルダとして納品してください。また、上記のデフォルトの 対話型実行モードに従い、一括でのファイル出力ではなく、各ステップで実際に実行しながら段階的に 構築してください:

• ストラテジー名のディレクトリ（例: strategies/sma_crossover/）を作成し、そのすべてのファイルをそこに配置します — シグナル/エントリーロジック、設定、ランナー、必要に応じて requirements.txt、.env（ステップ 1 に従って雛形を作成）、そして短い README.md です。複数パートからなるストラテジーを決して 1 つのファイルに押し込まないでください。venv、.env、およびすべてのモジュールはこの 1 つのフォルダーに置かれます — 以降の会話では、すべてのスクリプトはここから、これらの実際のファイルに対して実行されます。
• 少しずつ構築してください: 小さな部分を 1 つ書き込み/編集する（例: ローソク足取得、次にシグナル、次に注文スタブ）→ ストラテジーフォルダーから Bash 経由で実際に実行する → 実際の出力をチャットに表示する → ユーザーに軌道修正させる → 次の部分に進む。ストラテジー全体を書いてから最後に一度だけ実行するのは避けてください。
• ストラテジーを書き終えたら、アルゴリズムの Mermaid フロー図（データ → シグナル → リスクチェック → 注文 → ログ記録）を作成し、フォルダーに保存します（例: flow.mmd、またはフォルダーの README.md に埋め込む）。ユーザーがロジックを一目で確認できるようにするためです。図をユーザーに表示してください。
• ストラテジーが機能するようになったら、自動的にバックテストを実行してください — 依頼されるまで待たないでください。 元のストラテジーが実際のデータに対して実行されたらすぐに、FYERS のヒストリカルローソク足に対して、ストラテジーフォルダー内でバックテストを自分で構築・実行し（references/backtesting.md、scripts/example_strategy.py）、実際のメトリクスをチャットに表示してください（何が表示されるかの説明ではなく）。これはデフォルトのフローであり、提案ではありません — プロンプトなしで進めてください。（ユーザーが「デフォルトモード: 会話型実行」に従い、エージェントによるコード実行を明示的にオプトアウトした場合のみスキップしてください。）バックテストは同じストラテジーフォルダーに置いてください。
• 次に、これも依頼されずに自動的に QuantStats ティアシートを生成してください。 バックテストがリターン系列（df["strat_ret"]）を生成した直後に、それに対して scripts/quantstats_report.py を実行し（完全な HTML ティアシートには html_report()、チャットで主要な数値を示すには key_metrics() を併用）、ユーザーが自身のアルゴのパフォーマンスをプロフェッショナルな視点で確認できるようにします — Sharpe/Sortino/ドローダウン/CAGR および月次リターンのヒートマップです。ティアシートはストラテジーフォルダーに保存し（例: report.html）、そのパスと主要なメトリクスをユーザーに伝えてください。QuantStats のインストールが必要です（references/quantstats.md）。インストールされていない場合はその旨を伝え、それでもバックテスト自体のメトリクスを報告してください。references/quantstats.md に記載されているイントラデイ→デイリーおよび「2 つの勝率」の注意点に留意してください。
• 最初のバックテストが成功したら、スーパーチャージモードを提案してください。 ストラテジーが実際のメトリクスを伴う動作するバックテストを備えたら、それを最適化することを提案してください — 姉妹スキルである fyers-supercharge に引き継ぎます。これはマルチエージェントのストラテジスト評議会を招集し、改善点について議論し、最適化されたバリアントを生成し、バックテストを行い、測定可能により優れたバージョンを探します（元のものを不変のベースラインとして保持します）。次のように提示してください: 「あなたのストラテジーは準備が整いました。スーパーチャージモードを解除しますか？プロのストラテジストによる AI チームが、それを分析し、改善点を議論し、最適化されたバリアントを生成し、より強力な代替案を提案します。」「はい」の場合、fyers-supercharge に切り替えます。そのスキルがインストールされている必要があり、上記のすべての安全ルールを継承します。
• 注文のドライランも同じように行います — 注文コードを自分でドライランで実行し、実際に記録されたペイロードを表示してください。本番稼働はゲートで制御されます（上記の安全ルールの 2 ゲートルールを参照）。また、会話が進むにつれて（例: ドライランや本番約定の後）、ユーザーが明示的にログを求めたときだけでなく、scripts/trade_logger.py の tail/summary 出力をチャットで積極的に提示することもできます。
• 再現性: 会話中に作成・実行したすべては、その後もストラテジーフォルダー内の実際の、単独で実行可能なファイルとして残らなければなりません（例: python strategies/sma_crossover/run.py） — 会話型実行は開発ループであり、結果を実行する唯一の方法ではありません。

スクリプト

• scripts/fyers_login.py — OAuth ログイン + 日次トークンキャッシュ（--check、--print-token）。
• scripts/fyers_client.py — 再利用可能な REST クライアント（プロフィール/資金/保有銘柄/ポジション/ 注文/クォート/ヒストリー/オプションチェーン）。ドライランでの注文発注 + 429 ハンドリングに対応。
• scripts/fyers_symbols.py — 日次のシンボルマスターファイルをダウンロード/キャッシュし、 名前 → 正確なシンボルを解決します（search / info / refresh）。トークン不要（公開ファイル）。
• scripts/helper.py — トークン不要の注文ユーティリティ: ロット/数量の検証、ティックサイズへの 価格丸め、限月日のパース、DTE、および order_checks()（すべての発注前チェックを 1 回の呼び出しで）。
• scripts/option_chain.py — トークン不要のオプションチェーンヘルパー: parse_chain()、atm_strike()、 filter_expiry()、pcr()、straddle_cost()、max_pain()。CLI: demo。
• scripts/example_strategy.py — エンドツーエンドのテンプレート: ローソク足取得 → シグナル → ドライラン 注文。コピーして改変してください。本番運用に切り替えるのは明示的な --live を指定した場合のみです。
• scripts/indicators.py — 一般的な指標向けの TA-Lib ラッパー（SMA/EMA/WMA、ボリンジャー、 ADX、RSI、MACD、ストキャスティクス、CCI、モメンタム、ROC、OBV、A/D、ATR/NATR）。talib の遅延インポート。 CLI: demo。
• scripts/quantstats_report.py — バックテストのリターン系列を可視化/レポートする QuantStats ラッパー: 完全な HTML ティアシート、Sharpe/Sortino/ドローダウン/CAGR、月次ヒートマップ。 イントラデイ→日次のリサンプリング。quantstats の遅延インポート。CLI: demo。
• scripts/trade_logger.py — 追記専用の JSONL 監査ログ（~/.fyers/trades.jsonl）。 すべての注文試行後に fyers_client.place_order() から自動的に呼び出されます。log_order()、log_event()、tail(n)、summary() を公開。CLI: tail [--n N] / summary。