一、项目背景:为什么量化交易需要自定义周期 K 线?**
在量化交易系统中,行情数据是策略研究、信号计算、回测和实盘执行的基础。常见行情接口通常提供 1 分钟、5 分钟、15 分钟、1 小时等标准周期 K 线,但部分策略需要更灵活的时间粒度,例如 10 秒、30 秒、2 分钟或 45 分钟 K 线。
对于订单流分析、短周期动量策略和跨市场时间对齐策略,固定周期可能无法满足研究需求。一个可控的做法是直接接入逐笔成交(Tick)数据,在自己的数据处理服务中按指定时间窗口聚合 OHLCV,从而生成自定义周期 K 线。
本文以 DeepTick API 为行情数据来源,使用 REST K 线接口获取历史数据,并使用 WebSocket 逐笔成交流接收实时 Tick。通过统一的时间窗口与聚合规则,让历史数据处理和实时数据处理尽可能复用同一套业务逻辑。
**二、整体方案:DeepTick REST K 线 + WebSocket Tick**
推荐将行情管线拆分为两个入口和一个统一聚合内核:
历史行情入口:调用 DeepTick REST Candles API,获取标准周期历史 K 线,用于图表初始化、指标计算和回测基准。
实时行情入口:连接 DeepTick WebSocket,使用 tick 类型 Topic 订阅逐笔成交数据。
统一处理内核:完成时间戳标准化、Tick 排序或乱序处理、时间桶计算、OHLCV 更新、K 线闭合与下游分发。
需要区分两种用途:REST Candles 返回的是服务端已经聚合的历史 K 线;WebSocket Tick 提供逐笔成交明细,可由客户端自行聚合出非标准周期。若要严格保证回测与实盘一致,建议在历史回测阶段也使用逐笔成交数据按相同算法聚合,而不是直接将不同数据源或不同口径的标准 K 线混用。
**三、DeepTick API 接入准备**
开始编码前,需要在 DeepTick 平台准备 API Token,并确认目标市场、交易标的、数据权限及套餐限制。示例以加密货币 BTCUSDT 为例;DeepTick Topic 中的市场代码和标的格式应按实际订阅品种调整。
将 Token 放入环境变量,避免将密钥写入源码、前端代码或公开代码仓库。
```
# Linux / macOS
export DEEPTICK_API_TOKEN="替换为你的 DeepTick API Token"
# Windows PowerShell
$env:DEEPTICK_API_TOKEN="替换为你的 DeepTick API Token"
```
**四、历史 K 线:使用 DeepTick REST Candles API**
历史 K 线通常用于回测数据加载、技术指标计算和图表初始化。DeepTick 的 K 线查询接口按周期返回历史 Bar。以下 Python 示例采用文档对应的 REST 路径与常见请求参数封装请求,并对 HTTP 状态、业务返回码和空数据进行检查。
接口路径:GET https://api.deeptick.cc/api/v1/candles。常用参数包括 symbols、interval、limit;可选 et 用于指定截止时间(Unix 毫秒)。周期值及条数范围应以 DeepTick 当前文档和账户权限为准。
```
import os
import requests
from typing import Any
BASE_URL = "//api.deeptick.cc"
API_TOKEN = os.environ["DEEPTICK_API_TOKEN"]
def get_candles(
symbol: str = "BTCUSDT.CR",
interval: str = "1m",
limit: int = 200,
end_time_ms: int | None = None,
) -> list[dict[str, Any]]:
"""获取历史 K 线。时间参数及字段口径请以 DeepTick 最新文档为准。"""
headers = {
"accept": "application/json",
"deeptoken": API_TOKEN,
}
params = {
"symbols": symbol,
"interval": interval,
"limit": limit,
}
if end_time_ms is not None:
params["et"] = end_time_ms
response = requests.get(
f"{BASE_URL}/api/v1/candles",
headers=headers,
params=params,
timeout=15,
)
response.raise_for_status()
payload = response.json()
if payload.get("code") != 0:
raise RuntimeError(f"DeepTick API error: {payload}")
return payload.get("data") or []
if __name__ == "__main__":
candles = get_candles(
symbol="BTCUSDT.CR",
interval="1m",
limit=100,
)
for candle in candles[:5]:
print(candle)
```
开发提示:K 线响应字段应以接口实际返回为准。常见字段映射可能包含 t(时间)、o(开盘价)、h(最高价)、l(最低价)、c(收盘价)、v(成交量)等;正式上线前应在代码中显式校验字段、时间戳单位、成交量含义和数据排序,避免把示例字段假设直接用于生产。
**五、实时成交:使用 DeepTick WebSocket Tick API**
实时逐笔成交适合需要逐笔级别数据的策略和行情系统。DeepTick WebSocket 接入地址为 wss://api.deeptick.cc/ws/v1,连接握手时通过 deeptoken 请求头完成鉴权。认证成功后,服务端会先发送 welcome 消息,客户端再发送订阅请求。
DeepTick 使用 Topic 订阅模型。逐笔成交 Topic 的格式为 tick.{market}.{symbol};例如加密货币 BTCUSDT 可使用 tick.CR.BTCUSDT。订阅请求采用 type、topics 和 request\_id 等字段。
```
# pip install websockets
import asyncio
import json
import os
import websockets
WS_URL = "wss://api.deeptick.cc/ws/v1"
TOKEN = os.environ["DEEPTICK_API_TOKEN"]
TICK_TOPIC = "tick.CR.BTCUSDT"
async def main():
async with websockets.connect(
WS_URL,
additional_headers={"deeptoken": TOKEN},
ping_interval=None,
) as ws:
# 鉴权成功后先接收服务端 welcome
welcome = json.loads(await ws.recv())
print("DeepTick welcome:", welcome)
# 发送 Tick 订阅请求
request = {
"type": "subscribe",
"topics": [TICK_TOPIC],
"request_id": "btc-tick-sub-001",
}
await ws.send(json.dumps(request))
while True:
raw = await ws.recv()
message = json.loads(raw)
if message.get("type") == "ack":
print("订阅回执:", message)
continue
if message.get("topic") == TICK_TOPIC:
# 保留原始消息;字段映射见下一节
print("Tick message:", message.get("data"))
asyncio.run(main())
```
注意:订阅是否成功应以服务端 ack 中的 accepted / rejected 为准,而不是仅以客户端 send() 未报错作为判断。不同数据类型的 Topic 应分开订阅;不要把 tick 与 quote、depth 等类型混在同一条 subscribe 请求中。
**六、Tick 数据标准化:统一价格、数量与时间戳**
Tick 聚合前,首先要把上游消息转换成内部统一的数据结构。不同市场和数据类型的字段定义可能不同,因此建议将 DeepTick 原始消息与内部标准字段隔离:只在一个适配函数中完成字段映射,后续聚合器只处理标准化 Tick。
下面示例假设标准化后的 Tick 包含 timestamp\_ms、price 和 volume。请根据 DeepTick 当前逐笔成交消息的数据字典,将原始 data 字段映射到这三个字段;不要在未核对文档前假定原始字段名或成交量是单笔量还是累计量。
```
from dataclasses import dataclass
from typing import Any
@dataclass
class Tick:
timestamp_ms: int
price: float
volume: float
def normalize_deeptick_tick(raw: dict[str, Any]) -> Tick:
"""将 DeepTick 原始 Tick 字段映射为内部统一结构。
请按 ws-tick 文档中的真实字段名修改下方映射。
timestamp_ms 必须是 Unix 毫秒时间戳;
volume 必须是单笔成交量,而非累计成交量。
"""
data = raw.get("data", raw)
# TODO: 将以下键替换为 DeepTick ws-tick 文档的实际字段
timestamp_ms = int(data["YOUR_TIMESTAMP_FIELD"])
price = float(data["YOUR_PRICE_FIELD"])
volume = float(data["YOUR_VOLUME_FIELD"])
return Tick(
timestamp_ms=timestamp_ms,
price=price,
volume=volume,
)
```
**七、Python 实现:按任意时间窗口合成 OHLCV K 线**
在统一毫秒时间戳后,可以通过整除计算 Tick 所属时间桶。设周期长度为 period\_ms,则时间桶起点为 timestamp\_ms - timestamp\_ms % period\_ms。对同一时间桶内的 Tick,按时间顺序计算开盘价、最高价、最低价、收盘价和成交量。
下面的聚合器支持任意毫秒周期,例如 10 秒、30 秒、2 分钟或 45 分钟。示例按事件到达顺序更新当前 K 线;如果上游可能乱序推送,应在进入聚合器前增加缓冲与排序窗口,或依据服务端序列号处理。
```
from dataclasses import dataclass
from typing import Optional
@dataclass
class Candle:
start_ms: int
open: float
high: float
low: float
close: float
volume: float
class CandleAggregator:
def __init__(self, period_seconds: int):
if period_seconds <= 0:
raise ValueError("period_seconds must be positive")
self.period_ms = period_seconds * 1000
self.current: Optional[Candle] = None
def update(self, tick: Tick) -> Optional[Candle]:
bucket = (
tick.timestamp_ms
- tick.timestamp_ms % self.period_ms
)
# 第一笔 Tick:初始化当前 Bar
if self.current is None:
self.current = Candle(
start_ms=bucket,
open=tick.price,
high=tick.price,
low=tick.price,
close=tick.price,
volume=tick.volume,
)
return None
# 新时间桶:闭合旧 Bar,并开始新 Bar
if bucket > self.current.start_ms:
completed = self.current
self.current = Candle(
start_ms=bucket,
open=tick.price,
high=tick.price,
low=tick.price,
close=tick.price,
volume=tick.volume,
)
return completed
# 旧时间桶 Tick:生产环境需定义乱序数据策略
if bucket < self.current.start_ms:
return None
# 同一时间桶:更新 OHLCV
self.current.high = max(self.current.high, tick.price)
self.current.low = min(self.current.low, tick.price)
self.current.close = tick.price
self.current.volume += tick.volume
return None
def flush(self) -> Optional[Candle]:
"""进程退出或切换交易日时,可显式输出当前未闭合 Bar。"""
completed = self.current
self.current = None
return completed
# 示例:合成 30 秒 K 线
aggregator = CandleAggregator(period_seconds=30)
# 将 normalize_deeptick_tick() 的结果逐笔传入:
# completed = aggregator.update(tick)
# if completed:
# publish_candle(completed)
```
**八、将 WebSocket Tick 与 K 线聚合器连接起来**
完成字段适配和聚合器后,可以在 WebSocket 消息循环中把每条 Tick 转换为内部对象,再送入聚合器。以下代码展示整体连接方式。normalize\_deeptick\_tick() 中的字段名仍需按 DeepTick 实际消息结构配置。
```
async def stream_and_aggregate(period_seconds: int = 30):
aggregator = CandleAggregator(period_seconds)
async with websockets.connect(
WS_URL,
additional_headers={"deeptoken": TOKEN},
ping_interval=None,
) as ws:
welcome = json.loads(await ws.recv())
print("Connected:", welcome)
await ws.send(json.dumps({
"type": "subscribe",
"topics": [TICK_TOPIC],
"request_id": "btc-tick-aggregate-001",
}))
while True:
message = json.loads(await ws.recv())
if message.get("type") == "ack":
if message.get("rejected"):
raise RuntimeError(
f"Tick subscription rejected: {message['rejected']}"
)
print("Subscribed:", message.get("accepted"))
continue
if message.get("topic") != TICK_TOPIC:
continue
tick = normalize_deeptick_tick(message)
completed = aggregator.update(tick)
if completed is not None:
print("Completed candle:", completed)
# TODO: 写入数据库、发布消息或推送给策略模块
# asyncio.run(stream_and_aggregate(period_seconds=30))
```
**九、历史与实时数据如何配合?**
常见行情应用会先加载历史 K 线,再使用实时数据更新最后一根 Bar。若历史数据来自 REST Candles、实时数据来自 Tick,需要特别注意周期边界、时区、成交量口径和数据源聚合规则。
启动时通过 REST Candles 获取图表所需的历史 K 线,并记录最新一根已完成 K 线的时间。
启动 WebSocket Tick 订阅,完成鉴权并确认订阅回执。
将实时 Tick 标准化后送入聚合器,按时间桶持续更新当前 K 线。
当新时间桶开始时,闭合上一根 K 线并写入数据库或消息队列。
断线重连后,先恢复订阅,再检查缺失时间段;必要时通过 REST K 线接口补齐标准周期数据。若需要精确重建自定义周期,应使用相同粒度的历史 Tick 数据补算。
**十、生产环境的关键工程问题**
**10.1 时间戳与时区统一**
所有数据入口建议统一转换为 UTC Unix 毫秒时间戳。需要明确接口返回的是秒还是毫秒,避免周期边界计算出现数量级错误。
**10.2 成交量口径校验**
确认 Tick 的 volume 表示单笔成交量还是累计成交量。如果接收到的是累计成交量,不能直接对每条消息求和,应先计算相邻累计值的差分,并处理重置、回补和异常跳变。
**10.3 乱序、重复与迟到数据**
网络抖动可能导致消息乱序或重复。生产环境应制定迟到数据容忍窗口、去重键和重算策略。若直接丢弃旧时间桶 Tick,需要评估对成交量和 OHLC 的影响。
**10.4 空窗口填充**
没有成交的时间窗口是否补平 K 线,应由策略定义。若需要连续时间序列,可用上一根收盘价填充 open/high/low/close,并将 volume 设为 0;同时建议增加 is\_synthetic 标记,区分真实成交 Bar 与填充 Bar。
**10.5 心跳、重连与续传**
为 WebSocket 连接增加心跳、指数退避重连、订阅恢复和缺口检测。连接成功不代表订阅成功,必须检查 ack。短时断线可按 DeepTick 对应的心跳与续传文档处理;超出续传能力时,再通过历史接口或历史 Tick 数据修复。
**10.6 监控与资源管理**
建议监控连接状态、订阅成功率、Tick 吞吐量、消息延迟、队列积压、聚合耗时、数据缺口和异常字段比例。对内存队列设置上限,避免下游处理速度不足时持续堆积。
**十一、常见问题(FAQ)**
**Q1:DeepTick API 可以获取历史 K 线吗?**
可以通过 DeepTick REST Candles 接口按标的和周期查询历史 K 线,适用于图表初始化、研究和回测。具体参数和可用周期以官方接口文档为准。
**Q2:如何通过 DeepTick 获取实时逐笔成交?**
连接 DeepTick WebSocket 地址 wss://api.deeptick.cc/ws/v1,在握手请求中携带 deeptoken,收到 welcome 后发送 tick 类型 Topic 的 subscribe 请求,并检查服务端 ack。
**Q3:可以合成 30 秒或 45 分钟等非标准 K 线吗?**
可以。将 Tick 时间戳统一为毫秒后,按自定义周期计算时间桶,并在每个时间桶内累计 OHLCV,即可生成所需周期。
**Q4:为什么回测 K 线和实盘 K 线可能不一致?**
常见原因包括数据源不同、时间窗口边界不同、时间戳精度不同、成交量字段口径不同、乱序或重复 Tick 处理不同。应尽可能让历史与实时共用同一套标准化和聚合逻辑。
**Q5:WebSocket 收到订阅请求后没有行情怎么办?**
先确认已收到 welcome,再检查 ack 中 accepted 和 rejected;随后核对 Topic 的市场代码、标的格式、数据权限及该标的是否支持逐笔成交订阅。
**十二、总结:构建可复用的 DeepTick 量化行情数据管线**
通过 DeepTick REST Candles API 获取历史 K 线,并通过 WebSocket Tick API 接入实时逐笔成交,可以形成覆盖历史研究与实时处理的行情数据链路。对于需要非标准周期的量化策略,Tick 聚合方式能够把 K 线周期、时间窗口和聚合规则掌握在系统自身手中。
真正影响生产稳定性的,不只是接口连接本身,还包括字段标准化、时间戳精度、成交量语义、乱序处理、断线恢复、历史补偿和监控告警。建议先用小规模标的完成端到端验证,再逐步扩展到多交易对、多周期和分布式行情服务。
免责声明:本文仅用于 API 接入与行情数据处理技术交流,不构成投资建议。行情数据的使用、展示、存储和再分发应遵守 DeepTick 服务条款及相关市场的数据授权要求。