{"openapi":"3.0.1","info":{"title":"ETF 固定历史数据 · 开放平台","description":"本页用于普通用户调试开放接口。先在门户申请并复制 Token，再到本页点击 Authorize 填写 `Bearer <Token>` 后发起请求。 文档仅包含开放接口（不含门户与管理端内部接口），响应统一为 JSON（code/message/data/requestId/ts）。","termsOfService":"/legal/terms","contact":{"name":""},"version":"2.0"},"servers":[{"url":"http://analytical-data.xray.top","description":"Generated server url"}],"tags":[{"name":"开放 · 元数据","description":"连通性、只读库健康检查、数据日期边界与覆盖范围。"},{"name":"开放 · 数据质量","description":"区间覆盖、缺口检查与数据完整性排查。"},{"name":"开放 · 行情","description":"证券检索（代码/名称）、交易日历、个股日 K、日快照、板块（行业/概念）与涨停池。"},{"name":"开放 · 批量行情","description":"跨日期、跨板块、跨股票集合的通用批量读取接口。"},{"name":"开放 · 外盘行情","description":"外盘股票/ETF 与商品/期货标的字典。"},{"name":"开放 · 外盘批量行情","description":"外盘股票/ETF 与商品/期货日线批量读取接口。"}],"paths":{"/api/v2/open/meta/ping":{"get":{"tags":["开放 · 元数据"],"summary":"连通性探测（Ping）","description":"校验 Bearer Token 是否有效，并回显 Token 主键、授权 scope 与请求路径。 调试时可在 Knife4j「文档管理 → 全局参数设置」或本页「Authorize」中配置 Authorization。 成功时 HTTP 200，业务 code=0；未授权 401，限流 429。\n\nRequired scope: `etf:meta:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"ping","parameters":[{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseOpenApiPing（统一响应信封（连通性探测））"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:meta:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/etf/bars/query":{"post":{"tags":["开放 · 行情"],"summary":"POST 查询 ETF K 线","description":"适用于避免复杂查询 URL 过长；边界与 GET 完全一致。\n\nRequired scope: `etf:bars:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"barsQuery","parameters":[{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EtfBarsQueryRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfBarsPageDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:bars:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/etfs":{"get":{"tags":["开放 · 行情"],"summary":"检索 ETF","description":"Required scope: `etf:security:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"list","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfBasicPageDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:security:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/etfs/{tsCode}":{"get":{"tags":["开放 · 行情"],"summary":"ETF 基础信息详情","description":"当前数据每个代码通常有两个日期表示变体，本接口全部返回，不任取第一行。\n\nRequired scope: `etf:security:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"detail","parameters":[{"name":"tsCode","in":"path","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfBasicDetailDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:security:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/etf/coverage":{"get":{"tags":["开放 · 行情"],"summary":"ETF 数据覆盖","description":"返回归档版本各频率文件数、行数和最小/最大时间。\n\nRequired scope: `etf:quality:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"coverage","parameters":[{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfDatasetCatalogDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:quality:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/etf/bars":{"get":{"tags":["开放 · 行情"],"summary":"查询 ETF K 线","description":"使用 Manifest 文件裁剪、PreparedStatement 与 c2 keyset 游标；不计算总行数。\n\nRequired scope: `etf:bars:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"bars","parameters":[{"name":"tsCode","in":"query","required":true,"schema":{"type":"string"},"example":"510300.SH"},{"name":"interval","in":"query","required":true,"schema":{"type":"string"},"example":"15m"},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-04-17"},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-09-15"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"adjust","in":"query","description":"none/qfq/hfq；qfq 基准为请求区间内截止 end 末条记录，不随分页变化","required":false,"schema":{"type":"string","default":"none"}},{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfBarsPageDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:bars:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/dataset":{"get":{"tags":["开放 · 行情"],"summary":"ETF 数据集目录","description":"Required scope: `etf:meta:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"datasets","parameters":[{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfDatasetCatalogDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:meta:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}},"/api/v2/open/dataset/schema":{"get":{"tags":["开放 · 行情"],"summary":"ETF 数据集 schema","description":"Required scope: `etf:meta:read`；`etf:read` 可作为 ETF 总读权限访问。","operationId":"schema","parameters":[{"name":"interval","in":"query","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"默认参数：Bearer stk_","required":false,"schema":{"type":"string","default":"Bearer stk_"}},{"name":"X-Request-Id","in":"header","description":"可选，客户端请求关联 ID。","required":false,"schema":{"type":"string"}},{"name":"X-Client-Name","in":"header","description":"可选，调用方名称或脚本标识。","required":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"建议 application/json。","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEtfSchemaDto"}}}}},"security":[{"Authorization":[]}],"x-required-scope":"etf:meta:read","x-market-read-compatible":false,"x-etf-read-compatible":true,"x-token-types":["open_user","admin"]}}},"components":{"schemas":{"EtfBarDto":{"type":"object","properties":{"tsCode":{"type":"string"},"tradeDate":{"type":"string","format":"date"},"tradeTime":{"type":"string","format":"date-time"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"vol":{"type":"number"},"amount":{"type":"number"},"adjFactor":{"type":"number"},"preClose":{"type":"number"},"change":{"type":"number"},"pctChg":{"type":"number"},"etfName":{"type":"string"},"totalShare":{"type":"number"},"totalSize":{"type":"number"},"nav":{"type":"number"},"exchange":{"type":"string"},"rawClose":{"type":"number","description":"复权计算前的原始收盘价；none 模式为空"},"adjustmentStatus":{"type":"string","description":"raw / adjusted / missing_factor / missing_anchor；缺失因子不自动填 1"}},"description":"ETF K 线数据行"},"EtfBarsPageDto":{"type":"object","properties":{"datasetVersion":{"type":"string"},"tsCode":{"type":"string"},"interval":{"type":"string"},"adjust":{"type":"string","description":"none 原始价格 / qfq 前复权 / hfq 后复权"},"adjustmentMethod":{"type":"string","description":"复权算法版本，固定为 factor-v1"},"adjustmentAnchorTime":{"type":"string","description":"qfq 基准：请求区间内截止 end 的末条记录时间；跨页固定","format":"date-time"},"adjustmentAnchorFactor":{"type":"number","description":"qfq 基准因子；空值或非正数时不能计算前复权"},"items":{"type":"array","description":"当前页/当前结果集数据行数组","items":{"$ref":"#/components/schemas/EtfBarDto"}},"count":{"type":"integer","description":"本次返回行数，即 items.length","format":"int32"},"total":{"type":"integer","format":"int64"},"totalRelation":{"type":"string"},"nextCursor":{"type":"string","description":"下一页游标；无下一页或接口不分页时为 null"},"hasMore":{"type":"boolean","description":"是否还有下一页"},"scannedFiles":{"type":"integer","format":"int32"},"estimatedScanBytes":{"type":"integer","format":"int64"}},"description":"ETF K 线游标分页结果"},"EtfBarsQueryRequest":{"required":["end","interval","start","tsCode"],"type":"object","properties":{"tsCode":{"type":"string"},"interval":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"cursor":{"type":"string"},"limit":{"type":"integer","format":"int32"},"adjust":{"type":"string","description":"none / qfq / hfq，默认 none；qfq 以查询 end 为基准"}}},"EtfBasicDetailDto":{"type":"object","properties":{"tsCode":{"type":"string"},"variantCount":{"type":"integer","format":"int32"},"dataQualityStatus":{"type":"string"},"representationIssue":{"type":"string"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/EtfBasicVariantDto"}}}},"EtfBasicPageDto":{"type":"object","properties":{"datasetVersion":{"type":"string"},"items":{"type":"array","description":"当前页/当前结果集数据行数组","items":{"$ref":"#/components/schemas/EtfBasicSummaryDto"}},"count":{"type":"integer","description":"本次返回行数，即 items.length","format":"int32"},"total":{"type":"integer","format":"int64"},"totalRelation":{"type":"string"},"nextCursor":{"type":"string","description":"下一页游标；无下一页或接口不分页时为 null"},"hasMore":{"type":"boolean","description":"是否还有下一页"}}},"EtfBasicSummaryDto":{"type":"object","properties":{"tsCode":{"type":"string"},"name":{"type":"string"},"exchange":{"type":"string"},"etfType":{"type":"string"},"variantCount":{"type":"integer","format":"int32"},"dataQualityStatus":{"type":"string"}}},"EtfBasicVariantDto":{"type":"object","properties":{"tsCode":{"type":"string"},"csname":{"type":"string"},"extname":{"type":"string"},"cname":{"type":"string"},"indexCode":{"type":"string"},"indexName":{"type":"string"},"setupDate":{"type":"string"},"listDate":{"type":"string"},"listStatus":{"type":"string"},"exchange":{"type":"string"},"managerName":{"type":"string"},"custodianName":{"type":"string"},"managementFee":{"type":"number"},"etfType":{"type":"string"}}},"EtfDatasetCatalogDto":{"type":"object","properties":{"datasetVersion":{"type":"string"},"schemaVersion":{"type":"string"},"generatedAt":{"type":"string"},"timezone":{"type":"string"},"compression":{"type":"string"},"freshnessStatus":{"type":"string"},"rowGroupSize":{"type":"integer","format":"int32"},"datasets":{"type":"array","items":{"$ref":"#/components/schemas/EtfDatasetDto"}}}},"EtfDatasetDto":{"type":"object","properties":{"interval":{"type":"string"},"partitionStrategy":{"type":"string"},"rowCount":{"type":"integer","format":"int64"},"fileCount":{"type":"integer","format":"int32"},"parquetBytes":{"type":"integer","format":"int64"},"minTime":{"type":"string"},"maxTime":{"type":"string"}}},"EtfSchemaDto":{"type":"object","properties":{"datasetVersion":{"type":"string"},"interval":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/EtfSchemaFieldDto"}}}},"EtfSchemaFieldDto":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"nullable":{"type":"boolean"}}},"OpenApiPing（开放平台连通性探测结果）":{"type":"object","properties":{"message":{"type":"string","description":"连通性提示信息","example":"open api reachable"},"tokenId":{"type":"integer","description":"当前 Bearer Token 对应的内部 Token 主键","format":"int64","example":3},"scope":{"type":"string","description":"当前 Token 授权 scope","example":"market:read"},"path":{"type":"string","description":"本次请求路径","example":"/api/v2/open/meta/ping"}},"description":"开放平台连通性探测结果。"},"ApiResponseEtfBarsPageDto":{"type":"object","properties":{"code":{"type":"integer","description":"业务错误码（0=成功，非0=失败）","format":"int32","example":0},"message":{"type":"string","description":"提示信息（成功通常为 success；失败为错误提示）","example":"success"},"data":{"$ref":"#/components/schemas/EtfBarsPageDto"},"requestId":{"type":"string","description":"请求追踪 ID（用于定位日志与排障）","example":"req_xxx"},"ts":{"type":"string","description":"服务端响应时间（Asia/Shanghai）","format":"date-time"}}},"ApiResponseEtfBasicDetailDto":{"type":"object","properties":{"code":{"type":"integer","description":"业务错误码（0=成功，非0=失败）","format":"int32","example":0},"message":{"type":"string","description":"提示信息（成功通常为 success；失败为错误提示）","example":"success"},"data":{"$ref":"#/components/schemas/EtfBasicDetailDto"},"requestId":{"type":"string","description":"请求追踪 ID（用于定位日志与排障）","example":"req_xxx"},"ts":{"type":"string","description":"服务端响应时间（Asia/Shanghai）","format":"date-time"}}},"ApiResponseEtfBasicPageDto":{"type":"object","properties":{"code":{"type":"integer","description":"业务错误码（0=成功，非0=失败）","format":"int32","example":0},"message":{"type":"string","description":"提示信息（成功通常为 success；失败为错误提示）","example":"success"},"data":{"$ref":"#/components/schemas/EtfBasicPageDto"},"requestId":{"type":"string","description":"请求追踪 ID（用于定位日志与排障）","example":"req_xxx"},"ts":{"type":"string","description":"服务端响应时间（Asia/Shanghai）","format":"date-time"}}},"ApiResponseEtfDatasetCatalogDto":{"type":"object","properties":{"code":{"type":"integer","description":"业务错误码（0=成功，非0=失败）","format":"int32","example":0},"message":{"type":"string","description":"提示信息（成功通常为 success；失败为错误提示）","example":"success"},"data":{"$ref":"#/components/schemas/EtfDatasetCatalogDto"},"requestId":{"type":"string","description":"请求追踪 ID（用于定位日志与排障）","example":"req_xxx"},"ts":{"type":"string","description":"服务端响应时间（Asia/Shanghai）","format":"date-time"}}},"ApiResponseEtfSchemaDto":{"type":"object","properties":{"code":{"type":"integer","description":"业务错误码（0=成功，非0=失败）","format":"int32","example":0},"message":{"type":"string","description":"提示信息（成功通常为 success；失败为错误提示）","example":"success"},"data":{"$ref":"#/components/schemas/EtfSchemaDto"},"requestId":{"type":"string","description":"请求追踪 ID（用于定位日志与排障）","example":"req_xxx"},"ts":{"type":"string","description":"服务端响应时间（Asia/Shanghai）","format":"date-time"}}},"ApiResponseOpenApiPing（统一响应信封（连通性探测））":{"type":"object","properties":{"code":{"type":"integer","description":"业务错误码（0=成功，非0=失败）","format":"int32","example":0},"message":{"type":"string","description":"提示信息（成功通常为 success；失败为错误提示）","example":"success"},"data":{"$ref":"#/components/schemas/OpenApiPing（开放平台连通性探测结果）"},"requestId":{"type":"string","description":"请求追踪 ID（用于定位日志与排障）","example":"req_xxx"},"ts":{"type":"string","description":"服务端响应时间（Asia/Shanghai）","format":"date-time"}}}},"securitySchemes":{"Authorization":{"type":"http","description":"默认参数：`Bearer stk_`（后续拼接完整 Token 明文）","scheme":"bearer","bearerFormat":"API Token"}}},"x-openapi":{"x-setting":{"customCode":200,"language":"zh-CN","enableSwaggerModels":true,"swaggerModelName":"Swagger Models","enableReloadCacheParameter":false,"enableAfterScript":true,"enableDocumentManage":true,"enableVersion":false,"enableRequestCache":true,"enableFilterMultipartApis":false,"enableFilterMultipartApiMethodType":"POST","enableHost":false,"enableHostText":"","enableDynamicParameter":false,"enableDebug":true,"enableFooter":true,"enableFooterCustom":false,"enableSearch":true,"enableOpenApi":true,"enableHomeCustom":false,"enableGroup":true,"enableResponseCode":true},"x-markdownFiles":[]}}