ashareapi-com Free API

openapi: 3.2.0
info:
  title: A股数据 Free API
  description: 多源数据通道（自动切换） · 行情/财务/资金/选股/宏观/可转债/ETF
  version: 0.1.0
tags:
- name: free
paths:
  /v1/models:
    get:
      tags:
      - free
      summary: OpenAI / Anthropic 兼容模型清单（免费）
      description: '⭐ 给 OpenAI SDK / Anthropic SDK / 通用客户端的 model list。


        返回真实可用的 `deepseek-flash` / `gpt-5.6-luna` / `claude-*`；另含 `ashare/scanner@deepseek-flash`（选股 Agent，专业版 ¥99+）。免费、无需 Key。聊天仍需 `apiKey = ct-xxx:sk-yyy`（BYOK）。'
      operationId: list_models_v1_models_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/health:
    get:
      tags:
      - free
      summary: 服务健康检查
      description: 检查服务状态与数据通道是否可用（data_ready=true 表示能正常取数）。数据通道状态随时可查
      operationId: health_v1_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/challenge:
    get:
      tags:
      - free
      summary: 获取 PoW 挑战（匿名提额用）
      description: '匿名请求超限（429）时也会直接返回同一份挑战。解出 nonce 后带 `X-PoW: .` 请求，匿名配额从 5 次/分提升到 15 次/分。⚠️ 只提升**每分钟次数**，**不提升每日条数**（匿名每日最多取 10 万条）。付费 Key 用户无需使用。'
      operationId: challenge_v1_challenge_get
      parameters:
      - name: difficulty
        in: query
        required: false
        schema:
          type: integer
          maximum: 24
          minimum: 0
          description: 自定义难度（前导 0 位数），0=服务端默认
          default: 0
          title: Difficulty
        description: 自定义难度（前导 0 位数），0=服务端默认
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/quote:
    get:
      tags:
      - free
      summary: 实时行情快照
      description: 'A股/港股/美股实时行情（**轻量 8 字段**）：现价、开高低、成交量、成交额、换手率。用户问『某股票现在多少钱/什么价/现价』时用这个。⚠️ 数据为**当日盘中滚动更新**（约每分钟刷新）；取现价用 `data[0]`。⚠️ **免费 / 匿名档按 5 分钟刷新**（保障服务稳定性）；**付费档实时**（每次取此刻最新）。⚠️ `data` 是**数组**（默认 30 条日线，`data[0]` 为最新）。⚠️ 换手率的字段名是 **`turnover`**（单位 %）—— 与 /v1/snapshot **同名同值**（sz000001 两者均 0.54）。⚠️ **2026-09-26 改名**：该字段此前叫 `exchange`（数据源历史命名，**极易被误读为「交易所」**）—— 已统一为 `turnover`；如需兼容旧代码，读 `turnover` 即可。⚠️ **不含**估值 / 市值 —— 要这些字段用 /v1/snapshot（35 字段，pro 档，仅 A 股）。⚠️ **`code` 支持逗号批量**（多标的）—— 但**匿名单次最多 5 只标的**（付费不限）。

        ⭐ **美股三大指数也能查**：道指 `usDJI` · 纳指 `usIXIC` · 标普500 `usINX`。⚠️ 标普 500 的代码是 **`usINX`**（不是常见的 `usSPX`）。'
      operationId: quote_v1_quote_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          description: 股票代码，带市场前缀：sh600667（沪）/ sz000001（深）/ hk00700（港）/ usAAPL（美）。**支持逗号批量**（多标的），但匿名单次最多 5 只
          title: Code
        description: 股票代码，带市场前缀：sh600667（沪）/ sz000001（深）/ hk00700（港）/ usAAPL（美）。**支持逗号批量**（多标的），但匿名单次最多 5 只
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/kline:
    get:
      tags:
      - free
      summary: K线（分钟/日/周/月/季/年）
      description: 历史 K 线数据。用户问『走势/最近表现/历史K线/趋势/分时』时用这个。**周期**：`day` 日线（默认）/ `week` 周线 / `month` 月线 / `season` 季线 / `year` 年线 / `m1` `m5` `m15` `m30` `m60` `m120` 分钟线。**日期范围**：`start` + `end`（`YYYY-MM-DD`），仅 `day` 与分钟线支持（周/月/季/年线用 `count` 取条数，1212 条已覆盖 20+ 年月线；**港股 / 美股 不提供日期范围** —— 原因是同一标的在不同数据通道上的**复权口径不同**，带范围会与不带范围给出**不同的价格口径**；请用 `count` 取最近 N 条）。⚠️ 换手率字段名是 **`turnover`**（单位 %）—— 与 /v1/quote、/v1/snapshot **同名同值**（2026-09-26 由 `exchange` 改名）。⚠️ **收盘价的字段名是 `last`（不是 `close`）**；**返回按日期降序 = 最新一条在 `data[0]`**（`data[-1]` 是最早），算涨跌幅时请勿当成升序。8 列字段（恒定，不随参数变化）：`date / open / last(收盘) / high / low / volume / amount / turnover(换手%)`。⚠️ 代码可传带前缀（`sh600519`）或**裸 6 位（`600519`，自动补市场前缀）**；⚠️ 唯一歧义是 `000001`（上证指数 vs 平安银行，按深市处理）—— 指数请显式传 `sh000001`。⚠️ 价格口径**固定为前复权**（除权除息日不跳空；本端点**没有 `fq` 参数**）—— **不要再自己复权**（会二次复权）。分钟线**不复权**（数据源对分钟级数据固定给原始价）。⭐ **要原始价（`nofq`）/ 后复权（`hfq`）** ⇒ 用 `/v1/kline-batch`（专业版 ¥99）或 `/v1/kline-full`（标准版 ¥29.9，仅 A 股）—— 复权口径是**付费档能力**，免费端点只给前复权以保证「同一个 code 永远同一个价格口径」。⚠️ 分钟线覆盖**近 1 个月**（窗口起点约为上个自然月月初；港股 / 美股窗口更短，实测只覆盖最近几个交易日），超范围返回空结果。⚠️ **分钟线需 `standard`（¥29.9）及以上档位**；日 / 周 / 月 / 季 / 年线免费（**免费 / 匿名档按 5 分钟刷新**；**付费档实时**）。⚠️ **`code` 支持逗号批量**（一次取多只，如 `code=sh600000,sz000001`）—— 但 **匿名单次最多 5 只标的**（付费不限）；且**单次预估总条数**（标的数 × `count`）**上限 6 万条**（防单请求过大，正常用户撞不到）。⚠️ **标的边界**：分钟线支持 A股 / 指数 / 板块 / ETF / 可转债 / 港股 / 美股（北交所 / 期货 / 外汇 / 美股指数无分钟线）；**美股指数** `usDJI`（道指）/ `usIXIC`（纳指） / `usINX`（标普500，⛔ 不是 usSPX）**仅支持 day**；期货 / 外汇只有 day / week / month（无季 / 年线）。⚠️ 字段固定 8 列（`date` `open` `last` `high` `low` `volume` `amount` `turnover`）—— 不随周期/范围变化。
      operationId: kline_v1_kline_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          description: 股票代码：sh600667；同样支持 指数 sh000001 / 板块 pt01801081 / ETF sh510300 / 港股 hk00700 / 美股 usAAPL / 可转债 sz128136 / 期货 fuCN / 外汇 fxCNH。**支持逗号批量**（多标的），但匿名单次最多 5 只
          title: Code
        description: 股票代码：sh600667；同样支持 指数 sh000001 / 板块 pt01801081 / ETF sh510300 / 港股 hk00700 / 美股 usAAPL / 可转债 sz128136 / 期货 fuCN / 外汇 fxCNH。**支持逗号批量**（多标的），但匿名单次最多 5 只
      - name: period
        in: query
        required: false
        schema:
          type: string
          description: 周期：day 日线（默认）/ week 周线 / month 月线 / season 季线 / year 年线 / m1 m5 m15 m30 m60 m120 分钟线
          default: day
          title: Period
        description: 周期：day 日线（默认）/ week 周线 / month 月线 / season 季线 / year 年线 / m1 m5 m15 m30 m60 m120 分钟线
      - name: count
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 1212
            minimum: 1
          - type: 'null'
          description: 返回条数上限。不带 start/end 时默认 30；带 start/end 时默认取满区间（1212）。最大 1212（免 Key 匿名最多 250；分钟线需 Key）。⚠️ 多标的时**总条数（标的数 × count）上限 6 万**
          title: Count
        description: 返回条数上限。不带 start/end 时默认 30；带 start/end 时默认取满区间（1212）。最大 1212（免 Key 匿名最多 250；分钟线需 Key）。⚠️ 多标的时**总条数（标的数 × count）上限 6 万**
      - name: start
        in: query
        required: false
        schema:
          type: string
          description: 起始日期 YYYY-MM-DD（仅 day 与分钟线；须与 end 配对；港股/美股/期货/外汇不支持）
          default: ''
          title: Start
        description: 起始日期 YYYY-MM-DD（仅 day 与分钟线；须与 end 配对；港股/美股/期货/外汇不支持）
      - name: end
        in: query
        required: false
        schema:
          type: string
          description: 结束日期 YYYY-MM-DD（仅 day 与分钟线；须与 start 配对；港股/美股/期货/外汇不支持）
          default: ''
          title: End
        description: 结束日期 YYYY-MM-DD（仅 day 与分钟线；须与 start 配对；港股/美股/期货/外汇不支持）
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/wiki:
    get:
      tags:
      - free
      summary: 文档检索（字段 / 口径 / 常见误用）
      description: '⭐ **产品文档检索**：字段单位、口径说明、常见误用、跨市场差异 —— **当你（agent）不确定某字段含义/单位/口径时先查这里，比猜更准**。


        **渐进加载（三步走，省 token）**：

        | 调用 | 返回 | 大小 |

        |---|---|---|

        | `/v1/wiki`（不带参） | **目录**：slug + 标题 + 一句话 | 小 |

        | `/v1/wiki?q=关键词` | **命中篇的摘要**（标题 + lead + 匹配片段），⚠️ 不含全文 | 中 |

        | `/v1/wiki?slug=units` | **该篇全文**（正文 Markdown） | 单篇 |


        ⚠️ **不会一次性吐出全部文档**（全文合计 70KB+）—— 请先看目录、再取单篇，避免浪费你的上下文。

        `lang`：`zh`（默认）/ `en`。

        ⚠️ 属**免费层**（无需 API Key）—— 但**每次调用仍计入用量与限流**。'
      operationId: wiki_v1_wiki_get
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
          description: 关键词检索（如 '换手率单位' / 'code 格式'）；留空=返回目录
          default: ''
          title: Q
        description: 关键词检索（如 '换手率单位' / 'code 格式'）；留空=返回目录
      - name: slug
        in: query
        required: false
        schema:
          type: string
          description: 取某一篇全文（如 units / kline-fields）；留空=不用
          default: ''
          title: Slug
        description: 取某一篇全文（如 units / kline-fields）；留空=不用
      - name: lang
        in: query
        required: false
        schema:
          type: string
          description: 语言：zh（默认）/ en
          default: zh
          title: Lang
        description: 语言：zh（默认）/ en
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/hot:
    get:
      tags:
      - free
      summary: 热度榜（5 类，字段各不相同）
      description: '**关注度**排名（谁在被关注，⛔ 不是「谁在涨」）。用户问『什么股票热门/大家在看什么/热度榜/热门板块/热文』时用这个。


        ⚠️⚠️ **5 类的字段结构完全不同**，⛔ 别按同一套字段读：

        · `type=stock`（默认）热搜**股票**：`code` · `name` · `zdf` 涨跌幅 · `zxj` 最新价

        · `type=wx` 全市场热度**股票**：同 stock，⭐ **多 `pv` 热度值**（唯一能量化热度）

        · `type=news` 热门**文章**：⚠️ **`news_id` · `news_title` · `source`** —— ⛔ **没有 code/name**

        · `type=sector` 热门**板块**：⚠️ **`symbol`**（pt0…）· `name` · `rankdelta` 排名变化 —— ⛔ **没有 code**

        · `type=etf` 热搜 **ETF**：`code` · `name` · `title` 涨幅说明 · `tag` 标签


        ⚠️ 这是**当前快照**（数据源无历史、无趋势）—— 别用它算「热度变化」。'
      operationId: hot_v1_hot_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: 返回条数，默认 30（榜单上限 50，超出按 50 返回）
          default: 30
          title: Limit
        description: 返回条数，默认 30（榜单上限 50，超出按 50 返回）
      - name: type
        in: query
        required: false
        schema:
          type: string
          description: stock 热搜股票 / wx 全市场热度（带 pv）/ news 热门文章 / sector 热门板块 / etf 热搜 ETF（⚠️ 5 类字段各不相同）
          default: stock
          title: Type
        description: stock 热搜股票 / wx 全市场热度（带 pv）/ news 热门文章 / sector 热门板块 / etf 热搜 ETF（⚠️ 5 类字段各不相同）
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/market-overview:
    get:
      tags:
      - free
      summary: 市场总览（大盘画像）
      description: 市场整体画像。type=summary 总评画像 / trade 收盘 / interval 多周期 / technical 大盘技术 / margin 两融 / valuation 估值分位 / rotation 风格轮动。用户问『今天市场怎么样/大盘情况/市场环境/风格轮动/估值分位』时用这个。⚠️ type=updown（涨跌分布）是 **T-1 口径**（返回里会标数据日期，可能滞后一个交易日）—— 要**当期**涨跌家数/涨停家数/市场广度，请用 /v1/changedist（两者数值会不同）。
      operationId: market_overview_v1_market_overview_get
      parameters:
      - name: type
        in: query
        required: false
        schema:
          type: string
          description: 类型：summary/trade/interval/technical/margin/valuation/rotation（updown 为 T-1 口径，当期涨跌家数请用 /v1/changedist）
          default: summary
          title: Type
        description: 类型：summary/trade/interval/technical/margin/valuation/rotation（updown 为 T-1 口径，当期涨跌家数请用 /v1/changedist）
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/changedist:
    get:
      tags:
      - free
      summary: 涨跌分布（市场广度）
      description: 全市场涨跌家数、涨跌停家数、停牌、成交额与涨跌幅区间分布——衡量市场广度与情绪（**当期口径**）。这是市场广度的推荐入口：不要用 /v1/market-overview?type=updown 取同一数据（那是 T-1 口径，数值会不一致）。
      operationId: changedist_v1_changedist_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/trade-calendar:
    get:
      tags:
      - free
      summary: 交易日历（开市/休市 · 年末最后交易日）
      description: '**A 股交易日历**：逐个日期给出是否开市，以及该日是不是本周/本月/本季/本年的**最后一个交易日**（做结算日、到期日、调仓日的时候要用）。


        **和 `/v1/calendar` 的区别**：那个是**个股事件日历**（分红/解禁/财报披露…），这个**只讲市场开不开市**。两个都要的话各调一次。


        **三种查询方式（三选一）**：

        - 不传参数 → 当月整月

        - `date=2026-10-16` → 单日

        - `start`+`end` → 任意区间；或 `year=2026` → 整年


        **`trading_only=true`**：只返回开市日（整年约 242 行，比 365 行更好用）。


        ⚠️ **`limit` 默认已按查询范围自动补足**（年/区间默认给满一年 400 行上限），不会截断；要翻页用 `offset`。


        `data` 是排版好的表格；程序化读取用 **`structured`**（单表，`[{列: 值}]`）。列为：`日期` / `是否交易日` / `本周最后交易日` / `本季最后交易日` / `本年最后交易日` / `本月最后交易日`。


        ⚠️ 本端点**免费**（不需要 API Key）。'
      operationId: trade_calendar_v1_trade_calendar_get
      parameters:
      - name: date
        in: query
        required: false
        schema:
          type: string
          description: 单日 YYYY-MM-DD；留空则看 year/start+end，都空=当月
          default: ''
          title: Date
        description: 单日 YYYY-MM-DD；留空则看 year/start+end，都空=当月
      - name: start
        in: query
        required: false
        schema:
          type: string
          description: 区间起始日 YYYY-MM-DD（与 end 配对）
          default: ''
          title: Start
        description: 区间起始日 YYYY-MM-DD（与 end 配对）
      - name: end
        in: query
        required: false
        schema:
          type: string
          description: 区间结束日 YYYY-MM-DD（与 start 配对）
          default: ''
          title: End
        description: 区间结束日 YYYY-MM-DD（与 start 配对）
      - name: year
        in: query
        required: false
        schema:
          type: string
          description: 整年，如 2026（与 date/start+end 三选一）
          default: ''
          title: Year
        description: 整年，如 2026（与 date/start+end 三选一）
      - name: trading_only
        in: query
        required: false
        schema:
          type: boolean
          description: true=只返回开市日
          default: false
          title: Trading Only
        description: true=只返回开市日
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: 返回行数上限（0=按范围自动：单日/当月不补，年/区间补满 400）
          default: 0
          title: Limit
        description: 返回行数上限（0=按范围自动：单日/当月不补，年/区间补满 400）
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          description: 跳过前 N 行（翻页用）
          default: 0
          title: Offset
        description: 跳过前 N 行（翻页用）
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError