常用端点文档：K 线 · 因子选股 · 健康检查

pip install ashareapi            # 基础（返回 list[dict]）
pip install "ashareapi[pandas]"  # 加 DataFrame 支持（推荐）

也有 Node.js / TypeScript SDK：npm install ashareapi —— npm

30 秒上手

from ashareapi import AShareAPI

cli = AShareAPI()                     # 免费端点无需 Key
df = cli.quote("sh600667")            # 实时行情 → DataFrame
print(df[["date", "last", "turnover"]])

print(cli.kline("600667.SH", count=5))  # 代码格式随便写（自动归一化）
print(cli.hot(limit=10))                # 热搜榜

付费端点（财务 / 资金 / 龙虎榜 / 选股等）需要 Key（获取，¥9.9 起）：

cli = AShareAPI("ct-你的Key")          # 或设环境变量 ASHARE_API_KEY
df = cli.screen(preset="low_pe", orderby="ROETTM", limit=10)
print(df.head())

为什么用它

• 免费端点真的免 Key：quote / kline / hot / market-overview / changedist 直接调，无需注册
• 代码格式兼容：sh600667 / 600667.SH / 600667 都认（不同写法的项目都能直接用）
• 多源自动切换：后端 70 个数据源互为备份，取数失败会自动换源且不扣调用次数
• 错误分类清楚：AuthError / RateLimitError / UpstreamError / EmptyResultError（无数据 ≠ 失败）—— 每类都告诉你该做什么
• pandas 可选：不想装 pandas 也能用（返回 list[dict]）

端点一览

⚠️ K 线价格口径固定为前复权（除权除息日不跳空；没有 adjust 参数）—— 不要再自己复权（会二次复权）。

（完整 32 端点见 端点清单）

返回形态

装了 pandas 时方法返回 DataFrame（未装则返回 list[dict]），可直接按列名取字段：

df = cli.quote("sh600667")
print(df[["date", "last", "turnover"]])

需要原始信封（含 endpoint / tier / elapsed_ms / source）时用 raw=True：

cli = AShareAPI(raw=True)
env = cli.quote("sh600667")
# { 'ok': True, 'endpoint': '/v1/quote', 'tier': 'free', 'elapsed_ms': 862, 'source': '...', 'data': [...] }

⚠️ 三种返回形态：多数端点是单表 → DataFrame；finance() 是表列表（list[list[dict]]）；shareholder() / calendar() 是多段结构（{tables, data}，原样 dict）。后两种不会被套成 DataFrame。

错误处理

from ashareapi import AShareAPI, AuthError, RateLimitError, UpstreamError, EmptyResultError

cli = AShareAPI()
try:
    df = cli.fund("sh600667")
except AuthError as e:          # 401 / 缺 Key → 去拿 Key
    print(e)
except RateLimitError as e:     # 429 → 降频 / 解 PoW 挑战提额 / 升级档位
    print(e)
except UpstreamError as e:      # 上游取数失败（已自动换源、不扣次数）→ 重试一次通常就好
    print(e)
except EmptyResultError as e:   # 当前无数据（如当天无大宗交易）→ 不计费，换条件或稍后再试
    print(e)

也用 AI Agent（MCP / Agent Skill）

除了 Python SDK，我们还提供两种 AI Agent 接入方式：

• MCP 服务器（Streamable HTTP）—— 服务器地址 https://api.ashareapi.com/mcp （⚠️ 填这个接口地址；站点介绍页 ashareapi.com/mcp 不是接口）
• 各客户端配置写法（Claude Code / Cursor / VS Code / Codex 等 19 家，键名差异都核对过官方文档）： https://ashareapi.com/mcp
• Agent Skill（给 AI Agent 读的接口说明书 + 分发包，装进 skills 目录即用）：https://ashareapi.com/skill

免费工具/端点无需 Key；付费工具在请求头带 Authorization: Bearer <你的 Key>。

示例

仓里 examples/ 有可直接跑的示例：

python examples/quickstart.py

环境要求

• Python ≥ 3.9
• 只依赖 requests（≥ 2.28）
• pandas 可选：装了返回 DataFrame，不装返回 list[dict]
• 示例代码见 examples/quickstart.py

版本记录

当前版本：0.1.9（2026-09-30）

⚠️ 端点本身永远是最新的（服务端演进，无需升级 SDK）—— 升级只是为了用上新增的便利方法。

完整变更记录 → 包内 CHANGELOG.md · 站内更新日志 · PyPI 版本历史

License

MIT · 数据仅供研究参考，不构成投资建议