ashareapi — A 股数据 API

40 个 HTTP 端点（https://api.ashareapi.com/v1/...），覆盖行情 / K线 / 五档盘口 / 财务 / 资金 / 龙虎榜 / 板块 / 转债 / 选股 / 量化回测 / 宏观 / 产业链。 5 个端点无需 Key（装上就能调），其余需要 Key（¥9.9 起）。另有官方 SDK：Python pip install ashareapi · Node.js / TypeScript npm install ashareapi。

一、先判断：这个任务要不要 Key

免费 5 个：/v1/quote（行情）· /v1/kline（K线）· /v1/hot（热搜）· /v1/market-overview（大盘画像）· /v1/changedist（涨跌分布） 工具端点（也免 Key）：/v1/health（健康检查）· /v1/challenge（PoW 提额）

二、免费端点：直接调（无需任何鉴权）

# 行情：现价 / 开高低 / 成交量 / 换手率
curl "https://api.ashareapi.com/v1/quote?code=sh600667"

# K线（日/周/月）
curl "https://api.ashareapi.com/v1/kline?code=sh600667&period=day&count=5"

# 热搜榜
curl "https://api.ashareapi.com/v1/hot?limit=10"

Python：

import requests

r = requests.get("https://api.ashareapi.com/v1/quote",
                 params={"code": "sh600667"}, timeout=10)
body = r.json()
if not body.get("ok"):
    raise RuntimeError(body)          # 上游取数失败（已自动换源，且不扣次数）
bar = body["data"][0]                 # 最新一根（当日实时）
print(bar["date"], bar["last"], bar["turnover"])

三、带 Key 调用

curl -H "Authorization: Bearer ct-你的Key" \
     "https://api.ashareapi.com/v1/fund?code=sh600667"

Key 从 https://ashareapi.com/pricing 获取。401 = 没带 Key 调了付费端点。

四、按任务找端点（决策树）

完整参数与返回字段 → 读 references/endpoints.md。

五、四个必知语义（最常踩的坑）

1. 单位不统一，先看清

   • volume 是手（×100 = 股）· amount 是元（不是万元）
   • 比率字段是百分数：instBuyRate: 20 表示 20%（不是 0.2）
   • 金额有时以字符串返回（"135160431.2"）→ 先 float() 再算，否则 + 会拼字符串

2. 数据日期语义：休市日不会变成"今天"。看返回里的 date 字段判断数据属于哪个交易日（quote 的最新一根就是当日实时）。

3. 返回结构：data 是主载荷，形状有 4 种（统一信封 {ok, endpoint, tier, elapsed_ms, source, data}）

   • data 可能是：对象数组（多数端点）/ 表列表（finance）/ 多段结构（shareholder·calendar）/ Markdown 文本（bond·sector 等 9 个）
   • ⚠️ structured / tables 是【条件字段】—— 不是每个端点都有：只有 data 是 Markdown 时才附 ⇒ 代码里一律写 body.get("structured")；写 body["structured"] 在 quote/kline/finance 上会 KeyError
   • ⚠️ /v1/health · /v1/challenge · /v1/usage · /v1/ip-whitelist 信封没有 data
   • 四种形状怎么判别 + 通吃写法 → references/endpoints.md §返回形态

4. ok:false 不等于"我们写错了"：那是上游取数失败（我们已自动换源，不扣调用次数）→ 重试一次通常就好。空结果（如当天没大宗交易）与"失败"是两件事。

六、错误与限流

匿名提额（PoW）：

# 1) 拿挑战
curl "https://api.ashareapi.com/v1/challenge"
# → {challenge, difficulty, expires_in, how_to}
# 2) 算 nonce（sha256(challenge.nonce) 前 difficulty 位为 0），然后：
curl -H "X-PoW: <challenge>.<nonce>" "https://api.ashareapi.com/v1/quote?code=sh600667"

⚠️ PoW 只提升每分钟次数，不提升每日条数 —— 匿名每天仍最多 10 万条；批量补历史/回测请用 Key。

详细错误语义 → 读 references/errors.md。

七、要写代码？用官方 SDK（Python / Node.js）

Python：

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

from ashareapi import AShareAPI

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

cli = AShareAPI("ct-你的Key")      # 付费端点
print(cli.fund("sh600667"))        # 资金流 + 龙虎榜 + 大宗 + 两融
print(cli.screen(preset="low_pe", limit=10))

Node.js / TypeScript：

npm install ashareapi            # 零运行时依赖（原生 fetch，需 Node ≥ 18）

import { AShareAPI } from "ashareapi";

const cli = new AShareAPI();                 // 免费端点无需 Key
const bars = await cli.quote("sh600667");    // → 对象数组
console.log(bars[0].last);

const paid = new AShareAPI({ apiKey: "ct-你的Key" });
console.log(await paid.screen("", "low_pe", 10, "ROETTM"));

两个 SDK 同 40 个方法 / 同 5 类异常 / 同重试策略；差异只是语言惯例： Python 用 snake_case 且返回 DataFrame，Node 用 camelCase（也认 snake_case 别名）且全部返回 Promise。

代码格式随便写：sh600667 / 600667.SH / 600667 都认（自动归一化）。 40 个端点 = 40 个方法（/v1/margin-trade → Python margin_trade() / Node marginTrade()）。

完整用法与 5 类异常 → 读 references/sdk.md。

八、详细参考（按需读取，不要一次全读）

边界（诚实）：

• K 线支持日/周/月/季/年 + 分钟线 m1~m120（分钟线属付费层，窗口近 1 个月）；另有 /v1/minute 分时（当日 / 近 5 日）。⚠️ 期货 / 外汇 / 北交所无分钟线
• 新闻/公告全文不在 API 范围（有 dehydrated 研报摘要、events 事件标签、calendar 事件日历）
• 数据仅供研究参考，不构成投资建议 —— 本 skill 只讲怎么取数与计算，不给买卖建议

九、本 skill 版本

当前版本：0.2.8（2026-10-08）

本版更新：

• 新增 7 个端点（端点数 33 → 40）：量化回测 /v1/backtest（单标的实时 / 组合预置区间）· /v1/backtest-batch（多标的×多策略矩阵，≤20×≤10）· /v1/strategies（策略清单 20+9 条）· /v1/factors（因子库 88 因子 + 50 筛选入口 + 22 预设）· /v1/playbooks（方法论 13 条）· /v1/kline-full（10 年全历史日线，可选复权）· /v1/ip-whitelist（IP 白名单，Unlimited 档）。
• MCP 工具 25 → 31、SDK 方法 33 → 40（references/ 三份同步）。
• 修正边界说明：此前写「K 线没有分钟级」与实际不符 —— 分钟线（m1~m120）与分时 /v1/minute 均已提供（属付费层）。
• 补 /v1/kline-full 说明：与 /v1/kline 的区别是「全历史 + 复权口径可选」。

怎么知道该更新

本 skill 是随 API 演进的快照 —— 每次新增端点/字段，references/ 里的清单会同步但你手上装的可能还是旧版。判断方法：

任一项对不上 → 你装的是旧版。

怎么更新

1. 重新下载：**https://ashareapi.com/skill**（页面有 zip 下载）
2. 解压覆盖到你的 skills 目录（.claude/skills/ · .agents/skills/ · .opencode/skills/ 等）
3. 重启客户端

⚠️ API 本身不需要更新 —— 端点永远是最新的（服务端演进）；需要更新的是这份说明（否则你可能不知道新端点存在）。

版本记录

完整更新日志（含字段级变更）→ https://ashareapi.com/changelog