快速開始

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 查同一套資料。