内核概念

交易日与时段

交易日是该商品所属交易所的营业日，写成 YYYY-MM-DD。它不一定等于每一笔 数据的日历日期：晚上开始的时段可能属于下一个交易日。这取决于交易所与商品， 不是全产品统一的规则。

GET /v2/catalog/calendar 以 UTC 返回时段，kind 是交易所的标签，例如 night、day、auction、pre、regular 或 post。标签是开放集合；不认得 的值就当成一般时段。

不要假设：

• 每个交易所都有夜盘；
• 夜盘一定属于下一个交易日；
• 同一交易所的两个商品共用时段样板。

请读你所用交易所与商品的日历。

时间戳与数据顺序

每笔数据列都有：

• ts：交易所事件时间，RFC 3339 UTC，奈秒精度；
• trading_day：这笔数据所属的交易日；
• seq：同一商品、同一交易日、同一时间戳内的顺序。

数据依商品、再依 (ts, seq) 排序。跨商品查找时，会先回完一个商品的时间串行， 再接下一个商品。

请求用交易日（trading_day，或 from_day 与 to_day）或时间点（start 含、end 不含）。时间点必须带时区或 Z。

代号

公开代号是 VENUE.code，例如 SHFE.rb2701、SSE.600000 或 SHFE.rb.main。code 的形状由交易所决定：

• 期货交易所的商品加交割月（SHFE.rb2701）；
• 证券交易所的交易所代码（SSE.600000）；
• 选择权串行（SHFE.rb2701-C-3000）；
• veinmesh 连续合约（SHFE.rb.main、SHFE.rb.c1）。

代号依日期解析。同一天同一个拼法对到两个商品时，API 回 ambiguous_symbol；请改用完整代号或 instrument_id。instrument_id 永不 变更、永不重用。

精确小数

价格、数量、乘数与最小跳动都是精确小数。JSON 默认以字符串返回，例如 "3061" 或 "0.01"，避免浮点误差。加 numbers=float 可改收 JSON 数字。

Python SDK 的 to_pandas() 默认把小数转成 float；传 exact=True 可保留 Decimal。

分页与目录版本

数据端点一次回一页。把响应的 next_cursor 当成 cursor 传回即可取下一页； 最后一页的 next_cursor 是 null。cursor 只属于产生它的查找与密钥。

每个响应都带 catalog_version，代表解析代号与分区所用的目录快照。把它传回 可固定可重现的结果。服务只保留有限版本的目录；太旧的版本回 version_unavailable（410）。K 线响应另外带 calc_version，代表计算规则的 版本。

API 的兼容承诺

/v2 只做加法变更：新路由、新选填参数、新响应字段与新枚举值。用户端必须忽略 不认得的字段，并把不认得的枚举值视为「其他」。不会默默改变既有请求的语意。

错误一律是 application/problem+json（RFC 9457）。请依 code 分支，不要依 detail；detail 是给人看的，可能改写。见错误。

哪些规则不能跨市场套用

以下是交易所或数据集决定的，不是 veinmesh 的产品规则：

• 是否有夜盘，以及夜盘属于哪个交易日；
• 代号形状，包括交割月的写法；
• 主力合约的定义与换月规则；
• 成交量是否为累计值，以及何时重置；
• K 线 anchor=session 使用的时段边界。

请从目录、数据集 schema 与日历读取。本手册描述目前服务市场的行为，不是所有 交易所的规则书。