top369 Python SDK

股票数据API服务平台官方 Python SDK，tushare 风格封装——用过 ts.pro_api() 即可 10 秒上手。

安装

pip install top369          # Python SDK
pip install "top369[mcp]"   # 含 MCP Server: Claude/Cursor 直接查A股(需 Python 3.10+)

依赖仅 requests + pandas。

安装即测（不用写代码）

top369-demo                # 跑通全部接口演示; API Key 从环境变量 TOP369_API_KEY 读, 未设则交互粘贴
python -m top369.demo      # 等价写法

demo 按 Key 档位自适应：先显示账户档位与今日用量，档位达不到要求的接口会打印后端提示并跳过，不中断。

快速上手

import top369 as gp

pro = gp.pro_api('sk-xxxx')   # 控制台获取 Key; 默认连 https://api.369.top

# 查询当前所有正常上市交易的股票列表 (对应 tushare 的 stock_basic)
data = pro.stock_basic(page=1, page_size=200,
                       fields='code,name,market,type')

# 或者通用调用风格
data = pro.query('stock_basic', page=1, fields='code,name')

标的代码：四种写法都认

后端统一收口，不用自己改写（tushare 迁移用户可直接粘 ts_code）：

pro.stock_day(code='600519.SH')   # 四种写法完全等价; 显式写了市场则不做择优
                                  # (如 000300.SH 是沪深300指数, 不会判成深市股票)

本地转换/校验而不发请求时用 symbols 模块：

from top369 import normalize, to_dot, to_plain, market_of

normalize('600519.SH')     # 'sh600519'  → 平台写法
to_dot('sz000001')         # '000001.SZ' → 喂 tushare 等外部库
to_plain('sh.600519')      # '600519'
market_of('000001.SZ')     # 'sz'

接口一览

所有方法支持 tushare 风格的 fields='col1,col2' 列过滤（account/usage 除外）。

常用示例

# 日线(默认最新100根不指定则全历史), 复权
df = pro.stock_day(code='sz000911', start_date='2026-01-01',
                   adjust='qfq', limit=100)
print(df.tail())          # date/open/high/low/close/volume/amount/turnover
print(df.attrs['name'])   # 股票名称等元信息

# 60分钟K线
df = pro.kline(code='sz000911', period=60)

# 分笔
df = pro.tick(code='sz000911', date='2026-08-28')

# 交易日历(按交易日循环, 不空跑节假日)
df = pro.trade_calendar(start_date='2026-01-01')
for d in df['date']:
    ...

不要 DataFrame？

pro = gp.pro_api('sk-xxxx', to_dataframe=False)   # 全部接口返回原始结构(信封里的 data)
pro.to_dataframe = True                           # 也可运行时随时切换

（to_dataframe=False 时 fields 过滤不生效——原始结构上没有列可挑。）

认证与限流

• 认证走 X-API-Key 请求头，SDK 自动携带；网络错误自动重试 2 次（指数退避）
• 平台按会员档位控制可调用的接口（体验版注册即得 → 基础版/专业版/旗舰版）： 低档调用高档接口返回 403，错误信息带所需档位与价格； 会员到期自动回落体验版权益，不整体拦截。各档位不按次扣费，仅受 RPM/日配额约束
• pro.account() / pro.usage() 随时可查自己的档位与用量

错误处理

from top369 import AuthError, GupiaoApiError, QuotaExceeded

try:
    df = pro.stock_day(code='sz000001', limit=10)
except AuthError as e:
    print('Key无效/档位不足, 勿重试:', e)      # 401/403
except QuotaExceeded as e:
    print('配额/频率超限, 策略降级:', e)        # 429
except GupiaoApiError as e:
    print(e)                      # 人话错误信息
    print(e.status_code)          # 401=Key无效 429=配额用尽 403=该接口需更高档位

MCP 接入：让 Claude / Cursor 直接查A股数据

不用写代码——把平台作为 MCP Server 挂进 AI 编程助手，Agent 即可直接调用全部数据工具 （行情/K线/财务/ST名单/名称历史/沪深港通等 16 个）。

要求 Python 3.10+：

pip install "top369[mcp]"

Claude Desktop（claude_desktop_config.json）或 Cursor（mcp.json）：

{
  "mcpServers": {
    "top369": {
      "command": "top369-mcp",
      "env": {
        "TOP369_API_KEY": "sk-xxxxxxxxxxxx"
      }
    }
  }
}

环境变量：

工具与 SDK 方法同名同参（stock_day / kline / stock_st_list / stock_name_history / special_list / hsgt ...），SDK 文档的用法直接适用。行为约定：

• 结果为紧凑 JSON，行表默认最多 100 行（可传 max_rows 调整，硬上限 500）， 超出会带 _truncated 提示——收窄日期区间或用 fields 挑字段
• stock_basic 检索参数三层统一（HTTP / SDK / MCP）二选一：name=（股票名称 模糊匹配）或 code=（四种代码写法都认，后端归一精确匹配）；互斥与 “name 像代码”护栏由后端统一校验，违反返回 400
• 出错返回结构化 {"error", "status", "hint"}，例如档位不足的 403 会提示用 account 工具查档位、429 会提示用 usage 查余量——Agent 可自我纠正

其他语言

SDK 只是薄封装，后端是标准 REST，任何语言直接调用：

GET /api/stock/day?code=sz000911&limit=10
X-API-Key: sk-xxxx

响应统一信封 {code, message, data}，接口文档见 https://api.369.top/docs。