Market data

This page explains how to query data and what the answers mean. The exact parameters, defaults and response fields are in the API reference; this page does not repeat them.

Before you query

1. Find the instrument in the catalog. Symbols are resolved as of a date; use the full symbol or instrument_id when a short form is ambiguous. See Catalog and symbols.
2. Check that it has the dataset you need. GET /v2/catalog/instruments/{symbol} returns a datasets array; an empty array means there is no published data for that instrument yet.
3. Choose a trading-day range or an instant range. They are alternatives: give one, not both.

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}'

Reading a page

Each response has rows, next_cursor and catalog_version.

• Pass next_cursor back as cursor to get the next page. null means the end.
• A cursor belongs to the query and the key that produced it; do not reuse it with different filters.
• Keep catalog_version if you need to reproduce the result later. Old versions eventually answer version_unavailable (410).
• Ordering is by instrument, then (ts, seq), never by trading_day alone.

Rows are exact decimals as strings by default. Add numbers=float for JSON numbers. Common fields (symbol, instrument_id, ts, trading_day, seq, flags) are described in Core concepts; the dataset fields are in GET /v2/schemas.

open, high, low, limit_up, limit_down, prev_close and prev_settlement are nullable. The live tier fills them from the venue quote while the session is running. For a closed day, prev_close and prev_settlement are filled from the previous trading day's stored close and official settlement when the service has them. On an ex-dividend or ex-rights day, a stock's prev_close is the exchange's published reference price, not the unadjusted previous close; the daily live capture supplies it. limit_up and limit_down may stay null on a closed day because the download source does not publish them. A null means the source did not publish that value for that row; it is not zero.

Trading days still being prepared

The service prepares history day by day. A day that is not ready yet is fetched when first queried:

• the request waits for a short while;
• if the day is still missing, the answer is 503 with code data_pending, retry_after, and counts of pending and ready instrument-days;
• retrying with the same request does not start the work twice.

The trading day under way, including any overnight session that belongs to it, is read from the live tier and updates during the session. After the close it is replaced by the settled version.

K-lines

K-lines are computed by the server from book.snapshot. The request chooses:

• type: time, tick, volume, turnover, range or renko;
• interval: seconds for intraday time bars, or 1d, 1w, 1mo, 1q, 1y; for the other types, the number of trades, size, amount or ticks;
• anchor (time bars): session starts at each continuous trading session and does not cross a break; clock starts at local midnight;
• fill: omit empty intervals, or forward-fill the previous close;
• transform: none or Heikin-Ashi;
• adjust (continuous contracts): none, price difference or ratio.

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 means the bar can still change: it is the bar under way, or it is cut by the start or end of the requested range. A bar's trading_day follows the instrument's exchange calendar, so an overnight bar belongs to the trading day its venue assigns it to.

When start or end falls inside a bar, that bar covers only the requested part. Its volume, turnover and count are recomputed from the steps inside the range, and it is returned with complete: false. A time bar keeps its session-aligned start and end; an event bar starts at its first step inside the range.

Continuous contracts

SHFE.rb.main follows the product's main contract; SHFE.rb.c1, .c2, … follow the n-th nearest contract still trading. With adjust=diff or ratio, prices are back-adjusted across rolls so a continuous series does not jump at a roll.

Continuous bars are computed from the contracts that exist in the catalog. Live bars are not back-adjusted; the contract field on a bar says which contract was used. To learn which contract .main names on a day, use GET /v2/catalog/continuous or GET /v2/catalog/continuous/{symbol}. The catalog does not list virtual continuous symbols as instruments.

For raw data, a from_day/to_day range resolves the continuous symbol to the contract trading on each day. Rows keep the continuous symbol, carry that contract's instrument_id, and add contract with the resolved contract. Use one continuous symbol per request. Exports still require one trading day, because a job pins its targets when it is created.

Resolution

A bar cannot be finer than the source data. If the requested interval is below the venue's snapshot interval, the answer is unsupported_resolution (400). The venue's interval is in 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()          # decimals become floats
exact = daily.to_pandas(exact=True)  # keep Decimal

The SDK splits long ranges and long symbol lists into requests the API accepts, follows next_cursor, and waits for data_pending up to pending_timeout.

Limits

Query windows, row caps and export sizes are collected in Limits.