1 概述

黄金眼数据查询接口提供证券市场主力资金（黄金眼）数据的查询能力，支持按证券代码、时间范围与指定字段查询，返回日级或 3 秒级粒度的成交分布数据。本文档定义接口的请求契约、返回字段与使用规则，供接入方集成调用。

当前能力边界为：单市场、单证券、指定时间范围、指定字段查询，结果按时间倒序分页返回。

2 接口信息

请求方式

POST

Content-Type

application/json

鉴权方式

Bearer Token（详见第 3 节）

query_type

固定值 goldeneye

字符编码

UTF-8

3 鉴权

接口采用 Bearer Token 鉴权，每次查询请求须在请求头携带有效 Token。

请求头

Authorization: Bearer <token>

获取 Token

POST /api/auth/login，提交用户名与密码，返回 token 及 refresh_token

续期换发

POST /api/auth/refresh，使用 refresh_token 换发新 Token，无需重复提交用户名密码

服务端校验

校验 Token 有效性，无效或过期将拒绝请求

4 请求参数

请求体为 JSON 对象，参数说明如下。时间区间为左闭右开 [start_time, end_time)，且须满足 start_time < end_time。

请求示例

{
  "query_type": "goldeneye",
  "symbols": [
    "009898"
  ],
  "start_time": "2026-06-23 00:00:00",
  "end_time": "2026-06-23 16:00:00",
  "time_granularity": "AUTO",
  "market_id": 153,
  "fields": [
    "market_id",
    "code_str",
    "trade_date",
    "market_time",
    "contracts_0_0",
    "amount_1_1"
  ],
  "page_size": 5,
  "page_token": null
}

5 market_id 取值

单次查询仅允许传入一个 market_id，常用取值如下。

6 查询粒度

time_granularity 控制返回结果的时间粒度与数据来源，取值如下。

6.1 AUTO（默认）

由系统自动判断历史日线与当日最新快照如何拼接，适用于无需自行区分历史与实时数据的默认查询场景。

• 当 end_time 不在今天时，只返回历史日级数据。
• 当 end_time 落在今天时：今天之前返回历史日级数据；今天当天不返回整段盘中明细，只取当日最新一条 3 秒快照，按当日日级口径参与拼接返回。

适用：在一个请求中自动获取“历史日线 + 今日最新快照”的混合结果。

6.2 DAY

强制按日粒度查询，只返回日级数据。

• 以 trade_date 为主时间字段。
• 不返回盘中 3 秒明细。
• 当日数据不由 DAY 主动补齐。

适用：日级分析、回测、离线汇总等明确不需要盘中明细的场景。

6.3 THREE_SECOND

强制按 3 秒粒度查询，只返回盘中 3 秒明细。

• 以 market_time 为主时间字段。
• 不返回任何历史日级记录。
• 查询时间范围受“最多近 7 天”限制。

适用：盘中实时监控、短周期行为观察等明确排除历史日聚合结果的场景。

7 查询规则与限制

• 单次仅支持 1 个证券代码，且不带交易所扩展名。
• 单次仅支持 1 个 market_id。
• 时间区间为左闭右开 [start_time, end_time)，须满足 start_time < end_time。
• page_size 最大 500。
• 3 秒实时数据最多查询近 7 天。
• 历史日线最多查询近 3 年。
• AUTO 模式下，即使结束日期为今天，仅补当天最后一条 3 秒记录，不受“近 7 天 3 秒明细跨度”限制。
• fields 至少传 1 个字段，仅允许白名单字段；请求未开放字段将被拒绝。
• 不支持自定义排序，结果固定按时间倒序返回。

8 返回字段

返回字段直接使用数据库标准字段名，调用方在 fields 中指定需返回的字段。仅白名单字段可用，非白名单字段请求将被拒绝。

8.1 定位与时间字段

8.2 业务字段（主力资金成交分布）

业务字段命名遵循 {指标}_{方向}_{单别} 规则，编码说明如下：

• 方向（第二位）：0 买方，1 卖方。
• 单别（第三位）：0 庄单，1 大单，2 中单，3 小单。
• 指标：contracts 成交笔数，volume 成交量，amount 成交额。

例如 contracts_0_0 表示买方庄单成交笔数，amount_1_1 表示卖方大单成交额。

买方字段（方向 = 0）

卖方字段（方向 = 1）

8.3 字段适用粒度补充

• trade_date、source_record_index、imported_at 仅日级粒度可用。
• market_time、insert_time 仅 3 秒粒度可用。
• 其余 24 个业务字段在日级与 3 秒粒度下均可用。

9 响应结构

响应示例

{
  "code": "SUCCESS",
  "message": "请求成功",
  "traceId": "TRACE-20260623-000001",
  "data": {
    "query_type": "goldeneye",
    "items": [
      {
        "market_id": 153,
        "code_str": "009898",
        "market_time": "2026-06-23T15:59:54",
        "trade_date": "2026-06-23",
        "contracts_0_0": 0,
        "amount_1_1": 0.00
      }
    ],
    "page": {
      "page_size": 5,
      "next_page_token": null,
      "total": 1
    }
  },
  "page": {
    "page_size": 5,
    "next_page_token": null,
    "total": 1
  }
}

9.1 顶层字段

9.2 items 公共字段

10 分页使用

结果按时间倒序排序后分页，采用 seek 游标翻页。

• 首次请求不传 page_token（或传 null）。
• 响应返回 page.next_page_token，没有下一页时为 null。
• 下一页请求将该值原样回填到 page_token，其余查询条件保持不变。
• next_page_token 为不透明复合游标，调用方只需原样回传，不应依赖其内部编码格式。
• total 为当前查询条件下的真实总量，而非当前页返回条数。

11 错误处理

响应通过顶层 code 标识请求结果，message 给出说明，traceId 用于问题追踪。SUCCESS 表示成功，其余取值表示失败，具体错误码以服务端返回为准。

常见拒绝场景包括：未携带或无效 Token、请求了未开放字段、参数校验失败（如时间格式错误、page_size 超限、symbols 多于 1 个、时间区间非法、3 秒数据超出近 7 天、日线数据超出近 3 年等）。接入方应根据返回的 code 与 message 进行处理，必要时凭 traceId 联系支持方定位。