ETF data: from the whole market down to that day's premium
ETF research is never just "a quote for one ticker". It is three questions: how to find the target among 1,716 funds, how to read a single fund's size / premium-discount / NAV / holdings, and what the premium was on that particular day. We made all three into endpoints.
ETF data = find the target (whole market) + read one fund (7 datasets) + look back (historical snapshots). The first two are common; the third is what price research actually needs — today's premium cannot tell you whether it was expensive then.
Four capabilities, four entry points
Pick the entry point by the question you are answering:
| Your question | Entry point | What you get |
|---|---|---|
| "Which ETFs are worth a look?" | /v1/screen?asset=etf | 1,716 funds: 9 cross-sectional rankings (size / valuation / historical percentile / daily / interval returns / turnover / amount / premium-discount) + 48 theme pools (100bn+, 10bn+, award winners, high STAR-market exposure…) |
| "What is this fund doing now?" | /v1/etf?kind=概览 | 59 fields: size, shares, premium-discount (today / week / month / quarter / year averages), money flow, valuation percentile, drawdown |
| "Was it expensive on that day?" | /v1/etf?kind=概览&date= | Historical snapshot: that day's premium, size and valuation percentile (measured 2026-06-30: premium 0.13% vs -0.15% today) |
| "What does it actually hold?" | /v1/etf?kind=持仓 · /v1/index-constituent | Top-20 holdings with weights (add date for historical holdings); full list via the tracked index (sh000300 → 300 names) |
/v1/screen?asset=etf/v1/etf?kind=概览/v1/etf?kind=概览&date=/v1/etf?kind=持仓 · /v1/index-constituentdate for historical holdings); full list via the tracked index (sh000300 → 300 names)⇒ Five general endpoints also accept ETF codes directly: /v1/kline (K-lines, forward-adjusted by default), /v1/minute (intraday), /v1/technical (55 indicators), /v1/fund (money flow), /v1/chip (chip distribution: average cost / profit ratio / concentration).
Seven datasets for one fund
Same endpoint, switch with kind:
| kind | What it gives | Typical use |
|---|---|---|
概览 (default) | Quote + size + premium-discount + money flow + drawdown + valuation (59 fields) | Is it expensive now, is money flowing in |
详情 | Fund terms + fees + shares + managers + top-20 holdings (with top20Ratio) | Fee level, tracked index, concentration |
持仓 | Top-20 holdings and weights; with date → historical holdings (heavyweights + first 10 basket rows) | What it is betting on |
净值 | Historical NAV per unit (4 decimals) + closePrice + real navChange | Premium math, NAV curve (start/end required) |
公司 | Manager / custodian / tracked index | Issuer and benchmark |
持有人 | Holder count + institutional vs retail share | Retail or institutional base |
财务 | Asset allocation: equity / bond / commodity / fund | What assets it actually holds |
概览 (default)详情top20Ratio)持仓date → historical holdings (heavyweights + first 10 basket rows)净值closePrice + real navChangestart/end required)公司持有人财务Three examples you can run now
/v1/kline and /v1/hot are free without a key; /v1/etf, /v1/screen and /v1/index-constituent need a paid tier.
# 1) Find targets: whole market ranked by size (top 20)
curl "https://api.ashareapi.com/v1/screen?asset=etf&mode=ranking&type=size&limit=20&key=$KEY"
# 2) Read one fund: size / premium / valuation in one call
curl "https://api.ashareapi.com/v1/etf?code=sh510300&kind=概览&key=$KEY"
# 3) Look back: that day's premium and size
curl "https://api.ashareapi.com/v1/etf?code=sh510300&kind=概览&date=2026-06-30&key=$KEY"
# 4) Look underneath: full constituents of the tracked index (300 names)
curl "https://api.ashareapi.com/v1/index-constituent?code=sh000300&key=$KEY"⚠️ Two upstream boundaries on snapshots: a future date returns the most recent trading day (check the date column — do not assume you got the future); dates before listing return all zeros (flagged as ok:false, not a broken endpoint).
An agent can work from this page alone
Once the endpoints are wired as MCP tools, an agent can answer these directly — here is the mapping from question to call:
| User asks | Agent calls | Note |
|---|---|---|
| "Which ETFs are there / biggest ones" | ashare_screen(mode="label", asset="etf") or mode="ranking" | Use list=true first, never guess type |
| "What is 510300 doing" | ashare_etf(code="sh510300", kind="概览") | Premium = etfDisc, size = etfSize |
| "What was its premium on 2026-06-30" | ashare_etf(kind="概览", date="2026-06-30") | Trust the date column in the response |
| "What does it hold" | ashare_etf(kind="持仓") plus ashare_index_constituent | Top 20 with weights; full list via tracked index |
| "Constituents of CSI 300" | ashare_index_constituent(code="sh000300") | Index codes only; stocks/ETFs return 422 |
| "ETF trend / backtest" | ashare_kline(code="sh510300", period="day") | Forward-adjusted by default; nofq/hfq via ashare_kline_batch (Pro) |
| "Is money flowing in" | ashare_fund(code="sh510300") | Main net inflow + 5/10/20-day cumulative |
| "Chip concentration" | ashare_chip(code="sh510300") | Average cost / profit ratio / concentration (ETFs supported) |
ashare_screen(mode="label", asset="etf") or mode="ranking"list=true first, never guess typeashare_etf(code="sh510300", kind="概览")etfDisc, size = etfSizeashare_etf(kind="概览", date="2026-06-30")date column in the responseashare_etf(kind="持仓") plus ashare_index_constituentashare_index_constituent(code="sh000300")ashare_kline(code="sh510300", period="day")ashare_kline_batch (Pro)ashare_fund(code="sh510300")ashare_chip(code="sh510300")⚠️ Three rules for agents: (1) ashare_etf takes one fund per call (comma-separated returns 422); (2) do not use ashare_profile for ETFs (only code/name/listing date are populated); (3) ETFs are not margin-trading eligible — ashare_margin_trade always returns NOT_DISCLOSED, do not retry it as a delay.
Every endpoint involved
ETFs touch 12 endpoints — 4 dedicated, 8 general (call them with an ETF code):
| Endpoint | What it gives | Tier |
|---|---|---|
| /v1/etf | 7 per-fund datasets + historical snapshots (date) | Pro |
/v1/screen?asset=etf | 1,716 funds: 9 cross-sectional rankings + 48 theme pools | Standard+ |
| /v1/index-constituent | Full index constituents (sh000300 → 300 names, no weights) | Standard+ |
/v1/hot?type=etf | ETF hot list | Free |
/v1/quote | Real-time quote (8 lightweight fields) | Free |
| /v1/kline | K-lines (forward-adjusted; minute bars need Standard+) | Free |
| /v1/minute | Intraday / last 5 sessions | Standard+ |
| /v1/technical | 55 technical indicators (MA/MACD/KDJ/RSI/BOLL…) | Pro |
| /v1/fund | Money flow (main inflow + multi-day cumulative) | Pro |
| /v1/chip | Chip distribution: average cost / profit ratio / concentration | Pro |
/v1/search | Fuzzy name / code search (disambiguation) | Pro |
| /v1/kline-batch | Multiple ETFs over the same window (the only entry that lets you pick an adjustment mode) | Pro |
/v1/screen?asset=etf/v1/hot?type=etf/v1/quote/v1/searchBoundaries up front
These four are not "unfinished" — the upstream data simply does not provide them:
The ETF basket (PCG) has 300 names but upstream always shows just 10; --limit does nothing. To see "what it holds", use /v1/index-constituent on the tracked index (no weights).
Only divTtm / divTtmPct in the overview. To locate ex-dates, compare kline series with fq=qfq vs fq=nofq (fq is a paid-tier capability).
/v1/screen condition and strategy apply to stocks only; with asset=etf, ranking sorts but does not filter (upstream silently drops thresholds). Workaround: page through and filter yourself (limit=200 + offset, ~9 pages for 1,716).
/v1/etf rejects comma-separated codes with 422 — upstream "multi" is sequential (10 funds ≈ 20s, prone to timeouts). Call per fund; each counts once.
FAQ
/v1/kline is forward-adjusted by default (no gap on ex-dividend days), which is right for charting. For real traded prices (nofq) or back-adjusted (hfq) use /v1/kline-batch (Pro) — adjustment modes are a paid-tier capability.
As far as the upstream has data (measured sh510300 2026-06-30 returns normally); dates earlier than upstream coverage return all zeros and are flagged ok:false.
No. /v1/margin-trade with an ETF always returns NOT_DISCLOSED — that is not a data delay, the instrument simply is not on the margin list.
Yes, the data is there: 9 cross-sectional metrics (size / valuation / percentile / interval returns / turnover / amount / premium) + per-fund NAV curves + money flow. The strategy is yours to write — we provide data and validation.
Go deeper
Related docs: