市场数据

本页说明怎么查数据、答案代表什么。确切参数、默认值与响应字段在 API 文档；本页不重复。

查找前

1. 从目录找到商品。代号依日期解析；短写法有歧义时，用完整代号或 instrument_id。见目录与代号。
2. 确认它有你要的数据集。GET /v2/catalog/instruments/{symbol} 的 datasets 是空数组，代表这个商品目前还没有已发布数据。
3. 选交易日区间或时间点区间。两者是替代方案，只给一种。

H="Authorization: Bearer $VEINMESH_API_KEY"
API=https://data.cyberun.cloud

curl -s -H "$H" \
  "$API/v2/data/book.snapshot?symbols=SHFE.rb2701&trading_day=2026-10-20&limit=100" \
  | jq '.rows[] | {ts, trading_day, last, volume, bid_px, ask_px}'

读一页

每个响应有 rows、next_cursor 与 catalog_version。

• 把 next_cursor 当成 cursor 传回取下一页；null 代表结束。
• cursor 只属于产生它的查找与密钥，不要搭配不同条件重用。
• 需要重现结果时保留 catalog_version。旧版本最后会回 version_unavailable（410）。
• 排序是先商品，再 (ts, seq)，不是只依 trading_day。

数据列的小数默认是字符串；加 numbers=float 改成 JSON 数字。共同字段 （symbol、instrument_id、ts、trading_day、seq、flags）见 内核概念；数据集字段见 GET /v2/schemas。

open、high、low、limit_up、limit_down、prev_close、 prev_settlement 可为空值。交易进行中，实时层会用交易所行情填入这些字段。 已收盘交易日若服务有前一交易日的收盘价与官方结算价，会填入 prev_close 与 prev_settlement。股票在除权息日时，prev_close 是交易所公布的参考价， 不是未调整的前一日收盘；每日 live 采集会提供这个值。limit_up、 limit_down 可能仍是空值，因为下载来源没有发布。空值代表来源没有发布该行的这个值，不是零。

还在准备的交易日

服务会逐日准备历史数据。第一次查到还没准备好的交易日时：

• 请求会先等待一小段时间；
• 还没好就回 503、代码 data_pending、retry_after，以及待处理与已就绪的 instrument-day 数量；
• 用同一个请求重试，不会把工作重复排一次。

进行中的交易日（含属于它的跨夜时段）从实时层读取，并在盘中更新；收盘后换成 结算版本。

K 线

K 线由服务器从 book.snapshot 计算。请求可选：

• type：time、tick、volume、turnover、range 或 renko；
• interval：盘中时间 K 线用秒数，或 1d、1w、1mo、1q、1y；其他 类型用成交笔数、数量、金额或 tick 数；
• anchor（时间 K 线）：session 从每个连续交易时段起算，不跨休息； clock 从当地午夜起算；
• fill：略过没有数据的区间，或用前一个收盘价补值；
• transform：无，或 Heikin-Ashi；
• adjust（连续合约）：不调整、价差或比例。

curl -s -H "$H" \
  "$API/v2/bars?symbol=SHFE.rb2701&interval=1080&from_day=2026-10-01&to_day=2026-10-20" \
  | jq '.bars[] | {start, end, open, high, low, close, volume, complete}'

complete: false 代表这根 K 线还会变：它是进行中的那根，或被查找区间的起点 或终点截断。K 线的 trading_day 依商品的交易所日历，跨夜 K 线属于交易所指 定的交易日。

当 start 或 end 落在一根 K 线中间，那根只涵盖区间内的部分。它的成交量、 成交额与笔数会用区间内的 step 重算，并以 complete: false 返回。时间 K 线 保留对齐交易时段的 start 与 end；事件 K 线从区间内第一个 step 起算。

连续合约

SHFE.rb.main 跟着该商品的主力合约；SHFE.rb.c1、.c2… 是仍在交易的第 1、2… 近合约。adjust=diff 或 ratio 会把换月前后的价格接平，避免连续串行 在换月时跳空。

连续 K 线由目录中实际存在的合约计算。实时 K 线不做还原调整；每根 K 线的 contract 字段指出用了哪个合约。要知道某天 .main 对应哪个合约，用 GET /v2/catalog/continuous 或 GET /v2/catalog/continuous/{symbol}。目录不把虚拟的连续代号列为 instrument。

原始数据方面，from_day／to_day 区间会逐交易日解析连续代号对应的合约。 每行保留连续 symbol，带该合约的 instrument_id，并加上 contract 指出 解析到的合约。一次请求只能有一个连续代号。导出仍只接受单一交易日，因为 工作在创建时就固定 targets。

分辨率

K 线不能比来源数据更细。要求的周期小于交易所快照间隔时，回 unsupported_resolution（400）。交易所间隔在 GET /v2/catalog/datasets。

Python

t = client.data("book.snapshot", "SHFE.rb2701", trading_day="2026-10-20")
daily = client.bars("SHFE.rb.main", "1d", from_day="2025-01-02", to_day="2026-10-20",
                    adjust="diff")
df = daily.to_pandas()               # 小数转成 float
exact = daily.to_pandas(exact=True)  # 保留 Decimal

SDK 会把过长的区间与商品清单拆成 API 接受的请求，自动跟 next_cursor，并在 pending_timeout 内等待 data_pending。

限制

查找区间、数据列上限与导出大小集中在限制。