黄金眼数据查询接口标准文档

项目	内容
接口路径	`POST /api/marketdata/query`
query_type	`goldeneye`
版本	v1.0
日期	2026-07-30

1 概述

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

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

2 接口信息

POST /api/marketdata/query

项目	内容
请求方式	POST
Content-Type	application/json
鉴权方式	Bearer Token（详见第 3 节）
query_type	固定值 `goldeneye`
字符编码	UTF-8

3 鉴权

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

项目	说明
请求头	`Authorization: Bearer`
获取 Token	`POST /api/auth/login`，提交用户名与密码，返回 `token` 及 `refresh_token`
续期换发	`POST /api/auth/refresh`，使用 `refresh_token` 换发新 Token，无需重复提交用户名密码
服务端校验	校验 Token 有效性，无效或过期将拒绝请求

首次使用先调用登录接口获取 Token，后续查询请求统一在请求头携带 Authorization: Bearer ；Token 即将过期时通过刷新接口续期。

4 请求参数

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

参数	类型	必填	说明
`query_type`	string	是	统一市场数据入口的路由参数，固定为 `goldeneye`。
`symbols`	string[]	是	证券代码数组。当前仅支持传入 1 个元素，且不带 `.XSHG`、`.XSHE` 等交易所扩展名，直接传证券代码。
`start_time`	datetime	是	查询起始时间，采用本地交易所时间，格式 `yyyy-MM-dd HH:mm:ss`。
`end_time`	datetime	是	查询结束时间，采用本地交易所时间，格式 `yyyy-MM-dd HH:mm:ss`。
`time_granularity`	string	是	查询粒度，取值 `AUTO`、`DAY`、`THREE_SECOND`，详见第 6 节。
`market_id`	int	是	市场 ID，单次只允许传入 1 个值，取值见第 5 节。
`fields`	string[]	是	指定返回字段，至少传 1 个，且仅允许白名单字段（见第 8 节）。
`page_size`	int	是	分页大小，最大 500。
`page_token`	string	否	翻页游标。首次请求不传，后续原样回传上一页响应中的 `nextpagetoken`。

请求示例：

{
  "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
}

首次请求 pagetoken 可不传；若需显式传空值，必须写为合法 JSON "pagetoken": null，不可写 page_token:null（非法 JSON 会在进入业务前被拦截）。

5 market_id 取值

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

market_id	含义
`150`	上海黄金眼
`151`	深圳黄金眼
`152`	板块黄金眼
`153`	香港黄金眼

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。
时间区间为左闭右开 [starttime, endtime)，须满足 starttime < endtime。
page_size 最大 500。
3 秒实时数据最多查询近 7 天。
历史日线最多查询近 3 年。
AUTO 模式下，即使结束日期为今天，仅补当天最后一条 3 秒记录，不受"近 7 天 3 秒明细跨度"限制。
fields 至少传 1 个字段，仅允许白名单字段；请求未开放字段将被拒绝。
不支持自定义排序，结果固定按时间倒序返回。

8 返回字段

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

8.1 定位与时间字段

字段名	适用粒度	说明
`market_id`	DAY / THREE_SECOND / AUTO	市场 ID，取值见第 5 节
`code_str`	DAY / THREE_SECOND / AUTO	证券代码
`trade_date`	DAY / AUTO	日级记录的交易日期
`market_time`	THREE_SECOND / AUTO	3 秒行情记录时间
`sourcerecordindex`	DAY	日级内部排序辅助序号
`imported_at`	DAY	日级记录导入时间
`insert_time`	THREE_SECOND	3 秒记录入库时间

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

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

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

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

买方字段（方向 = 0）

字段名	中文说明
`contracts00`	买方庄单成交笔数
`volume00`	买方庄单成交量
`amount00`	买方庄单成交额
`contracts01`	买方大单成交笔数
`volume01`	买方大单成交量
`amount01`	买方大单成交额
`contracts02`	买方中单成交笔数
`volume02`	买方中单成交量
`amount02`	买方中单成交额
`contracts03`	买方小单成交笔数
`volume03`	买方小单成交量
`amount03`	买方小单成交额

卖方字段（方向 = 1）

字段名	中文说明
`contracts10`	卖方庄单成交笔数
`volume10`	卖方庄单成交量
`amount10`	卖方庄单成交额
`contracts11`	卖方大单成交笔数
`volume11`	卖方大单成交量
`amount11`	卖方大单成交额
`contracts12`	卖方中单成交笔数
`volume12`	卖方中单成交量
`amount12`	卖方中单成交额
`contracts13`	卖方小单成交笔数
`volume13`	卖方小单成交量
`amount13`	卖方小单成交额

8.3 字段适用粒度补充

tradedate、sourcerecordindex、importedat 仅日级粒度可用。
markettime、inserttime 仅 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 顶层字段

字段名	说明
`code`	响应码，`SUCCESS` 表示请求成功。
`message`	响应说明。
`traceId`	请求追踪标识，用于问题定位。
`data`	业务数据，包含 `query_type`、`items`、`page`。
`page`	分页信息（顶层与 `data.page` 一致）。

9.2 items 公共字段

字段名	说明
`market_id`	市场 ID，取值见第 5 节
`code_str`	证券代码
`trade_date`	日级记录的交易日
`market_time`	3 秒记录的行情时间

items 中实际返回的字段由请求 fields 决定；未请求的字段不会出现在返回结果中。日级记录含 tradedate，3 秒记录含 markettime，AUTO 模式下二者按各自口径混合返回。

10 分页使用

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

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

注意：显式传空值须使用合法 JSON "pagetoken": null；写成 pagetoken:null 属于非法 JSON，请求会在进入业务前被拦截。

11 错误处理

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

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

黄金眼数据查询接口标准文档 · v1.0 · 2026-07-30 · 本文档描述接口契约与使用规则，具体错误码与参数校验细节以服务端实际返回为准。