跳至主要内容
API docs by Redocly

veinmesh market data API (2.0.0)

Download OpenAPI specification:Download

The public veinmesh market data API: book snapshots, any-interval K-lines, bulk exports and live streams. The venues and markets served today are the ones GET /v2/catalog/venues and GET /v2/catalog/datasets return.

  • Instruments are named by public symbol (for example SHFE.rb2701, SSE.600000, CZCE.AP2610) or instrument_id; symbols are resolved as of a date. The symbol shape is the venue's, not a product-wide rule.
  • Every data row has ts (exchange event time, UTC), trading_day (the trading day of the instrument's exchange calendar) and seq; rows are ordered by instrument, then (ts, seq).
  • Prices and sizes are exact decimals. JSON returns them as strings by default; add numbers=float for numbers.
  • /v2 changes additively only: routes, optional parameters, response fields and enum values may be added. Clients must ignore unknown fields and treat unknown enum values as other.
  • Errors are always application/problem+json (RFC 9457); branch on code.

catalog

Instrument catalog covering venues, products, instruments, datasets and the trading calendar. A valid key is required; no data entitlement is needed and responses may be cached.

List venues

Authorizations:
bearer
header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "venues": [
    ]
}

List products

Authorizations:
bearer
query Parameters
venue
string

Venue code

header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "products": [
    ]
}

List and search instruments

Authorizations:
bearer
query Parameters
venue
string

Venue code.

product
string

Product

kind
string (InstrumentKind)
Enum: "future" "option" "stock" "etf" "fund" "index" "combo" "continuous" "synthetic_index" "fx" "other"
status
string
Default: "active"
Enum: "active" "expired" "all"
q
string

Part of a symbol or name.

as_of
string <date>

Resolve symbols and status as of this trading day; defaults to today.

cursor
string

The next_cursor of the previous page. Bound to the key.

limit
integer [ 1 .. 10000 ]
Default: 1000
header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "instruments": [
    ],
  • "next_cursor": "string"
}

One instrument's specification

Authorizations:
bearer
path Parameters
symbol
required
string

Public symbol

query Parameters
as_of
string <date>

Resolve the symbol as of this trading day; defaults to today.

header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "instrument": {
    },
  • "datasets": [
    ],
  • "availability": {
    }
}

Per-day dataset availability

Authorizations:
bearer
query Parameters
venue
required
string
dataset
string
Default: "book.snapshot"
from_day
required
string <date>
to_day
required
string <date>
header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "coverage": [
    ]
}

Resolve symbols to instruments as of a day

Authorizations:
bearer
Request Body schema: application/json
required
symbols
required
Array of strings <= 1000 items
as_of
string <date>

Responses

Request samples

Content type
application/json
{
  • "symbols": [
    ],
  • "as_of": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "as_of": "2019-08-24",
  • "results": {
    },
  • "not_found": [
    ]
}

Datasets and coverage per venue

Authorizations:
bearer
query Parameters
venue
string
header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "datasets": [
    ]
}

Trading days and sessions

Authorizations:
bearer
query Parameters
venue
required
string
product
string

Product whose session template to resolve. Sessions differ between products and venues.

from_day
required
string <date>
to_day
required
string <date>
header Parameters
If-None-Match
string

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "venue": "string",
  • "product": "string",
  • "days": [
    ]
}

Current main contract per futures product

Resolves each futures product's .main continuous symbol on the requested day. The catalog does not store virtual continuous rows as instruments; this route is their directory.

Authorizations:
bearer
query Parameters
venue
string
product
string

Product symbol such as SHFE.rb.

as_of
string <date>

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "as_of": "2019-08-24",
  • "continuous": [
    ]
}

Resolve one continuous contract

Authorizations:
bearer
path Parameters
symbol
required
string

SHFE.rb.main or SHFE.rb.c1

query Parameters
as_of
string <date>

Responses

Response samples

Content type
application/json
{
  • "catalog_version": "string",
  • "as_of": "2019-08-24",
  • "continuous": {
    }
}

data

Raw data queries and bulk exports.

Query raw data (paged)

Returns rows of one or more instruments over a time range or a trading-day range, ordered by instrument, ts and seq. Give either a time range or a trading-day range. Use exports for large amounts. The trading day under way (including any overnight session that belongs to it) is readable and updates during the session; after the close it is replaced by the settled version.

Trading days not prepared yet are fetched when queried: the service waits up to about 20 seconds, then answers 503 with code data_pending, retry_after seconds, pending (instrument-days still queued) and ready (already prepared). Retry with the same request; queued work is not repeated.

A continuous symbol (SHFE.rb.main, .cN) resolves to the contract trading on each day of a from_day/to_day range. Rows keep the continuous symbol, carry that contract's instrument_id, and add contract with the resolved contract. Use one continuous symbol per request; instant ranges are not accepted for continuous symbols.

Authorizations:
bearer
path Parameters
dataset
required
string

Dataset name. The API currently serves book.snapshot.

query Parameters
symbols
required
string

Comma-separated public symbols or instrument_ids, at most 100.

start
string <date-time>

Start (inclusive), RFC 3339 with a zone or Z, down to nanoseconds. Time-only values are rejected.

end
string <date-time>

End (exclusive), same format as start.

trading_day
string <date>

One trading day; same as from_day=to_day.

from_day
string <date>

First trading day (inclusive).

to_day
string <date>

Last trading day (inclusive).

fields
string

Comma-separated fields; all by default. Common fields are always returned.

numbers
string
Default: "string"
Enum: "string" "float"

Decimal representation in JSON.

catalog_version
string (CatalogVersion)

Pin a catalog snapshot's partition versions, for example to reproduce a backtest. Answers version_unavailable when it is no longer kept.

cursor
string

The next_cursor of the previous page. Bound to the key.

limit
integer [ 1 .. 10000 ]
Default: 1000

Responses

Response samples

Content type
application/json
{
  • "dataset": "string",
  • "catalog_version": "string",
  • "resolution": {
    },
  • "rows": [
    ],
  • "next_cursor": "string"
}

Create a bulk export

A bulk export of several instruments over several trading days. Files are streamed by this service; no storage URL is provided. The result lists the partition versions that were read, so catalog_version can reproduce it. Formats are parquet and csv. Trading days not prepared yet are fetched first (status stays running, pending is the remaining count). Each file is at most about 1 GB; rows are grouped in 31-day segments, ordered by instrument and time inside a segment. Files are kept for 7 days.

Authorizations:
bearer
Request Body schema: application/json
required
dataset
required
string
symbols
required
Array of strings <= 5000 items
from_day
string <date>
to_day
string <date>
start
string <date-time>
end
string <date-time>
fields
Array of strings
format
required
string
Enum: "parquet" "csv"
catalog_version
string (CatalogVersion)

Catalog snapshot identifier (opaque).

Responses

Request samples

Content type
application/json
{
  • "dataset": "string",
  • "symbols": [
    ],
  • "from_day": "2019-08-24",
  • "to_day": "2019-08-24",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "fields": [
    ],
  • "format": "parquet",
  • "catalog_version": "string"
}

Response samples

Content type
application/json
{
  • "export_id": "string",
  • "status": "queued",
  • "request": {
    },
  • "catalog_version": "string",
  • "rows": 0,
  • "files": [
    ],
  • "partitions": [
    ],
  • "pending": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "problem": {
    }
}

Export status and file list

Authorizations:
bearer
path Parameters
export_id
required
string

Responses

Response samples

Content type
application/json
{
  • "export_id": "string",
  • "status": "queued",
  • "request": {
    },
  • "catalog_version": "string",
  • "rows": 0,
  • "files": [
    ],
  • "partitions": [
    ],
  • "pending": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "problem": {
    }
}

Download an export file

Authorizations:
bearer
path Parameters
export_id
required
string
file_index
required
integer >= 0

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "code": "unauthenticated",
  • "detail": "string",
  • "retry_after": 0,
  • "param": "string",
  • "pending": 0,
  • "ready": 0
}

bars

K-lines computed by the server.

K-lines

K-lines are computed by the server from the dataset. The interval must not be finer than the data resolution; unsupported combinations answer unsupported_resolution and are never silently downgraded.

Authorizations:
bearer
query Parameters
symbol
required
string

Public symbol

type
string (BarType)
Default: "time"
Enum: "time" "tick" "volume" "turnover" "range" "renko"
interval
required
string

For type: time takes seconds (70, 900) or 1d, 1w, 1mo, 1q, 1y; tick takes a number of trades; volume a size; turnover an amount; range and renko a number of ticks.

dataset
string

Dataset used for the calculation; defaults to the finest dataset available for the instrument.

anchor
string
Default: "session"
Enum: "session" "clock"

session starts at each continuous trading session and does not cross a break between sessions; clock starts at local midnight.

adjust
string
Default: "none"
Enum: "none" "diff" "ratio"

Continuous contracts take none, diff or ratio.

transform
string
Default: "none"
Enum: "none" "heikin_ashi"
fill
string
Default: "none"
Enum: "none" "forward"

Intervals without data are omitted by default; forward fills them with the previous close and sets a flag.

start
string <date-time>

Start (inclusive), RFC 3339 with a zone or Z, down to nanoseconds. Time-only values are rejected.

end
string <date-time>

End (exclusive), same format as start.

from_day
string <date>

First trading day (inclusive).

to_day
string <date>

Last trading day (inclusive).

numbers
string
Default: "string"
Enum: "string" "float"

Decimal representation in JSON.

catalog_version
string (CatalogVersion)

Pin a catalog snapshot's partition versions, for example to reproduce a backtest. Answers version_unavailable when it is no longer kept.

cursor
string

The next_cursor of the previous page. Bound to the key.

limit
integer [ 1 .. 10000 ]
Default: 1000
format
string
Default: "json"
Enum: "json" "csv"

Responses

Response samples

Content type
{
  • "symbol": "string",
  • "spec": {
    },
  • "resolution": {
    },
  • "calc_version": "string",
  • "catalog_version": "string",
  • "bars": [
    ],
  • "next_cursor": "string"
}

stream

Live data over WebSocket.

Live data over WebSocket

Upgrades to WebSocket with subprotocol veinmesh.v2. The key needs the live permission and the book_snapshot kind. One connection holds at most 100 subscriptions and 1000 symbols in total. Message shapes are StreamClientMessage and StreamServerMessage.

  • Row subscriptions: every new row arrives as data (same shape as /v2/data). from takes the last resume_token (valid for about 50 minutes) or an RFC 3339 instant on the current day; missing rows are sent before live updates.
  • Bar subscriptions (with bars): every bar of today so far is sent first, then the current bar on every change (complete=false) and once more when it closes (complete=true). A continuous contract such as SHFE.rb.main follows the contract of the day; live bars are not back-adjusted.
  • A heartbeat every 15 seconds. Slow clients have a bounded queue; when it overflows the server sends error (resync_required) and closes, never dropping data silently.
Authorizations:
bearer

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "code": "unauthenticated",
  • "detail": "string",
  • "retry_after": 0,
  • "param": "string",
  • "pending": 0,
  • "ready": 0
}

meta

Machine-readable contract.

Dataset field definitions

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "datasets": [
    ],
  • "flags": [
    ]
}

This document

Responses

Response samples

Content type
application/json
{ }