ETF 数据：从全市场清单，到那一天的折溢价
做 ETF 研究，要的从来不是"一只票的行情"，而是三件事：1716 只里怎么找到目标、单只的规模/折溢价/净值/持仓怎么看、以及那一天的折溢价是多少。我们把这三件事都做成了接口。
ETF 数据 = 找标的（全市场）＋ 看单只（7 类）＋ 能回看（历史快照）。前两项很多接口都有，第三项才是价格研究真正需要的 —— 今天的折溢价不能回答「当时贵不贵」。
四类能力，对应四个入口
按你要回答的问题选入口，不用一个接口硬凑：
| 你要回答的问题 | 入口 | 拿到什么 |
|---|---|---|
| 「有哪些 ETF 值得看？」 | /v1/screen?asset=etf | 1716 只全市场：9 类横截面排行（规模 / 估值 / 历史百分位 / 单日 / 区间涨跌 / 换手 / 成交额 / 溢折率）+ 48 个主题池（千亿 / 百亿 / 金牛奖 / 科创占比高…） |
| 「这只 ETF 现在什么情况？」 | /v1/etf?kind=概览 | 59 个字段：规模、份额、折溢价（当日/近周/近月/近季/近年均值）、资金流、估值百分位、回撤 |
| 「这只 ETF 那天贵不贵？」 | /v1/etf?kind=概览&date= | 历史快照：那一天的折溢价 / 规模 / 估值百分位（实测 2026-06-30 折溢价 0.13%，当日是 -0.15%） |
| 「它到底持有什么？」 | /v1/etf?kind=持仓 · /v1/index-constituent | Top20 重仓股带权重（加 date 看历史持仓）；全量成分股用跟踪指数查（sh000300 → 300 只） |
/v1/screen?asset=etf/v1/etf?kind=概览/v1/etf?kind=概览&date=/v1/etf?kind=持仓 · /v1/index-constituentdate 看历史持仓）；全量成分股用跟踪指数查（sh000300 → 300 只）⇒ 另外还有四类通用接口直接支持 ETF 代码：/v1/kline（K 线，默认前复权）、/v1/minute（分时）、/v1/technical（55 项技术指标）、/v1/fund（资金流）、/v1/chip（筹码：平均成本 / 获利比例 / 集中度）。
单只 ETF 的 7 类数据
同一个端点，用 kind 切换：
| kind | 给什么 | 典型用法 |
|---|---|---|
概览（默认） | 行情 + 规模 + 折溢价 + 资金流 + 回撤 + 估值（59 字段） | 判断"现在贵不贵、有没有资金在进" |
详情 | 基金要素 + 费率 + 份额 + 基金经理 + 持仓 Top20（含 top20Ratio） | 看产品本身：费率多少、跟踪谁、集中度多高 |
持仓 | Top20 成分股及权重；加 date 则为历史持仓（重仓股 + 申赎清单前 10） | 看它押注了什么 |
净值 | 历史单位净值（4 位小数）+ closePrice + 真实 navChange | 算折溢价、做净值曲线（start/end 必填） |
公司 | 管理人 / 托管人 / 跟踪指数 | 查发行方与标的指数 |
持有人 | 户数 + 机构 / 个人占比 | 看是散户盘还是机构盘 |
财务 | 资产配置：股 / 债 / 商品 / 基金占比 | 看它实际装了什么资产 |
概览（默认）详情top20Ratio）持仓date 则为历史持仓（重仓股 + 申赎清单前 10）净值closePrice + 真实 navChangestart/end 必填）公司持有人财务三条能直接跑的例子
免费端点（/v1/kline、/v1/hot）无需 Key；/v1/etf、/v1/screen、/v1/index-constituent 需付费档。
# ① 找标的：全市场按规模排行（前 20）
curl "https://api.ashareapi.com/v1/screen?asset=etf&mode=ranking&type=size&limit=20&key=$KEY"
# ② 看单只：规模 / 折溢价 / 估值 一次拿全
curl "https://api.ashareapi.com/v1/etf?code=sh510300&kind=概览&key=$KEY"
# ③ 回看：那一天的折溢价与规模
curl "https://api.ashareapi.com/v1/etf?code=sh510300&kind=概览&date=2026-06-30&key=$KEY"
# ④ 看底层：跟踪指数的全量成分股（300 只）
curl "https://api.ashareapi.com/v1/index-constituent?code=sh000300&key=$KEY"⚠️ 历史快照的两个上游边界：未来日期会按最近交易日返回（看返回行的 date 列自证，别当成拿到了未来）；上市前的日期返回全 0（会被判 ok:false，不是接口坏了）。
Agent 拿这一页就能用
接成 MCP 工具后，Agent 可以直接答这些问题 —— 下面是从「用户问句」到「该调什么」的映射：
| 用户这么问 | Agent 该调 | 要点 |
|---|---|---|
| 「有哪些 ETF / 规模最大的 ETF」 | ashare_screen(mode="label", asset="etf") 或 mode="ranking" | 不确定取值先 list=true，⛔ 不要猜 type |
| 「510300 现在什么情况」 | ashare_etf(code="sh510300", kind="概览") | 折溢价看 etfDisc，规模看 etfSize |
| 「6 月 30 日它折溢价多少」 | ashare_etf(kind="概览", date="2026-06-30") | 以返回行的 date 为准（未来日期会被回退） |
| 「它持有什么 / 重仓股」 | ashare_etf(kind="持仓") ＋ ashare_index_constituent | Top20 带权重；全量成分用跟踪指数 |
| 「沪深300 有哪些成分股」 | ashare_index_constituent(code="sh000300") | 只收指数代码，个股/ETF 会 422 |
| 「ETF 走势 / 回测」 | ashare_kline(code="sh510300", period="day") | 默认前复权；要 nofq/hfq 走 ashare_kline_batch（专业版） |
| 「ETF 资金在进还是出」 | ashare_fund(code="sh510300") | 主力净流入 + 5/10/20 日累计 |
| 「ETF 筹码/成本集中吗」 | ashare_chip(code="sh510300") | 平均成本 / 获利比例 / 集中度（ETF 也支持） |
ashare_screen(mode="label", asset="etf") 或 mode="ranking"list=true，⛔ 不要猜 typeashare_etf(code="sh510300", kind="概览")etfDisc，规模看 etfSizeashare_etf(kind="概览", date="2026-06-30")date 为准（未来日期会被回退）ashare_etf(kind="持仓") ＋ ashare_index_constituentashare_index_constituent(code="sh000300")ashare_kline(code="sh510300", period="day")ashare_kline_batch（专业版）ashare_fund(code="sh510300")ashare_chip(code="sh510300")⚠️ Agent 的三个纪律：① ashare_etf 一次只查 1 只（传逗号 422）；② 不要用 ashare_profile 查 ETF（只有代码/名称/上市日有值）；③ ETF 不在两融名单，ashare_margin_trade 恒回 NOT_DISCLOSED，别当延迟重试。
全部接口（一个不落）
ETF 涉及 12 个端点 —— 4 个专用、8 个通用（用 ETF 代码直接调）：
| 端点 | 给什么 | 档位 |
|---|---|---|
| /v1/etf | 7 类单只数据 + 历史快照（date） | 专业版 |
/v1/screen?asset=etf | 1716 只：9 类横截面排行 + 48 主题池 | 标准版起 |
| /v1/index-constituent | 指数成分股全量（sh000300 → 300 只，无权重） | 标准版起 |
/v1/hot?type=etf | ETF 热搜榜 | 免费 |
/v1/quote | 实时行情（轻量 8 字段） | 免费 |
| /v1/kline | K 线（默认前复权；分钟线标准版起） | 免费 |
| /v1/minute | 当日 / 近 5 日分时 | 标准版起 |
| /v1/technical | 55 项技术指标（MA/MACD/KDJ/RSI/BOLL…） | 专业版 |
| /v1/fund | 资金流（主力净流入 + 多日累计） | 专业版 |
| /v1/chip | 筹码：平均成本 / 获利比例 / 集中度 | 专业版 |
/v1/search | 名称 / 代码模糊搜索（消歧） | 专业版 |
| /v1/kline-batch | 多只 ETF × 同一段时间（唯一能选复权口径的入口） | 专业版 |
/v1/screen?asset=etf/v1/hot?type=etf/v1/quote/v1/search边界先说清（省你试错）
这四件事我们做不到，不是"没做好"，是上游就没有：
ETF 申赎清单（PCG）共 300 条，上游固定只显示前 10，--limit 无效。想看"持有什么"，用 /v1/index-constituent 查跟踪指数的全量成分股（没有权重）。
只有概览里的 divTtm / divTtmPct（近 12 月分红与股息率）。要定位除权日，可对比 kline 的 fq=qfq 与 fq=nofq 序列自己判断（fq 属付费档）。
/v1/screen 的 condition（因子表达式）与 strategy 只对股票生效；asset=etf 下 ranking 只有排序、没有条件过滤（上游会静默丢弃阈值）。替代：翻页取全量自己筛（limit=200 + offset，1716 只约 9 页）。
/v1/etf 的 code 传逗号会 422 —— 上游的"多只"是串行跑，10 只要 20 秒，容易超时；多只请分别请求，每只独立计次。
常见问题
/v1/kline 默认就是前复权（分红除权日不跳空），对看走势足够。要真实成交价（nofq）或后复权（hfq）用 /v1/kline-batch（专业版）—— 复权口径属付费档能力。
只要上游有该日数据就能取（实测 sh510300 2026-06-30 正常返回）；太早的日期（早于上游覆盖范围）会返回全 0 并判 ok:false。
没有。/v1/margin-trade 传 ETF 会恒回 NOT_DISCLOSED，那不是数据延迟，是该标的不在两融名单里。
能，数据齐了：全市场 9 类横截面指标（规模/估值/百分位/区间涨跌/换手/成交额/溢折率）+ 单只净值曲线 + 资金流。策略本身要你自己写 —— 我们只提供数据与验证。
想再深入
相关文档与端点说明：