Python SDK

仅登录后可下载。SDK 安装在调用者电脑或程序服务器上，支持 Windows、macOS 和 Linux，不需要在金牛服务器新增服务。尚未发布 PyPI，请先下载安装包。

SHA-256：8da4333e2e002a72a7ea461ca57ee4a3d8b4b729fd1962192c1cefacd18f5637

1. 安装

在安装包所在文件夹运行；首次安装会安装 pandas、requests 等依赖，满足版本要求的已有依赖无需重复下载，不会下载全量行情。

python -m pip install --upgrade ./jinniu_sdk-0.2.0-py3-none-any.whl

交给 AI 安装（可选）

先登录下载安装包，再把下方说明交给能访问本地文件并执行终端命令的 AI。仅聊天的 AI 可以指导操作，不能代替你安装。真实 API Key 请在本地配置，不要粘贴到聊天里。

请在这台电脑上安装金牛 Python SDK，并验证安装结果。

安装包：jinniu_sdk-0.2.0-py3-none-any.whl（我已从金牛网站登录下载，请先确认文件位置）
文档：https://jinniu.ziyoutang.com/daily-data-docs/sdk
SHA-256：8da4333e2e002a72a7ea461ca57ee4a3d8b4b729fd1962192c1cefacd18f5637

1. 检查操作系统和 Python 版本，要求 Python 3.9+。如果不满足，先说明所需操作；不要擅自更改系统配置。
2. 创建独立虚拟环境 .venv，核对安装包 SHA-256，再使用该环境的 Python 执行：
   python -m pip install --upgrade /实际路径/jinniu_sdk-0.2.0-py3-none-any.whl
   不修改全局 Python，不使用管理员权限。SDK 尚未发布 PyPI，不安装网上同名包。
3. 用该虚拟环境验证 from jinniu_sdk import JinniuClient，并运行 python -m pip check；报告环境路径、SDK 版本和验证结果。
4. API Key 由我在本地配置为 JINNIU_API_KEY 环境变量。不要要求我把真实 Key 发到聊天，不要打印、写入源码或提交到 Git。尚未配置时，先完成安装验证，暂停接口测试并说明下一步。
5. 配置完成后，按文档使用 JinniuClient()，对已开通且未到期的接口发起一次小范围请求；分钟示例 limit=4000，但不得超过账户实际单次上限。不要下载全量数据，不增加并发或绕过额度限制。
6. 报告请求是否成功、返回行数和耗时；若无权限、到期、超限或网络失败，保留实际错误原因并说明处理方法，不反复重试。不执行实盘交易。

注意：SDK 安装成功不代表接口权限已开通；仍需要有效 Key、对应权限和可用额度。

2. 配置 API Key

在个人中心获取 API Key。推荐通过 JINNIU_API_KEY 环境变量提供，或在自己的程序中传入 api_key。不要把真实 Key 放入公开仓库、浏览器前端或截图。

3. 直接调用

from jinniu_sdk import JinniuClient

# Replace YOUR_API_KEY with your own key; do not share it.
with JinniuClient(api_key="YOUR_API_KEY") as client:
    df = client.stk_mins(
        ts_code="000001.SZ",
        freq="1min",
        start_date="2026-09-30 09:00:00",
        end_date="2026-09-30 15:00:00",
        limit=4000,
        fields=["ts_code", "trade_time", "open", "close", "vol", "amount"],
    )
    print(df.head(2))
    print(df.attrs["jinniu"])

使用环境变量时，将构造函数改为 JinniuClient()。命名接口方法和 client.query("stk_mins", ...) 返回 pandas DataFrame；client.request(...) 保留原始响应与服务器 meta。支持的36个接口可用 JinniuClient.available_apis() 列出，参数与对应接口文档一致。

FAQ 查询

0.2.0 新增期货合约信息 fut_basic、日线 fut_daily、主力映射 fut_mapping、复权因子 fut_adjfactor、后复权日线 fut_daily_adj、持仓排名 fut_holding、仓单日报 fut_wsr。方法名与接口名一致，例如 client.fut_adjfactor(ts_code="CU.SHF", trade_date="20261015", limit=10)。需要期货历史权限，参数、字段和单位见期货文档。

0.1.1起可用 client.faq_search(q="停牌", page=1) 查询已核验且可解释的FAQ，固定每页20条，不要求行情权限、不扣行情日额度。旧版SDK需下载安装包后按上方命令升级。结果包含问题、答案、适用范围和核验日期；分页信息在 attrs["jinniu"]["meta"]。

from jinniu_sdk import JinniuClient

# Set JINNIU_API_KEY in your local environment.
with JinniuClient() as client:
    result = client.faq_search(q="停牌", page=1)
    print(result[["question", "answer", "scope"]])
    print(result.attrs["jinniu"]["meta"])

4. 分批获取历史分钟

from jinniu_sdk import JinniuClient

with JinniuClient(api_key="YOUR_API_KEY") as client:
    df = client.fetch_minutes(
        "stk_mins", ts_code="000001.SZ", freq="5min",
        start_date="2026-09-01", end_date="2026-09-30",
        limit=4000, window_days=1,
    )
    df.to_csv("000001_5min.csv", index=False, encoding="utf-8-sig")

服务端返回截断标记时会缩小窗口重新查询；不自动补造缺失交易日或分钟。多年历史可改用 iter_minutes 逐批处理，避免一次合并大表。价格、复权、单位与北京时间均按接口原样保留，不做 SDK 行情缓存。

5. 默认请求控制

• 同一 SDK 实例默认每分钟 60 次、最多 2 个并发请求；可配置 requests_per_minute 和 max_concurrency，但不得超过账户实际额度。服务端限制和后台配置优先。
• 多个线程应共享同一个客户端实例；不同实例、进程或电脑的调用量不会自动合并。
• 连接复用、gzip 自动解压；网络故障、5xx 和非每日 429 最多重试 2 次，遵守 Retry-After，累计重试等待超过 90 秒则返回错误。重试和缩小窗口重查仍可能消耗额度。
• 默认连接超时 5 秒、读取停顿超时 60 秒，不是整次调用的总时间上限。单次示例 limit=4000 不是服务端上限；后台设置更小时需同步降低请求参数。

6. 常见错误

• AuthenticationError：Key 无效或已删除，去个人中心核对。
• PermissionDeniedError：对应数据权限未开通或已到期，去权限中心联系开通或续订。
• DailyLimitError：超过每日额度，SDK 不自动重试，等待额度重置或联系管理员。
• ParameterError：参数不合法，包括 limit 超过当前服务端上限；按错误原因修改。
• RateLimitError：重试后仍受限，查看 retry_after 后再尝试，不要增加线程。
• NetworkError / ServerError：有限重试后仍失败，缩小请求、检查网络，保留接口名称与错误时间反馈。