付费端点 · 付费

自然语言受控检索（带证据链 · 供开发者编排） API

Q: 这些端点需要 API Key 吗？

免费端点不需要：health、challenge、quote、kline、hot、market-overview、changedist 匿名即可调用。付费端点需要：在请求头带 Authorization: Bearer 。⚠️ 匿名额度按调用者类型分级：浏览器（真人）5 次/分；脚本 / SDK / AI Agent（curl、requests、axios、openai 等 UA）2 次/分 —— 自动化流量更易被滥用。解一次 PoW 挑战（GET /v1/challenge，再带 X-PoW 头）可提到 15 次/分，与类型无关。⚠️ 另外，匿名调用单次最多取 250 根 K 线、每天最多 10 万条 —— 要一次拿满 1212 根或不限日量，请用 API Key。

Q: 返回为空或上游报错时，会扣我的调用次数吗？

不会。上游失败或空结果时返回 ok:false，并自动退回本次计费（total_calls / usage_log / ep_log 三处同时回滚）。只有真正取到数据的请求才计入用量。

Q: 数据多久更新一次？

行情类（quote / kline / orderbook / changedist）为实时或当日；财务、股东、分红、事件等为上游披露后 T+1 内。响应里的 source 字段标明本次实际命中的数据通道。

Q: 一次请求能批量拿多只股票吗？

不能。code 是单值参数，一次一只；批量请并发调用（注意各自档位的每分钟限流）。

⭐ 自然语言 → 带证据链的结构化候选，供你自己编排。我们不生成答案，只给「结构化结果 + 证据元数据」。与其它端点的区别：你不用先知道调哪个端点 —— 说人话就行，我们识别标的与意图，再取数。每行结果带证据链 evidence：endpoint / params / field_path / value / value_hash（16 位）/ hash_alg。拿 endpoint+params 重取一次，按同一条记录重算 sha256，应得到同一个 value_hash —— 不必"信我们"。响应结构：data = 结果数组（每项含 data + evidence）；顶层另有 interpreted（标的 + 意图 + intent_source）与 ok/tier/elapsed_ms。当前范围（P1：两个通道）： · ashare 通道 —— 问资金流（「宁德时代最近资金流入」）或行情价格（「贵州茅台最新股价」），返回一行结构化数据； · evidence 通道 —— 问公告/资讯/研报（「宁德时代最近有什么公告」），返回多条跨源检索结果，每行带 kind（notice/news/report）/ 标题 / 媒体 / 日期 / 链接 / snippet；公告 authority_score=1.0、资讯与研报 0.5。 ⭐ 每行结果的 interpreted.channel 会说明这条数据从哪个通道来。 ⚠️ 意图识别目前是规则，响应里的 interpreted.intent_source 会明确标 rules —— 不是模型理解；覆盖不到的问法明确拒答（ok:false + 建议问法 + 支持清单），⛔ 不猜。 ⭐ readable（可读值）：资金流/成交额/成交量这类大数值，每行额外给 readable（如 -14.26 亿元）+ unit + rule（换算规则，可反算回原值）—— 省得你自己换算。⚠️ value 仍是数据源原值、一字不改；价格/点位类不换算（readable=null）。 ⭐ number_gate（数字自查）：若你要据此写一段话，按其中的 rules 自查 —— verbatim（原值）/ unit_convert（换单位）可，derived（涨跌幅/同比/占比这类自行计算的派生量）不可。派生量必须来自数据源，不能自己算。 ⚠️ 拒答 / 取数为空时不扣次数。

付费GET /v1/agent-search

接口签名

GET /v1/agent-search?q=%E5%A4%AA%E6%9E%81%E5%AE%9E%E4%B8%9A&scope=

一行可跑

curl "https://api.ashareapi.com/v1/agent-search?q=%E5%A4%AA%E6%9E%81%E5%AE%9E%E4%B8%9A&scope=&key=YOUR_KEY"

参数：q * · scope · depth · max_results · clarify · claim · replay · authority_min · recency带 * 为必填

快速开始

把下面的代码里的 Key 换成你的（免费端点无需 Key，直接调）：

curl

# 注：q 的值已做 URL 编码（含 [ ] 空格 等）
# 推荐：Authorization 头（密钥不进日志）
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.ashareapi.com/v1/agent-search?q=%E5%A4%AA%E6%9E%81%E5%AE%9E%E4%B8%9A&scope="

# 快速测试：直接浏览器打开（?key= 会留在日志/历史里，别用于生产）
curl "https://api.ashareapi.com/v1/agent-search?q=%E5%A4%AA%E6%9E%81%E5%AE%9E%E4%B8%9A&scope=&key=YOUR_KEY"

Python

import requests

r = requests.get(
    "https://api.ashareapi.com/v1/agent-search",
    headers={"Authorization": "Bearer YOUR_KEY"},
    params={"q": "太极实业"},
    timeout=30,
)
print(r.json())

JavaScript

const r = await fetch("https://api.ashareapi.com/v1/agent-search?q=%E5%A4%AA%E6%9E%81%E5%AE%9E%E4%B8%9A&scope=", {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
console.log(await r.json());

参数

参数	类型	必填	说明
q	string	是	自然语言查询，如「宁德时代最近资金流入」「贵州茅台最新股价」
scope	string	否	数据源范围（可选；不传 = 按问句自动选通道）。可用值：ashare（自有数据：资金流/行情/龙虎榜/大宗/两融）· notice,news,report（公告/资讯/研报原文）· web（网页检索，需 X-LLM-Key）· wechat（微信公众号，同上，等价于 web + site:mp.weixin.qq.com）。⚠️ 显式传 web/wechat 时只在该通道内找，取不到会如实 ok:false（⛔ 不会退回别的通道凑答案）；⛔ 暂不支持：a2b（浏览器渲染）· xhs · local（本地文档库）
depth	string	否	深度。⚠️ P0 只支持 fast
max_results	integer	否	结果条数上限
clarify	boolean	否	只做标的消歧，不取数（返回带说明的选项）
claim	string	否	要核验的断言原文（可选，传了才判 contradicted）
replay	boolean	否	C6 重放对账（可选）。开启后额外调一次模型比对输出，结果标 match / non_deterministic / not_replayable / skipped_no_client —— ⚠️ 模型路径下通常为 non_deterministic，这不代表结论不可靠
authority_min	number	否	权威性下限：低于此分的结果被过滤。公告 1.0 / 资讯研报 0.5，传 0.6 只要官方一手来源；默认 0（不过滤）
recency	string	否	时效窗口，如 7d / 24h / 30m。⚠️ 只影响裁决，不过滤结果 —— 超出窗口的照常返回，但 verification 里会标 unverified（我们的定位是把"哪些验证了、哪些没有"暴露出来）。不传 ⇒ 不判时效。

qstring是

自然语言查询，如「宁德时代最近资金流入」「贵州茅台最新股价」

scopestring

数据源范围（可选；不传 = 按问句自动选通道）。可用值：ashare（自有数据：资金流/行情/龙虎榜/大宗/两融）· notice,news,report（公告/资讯/研报原文）· web（网页检索，需 X-LLM-Key）· wechat（微信公众号，同上，等价于 web + site:mp.weixin.qq.com）。⚠️ 显式传 web/wechat 时只在该通道内找，取不到会如实 ok:false（⛔ 不会退回别的通道凑答案）；⛔ 暂不支持：a2b（浏览器渲染）· xhs · local（本地文档库）

depthstring

深度。⚠️ P0 只支持 fast

max_resultsinteger

结果条数上限

clarifyboolean

只做标的消歧，不取数（返回带说明的选项）

claimstring

要核验的断言原文（可选，传了才判 contradicted）

replayboolean

C6 重放对账（可选）。开启后额外调一次模型比对输出，结果标 match / non_deterministic / not_replayable / skipped_no_client —— ⚠️ 模型路径下通常为 non_deterministic，这不代表结论不可靠

authority_minnumber

权威性下限：低于此分的结果被过滤。公告 1.0 / 资讯研报 0.5，传 0.6 只要官方一手来源；默认 0（不过滤）

recencystring

时效窗口，如 7d / 24h / 30m。⚠️ 只影响裁决，不过滤结果 —— 超出窗口的照常返回，但 verification 里会标 unverified（我们的定位是把"哪些验证了、哪些没有"暴露出来）。不传 ⇒ 不判时效。

返回字段

下表由线上真实调用采集（非文档推断）：每行是响应里的字段名、类型和一条真实样例值，用来对齐解析代码。

所在位置: data统一信封: ok / endpoint / tier / elapsed_ms / source取样日: 2026-10-20

字段	类型	真实样例值
rank	num	1
source_type	str	ashare_api
source_endpoint	str	/fund
source_params_json	str	{"code": "sz300750"}
field_path	str	main_net
value	str	-1294791163.00
readable	str	-12.95 亿元
unit	str	亿元
rule	str	value / 1e+08，保留 2 位小数（可反算回原值）
value_hash	str	bd545a6f7677b695
hash_alg	str	sha256-v1
as_of	str	2026-10-21
subject	str	宁德时代
subject_code	str	sz300750
authority_score	num	0.95
authority_reason	str	data_point(base=1.0) × source_kind(0.95) × cov…
authority_source	str	authority.py
authority_parts		—
upstream_authority	null	—
evidence		—
date	str	2026-10-21

统一返回信封： { ok, endpoint, tier, elapsed_ms, source, data }

数据在 data 字段；上游为空时 ok:false 且不扣次数。

限流与额度

免费端点无需 Key（匿名 5 次/分，解一次 PoW 可到 15 次/分；每次最多 250 根 K 线、每天最多 10 万条）。付费端点按档位限流：体验 30 · 标准 120 · 专业 300 · 不限量 600 次/分；买断档按总量计（不用完不过期）。

看错误码对照表 →

常见问题

通用问题（所有端点通用）

这些端点需要 API Key 吗？

免费端点不需要：health、challenge、quote、kline、hot、market-overview、changedist 匿名即可调用。付费端点需要：在请求头带 Authorization: Bearer <你的 Key>。⚠️ 匿名额度按调用者类型分级：浏览器（真人）5 次/分；脚本 / SDK / AI Agent（curl、requests、axios、openai 等 UA）2 次/分 —— 自动化流量更易被滥用。解一次 PoW 挑战（GET /v1/challenge，再带 X-PoW 头）可提到 15 次/分，与类型无关。⚠️ 另外，匿名调用单次最多取 250 根 K 线、每天最多 10 万条 —— 要一次拿满 1212 根或不限日量，请用 API Key。

返回为空或上游报错时，会扣我的调用次数吗？

不会。上游失败或空结果时返回 ok:false，并自动退回本次计费（total_calls / usage_log / ep_log 三处同时回滚）。只有真正取到数据的请求才计入用量。

数据多久更新一次？

行情类（quote / kline / orderbook / changedist）为实时或当日；财务、股东、分红、事件等为上游披露后 T+1 内。响应里的 source 字段标明本次实际命中的数据通道。

一次请求能批量拿多只股票吗？

不能。code 是单值参数，一次一只；批量请并发调用（注意各自档位的每分钟限流）。

怎么在 Claude / Cursor / ChatGPT 里直接调用？

配一次 MCP 即可，之后直接问 AI「查一下……」它会自己调。MCP 暴露 65 个工具，覆盖行情 / 财务 / 选股 / 板块 / 宏观。

自然语言受控检索（带证据链 · 供开发者编排） API

快速开始

参数

返回字段

常见问题

通用问题（所有端点通用）

相关端点