查询港股 K 线（hk-candlesticks）

1. 接口描述

项目	说明
接口名称	查询港股 K 线
外部接口	/api/v2/market/data/hk/hk-candlesticks
请求方式	GET
适用场景	按港股代码查询日/月/季/年 K 线；请求与响应中的代码均为 5 位数字 + .HK

2. 请求参数

参数名	类型	是否必填	描述	取值示例	备注
trade_code	string	是	港股代码	00700.HK	支持 700 或 00700.HK，响应中统一为 5 位 + .HK
interval_unit	string	是	K 线间隔单位	day	day/month/quarter/year（大小写不敏感）；不支持 week
until_date	string	是	结束日期	2026-03-24	格式 YYYY-MM-DD
since_date	string	否	开始日期	2026-01-01	不传则从库中最早数据起至 until_date
adjust_kind	string	否	复权类型	forward	默认 forward（前复权）；none 为不复权；取值大小写不敏感
interval_value	int	否	间隔数值	1	当前仅支持 1，其它值会报错
limit	int	否	返回条数上限	100	日 K 在 SQL 层下推；月/季/年在聚合后截取最近 N 根

3. 响应说明

返回值为 HkCandlesticksResponse：trade_code + K 线数组 items。

HkCandlesticksResponse 结构

字段名	类型	是否可为空	说明	单位
trade_code	String	否	规范化后的港股代码（5 位 + .HK）	-
items	Array	否	K 线列表，按日期升序	-

HkCandlestick 结构（items 元素）

字段名	类型	是否可为空	说明	单位
open	String	否	开盘价	元
high	String	否	最高价	元
low	String	否	最低价	元
close	String	否	收盘价	元
date	String	否	交易日	YYYY-MM-DD
turnover	String	否	成交额	元
volume	int64	否	成交量	股

时区说明

since_date / until_date 及响应中的 date 均为 港交所交易日历（UTC+8 / 东八区） 日期。若 Agent 所在系统时区非东八区，计算「今天」等相对日期时应先转为东八区再传参。Handler 内置了东八区容错：若传入 ISO 8601 含时区的字符串，会自动转为东八区后截取日期部分。

4. 调用方式

本 handler 与上级 FTShare-hk-data/run.py 配合使用：

python <RUN_PY> hk-candlesticks --trade-code 00700.HK --interval-unit day --until-date 2026-03-24 --since-date 2026-03-01 --limit 20
python <RUN_PY> hk-candlesticks --trade-code 00700.HK --interval-unit month --until-date 2026-03-24 --limit 12

其中 <RUN_PY> 为 FTShare-hk-data/run.py 的绝对路径。

CLI 统一使用 kebab-case 长选项名：--trade-code、--interval-unit、--until-date、--since-date、--adjust-kind、--interval-value；查询串参数名仍为接口文档中的 snake_case。

直接执行 handler（调试）

python scripts/handler.py --trade-code 00700.HK --interval-unit day --until-date 2026-03-24

（需在 sub-skills/hk-candlesticks 目录下执行，或传入脚本完整路径。）

5. 请求示例

GET /api/v2/market/data/hk/hk-candlesticks?trade_code=00700.HK&interval_unit=day&since_date=2026-03-01&until_date=2026-03-24&limit=20