ETF 数据研究接入文档

01 / 开始使用

注册时阅读固定用户协议，完成邮件验证与 TOTP 绑定；登录门户后获取试用或已审核的 Open API Token。浏览公开归档不需要 Token，调用 Open API 使用 Authorization: Bearer。Portal/Admin Cookie 与 API Token 分开，量化脚本使用 Token。

设置 ETF_API_ORIGIN 为当前平台的完整地址，ETF_API_TOKEN 为你的密钥。示例不把密钥写入代码或浏览器存储。

1curl --get "$ETF_API_ORIGIN/api/v2/open/etf/bars" \
2  --header "Authorization: Bearer $ETF_API_TOKEN" \
3  --data-urlencode 'tsCode=510300.SH' \
4  --data-urlencode 'interval=1d' \
5  --data-urlencode 'start=2025-01-01' \
6  --data-urlencode 'end=2025-12-31' \
7  --data-urlencode 'adjust=qfq' \
8  --data-urlencode 'limit=500'

02 / 数据集与字段

提供 1m、5m、15m、30m、60m、1d 六种周期。分钟线主要按年份分区，日线为独立文件。归档价格未复权，复权由 API 使用每行 adj_factor 动态计算。固定历史数据不代表实时覆盖，也不保证每只 ETF 全区间完整。

基础资料存在同代码多种日期表示；检索接口按代码归并，详情保留 variants。不得把当前名称/存续状态直接当作历史可投资股票池。缺失行、停牌、退市、时点可得性需要在研究侧明确处理。

03 / 接口目录

GET bars 参数：tsCode、interval、start、end 必填；limit 默认 500、最大 5000；cursor 可选；adjust 默认为 none。POST 使用同名 JSON 字段。日期按整天闭区间，日期时间支持 YYYY-MM-DDTHH:mm:ss；不接收任意 SQL、文件路径或数据版本。

04 / 前复权与后复权

1P = 原始 OHLC，F(t) = 当前行 adj_factor
2none: P(t)
3hfq:  P(t) × F(t)
4qfq:  P(t) × F(t) ÷ F(anchor)
5anchor = 同代码、同周期、完整请求区间内，截止 end 的末条记录

例如原始价格为 10，当前因子为 1.2，基准因子为 1.5，前复权价格为 8，后复权价格为 12。后复权沿用源因子的尺度；不会再除以请求起点因子。

推荐大批量研究请求 adjust=none，在本地用 adjFactor 计算并缓存结果，减少服务端计算。none/hfq 不额外读取基准；qfq 首次查询需要额外扫描基准，进程内使用最多 256 项 LRU 缓存。相同目录快照、代码、周期、起止时间的后续页可命中；缓存逐出或进程重启后需重新查询，并发冷请求仍可能重复加载。

qfq 响应包含 adjustmentAnchorTime / adjustmentAnchorFactor。基准按完整查询区间确定，与 limit 和当前页无关；更改 end 会改变前复权结果。跨区间拼接时应使用一致的截止时间或使用 hfq 后自行归一化。分页必须保持原请求参数。

缺失或非正 adjFactor：adjustmentStatus=missing_factor；qfq 基准因子缺失或非正：missing_anchor；对应 OHLC 返回 null。成功为 adjusted，未复权为 raw。不会取未来日期因子、不会填 1 或跨缺失行自动补齐。源因子的发布时点不在归档中，复权价格本身不能保证回测没有未来信息。

公式参考 Tushare 复权计算说明；此平台用归档原始因子计算，不调用外部行情服务。

也可以下载 Python 客户端复权工具（仅标准库），在本地完成相同计算。输入必须为 adjust=none 的原始 API 行；直接读取 Parquet 时先将 adj_factor 映射为 adjFactor。选择基准应结合策略可得时点，不要把后续因子用于早期决策。

1# 先下载本页提供的 adjust_prices.py（与脚本放在同一目录）
2from adjust_prices import adjust_bar
3
4# API 请求指定 adjust=none，按页保存原始行。
5# 显式选择同代码同周期的基准日期，从那条原始记录取得 adjFactor。
6# 例：基准因子 1.5；真实研究必须替换为已核验的实际因子。
7anchor_factor = "1.5"
8raw_bar = dict(open=10, high=12, low=9, close=10, adjFactor=1.2)
9print(adjust_bar(raw_bar, "qfq", anchor_factor=anchor_factor)["close"])  # 8
10print(adjust_bar(raw_bar, "hfq")["close"])  # 12
11# 对所有分页/分块复用同一个 anchor_factor；不要用每页末行作基准。
12# 返回价格为 Decimal，写 JSON 时可转字符串以保留计算精度。

05 / 游标与 Python

响应外壳为 code / message / data / requestId / ts。data.items 是本页数据，count 是本页条数，total 为 null。根据 hasMore 和 nextCursor 顺序翻页；游标绑定版本、代码、周期、起止时间、adjust 和算法版本，修改条件后从第一页开始。

1import os
2import requests
3
4origin = os.environ["ETF_API_ORIGIN"].rstrip("/")
5headers = {"Authorization": "Bearer " + os.environ["ETF_API_TOKEN"]}
6params = dict(tsCode="510300.SH", interval="1d", start="2025-01-01",
7              end="2025-12-31", adjust="qfq", limit=500)
8with requests.Session() as client:
9    while True:
10        response = client.get(origin + "/api/v2/open/etf/bars",
11                              params=params, headers=headers, timeout=65)
12        response.raise_for_status()
13        envelope = response.json()
14        if envelope["code"] != 0:
15            raise RuntimeError(envelope)
16        page = envelope["data"]
17        for bar in page["items"]:
18            if bar["adjustmentStatus"] != "adjusted":
19                raise ValueError("复权因子缺失，请先处理数据质量: " + str(bar))
20            # 按页写文件或送入研究流程，避免无限累积内存
21            print(bar["tradeDate"], bar["close"])
22        if not page["hasMore"]:
23            break
24        params["cursor"] = page["nextCursor"]

不支持深度 offset 或随机页跳转；不要为统计总数循环下载整个归档。需要计数时先看 /open-data 的 Manifest 摘要。

06 / 在线浏览

进入 数据阅读器，选择本地文件、HTTP URL、R2 或默认清单。先读 Schema，选择显示字段、本地别名和格式，再查询数据。文件无需上传；本地操作不修改原始 Parquet。

阅读器展示原始数据。需要复权研究结果时使用 bars API。后台数据资产表可按文件进入阅读器，公开数据目录可按周期进入。CSV 支持当前页、已缓存页和最多 10,000 行筛选结果；导出字段名使用本地显示设置。

远程文件要求 CORS 与 HTTP Range；R2 放行实际平台 Origin、GET/HEAD、Range 请求头，暴露 Content-Range、Content-Length、ETag。Worker/WASM 来自主应用，Parquet 从 R2 直读。

07 / 错误、额度与查询限制

单次时间跨度上限：1m 31 天、5m 93 天、15m 366 天、30m 730 天、60m 1825 天、1d 7300 天。候选文件与扫描字节也有预算限制；查询超时应缩小区间。

非零 code 为业务失败，即便 HTTP 成功也应检查。HTTP 401/403 检查 Token、过期和 Scope；429 按服务端限流响应等待。CURSOR_INVALID 重新发起相同查询第一页；QUERY_TOO_BROAD / QUERY_SCAN_BUDGET_EXCEEDED 缩小区间；QUERY_BUSY / QUERY_TIMEOUT 降低并发并有限重试。业务 code 实际返回数字，以上是文档中的符号名称。

平台提供历史研究数据与计算工具。使用前阅读 用户协议，并自行核实数据授权范围、样本偏差和研究结果。公开可读不等于允许再次分发。

08 / 账号与身份验证

只浏览公开归档无需注册。需要 API、用量记录或 Token 管理时，先打开 注册页，按页面提示阅读固定用户协议、滚动到底并完成阅读等待，明确同意后进入注册表单。本平台使用“邮箱 + 动态验证码”，不是传统邮箱密码登录。

1. 输入邮箱并发送验证码。服务端有邮箱域名白名单，以页面实际反馈为准。默认验证码有效期 5 分钟、重发冷却 60 秒，部署可能调整。
2. 输入邮件中的 6 位验证码。验证成功后展示 TOTP 二维码/密钥。用认证器扫码，妥善离线备份；不要把二维码或密钥发给别人。
3. 输入认证器当前的 6 位动态码，提交绑定；注册会记录此前明确同意的固定协议。绑定流程默认 10 分钟有效，过期后重新从页面开始。
4. 完成注册进入门户。若平台启用注册试用，会显示一次性的试用 Token 明文；立即保存。没有发放时通过申请页申请，不要重复注册。
5. 以后在 登录页 使用邮箱和 TOTP 登录。浏览器会话只管理账户，不能替代 Open API Bearer Token。

手机丢失或密钥不可用：打开 恢复页，通过邮件验证后重新绑定 TOTP。不要循环猜码；默认连续失败会触发短期锁定。动态码持续错误时检查手机自动校时、绑定的账号以及刚过期的验证码。

Cookie 用于登录会话与本地偏好。API Token、TOTP secret 不应写入共享文档、工单、日志或截图。退出登录后再次访问门户应要求重新登录。

09 / Token 申请、轮换与额度

在 Token 管理 查看状态、Scope、过期时间、请求和出站字节用量。默认试用配置为 24 小时有效、100 次请求、100 MiB 出站额度；这些值可以被部署配置覆盖，始终以门户实际显示为准。

需要更多额度时进入 申请页，填写名称、研究用途、权限、请求额度、字节额度与有效期。申请提交不等于立即授权，需要管理员审核；申请状态在门户申请记录中查看。

额度是滚动 24 小时窗口，不是每天零点统一清零；还存在单 Token 每 10 秒 30 次的突发限制。请求额度、字节额度和 Token 绝对过期时间互相独立。轮换/禁用再启用不应被当作清零额度的方法。请求失败也可能消耗已经预占的额度，请关注响应头与门户。

查看 调用记录 与 用量分析。聚合计数/最近使用时间可能批量刷新，不是每一次请求都即时反映；定位失败优先使用 requestId。

10 / 查询参数与响应逐项说明

下面是结构示意，不是真实行情样本；items 为空表示该查询无记录。实际返回以实时接口为准，estimatedScanBytes 是候选分片大小之和，不等于实际磁盘读取量或网络出站量。

1{
2  "code": 0,
3  "message": "success",
4  "data": {
5    "datasetVersion": "v2026-07-31-r2",
6    "tsCode": "510300.SH",
7    "interval": "1d",
8    "adjust": "none",
9    "adjustmentMethod": "factor-v1",
10    "adjustmentAnchorTime": null,
11    "adjustmentAnchorFactor": null,
12    "items": [],
13    "count": 0,
14    "total": null,
15    "totalRelation": "unknown",
16    "nextCursor": null,
17    "hasMore": false,
18    "scannedFiles": 1,
19    "estimatedScanBytes": 123456
20  },
21  "requestId": "example-request-id",
22  "ts": "2026-09-14T12:00:00"
23}

count 是当前页条数；hasMore=true 时必须使用 nextCursor；total=null / totalRelation=unknown 表示没有做总数扫描。datasetVersion 固定；scannedFiles 是候选分片数量。qfq 的 adjustmentAnchorTime/Factor 标记当前查询基准，none/hfq 没有这个基准。

日线只用 tradeDate，tradeTime 为空；分钟线包含 tradeTime。价格允许 null，不应转换成零。所有频率保留原始 adjFactor；rawClose 仅在复权模式保留原始收盘价。NaN、空白显示和缺失行不是同一概念。

11 / 多语言调用与有限重试

先在本地终端设置 ETF_API_ORIGIN 和 ETF_API_TOKEN。API 域名使用当前站点，不要把 Parquet 文件域名当作 API 地址。下面的 POST 与 GET 查询规则完全一致。

1curl --request POST "$ETF_API_ORIGIN/api/v2/open/etf/bars/query" \
2  --header "Authorization: Bearer $ETF_API_TOKEN" \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "tsCode": "510300.SH",
6    "interval": "15m",
7    "start": "2026-07-01",
8    "end": "2026-07-31",
9    "limit": 500,
10    "adjust": "none"
11  }'

1// Node.js 22；只在服务端/本地脚本使用，不把 Token 写入公开网页。
2const origin = process.env.ETF_API_ORIGIN?.replace(/\/$/, "");
3const token = process.env.ETF_API_TOKEN;
4if (!origin || !token) throw new Error("请设置环境变量");
5const params = new URLSearchParams({
6  tsCode: "510300.SH", interval: "15m",
7  start: "2026-07-01", end: "2026-07-31",
8  adjust: "none", limit: "500"
9});
10let lastCursor;
11for (;;) {
12  const response = await fetch(origin + "/api/v2/open/etf/bars?" + params, {
13    headers: { Authorization: "Bearer " + token },
14    signal: AbortSignal.timeout(35000)
15  });
16  const body = await response.json();
17  if (!response.ok || body.code !== 0) {
18    throw new Error(JSON.stringify({
19      status: response.status, code: body.code, requestId: body.requestId
20    }));
21  }
22  // 替换成按页落盘；不要把全部页面保存在数组里。
23  console.log(body.data.items.length);
24  if (!body.data.hasMore) break;
25  const cursor = body.data.nextCursor;
26  if (!cursor || cursor === lastCursor) throw new Error("游标未推进");
27  params.set("cursor", cursor);
28  lastCursor = cursor;
29}

Python 依赖安装：python -m pip install requests。上一节完整分页示例适合验证连通性；需要容错时可使用下面的有限重试函数替换读页动作。网络连接异常由调用方记录断点并决定恢复，不无限重试。

1import random
2import time
3import requests
4
5def read_page(client, url, params, headers):
6    """最多 4 次；仅重试只读查询，不用于注册/Token 轮换。"""
7    for attempt in range(4):
8        response = client.get(url, params=params, headers=headers,
9                              timeout=(5, 35))
10        try:
11            body = response.json()
12        except ValueError:
13            body = {}
14        if response.ok and body.get("code") == 0:
15            return body["data"]
16        code = body.get("code")
17        # 429 可能是 24h 配额耗尽；交给调用方查看额度头后决定何时恢复。
18        if response.status_code == 429:
19            raise RuntimeError("检查 X-RateLimit-* / X-ByteQuota-*，不要立即重试")
20        if code not in (50311, 50312) or attempt == 3:
21            raise RuntimeError({
22                "status": response.status_code,
23                "code": code, "requestId": body.get("requestId")
24            })
25        time.sleep(min(8, 2 ** attempt) + random.random())
26    raise RuntimeError("重试次数已耗尽")

HTTP 429 不一定是瞬间请求太快，可能是 24 小时额度不足；盲目每秒重试只会增加拒绝与日志。参数错误、权限错误、游标错误不会因为重试同一请求自行恢复。注册、审批、删除、Token 轮换等写操作不要套用只读重试逻辑。

12 / 推荐的批量研究工作流

1. 先查目录和 Schema，确认版本、周期、字段和时间范围。覆盖范围是 Manifest 事实，不保证每只 ETF 每个时间点都有值。
2. 小规模接入用单代码 bars API；大批量训练优先将公开 Parquet 下载到本地离线研究，不要用数千次预览请求搬运完整归档。
3. 按代码与有限时间窗口串行游标读取。每页成功落盘后，再保存“版本、代码、周期、起止、adjust、nextCursor”断点。对超出跨度限制的任务拆分时间窗口，处理闭区间边界去重。
4. 原始行情保留一份；本地复权结果单独保存并记录公式、基准日期/因子和工具版本。不要覆盖原始数据，不要将已复权价格再次乘因子。
5. 处理缺失因子、缺失行情、同代码多种资料表示和存续期；再基于一致价格口径计算相邻收益率。单位未核验前不要计算换手率、成交量加权价或规模指标。
6. 建立样本内/外划分与数据可得时点约束。固定数据版本有助于复现，但不能消除幸存者偏差和未来函数。

尤其注意：API 前复权使用完整请求区间的末条记录为基准。分别查询不同窗口得到的 qfq 结果不一定能直接拼接；跨窗口研究可取原始数据，在客户端用统一基准重算。若基准行因子缺失，不能悄悄改用更早日期而不记录口径。

API 与 Viewer 不是同一个排序契约：API 按代码内时间推进；Viewer 用文件/物理行位置浏览原始数据，不应把 Viewer 当前顺序视为研究时序。研究前自行按代码和时间排序并检查重复值。

13 / 阅读器详细操作

字段、筛选与分页

字段配置可选择显示列、修改显示名称、调整顺序/宽度和格式（自动、文本、数值、日期、日期时间、JSON）。改名只影响本地展示与 CSV 列头，不改变 Parquet，也不改变 API 字段名。至少保留一列；隐藏不需要的列可减少列式读取工作。

筛选器支持等于、不等于、比较、包含、前缀、为空/非空。多个条件按 AND 组合；字符串条件不是正则表达式。按“应用并查询”生效，修改条件后回到新查询的起点；参数通过 prepared parameters 绑定，而不是把用户输入直接拼进 SQL。

表格只渲染可见行。下一页是游标查询，不是深度 OFFSET；当前缓存最多 5 页、16 MiB，旧页会被逐出。缓存页不是整份数据，不能用当前行数推断文件总量。首次启动需加载 DuckDB Worker/WASM，大文件首次解析可能比后续页慢。

CSV 导出

支持当前页、已缓存页和最多 10,000 行筛选结果。缓存导出只覆盖当时仍在缓存中的页，不是所有曾经浏览过的数据。列顺序、列头和显示格式随本地设置；null 导出为空单元格，文件带 UTF-8 BOM，便于常见表格软件识别中文。

以 =、+、-、@ 开头的导出文本会添加单引号防止电子表格公式执行；负数字符串也可能因此成为文本。CSV 是展示结果导出，不是无损数值存档。需要严格类型/精度时使用原始 Parquet 或 API，不要从 CSV 反推原始浮点数。

偏好、隐私和资源占用

偏好按数据源保存在浏览器 localStorage；小型 Cookie 保存当前偏好，过大时只保存指针。它不是云端同步；清理站点数据或使用隐身窗口会失去配置。不要在 URL 中放长期私钥；带签名参数的临时链接可能暴露于地址栏、浏览器历史或本地偏好中。

“只读”表示不会修改源文件，不意味着任意查询都只下载少量字节。Range 可以避免整文件回退，但筛选/投影如果需要访问大量 Row Group，累计传输仍可能接近整文件。不要同时打开很多大文件标签页；长期高负载研究应转本地 DuckDB/API。

14 / 管理员使用指南

管理员身份由平台运营方授予，普通注册不自动变成管理员。使用管理员登录态进入后台；Open API etf:read 不授予后台写权限。

1. 数据资产：查看固定 v2026-07-31-r2 的完成标记、文件数和 Schema；通过“浏览文件”只读核验。平台不提供用户切换训练版本功能。
2. 申请审核：核对研究用途与最小 Scope，再设置额度、有效期和审批结果。不要为普通量化用户分配 admin:* 或系统运维 Token。
3. Token/用户：处理异常用量、泄露、禁用与轮换。确认操作对象，记录 requestId/审计事件；禁止把明文 Token 发到公告或工单。
4. 用量与审计：对照接口、状态码和时间范围识别大范围扫描、重复重试、额度不足；对公开业务给出明确限制，不通过无限放大资源掩盖慢查询。
5. 通知：批量邮件会真实发送，正式调度前先确认发信域名、目标名单与退订规则；测试时只用指定测试邮箱或隔离收件器。

本地验收环境会模拟邮件供应商，但生产收件成功、HTTPS、域名 CORS、备份恢复和服务器容量需要独立验收。页面能打开并不等于可以直接上线。

15 / 常见问题与安全边界

反馈问题时提供：操作步骤、页面/接口路径、查询参数（去掉密钥）、发生时间、HTTP 状态、业务 code、requestId、周期和版本。不要发送 Authorization、Cookie、TOTP secret、完整验证码邮件或带签名参数的私有 URL。

R2 配置应放行实际站点 Origin（localhost 和 127.0.0.1 是不同 Origin），GET/HEAD 和 Range 请求头，并暴露 Content-Range、Content-Length、ETag。浏览器跨域配置与 API 的 Token 权限是两层独立机制。生产使用 HTTPS 和安全 Cookie，不把本地演示密钥带上线。

本手册依据当前实现，不保证数据授权可用于任意再分发或商业交易用途。阅读 用户协议 后使用；价格复权不是交易可执行价，也不构成投资建议。