K线数据 (Klines / Candlesticks)

获取历史 K 线（蜡烛图）数据。

获取历史K线

接口信息

• Method: GET
• Path: /api/v1/markets/:symbol/candles
• Authentication: 不需身份验证

路径参数

参数	类型	必须	描述
symbol	string	是	交易对名称（如 BTCUSDT）

查询参数

参数	类型	必须	描述
period	string	是	时间周期（1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M）
limit	number	否	返回数量（默认 300，最大 10000）
from	number	否	开始时间（Unix 时间戳，秒）
to	number	否	结束时间（Unix 时间戳，秒）

时间周期说明

周期	描述
1m	1分钟
5m	5分钟
15m	15分钟
1h	1小时
4h	4小时
1d	1天
1w	1周
1M	1月

响应示例

{
  "symbol": "BTCUSDT",
  "period": "5m",
  "candles": [
    {
      "time": 1704067200,
      "open": "65000.00",
      "high": "65500.00",
      "low": "64900.00",
      "close": "65200.00",
      "volume": "100.5",
      "quote_volume": "6532500.00",
      "trade_count": 1250
    },
    {
      "time": 1704066900,
      "open": "64800.00",
      "high": "65100.00",
      "low": "64750.00",
      "close": "65000.00",
      "volume": "95.3",
      "quote_volume": "6185400.00",
      "trade_count": 1180
    }
  ]
}

响应字段说明

字段	类型	描述
symbol	string	交易对名称
period	string	时间周期
candles	array	K线数据列表

Candle 对象字段

字段	类型	描述
time	number	K线开始时间（Unix 时间戳，秒）
open	string	开盘价
high	string	最高价
low	string	最低价
close	string	收盘价
volume	string	成交量（基础资产）
quote_volume	string	成交额（报价资产）
trade_count	number	成交笔数

---

获取最新K线

接口信息

• Method: GET
• Path: /api/v1/markets/:symbol/candles/latest
• Authentication: 不需身份验证

路径参数

参数	类型	必须	描述
symbol	string	是	交易对名称（如 BTCUSDT）

查询参数

参数	类型	必须	描述
period	string	是	时间周期（1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M）

响应示例

{
  "symbol": "BTCUSDT",
  "period": "5m",
  "candle": {
    "time": 1704067200,
    "open": "65000.00",
    "high": "65500.00",
    "low": "64900.00",
    "close": "65200.00",
    "volume": "100.5",
    "quote_volume": "6532500.00",
    "trade_count": 1250
  },
  "is_final": false
}

响应字段说明

字段	类型	描述
symbol	string	交易对名称
period	string	时间周期
candle	object	K线数据
is_final	boolean	是否已完成（false 表示当前周期未结束，数据可能变化）

说明

• K线数据来源于系统内部的 kline service
• 数据存储在 TimescaleDB 中，支持高效的时间序列查询
• 所有价格和数量均为字符串格式以保证精度
• is_final 为 false 时表示当前K线周期未结束，数据会实时更新
• 历史K线数据按时间倒序排列（最新的在前）

错误响应

HTTP 状态码	错误码	描述
400	ERR_INVALID_PERIOD	无效的时间周期
400	ERR_INVALID_TIME_RANGE	无效的时间范围（from > to）
404	ERR_NO_DATA	没有可用的K线数据