历史 K 线
GET/api/v1.0/quote/{symbol}/history-kline获取指定时间区间的历史 K 线数据,支持向前翻页。
支持令牌续页:启用历史额度保护时,使用 pagination.next_page_token 作为下一页 page_token。令牌有效期 15 分钟,绑定当前用户、标的及 start/ktype/autype/num/extended_time/pred_side 的有效值;保持这些参数不变。令牌续页可省略 end/next_time;显式传 next_time 时必须与令牌一致。只有标记为首请求的历史限频规则豁免续页,其余限频仍执行。没有令牌时 end 与 next_time 至少传一个,仅传 next_time 按首请求计数。未启用历史额度保护时不会返回令牌,传 page_token 返回 -8 unsupported,应改用 end 或 next_time。
请求参数
| 参数 | 类型 | 位置 | 必填 | 说明 |
|---|---|---|---|---|
symbol | string | 路径 | 是 | 标的代码(路径参数),例: US.FUTU / HK.00700 最长长度 128; 格式 ^[A-Z0-9_]+\.[A-Za-z0-9_.\-]+$ |
start | string | 查询 | 否 | 起始日期 yyyy-MM-dd(含),不传则按 num 从 end 往前推。例: 2026-05-20 最长长度 10; 格式 ^$|^\d{4}-\d{2}-\d{2}$ |
end | string | 查询 | 否 | 结束日期 YYYY-MM-DD(标的市场时区)。分钟 K 线以该日 00:00 为截止边界,不含该日的分钟数据;查询单日时将 end 设为次日。日 K 线包含结束日。无有效 page_token 时,end 与 next_time 至少传一个;令牌续页可省略。 最长长度 10; 默认 ""; 格式 ^$|^\d{4}-\d{2}-\d{2}$ |
next_time | int | 查询 | 否 | 向前翻页游标(毫秒时间戳),取上一页响应 data.next_time 回传。传了 next_time 时作为下一页 end(秒级,半开区间,已排除上一页最早一条),优先级高于 end。0 表示不使用。例: 1779163200000 默认 0 |
ktype | int | 查询 | 否 | K 线类型。秒K(走 kline_type_v2):101=1秒 / 105=5秒 / 110=10秒 / 115=15秒 / 130=30秒 / 145=45秒。分K及以上:1=1分 / 2=日(默认)/ 3=周 / 4=月 / 5=年 / 6=5分 / 7=15分 / 8=30分 / 9=60分 / 10=3分 / 11=季 / 14=120分 / 15=240分 / 26=10分 / 29=180分。期权秒K仅 110/115/130 默认 2 |
autype | int | 查询 | 否 | 复权类型。0=不复权 / 1=前复权(默认)/ 2=后复权 默认 1; 取值 0, 1, 2 |
num | int | 查询 | 否 | 返回的 K 线条数,默认 370,最大 370 ≥ 1; ≤ 370; 默认 370 |
extended_time | int | 查询 | 否 | 盘前盘后开关。0=默认(不含)/ 1=含盘前盘后(美股分 K)/ 2=含夜盘(美股) 默认 0; 取值 0, 1, 2 |
pred_side | int | 查询 | 否 | 仅事件合约。0=按 symbol 原样查(默认);1=解析到 YES 子合约;2=解析到 NO 子合约。已带.YES/.NO 后缀时仍以 pred_side 为准(.YES + pred_side=2 会切到 NO)。其它品类忽略 默认 0; 取值 0, 1, 2 |
page_token | string | 查询 | 否 | 上一页 pagination.next_page_token;15 分钟内有效。可省略或传空字符串开始新查询。 最长长度 48; 格式 ^$|^[0-9a-f]{48}$ |
请求示例
查询 2026-11-09 的 QQQ 1 分钟 K 线,使用 start=2026-11-09&end=2026-11-10,不要将起止日期都设为 2026-11-09,否则分钟 K 线会返回空列表。5 分钟 K 线将 ktype 改为 6;日 K(ktype=2)包含结束日,可用相同的起止日期查询单日。
bash
curl -s "https://webapi.futunn.com/api/v1.0/quote/US.QQQ/history-kline?start=2026-11-09&end=2026-11-10&ktype=1&autype=1&num=370&extended_time=0" | jq响应字段
| 参数 | 类型 | 说明 |
|---|---|---|
data | object | |
data.kline_list | object[] | |
data.kline_list[].time_key | int | K 线时间,毫秒时间戳,例: 1779249600000 |
data.kline_list[].date | int | K 线日期 YYYYMMDD(分 K 为所属交易日,日 K 及以上为时间戳对应的当地日期),例: 20260523 |
data.kline_list[].time_zone | int | 时区偏移(分钟,相对 UTC),用于把 time_key 换算为标的所在市场的当地时间,例: 480(HK)/-300(US 夏令) |
data.kline_list[].open | number | 开盘价,例: 124.12 |
data.kline_list[].close | number | 收盘价,例: 124.72 |
data.kline_list[].high | number | 最高价,例: 127.45 |
data.kline_list[].low | number | 最低价,例: 122.7 |
data.kline_list[].volume | int | 成交量(股),例: 2960896 |
data.kline_list[].turnover | number | 成交额,例: 370529897 |
data.kline_list[].last_close | number | 昨收价,例: 124.5 |
data.kline_list[].pe_ratio | number | 市盈率(PE),例: 17.728 |
data.kline_list[].turnover_rate | number | 换手率(百分数),例: 0.49348 |
data.kline_list[].change_rate | number | 涨跌幅(百分数,相对昨收价),例: 0.17670682730923695 |
data.kline_list[].open_interest | int | 持仓量(仅期货/期权返回,其他品类为 0 或不返回),例: 12345 |
data.kline_list[].settle_price | number | 结算价:仅对期货/期权(日 K 及以上)有结算意义;其他品类(股票/ETF/指数等)服务端会回填为收盘价 close,调用方应忽略,不可当结算价使用。例: 124.5 |
data.kline_list[].implied_volatility | number | 隐含波动率(百分数,仅期权返回,其他品类为 0 或不返回),例: 12.345 |
data.kline_list[].name | string | 股票英文名 |
data.kline_list[].sc_name | string | 股票简体中文名 |
data.kline_list[].tc_name | string | 股票繁体中文名 |
data.next_time | int | 下一页 end 游标(毫秒戳,半开,已排除本页最早一条)。仅当 has_more=true(区间外还有更旧数据)时下发;向更早翻页时把它回传到 next_time 参数。例: 1779163199999 |
data.volume_precision | int | 成交量精度 n。kline_list[].volume 已被放大 10^n 倍,调用方需自行除以 10^n 还原真实成交量。仅事件合约/数字货币等特殊品类可能 >0;股票/ETF/期货/期权一般为 0,例: 0 |
pagination | object | |
pagination.has_more | bool | |
pagination.next_page_token | string | 下一页令牌。仅在历史额度保护启用、本页非空且 has_more=true 时返回;15 分钟内回传为 page_token。 |
限制范围
- code 必须是已开通行情前缀必须落在已注册市场前缀内,否则返回
invalid_symbol(如 HK / US / SH / SZ / BJ / SG / CA / AU / FX / JP / KR / CC / FT 等)。 - 支持品类:股票 / ETF / 指数 / 期货 / 期权 / 数字货币等;优先股 / SPAC / 可转债 / 牛熊证(CBBC)等不支持品类服务端返回空 kline_list。
- 市场前缀未在支持的枚举内(如 UK / IT 等):返回 ret_code=-8 unsupported。
错误码
| ret_code | error.code | 触发条件 | 处理建议 |
|---|---|---|---|
| 0 | — | 成功;合法但无数据时 kline_list 为空数组 | — |
| -3 | invalid_parameter | 无有效 page_token 时 end 与 next_time 同时缺失 / 类型错 / 枚举非法(ktype 越界)/ 日期格式不符 | 校正参数后重试 |
| -7 | invalid_symbol | symbol 格式合法但未找到对应证券(如 HK.99999999) | 通过 search 接口确认代码合法性 |
| -8 | unsupported | 市场前缀不在支持范围(如 UK.HSBA / IT.STM) | 确认市场前缀是否受支持 |
| -3 | invalid_page_token | 令牌无效、过期、查询参数不一致或分页状态失效 | 用 end 或 next_time 重新发起查询 |
| -11 | rate_limited | 命中当前限频策略 | 按 Retry-After 秒数退避 |
| -11 | history_quota_busy | 同标的新请求正在预占额度 | 1 秒后重试 |
| -12 | history_quota_exceeded | 新标的或新期权链无可用额度 | 查询额度,等待已占用项到期 |
| -13 | quota_unavailable | 权限、额度或限频依赖不可用 | 稍后退避重试 |
响应示例
json
{
"ret_code": 0,
"ret_msg": "success",
"data": {
"kline_list": [
{
"change_rate": 0.17670682730923695,
"close": 124.72,
"high": 127.45,
"last_close": 124.5,
"low": 122.7,
"name": "富途控股",
"open": 124.12,
"pe_ratio": 17.728,
"time_key": 1779249600000,
"turnover": 370529897,
"turnover_rate": 0.49348,
"volume": 2960896
},
{
"change_rate": -0.689544579858884,
"close": 123.86,
"high": 125.45,
"last_close": 124.72,
"low": 122.1,
"name": "富途控股",
"open": 122.7,
"pe_ratio": 17.606,
"time_key": 1779336000000,
"turnover": 271859605,
"turnover_rate": 0.36631,
"volume": 2197832
}
]
},
"pagination": {
"has_more": false
}
}额度与续页
首次成功返回非空数据后占用一个历史额度;默认 7×24 小时后释放,重复读取不延期。失败或空结果不新增占用。同一标的跨周期、复权和页面去重;期权按市场、标的与到期日组成的期权链计量,与普通池独立。详见行情权限与额度。
当 pagination.has_more=true 时,优先原样回传 pagination.next_page_token;没有令牌则回传 data.next_time。has_more=false 时停止。不要解析或自行生成令牌。