跳至主要内容

市場資料

本頁說明怎麼查資料、答案代表什麼。確切參數、預設值與回應欄位在 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。

限制​

查詢區間、資料列上限與匯出大小集中在限制。