exsdk 期货历史 K 线下载

download_kline_data() 同步返回 pandas DataFrame，无需调用 wait_update()。

查询历史 K 线#

将 YOUR_TOKEN 替换为自己的令牌。
将环境变量 EXSDK_SYMBOL 设置为需要查询的期货合约。
选择该合约有数据的日期范围，再运行下面的程序。

import os
from exsdk import ExApi

with ExApi(token="YOUR_TOKEN") as api:
    frame = api.tools.download_kline_data(
        symbol=os.environ["EXSDK_SYMBOL"],
        period="1m",
        start="20260901",
        end="20260909",
        limit=10000,
    )
    if frame.empty:
        print("指定合约与日期范围内没有返回 K 线")
    else:
        print(frame.head())
    print("本次下载行数", len(frame))

参数与返回值#

参数	约定
`start`、`end`	`YYYYMMDD` 交易日，包含首尾两天，且 `start <= end`；夜盘按所属交易日归属
`period`	与 `watch_kline()` 相同，仅支持期货
`limit`	1–10000 的整数，默认 10000；从起始交易日向后取数

返回字段与 K 线快照相同，按时间升序排列；无数据时返回带列名的空表。

返回行数取决于实际数据，不会补齐到 limit。空结果只表示这次查询没有返回数据：先检查是否传入期货合约、日期是否属于该合约交易期间，再核实服务的数据覆盖，不要把它直接解释为网络故障。日期应按交易日填写，而非直接按夜盘发生的自然日填写。

下载范围：一次结果可能未覆盖整个日期范围，需要完整下载时按下文循环拼接。

历史覆盖以服务实际存储为准，接口不承诺任意合约从上市到退市的数据都齐全。补录历史数据的 turnover 可能为 0，这不等于真实成交额为零；依赖成交额的指标应先核实数据口径，见数据字典。

循环拼接#

以下分页示例适用于分钟、小时和日线，放在已建立的 with ExApi(...) as api: 中执行。分页可避免单次行数上限造成的截断，不会补齐缺失数据。

import pandas as pd

start, end = "20260901", "20260930"
limit = 10000
cursor = start
pages = []
while True:
    page = api.tools.download_kline_data(symbol, "1m", cursor, end, limit=limit)
    pages.append(page)
    if len(page) < limit:
        break
    # Re-read the last TradingDay because a full page may truncate it.
    next_day = page.iloc[-1]["trading_day"]
    # Stop if the date cursor cannot advance.
    if next_day <= cursor:
        raise RuntimeError("Daily query limit reached; complete download cannot be guaranteed")
    cursor = next_day

frame = pd.concat(pages, ignore_index=True)
frame = frame.drop_duplicates("timestamp", keep="last").sort_values(
    "timestamp", ignore_index=True
)
print("拼接后行数", len(frame))

保存结果#

需要 CSV 时，可保存查询或拼接后的 DataFrame：

frame.to_csv("history.csv", index=False, encoding="utf-8-sig")

当前尚未结束的 K 线之后仍可能变化。