请求参数

请求示例

curl -X POST https://www.quantdb.cn/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

curl https://www.quantdb.cn/api/v1/auth/me \
  -H "Authorization: Bearer <jwt_token>"

{
  "username": "trader01",
  "email": "trader@example.com",
  "id": 2,
  "used_traffic": 1048576,
  "traffic_limit": 104857600,
  "credit_limit": 0,
  "purchased_traffic": 0,
  "balance_yuan": 0,
  "subscription": { "status": "free", "plan_id": "" }
}

curl https://www.quantdb.cn/api/v1/auth/usage \
  -H "Authorization: Bearer <jwt_token>"

{
  "used_traffic": 1048576,
  "traffic_limit": 104857600,
  "credit_limit": 0,
  "purchased_traffic": 0,
  "balance_yuan": 0,
  "subscription": { "status": "free", "plan_id": "" }
}

curl https://www.quantdb.cn/api/v1/auth/api-keys \
  -H "Authorization: Bearer <jwt_token>"

curl -X POST https://www.quantdb.cn/api/v1/auth/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "量化回测脚本"}'

df = client.query_stock_list(keyword="茅台", limit=5)
print(df)

df = client.query_calendar(start_date="2026-01-01", end_date="2026-12-31")

df = client.preview_as_df("1", "daily_forward", symbol="600519.SH", limit=5)

curl -OJ "https://www.quantdb.cn/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")

files = client.query_manifest("1", "daily_forward", layout="v2")
print(f"共 {len(files)} 个文件")

result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")

• 修复 get_usage() / a_get_usage() 漏算流量包额度：旧口径只算 traffic_limit + credit_limit + purchased_traffic - used_traffic，完全忽略流量包，导致持有流量包的用户剩余流量被低估、is_active 误判
• 新增额度明细字段：合计 total_gb / used_gb / remaining_gb，套餐额度 plan_total_gb / plan_used_gb / plan_remaining_gb，流量包额度 package_total_gb / package_used_gb / package_remaining_gb（原字段全部保留）
• quantdb usage CLI 改为分行展示套餐 / 流量包 / 合计的已用、总额与剩余

• per_share 数据集更名：中文名由「每股指标（补充）」改为「财务指标（TTM）」，描述与关键词同步更新（每股/eps → 财务/ttm）
• 该表实际为 TTM 口径财务指标补充表（营收 / 归母净利 / 扣非净利 / 经营现金流等）；per_share 标识符不变，client.data 用法不受影响

• 新增数据集 per_share（每股指标补充表，分类 3）：补登记为第 30 个数据集，client.data / sync_dataset() / mount() 均可直接按 per_share 使用
• 物理形态为 V1 逐股票文件 3_financial_data/per_share/{Symbol}.parquet（部分股票为空），读取 / 查询需提供 symbol
• 与 MCP catalog、后端 subCategoryMapping、前端分类表同步对齐（均为 30 项）

• 本地零流量读取提速（client.data.read_local / read）：改用 DuckDB 对精确分区文件列表做一次 read_parquet，symbol / 日期区间 / 列裁剪全部下推到 SQL；实测（120 分区 × 1000 标的）单标的全历史 0.62s → 0.22s，带 columns 列裁剪 → 0.07s
• 依赖下界：duckdb 由 >=0.8.0 提升到 >=1.0.0（read_parquet(filename=true) + * EXCLUDE 语法；0.8.x 在部分环境导入即崩溃）
• 修复：read_local(columns=[...]) 未下推 symbol 过滤，columns 不含 symbol 时会误返回全市场行

• 统一数据入口 client.data（同步 DataHub / 异步 AsyncDataHub）：只凭 dataset 名即可跨 6 大分类目录取数，无需再手填 category_id + sub_category，SDK 侧自动解析分类并路由，零后端改动
• 发现与本地零流量读取：datasets() 列出 29 个数据集，info() 叠加云端元数据；local_files() / local_path() / read_local() / read() 支持可配置 root 的本地零流量读取，V2 / tick 自动注入 trade_date
• 在线查询与同步映射：query() 按数据集自动路由（日线 / ETF / Tick / 通用 V2 / V1），并映射 preview / load / download / sync / mount；异步方法统一 a_ 前缀
• 新增 CLI quantdb datasets [name]：列出全部数据集目录或查看某数据集详情（无需 API Key）

• 分区大小查询 query_partition_size()（含异步 a_query_partition_size()）：返回各子分类的分区数 file_count、总字节 file_size 与换算列 file_size_gb，用于估算下载流量与数据占用；缺省返回全部子分类，可传 sub_category 单查
• query_meta() / a_query_meta() 新增 sub_category 参数：data_meta 现已包含 file_size（分区总字节），可按子分类精准查询各数据集日期范围/行数/文件数/文件大小

• ETF 日 K 线查询 query_etf_kline()（含异步 a_query_etf_kline()）：查询分类 4 的 etf_kline（V2 全市场按日分区，symbol 形如 510300.SH），自动优先 V2、覆盖不完整时回退 V1
• sync_dataset("etf_kline") 支持：增量同步 ETF 日线，此前会报「不支持同步的数据集」

• 本地完整性扫描 scan_local_directory()（scan_local() / a_scan_local() 方法）：扫描本地数据目录，流式计算每个文件的 MD5 与 COS 形态 ETag，用于发布前/对账的独立指纹核对，全程本地 IO 不消耗流量
• 支持递归/后缀过滤/进度回调，返回汇总与逐文件清单；读取失败文件登记到 errors 不中断扫描

• 同步 304 权威对账：sync_dataset() 对已存在本地文件先发 If-None-Match（服务端在预扣/直连前校验），命中 304 免流量只登记跳过，修复"本地有文件但 sqlite 记录/指纹对不上"时的整块重下
• 判重主键改为 sha256：不再依赖 release 对象的 etag 字段；下载后落库真实 COS ETag 供后续对账/304 复用

• CLI 目录规范命令：新增 quantdb layout，终端直接打印本地数据目录规范（无需 API Key）
• CLI 帮助增强：--help 提示演示脚本；sync 打印 matched 本地对账跳过数

• 目录规范模块：新增 quantdb_sdk.layout（CATEGORY_DIRS / dataset_dir / dataset_layout / local_relative_path / data_root），本地落地目录与平台统一约定一致，根目录可配置（QUANTDB_DATA_DIR）
• 演示脚本包：随 wheel 发布 6 个 quantdb_sdk.examples 示例
• 同步磁盘对账：sync_dataset() 目标文件已存在且本地 MD5 == COS ETag 时跳过下载，返回 matched 字段；数据根目录可自由指向，不会重复下载

• 规范对齐与稳定性增强：与 QuantDB 1.0.0 正式版规范全面对齐，优化 ETag 缓存比对与数据传输机制

• CDN 直连重试路径修复：0.2.8 引入的重试逻辑缺失 import time / import asyncio，触发重试时抛 NameError，已补齐导入

• CDN 直连 302 相对 URL 修复：服务端 CDN 直连模式 Stage 1 返回相对 URL（/api/v1/data/cdn-bridge?token=xxx），此前直接作为请求 URL 导致 MissingSchema / UnsupportedProtocol，CDN 直连下载完全不可用；现在自动拼接 api_host 构造完整 URL
• CDN 直连请求带重试：cdn-bridge 与 CDN 签名 URL 两跳请求均带 2 次重试（指数退避 1s/2s），网络抖动不再中断整个 sync_dataset
• 302 重定向链路手动跟随：统一用重试循环跟随最多 3 跳（/download → /cdn-bridge → CDN 签名 URL），ETag 逐跳透传

• V1 回退对纯 V2 数据集失效修复：query_kline / a_query_kline 无日期范围时不再默认走 V1。margin_trading、features_daily、l1_factors、l2_factors 等 11 个纯 V2 数据集在对象存储上已无 V1 逐股票文件，V1 回退会 404。现在无范围时也走 V2 manifest 路径（全量下载所有分区），仅在有日期范围时才做日历完整性校验
• 异步客户端时区处理对齐：AsyncQuantDBClient._normalise_kline 补齐 tz_convert 逻辑，与同步客户端行为一致

• 适配服务端 CDN 直连下载（302 跳转）：修复异步客户端在 CDN 直连模式下下载/同步接口失效的问题
• 凭证保护：同步与异步客户端统一改为手动处理 302 + 无鉴权头裸请求直连 CDN，API Key 不会泄露给 CDN 域
• 302 响应中的对象存储 ETag 回填至 CDN 响应，保证进程内 ETag 缓存与 If-None-Match 304 逻辑一致
• [后端安全] 一次性下载令牌：302 模式改为两跳（令牌中转），防止签名 URL 被重复使用或分享
• [后端安全] 移除 ?direct=1 请求级覆盖，用户无法强制走 302 模式

• [数据架构] 对象存储 V2 数据集全面清理 V1 残留文件（~1.8 万对象），11 个 V2 数据集均为纯 V2 存储，ListObjects 分页效率提升 3-5 倍
• [数据架构] L1 日频因子（l1_factors）V2 全量上线：覆盖 2016-01-04 至今全历史，支持按日范围高效查询与每日增量更新
• [数据架构] L2 高频因子（l2_factors）V2 上线：覆盖 2023 年至今全市场高频微观结构因子