flow — 期权资金流

​

端点

​

示例

# 默认：当日全部聚合（Order 与 Package，不限金额），最多 25 行
curl -s https://api.yehangshe.com/v1/flow/trades \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

# 只看 SPY 的 Order 聚合，权利金至少 $50,000
curl -s "https://api.yehangshe.com/v1/flow/trades?tickers=SPY&kind=order&min_premium_usd=50000" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

# SPY 最近 7 个交易日的 Flow 概览
curl -s "https://api.yehangshe.com/v1/flow/tickers/SPY/overview?window=7d" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

# 精确合约查询；冒号做 URL 编码
curl -s "https://api.yehangshe.com/v1/flow/contracts/lookup?contract_symbol=O%3ASPY261218C00600000" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

​

日期与代码

• 所有 Flow 日期参数都是 ET 交易日，只接受 YYYY-MM-DD，不接受 date-time。
• 「今天」按美东（America/New_York）日期计算，不是你本地的日期：session_date / end_session_date 晚于当天美东日期时返回 400 VALIDATION_ERROR，错误信息会写明当天的美东日期。例如北京时间早上查「今天」，美东往往还是前一天。
• 建议统一使用带 O: 前缀的完整 OCC 合约代码。flow.trades 的 contract_symbols 筛选要求使用这种 canonical 形式；多个 ticker、合约、到期日、right、side 或 strategy 用逗号分隔。
• SPX 是产品级汇总 ticker，概览、bars 和 bucket 会覆盖月度与周度 root；需要精确区分 SPX / SPXW 时，使用支持 root 的合约目录、boards 或 chain 端点。

​

数据范围

• 可查询的交易日有起点，且只保留最近约 90 天。过去的交易日没有 Flow 数据时（早于起点）返回 404 NOT_FOUND，重试无效，应改查有数据的交易日。
• 当天第一笔成交之前（例如盘前查当天）返回 503 READ_MODEL_UNAVAILABLE，开盘后同一请求即可成功；flow.trades 查当天返回空列表。
• 成交明细的起点晚于统计数据：更早的交易日里，flow.trades 与 flow.contract_bucket 返回 404 NOT_FOUND，flow.ticker_bucket 照常返回统计，但 trades 段为空、aggregate_count 为 0、volume_greater_than_oi 为 null。
• flow.contract_history 从 end_session_date 往前返回连续有数据的交易日，遇到第一个没有数据的交易日即停止，所以行数可能少于 limit；某个交易日有数据但该合约没有成交时，不出这一行。end_session_date 当天本身没有数据时，过去的交易日返回 404 NOT_FOUND，盘前查当天返回 503（要看此前的历史，把 end_session_date 设为上一交易日）。

​

分页与完整性

• flow.trades、flow.contract_options、flow.ticker_chain 和 flow.contract_bars 的下一页游标位于 _meta.next_cursor。
• flow.contract_bucket 与 flow.ticker_bucket 的 next_cursor / truncated 位于 data 内，因为它们同时表达源窗口本身是否达到上限。
• 除 flow.trades 外，分页列表按固定顺序输出：flow.contract_options 与 flow.ticker_chain 按到期日、认购/认沽、行权价、合约代码升序；flow.contract_bars 按时间升序；flow.contract_bucket 按成交时间从新到旧；flow.ticker_bucket 的成交与 top 合约按权利金从高到低。
• cursor 记住上一页最后一行的位置，下一页返回排在它之后的行。盘中数据在翻页之间更新不会让 cursor 失效：后面各页是请求时的最新值；翻页期间新出现的行，或权利金上涨排到 cursor 之前的行，本轮不会返回，已返回的行也不会重复。需要某一时刻的完整列表时，从第一页重新开始。
• cursor 绑定 command、ticker/合约、查询参数和交易日。跨查询复用，或当日列表跨到下一个交易日时，服务端返回 400 VALIDATION_ERROR；从第一页重新开始即可。
• truncated=true 表示源窗口已经达到自身上限。即使最后一页的 next_cursor 为 null，也不能把该窗口解释为完整全集。

​

注意点

• flow.contract_lookup 查询完整 OCC 代码时，会返回当日已经出现 Flow 活动的合约，即使它暂时还没有出现在按到期日浏览的 flow.contract_options 中。精确 lookup 与合约目录服务不同场景，不应要求两者在盘中每一刻完全一致。
• Flow 返回的是聚合后的成交与统计，不是逐笔原始成交。print_count 表示一个公开聚合包含的成交笔数。
• 金额字段使用 *_usd，比例字段使用 fractional *_pct（例如 0.25 表示 25%）；缺失值为 null，不会补成 0。
• 每个账户同时只能有 1 个 Flow 请求在处理，并行发出的会收到 429 IN_FLIGHT_EXCEEDED，按 Retry-After 稍后再发；请顺序调用 Flow 端点。
• 读模型短暂不可用或 Flow 查询繁忙时返回 503 READ_MODEL_UNAVAILABLE，稍后重试即可；具体策略见数据新鲜度。Flow 查询能力在所有调用方之间共享，繁忙时请求会先排队一小段时间。