Skip to main content

Catalog and calendar

The catalog tells you what exists and when it trades. This page shows the workflow; the parameters and response fields are in the API reference.

Every catalog response carries catalog_version, an ETag and Cache-Control: private, max-age=300. Send the ETag back as If-None-Match; an unchanged catalog answers 304.

Catalog endpoints need a valid key but no data permission, so they are the cheapest way to check that a key works.

Venues and markets​

Start with GET /v2/catalog/venues. Each venue has a code, name, MIC, time zone, country and the markets it serves. The markets served today are summarized on Data coverage.

curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/venues" \
  | jq '.venues[] | {code, timezone, markets}'

Products​

A product is a tradable family, for example SHFE.rb. Products carry the multiplier and tick size. List them with GET /v2/catalog/products, optionally for one venue.

curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/products?venue=SHFE" \
  | jq '.products[] | {code, name, multiplier, tick_size}'

Instruments​

An instrument is one tradable thing: a dated future, an option, a stock, an ETF, a fund or an index. Use GET /v2/catalog/instruments to search and page through them, or GET /v2/catalog/instruments/{symbol} for one.

# Every listed rebar future
curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/instruments?product=SHFE.rb&kind=future&status=active"

# One instrument, with the datasets it has
curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/instruments/SHFE.rb2701"

The single-instrument answer has instrument, datasets and, when it has no data, an availability object. datasets: [] with availability.status: reference_only means the instrument is in the catalog but has no published data; it is not an error.

Each instrument has:

  • instrument_id: stable, never reused; the right key for your own tables;
  • symbol: the public name valid at the time you ask;
  • kind, venue, product, currency, multiplier, tick_size;
  • listed_day, last_trading_day and expiry when known;
  • for stocks and funds, board (main, star, chinext, bse, fund) and risk_warning (none, st, *st); risk_warning_since is the first day veinmesh observed the current status, when known;
  • for funds, fund_type (etf, lof, reit, other) and tracking_board (main, star, chinext, bse, none): the board whose price-limit rules apply; none means no A-share board (bond, commodity, QDII, money-market or REIT funds); absent when unknown;
  • underlying, strike, right, exercise_style for options;
  • legs for combos;
  • aliases with validity periods for exchange-specific spellings.

The risk_warning value comes from the listed short name; when it changes, the catalog version changes. Stock and fund listed_day values come from reviewed public exchange snapshots; an instrument listed after its snapshot keeps listed_day: null until the snapshot is refreshed. Funds always use the fund board, including STAR and ChiNext trackers; read tracking_board to choose the price-limit rule. For SZSE funds, the exchange's published 20% price-limit fund list is authoritative: a fund on that list is star or chinext, and the rest are main (equity, 10%) or none (bond, commodity, QDII, money-market or REIT, 10%).

Symbols resolve as of a date. If a spelling matches two instruments on that day, the answer is ambiguous_symbol (409); use the full symbol or instrument_id. See Symbols.

Continuous contracts​

GET /v2/catalog/continuous lists each futures product's current .main contract for the requested day. GET /v2/catalog/continuous/{symbol} resolves one SHFE.rb.main or .cN. The answer gives the continuous symbol, its product, the actual contract and that contract's instrument_id. Virtual continuous symbols are not listed as instruments in GET /v2/catalog/instruments.

curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/continuous?product=SHFE.rb"

Paging​

Instrument lists are paged. Pass the answer's next_cursor back as cursor; null means the end. A cursor belongs to the filters that produced it.

Datasets and prepared days​

GET /v2/catalog/datasets lists each dataset with its resolution, book depth, snapshot interval and the trading days already prepared for that venue.

curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/datasets?venue=SHFE" \
  | jq '.datasets[] | {dataset, first_day, last_day, depth, resolution}'

first_day and last_day are the published range, not the source's earliest date. A day outside it can still be fetched when you query it; see Data coverage. For a single venue and dataset, GET /v2/catalog/coverage returns one status per trading day: available, missing or out_of_range.

Calendar​

GET /v2/catalog/calendar returns every trading day in a range with its sessions in UTC. Pass the venue, and usually the product: different products on one venue can have different session templates.

curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
  "https://data.cyberun.cloud/v2/catalog/calendar?venue=SHFE&product=SHFE.rb&from_day=2026-10-19&to_day=2026-10-23" \
  | jq '.days[] | {trading_day, sessions}'

Session labels are the exchange's. A night session starts on the previous calendar day and belongs to the trading day in the answer. Do not assume a label or a fixed set of labels; see Core concepts.

Calendar requests cover a limited range; see Limits and make several requests for a longer span.