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 读取。
2. 默认使用模拟运行。 下单代码必须默认启用 DRY_RUN=True（或 --dry-run）模式，只记录载荷而不发送。只有用户自行设置明确、显眼的选择加入标志， 才能实盘下单。
3. 每次下单前都要根据主数据验证交易品种。 绝不要使用手动拼接的交易品种进行下单、 修改订单或构建订单。先确认它存在于每日交易品种主数据中 （scripts/fyers_symbols.py / validate_symbol()），其中也会提供用于核对 qty 的手数。 未验证的交易品种实盘操作会以代码 -300 失败。默认情况下， fyers_client.place_order() 会强制执行此验证。
4. 实盘操作前必须确认。 运行任何会下达／修改／取消真实订单的操作前，清楚说明将要执行的操作， 并让用户确认。
5. 遵守速率限制： 每秒 10 个请求、每分钟 200 个请求、每天 100,000 个请求；订单操作每秒不超过 10 次 （遇到 HTTP 429 → 遵循 Retry-After）。每天超过每分钟上限 3 次以上 → 当天将被封禁。
6. 实时行情使用 WebSocket，绝不要通过轮询 /quotes 获取。
7. 令牌每天过期。 出现 401／代码 -8／-15／-16／-17 时，应重新登录，而不是重试。

实盘双重门槛规则（补充规则 2 和规则 4，并不取代它们）。 在默认的对话式执行模式下，你（Agent）可以自行运行模拟下单代码，并在聊天中展示真实记录的载荷。 但只有在两个门槛都满足时，你才可以自行执行实盘下单路径：(a) 代码／脚本本身要求用户自行设置明确的选择加入标志（例如 --live、在文件／ CLI 中设置 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，以及仅在需要 refresh-token 流程时使用的 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	—
根据历史 K 线回测策略	references/backtesting.md	scripts/example_strategy.py
技术指标（RSI、MACD、布林带、ATR 等）	references/indicators.md	scripts/indicators.py
可视化/报告回测表现（tear sheet、夏普比率、回撤、月度收益）	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 运行纯数据路径。绝不要运行实时下单代码来“测试”——请使用模拟运行。
• 确保枚举代码准确无误（订单 type 1/2/3/4、side 1/-1、productType、segment/ exchange ID）。这些内容见 references/endpoints.md；请勿猜测。

策略交付规范

构建策略、机器人或自动化工具时（任何超出一次性查询的内容），应将其作为自包含文件夹交付，而不是单个脚本；并且，按照上述默认的对话式执行模式，应逐步构建并在每一步实际执行，而不是一次性输出所有文件：

• 创建一个以策略命名的目录（例如 strategies/sma_crossover/），并将该策略的所有文件放在其中——信号／入场逻辑、配置、运行器、requirements.txt（如需要）、.env（按步骤 1 搭建）以及简短的 README.md。切勿把一个多部分策略全部塞进单个文件。虚拟环境、.env 和所有模块都放在这个文件夹中——在本次对话的其余过程中，所有脚本都要在此目录中，基于这些实际文件运行。
• 分步构建：编写／编辑一个小部分（例如先获取蜡烛数据，再编写信号，最后编写订单存根）→ 在策略文件夹中通过 Bash 实际运行 → 在聊天中展示实际输出 → 让用户调整方向 → 再继续下一部分。不要先写完整个策略，最后才运行一次。
• 策略编写完成后，生成一份算法的 Mermaid 流程图（数据 → 信号 → 风险检查 → 订单 → 日志），并将其保存在文件夹中（例如 flow.mmd，或嵌入文件夹的 README.md 中），以便用户一目了然地查看逻辑。向用户展示该图。
• 策略具备功能后，立即自动回测——不要等用户要求。 一旦原始策略能够使用真实数据运行，就在策略文件夹中自行基于 FYERS 历史蜡烛数据构建并运行回测（references/backtesting.md、scripts/example_strategy.py），并在聊天中展示真实指标（而不是描述会显示什么）。这是默认流程，不是提议——直接执行，无需提示。（只有用户根据“默认模式：对话式执行”明确选择不让 Agent 运行代码时，才跳过此步骤。）将回测文件放在同一策略文件夹中。
• 接着自动生成 QuantStats 绩效分析报告——同样无需用户要求。 回测生成收益序列（df["strat_ret"]）后，立即运行 scripts/quantstats_report.py（使用 html_report() 生成完整 HTML 绩效分析报告，并使用 key_metrics() 在聊天中展示主要指标），让用户通过专业视图了解其算法表现——Sharpe／Sortino／最大回撤／CAGR 和月收益热力图。将报告保存在策略文件夹中（例如 report.html），并告知用户文件路径和关键指标。需要安装 QuantStats（references/quantstats.md）；如果尚未安装，请说明情况，并仍然报告回测自身的指标。注意 references/quantstats.md 中关于日内→每日转换和“两种胜率”的注意事项。
• 首次回测成功后，提供 Supercharge Mode。 策略通过真实指标完成回测后，邀请用户对策略进行优化——交由同级技能 fyers-supercharge 处理。该技能会召集多 Agent 策略师委员会，讨论改进方案、生成优化变体、回测这些变体，并寻找有可衡量改进的版本（同时将原策略保留为不可变基线）。按以下文案进行介绍：“你的策略已准备就绪。要解锁 Supercharge Mode 吗？我们的 AI 专业策略师团队将对其进行分析、讨论改进方案、生成优化变体，并推荐更强的替代方案。”用户回答“Yes”后，切换至 fyers-supercharge。需要安装该技能；它会继承上述所有安全规则。
• 订单干运行同样如此——自行以干运行模式运行订单代码，并展示实际记录的载荷。实盘交易受门控限制（请参阅上述安全规则中的双重门控规则）。随着对话推进，你也可以主动在聊天中展示 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 客户端（profile/funds/holdings/positions/ orders/quotes/history/optionchain），支持模拟下单和 429 处理。
• scripts/fyers_symbols.py — 下载并缓存每日符号主文件，并解析名称 → 精确符号（search / info / refresh）；无需令牌（公开文件）。
• scripts/helper.py — 无需令牌的下单工具：手数/数量验证、价格按最小变动价位取整、到期日期解析、DTE，以及 order_checks()（一次完成所有下单前检查）。
• scripts/option_chain.py — 无需令牌的期权链辅助工具：parse_chain()、atm_strike()、 filter_expiry()、pcr()、straddle_cost()、max_pain()；CLI：demo。
• scripts/example_strategy.py — 端到端模板：获取 K 线 → 信号 → 模拟 下单。复制并调整；仅在显式指定 --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。