快速开始

1. 替换服务地址

本站所有示例都用占位符 https://api.<环境域名> 表示查询服务地址。同一份文档适用于每个环境：使用前把占位符整体替换为你所接入环境的服务地址（由服务提供方告知），路径 /v1/... 保持不变。

下文命令假定已在终端设置两个变量：

export BASE_URL='https://api.<环境域名>'  # 替换为实际服务地址
export ACCESS_TOKEN='<ACCESS_TOKEN>'      # 替换为账号签发的短时访问令牌

2. 检查服务

curl "$BASE_URL/v1/health"

status 为 ready 表示可以查询；为 not-ready 时 HTTP 状态是 503。publishedDatasets 是当前已发布的数据集数量。

3. 准备凭据

用 BuQuant 账号换取短时访问令牌（有效 5 分钟，换取方式见鉴权），在请求头中携带 Authorization: Bearer <ACCESS_TOKEN>。除健康检查与接口描述外，所有接口都必须携带令牌。

4. 查看数据集

curl "$BASE_URL/v1/datasets" -H "Authorization: Bearer $ACCESS_TOKEN"

datasets 中每一项有 datasetId、name、group 与 release。release 为 null 表示契约已经定义但尚未发布，此时查询返回 409 dataset-unavailable，而不是空结果。各数据集的字段与参数见数据集字典。

5. 第一次查询

数据集标识放在路径中，请求体只描述要取哪些列和哪些行：

curl -X POST "$BASE_URL/v1/datasets/equity.daily_bars/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["security_code", "trading_date", "close_price"],
    "where": [
      {"field": "security_code", "op": "eq", "value": "000001.SZ"},
      {"field": "trading_date", "op": "gte", "value": "2026-01-05"},
      {"field": "trading_date", "op": "lte", "value": "2026-01-05"}
    ],
    "page": {"limit": 1000}
  }'

响应：

{
  "datasetId": "equity.daily_bars",
  "fields": ["security_code", "trading_date", "close_price"],
  "data": [
    {"security_code": "000001.SZ", "trading_date": "2026-01-05", "close_price": "11.500000000000000000"}
  ],
  "page": {"nextCursor": null, "complete": true},
  "meta": {"releaseId": "<发布版本 ID>", "contractFingerprint": "<契约指纹>", "requestId": "<请求 ID>"}
}

结果行的键与 select 相同，是契约原名；省略 select 时返回该数据集的全部列。
十进制数值以字符串返回，保留契约声明的小数位，避免浮点误差。
where 的运算符为 eq、ne、gt、gte、lt、lte、in；in 的值是 1 至 1000 个元素的数组。
meta.releaseId 是本次查询实际使用的发布版本；继续翻页见分页与游标。

6. 生成客户端

接口描述是 OpenAPI 3.1：服务在 GET /v1/openapi.json 免鉴权提供，本站同时发布了同一份 openapi.json，两者逐字节相同。可以用任意 OpenAPI 工具从中生成类型与请求函数，不必照文档手写路径和字段。

命名规则

协议字段用 camelCase，数据集列名保持契约原名，错误码与枚举值用 kebab-case。完整说明见版本与错误。

1. 替换服务地址​

2. 检查服务​

3. 准备凭据​

4. 查看数据集​

5. 第一次查询​

6. 生成客户端​

命名规则​