API reference
Start with the conventions below (auth, envelope, errors, rate limits), then open a specific endpoint. Every sample response in these pages was captured from the live API — not derived from the source code.
Authentication
Paid endpoints authenticate with therequest header Authorization: Bearer <key> — the key stays out of URLs and access logs.
curl "https://api.fundapi.cn/v1/fund-nav?code=110022" \ -H "Authorization: Bearer YOUR_KEY"
- Adding
?key=to the URL also works — convenient for quick browser tests, but it ends up in logs.X-API-Keyisnot supported and returns 401. - An API key is shown in plain text exactly once, at issue time.
codeis always a 6-digit open-end fund code (e.g. 110022). Passing a stock code returns "not found".- The health check
GET /healthneeds no key and consumes no quota — safe to wire into monitoring.
Response envelope
Every endpoint returns the same shape. There is no second format:
{
"ok": true,
"endpoint": "fund-nav",
"tier": "pro",
"elapsed_ms": 426,
"data": { }
}ok:trueon success. Whenfalse,dataisnull— readerror.tier: the tier used for this request.elapsed_ms: server-side time in milliseconds.
⚠️ Business failures still return HTTP 200 withok:false. Always check okbefore the status code.
Error codes
| HTTP | Scenario | error example (as returned) |
|---|---|---|
200 + ok:false | Fund code not found / data source temporarily unavailable | 查询不到对应数据 |
401 | Missing or wrong API key | 需要 API Key |
403 | Tier too low / UA flagged as a scanner | 此端点需更高版本,如「此端点需专业版及以上」 / 请求被安全策略拦截 |
404 | Endpoint path does not exist | 端点不存在:/v1/fund-nope |
405 | Method other than GET | 该端点不支持这种请求方法 |
422 | Missing or malformed parameter | 缺少或不合法的参数:code |
429 | Rate limit / daily quota / concurrency | 见响应头 Retry-After |
The error strings are returned verbatim in Chinese. Parseok and the HTTP status; do not match on the message text.
Rate limits and concurrency
| Tier | Limit | Notes |
|---|---|---|
| Concurrent connections per IP | 8 | Beyond that you get 429; close the connection and retry |
| No key (anonymous) | 500 / day, 10 / minute | Counted per IP, free endpoints only (3 of them) |
| Trial | no daily cap, 30 / minute | Counted per API key, 7 days |
| Pro | no daily cap, 60 / minute | Counted per API key |
| Institutional | no daily cap, 300 / minute | Counted per API key |
- 8 concurrent connections is enough for batch work — one request returns tens or hundreds of rows. Do not fan out one request per fund.
- Over the limit returns
429withRetry-After; wait that long and retry. - Requests must carry a
User-Agent. An empty UA, or one matching a scanner signature, gets403.
Two data flags
| Flag | Meaning |
|---|---|
stale: true + stale_age_s | Data was returned but it is not fresh (N seconds old). Only appears when the upstream source is failing. |
degraded: true + reason | Nothing could be returned; retry later. |
They are mutually exclusive. stale does not mean the data is wrong — only that it is slightly late. The intraday estimate endpoint never returnsstale: a stale estimate is more misleading than an error.
All endpoints
| Endpoint | Name | Tier |
|---|---|---|
/v1/fund-search | Fund search | Free |
/v1/fund-profile | Fund profile | Free |
/v1/fund-screener-options | Screener options | Free |
/v1/fund-nav | NAV history | Trial |
/v1/fund-rank | Market ranking | Trial |
/v1/fund-notices | Fund notices | Trial |
/v1/fund-holdings | Quarterly holdings | Pro |
/v1/fund-managers | Fund managers | Pro |
/v1/fund-estimate | Intraday estimate | Pro |
/v1/fund-dividends | Dividends & splits | Pro |
/v1/fund-trade-rule | Trading rules | Pro |
/v1/fund-rating | Agency ratings | Pro |
/v1/fund-overlap | Holdings overlap | Institutional |
/v1/fund-portfolio-xray | Portfolio look-through | Institutional |
/v1/fund-portfolio-diagnose | Portfolio diagnostics | Institutional |
/v1/fund-holding-changes | Holdings changes | Institutional |
/v1/fund-manager-history | Manager history | Institutional |
/v1/fund-compare | Fund comparison | Institutional |
/v1/fund-screener | Market screener | Institutional |