接口概览

QuantDB 提供 RESTful API，支持 JWT Token（桌面客户端）和 X-API-Key（量化脚本）两种鉴权方式。所有 API 均挂载在 /api/v1 下，返回 JSON 格式。

开发环境: http://localhost:5000   |   生产环境: https://api.quantdb.cn   |   Content-Type: application/json

分类一览

分类端点鉴权
健康检查GET /health公开
认证POST /auth/login, POST /auth/register公开
账户GET /auth/me, GET /auth/api-keys需鉴权
元数据GET /data/stock-list, GET /data/calendar, GET /data/preview需鉴权
下载GET /data/download需鉴权

鉴权方式

JWT Bearer Token

桌面客户端或交互式使用，Token 24 小时过期。

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

X-API-Key

量化脚本或自动化场景，长期有效。

X-API-Key: qdb_abc123def456...

响应格式

成功返回 HTTP 200，数据放在 data 或 files 字段；失败返回对应 HTTP 状态码与 detail 错误描述。

{
  "detail": "错误描述信息（有错误时）"
}

认证接口

POST /api/v1/auth/login 60次/分 ▶
用户名或邮箱登录，返回 JWT Token。

请求参数

字段类型说明
usernamestring用户名或邮箱
passwordstring密码

请求示例

curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your_password"}'

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}
POST /api/v1/auth/register 3次/分·IP ▶
新用户注册，注册后需验证邮箱方可登录。

请求参数

字段类型说明
usernamestring3-32 字符，字母/数字/下划线
emailstring有效邮箱
passwordstring8-64 字符
curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"trader01","email":"trader@example.com","password":"pass1234"}'
GET /api/v1/auth/verify-email?token=<token> ▶
邮件验证链接，浏览器直接访问。
POST /api/v1/auth/forgot-password 3次/分·IP ▶
发送密码重置邮件到注册邮箱。
POST /api/v1/auth/reset-password ▶
使用邮件中的重置令牌设置新密码，令牌 30 分钟有效。

账户管理

查询用量、余额、管理 API Key。支持 Bearer Token 或 X-API-Key。

GET /api/v1/auth/me 60次/分 ▶
获取当前用户信息及流量使用情况。
curl http://localhost:5000/api/v1/auth/me \
  -H "Authorization: Bearer <jwt_token>"
{
  "username": "admin",
  "id": 1,
  "used_traffic": 1048576,
  "traffic_limit": 32212254720,
  "credit_limit": 0,
  "balance_yuan": 10.0
}
GET /api/v1/auth/api-keys 需鉴权 ▶
列出当前用户的 API Key 列表。
curl http://localhost:5000/api/v1/auth/api-keys \
  -H "Authorization: Bearer <jwt_token>"
POST /api/v1/auth/api-keys 需鉴权 ▶
创建新的 API Key（每用户仅限 1 个有效 Key）。
注意：API Key 创建后仅在返回时明文展示一次，请立即保存。 
curl -X POST http://localhost:5000/api/v1/auth/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "量化回测脚本"}'
DELETE /api/v1/auth/api-keys/:key_token 需鉴权 ▶
撤销指定 API Key。

元数据查询

股票列表、交易日历、数据预览等元数据接口：网关直读对象存储 Parquet 返回 JSON，仅登录 + 限流，不计流量，免费用户可用。业务数据（K 线 / Tick / 财务）的查询通过下载 Parquet 切片实现，见下方"数据预览与下载"。

GET /api/v1/data/stock-list 30次/分·用户 ▶
A 股基础信息：代码、名称、上市日、ST/退市状态。
df = client.query_stock_list(keyword="茅台", limit=5)
print(df)
GET /api/v1/data/calendar 30次/分·用户 ▶
A 股交易日历，返回交易日及是否开市标记。
df = client.query_calendar(start_date="2026-01-01", end_date="2026-12-31")

数据预览与下载

预览（免费）和下载（消耗流量）Parquet 原始数据文件。

GET /api/v1/data/preview 60次/分 ▶
预览本地 Parquet 尾部数据，不计流量费。
参数类型说明
category_idstring大分类 ID（1-6）
sub_categorystring子分类名，如 daily_forward
symbolstring股票代码
limitint返回行数，默认 30
df = client.preview_as_df("1", "daily_forward", symbol="600519.SH", limit=5)
GET /api/v1/data/download 30次/分 ▶
流式下载原始 Parquet 文件。每月前 30GB 免费，超出按 ¥1/GB 计费。
计费规则：两阶段事务 — 传输成功才扣费，中途断开自动回滚。余额不足返回 HTTP 402。 
curl -OJ "http://localhost:5000/api/v1/data/download?category_id=1&sub_category=daily_forward&symbol=600519.SH" \
  -H "X-API-Key: qdb_abc..."

Python SDK

# 下载到本地
path = client.download_file("1", "daily_forward", symbol="600519.SH")

# 直接加载到 DataFrame（不落盘）
df = client.load_as_df("1", "daily_forward", symbol="600519.SH")
GET /api/v1/data/download/manifest 10次/分 ▶
获取分类在 COS 上的全量文件清单（含 etag），用于批量下载和增量同步。不计费。
files = client.query_manifest("1", "daily_forward")
print(f"共 {len(files)} 个文件")
GET /api/v1/version 公开 ▶
客户端版本检查，返回最新版本号和下载地址。

Python SDK 快速入门

quantdb-sdk 是官方 Python SDK，一行代码即可调用全部接口。

安装：pip install quantdb-sdk（依赖 requests、pandas、httpx、duckdb）

初始化

from quantdb_sdk import QuantDBClient

# 方式一：API Key（推荐）
client = QuantDBClient(api_key="qdb_abc123...")

# 方式二：用户名密码登录
client = QuantDBClient(username="user", password="pass")

# 自定义服务地址
client = QuantDBClient(api_host="http://your-server:5000", api_key="qdb_abc...")

常用方法

方法分类说明
get_usage()账户查询流量用量、余额、剩余额度
query_kline()数据查询下载 K 线 Parquet 切片后客户端解析（消耗流量）
query_tick()数据查询下载 Tick Parquet 切片后客户端解析（消耗流量）
query_stock_list()元数据股票列表模糊搜索（不计流量）
query_calendar()元数据交易日历查询（不计流量）
query_manifest()批量下载COS 文件清单
preview_as_df()预览预览 Parquet 尾部数据
download_file()下载流式下载 Parquet 到本地
load_as_df()下载远端 Parquet 直读 DataFrame
query_local()本地查询DuckDB SQL 查询已下载 Parquet

完整 SDK 文档请查看 Python SDK 文档。

更新日志

v1.0.0 2026-07-22 当前版本
  • 全功能上线：认证、数据查询、下载、计费
  • 对象存储 Parquet 切片下载 + 客户端解析（K 线 / Tick / 财务）
  • COS Parquet 流式下载 + 两阶段计费事务
  • 邮箱注册验证 + 密码重置
  • API Key 全生命周期管理
  • 滑动窗口限流
  • Python SDK（同步 + 异步）
  • Electron 桌面客户端

HTTP 状态码速查

码含义说明
200成功请求正常处理
400参数错误缺少必填参数或格式不正确
401未认证JWT 过期 / API Key 无效
402余额不足下载时账户余额不足
403无权限邮箱未验证 / 账户禁用
404数据不存在Parquet 文件或 COS 对象不存在
409冲突用户名/邮箱已注册、API Key 已存在
429限流请求频率超限
500服务端错误内部错误
503服务不可用COS/邮件未配置