快速开始

1. 取得 API 密钥

向管理员索取 API 密钥。密钥长得像 vmk_<id>_<secret>；secret 只在签发时 显示一次。

• 把它当密码：放在环境变量或密码管理器，不要放进程序、notebook、Git 或聊天。
• AI agent 或自动化流程使用独立密钥，才能单独撤销。
• 密钥有有效期限；默认与上限见限制。

export VEINMESH_API_KEY='vmk_...'

密钥还需要你要读取的权限：历史、实时、导出与盘口档数。申请时一并说明； 权限细节见 API 密钥。

2. 检查密钥

curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/venues"

任何有效密钥都能读目录。"code":"unauthenticated"（401）代表密钥错误、过期或 已撤销；"code":"forbidden"（403）会指出缺少哪项权限。其他错误见 错误。

3. 安装 Python SDK

SDK 需要 Python 3.10 以上。

pip install "veinmesh[all] @ https://data.cyberun.cloud/docs/sdk/veinmesh-0.2.0-py3-none-any.whl"

import veinmesh

client = veinmesh.Client()   # 读取 VEINMESH_API_KEY

只安装需要的 extras 见 Python SDK。

4. 找商品

rb = client.instruments(product="SHFE.rb", kind="future", status="active")
for instrument in rb[:5]:
    print(instrument["symbol"], instrument["last_trading_day"])

已知代号时可直接查：

instrument = client.instrument("SHFE.rb2701")
print(instrument["instrument"]["symbol"], instrument["datasets"])

datasets 是空数组，代表这个商品目前还没有已发布的数据。

5. 读取第一笔数据

# 18 分钟 K 线，从每个交易时段起算
k18 = client.bars("SHFE.rb2701", 1080, from_day="2026-10-01", to_day="2026-10-20").to_pandas()

# 主力连续合约的日线，价差调整
main = client.bars("SHFE.rb.main", "1d", from_day="2025-01-02", to_day="2026-10-20",
                   adjust="diff").to_pandas()

# 单一交易日的盘口快照
snap = client.data("book.snapshot", "SHFE.rb2701", trading_day="2026-10-20",
                   fields=["last", "volume", "bid_px", "ask_px"]).to_pandas()

to_pandas() 默认把小数转成 float；要保留 Decimal 请传 exact=True。

6. 继续往下

• 内核概念：交易日、时段、代号、小数与分页。
• 数据范围：目前服务哪些市场，以及怎么查已发布范围。
• 市场数据：分页、字段、K 线与连续合约。
• 批量导出：大量下载与保留期限。
• 实时流：交易时段的数据列与 K 线。
• API 文档：每个路由、参数与响应格式。
• AI agent（MCP）：让 agent 查同一套数据。