K 线数据源接口文档

重要考虑：此接口建议考虑采用 WebSocket 的方式接入，以实现实时数据推送，减少 HTTP 轮询带来的性能开销和延迟。当前版本使用 HTTP 轮询方式，后续可优化为 WebSocket 实时订阅。

重要变更：接口参数已从 symbol（交易对符号）改为 pool（池子地址）。请使用 Aptos 链上的完整池子地址作为参数，格式为 64 个字符的十六进制地址（如 0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab）。

接口概述

本文档提供 K 线图表所需的数据源接口规范。前期版本使用 HTTP 轮询方式获取数据，通过定期调用历史 K 线数据接口来更新图表。搜索标的和 WebSocket 实时订阅功能作为后续优化项。

1. 获取历史 K 线数据接口（核心接口）

参考文档： https://klinecharts.com/guide/data-source

接口信息

接口路径: /api/kline/history
请求方法: GET
接口描述: 获取指定池子在指定时间周期内的历史 K 线数据。前期通过轮询此接口实现数据更新

请求参数

Query 参数

参数名	类型	必填	说明
pool	string	是	池子地址（Pool ID），Aptos 链上的完整地址，如 "0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab"
period	string	是	时间周期，如 "1m"、"5m"、"15m"、"1h"、"4h"、"1D"、"1W"、"1M"
from	number	是	起始时间戳（毫秒），Unix 时间戳，如 `1704067200000`
to	number	是	结束时间戳（毫秒），Unix 时间戳，如 `1704153600000`

请求示例

bash

GET /api/kline/history?pool=0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab&period=1D&from=1704067200000&to=1704153600000

响应数据结构

响应格式

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "timestamp": 1704067200000,
      "open": "42000.50",
      "high": "42500.00",
      "low": "41800.00",
      "close": "42300.75",
      "volume": "1234567.89",
      "turnover": "52123456789.12"
    }
  ]
}

响应字段说明

data 数组项字段

字段名	类型	必填	说明
timestamp	number	是	时间戳（毫秒），Unix 时间戳
open	string	是	开盘价，字符串格式的数字
high	string	是	最高价，字符串格式的数字
low	string	是	最低价，字符串格式的数字
close	string	是	收盘价，字符串格式的数字
volume	string	否	成交量，字符串格式的数字
turnover	string	否	成交额，字符串格式的数字（某些指标需要）

响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "timestamp": 1704067200000,
      "open": "42000.50",
      "high": "42500.00",
      "low": "41800.00",
      "close": "42300.75",
      "volume": "1234567.89",
      "turnover": "52123456789.12"
    },
    {
      "timestamp": 1704153600000,
      "open": "42300.75",
      "high": "42800.00",
      "low": "42100.00",
      "close": "42650.25",
      "volume": "1456789.12",
      "turnover": "62123456789.45"
    }
  ]
}

轮询说明

前期实现方式：前端通过定时器定期调用此接口获取最新数据，实现数据更新。

轮询频率建议：根据时间周期动态调整
- 1m、5m 周期：每 5-10 秒轮询一次
- 15m、30m、1h 周期：每 30-60 秒轮询一次
- 4h、1D 周期：每 1-5 分钟轮询一次
- 1W、1M 周期：每 5-10 分钟轮询一次
轮询时只需获取最新的几根 K 线数据（如最近 10-20 根），避免重复获取全部历史数据
建议在 from 参数中传入上次获取的最后一条数据的时间戳，只获取新数据

注意事项

pool、period、from、to 参数均为必填项
period 支持的时间周期：1m、5m、15m、30m、1h、4h、1D、1W、1M
from 和 to 必须使用毫秒级 Unix 时间戳（13 位数字）
返回的数据必须按时间从早到晚排序（timestamp 升序）
价格和成交量建议使用字符串格式，避免 JavaScript 数字精度问题
如果请求的时间范围内没有数据，返回空数组 []
返回的数据应在 from 到 to 的时间范围内，超出范围的数据会被前端过滤
volume 和 turnover 为可选字段，但建议提供以提高图表功能完整性
轮询时建议支持增量查询：如果传入的 from 时间戳与已有数据的时间戳有重叠，后端应只返回新数据部分

数据格式说明

K 线数据字段说明

字段名	类型	必填	说明
timestamp	number	是	时间戳（毫秒），Unix 时间戳，13 位数字，如 `1704067200000`
open	string	是	开盘价，字符串格式的数字，建议保留 2-8 位小数
high	string	是	最高价，字符串格式的数字，建议保留 2-8 位小数
low	string	是	最低价，字符串格式的数字，建议保留 2-8 位小数
close	string	是	收盘价，字符串格式的数字，建议保留 2-8 位小数
volume	string	否	成交量，字符串格式的数字
turnover	string	否	成交额，字符串格式的数字

时间周期说明

period 值	说明	示例时间间隔
1m	1 分钟	每分钟一根 K 线
5m	5 分钟	每 5 分钟一根 K 线
15m	15 分钟	每 15 分钟一根 K 线
30m	30 分钟	每 30 分钟一根 K 线
1h	1 小时	每小时一根 K 线
4h	4 小时	每 4 小时一根 K 线
1D	1 天	每天一根 K 线
1W	1 周	每周一根 K 线
1M	1 月	每月一根 K 线

通用注意事项

所有接口的响应格式遵循标准：code 为 0 表示成功，msg 为状态消息
时间戳统一使用毫秒级 Unix 时间戳（13 位数字）
价格和成交量建议使用字符串格式传递，避免 JavaScript 数字精度问题
历史数据必须按时间从早到晚排序（timestamp 升序）
所有接口都应包含适当的错误处理和错误响应格式
建议对接口进行限流和缓存优化，提高性能
前期版本通过 HTTP 轮询实现数据更新，后续将优化为 WebSocket 实时推送

后续优化项

以下功能作为后续优化项，前期版本暂不实现。

2. 搜索标的接口（后续优化）

接口信息

接口路径: /api/kline/symbols/search
请求方法: GET
接口描述: 模糊搜索标的（交易对），用于 K 线图表选择标的
状态: 后续优化项，前期版本暂不实现

请求参数

Query 参数

参数名	类型	必填	说明
q	string	否	搜索关键字，用于模糊匹配标的名称或代码

请求示例

bash

GET /api/kline/symbols/search?q=BTC

响应数据结构

响应格式

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "exchange": "CRYPTO",
      "market": "crypto",
      "name": "Bitcoin",
      "shortName": "BTC",
      "ticker": "BTC",
      "priceCurrency": "usd",
      "type": "CRYPTO"
    }
  ]
}

响应字段说明

data 数组项字段

字段名	类型	必填	说明
exchange	string	是	交易所名称，如 "CRYPTO"
market	string	是	市场类型，如 "crypto"
name	string	是	标的完整名称，如 "Bitcoin"
shortName	string	是	标的简称，如 "BTC"
ticker	string	是	标的代码，如 "BTC"
priceCurrency	string	是	计价货币，如 "usd"
type	string	是	标的类型，如 "CRYPTO"

响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "exchange": "CRYPTO",
      "market": "crypto",
      "name": "Bitcoin",
      "shortName": "BTC",
      "ticker": "BTC",
      "priceCurrency": "usd",
      "type": "CRYPTO"
    },
    {
      "exchange": "CRYPTO",
      "market": "crypto",
      "name": "Ethereum",
      "shortName": "ETH",
      "ticker": "ETH",
      "priceCurrency": "usd",
      "type": "CRYPTO"
    }
  ]
}

注意事项

q 参数为可选，当为空或不传时，可返回热门标的列表或空数组
搜索应支持模糊匹配标的名称、简称和代码
响应格式遵循标准：code 为 0 表示成功，msg 为状态消息
返回的数组应按相关度或热度排序

3. 实时数据订阅接口（WebSocket）（后续优化）

接口信息

接口路径: wss://api.example.com/kline/realtime
协议: WebSocket
接口描述: 订阅指定池子在指定时间周期下的实时 K 线数据更新
状态: 后续优化项，前期版本使用 HTTP 轮询替代

连接参数

Query 参数

参数名	类型	必填	说明
pool	string	是	池子地址（Pool ID），Aptos 链上的完整地址，如 "0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab"
period	string	是	时间周期，如 "1m"、"5m"、"15m"、"1h"、"4h"、"1D"、"1W"、"1M"

连接示例

javascript

const ws = new WebSocket('wss://api.example.com/kline/realtime?pool=0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab&period=1D')

消息格式

接收消息（服务器推送的 K 线数据）

json

{
  "timestamp": 1704067200000,
  "open": "42000.50",
  "high": "42500.00",
  "low": "41800.00",
  "close": "42300.75",
  "volume": "1234567.89",
  "turnover": "52123456789.12"
}

消息字段说明

字段名	类型	必填	说明
timestamp	number	是	时间戳（毫秒），Unix 时间戳
open	string	是	开盘价，字符串格式的数字
high	string	是	最高价，字符串格式的数字
low	string	是	最低价，字符串格式的数字
close	string	是	收盘价，字符串格式的数字
volume	string	否	成交量，字符串格式的数字
turnover	string	否	成交额，字符串格式的数字

连接流程示例

javascript

// 1. 建立 WebSocket 连接
const ws = new WebSocket('wss://api.example.com/kline/realtime?pool=0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab&period=1D')

// 2. 连接成功
ws.onopen = () => {
  console.log('WebSocket 连接已建立')
}

// 3. 接收实时数据
ws.onmessage = (event) => {
  const klineData = JSON.parse(event.data)
  // klineData 格式与历史数据接口返回的单个 K 线数据格式相同
  console.log('收到实时 K 线数据:', klineData)
}

// 4. 处理错误
ws.onerror = (error) => {
  console.error('WebSocket 错误:', error)
}

// 5. 连接关闭
ws.onclose = () => {
  console.log('WebSocket 连接已关闭')
  // 可以在这里实现重连逻辑
}

// 6. 关闭连接（取消订阅）
ws.close()

注意事项

WebSocket 连接地址中的 pool 和 period 参数为必填项
服务器应定期推送最新的 K 线数据更新（建议每秒或每分钟推送一次，取决于周期）
推送的数据格式与历史数据接口返回的单个 K 线数据格式相同
当池子或周期改变时，客户端会关闭旧连接并建立新连接
服务器应处理连接断开和重连的情况
建议实现心跳机制，保持连接活跃
如果连接失败，客户端可能会降级为轮询方式获取数据
价格和成交量建议使用字符串格式，避免 JavaScript 数字精度问题

K 线数据源接口文档 ​

接口概述 ​

1. 获取历史 K 线数据接口（核心接口） ​

参考文档 ： https://klinecharts.com/guide/data-source ​

接口信息 ​

请求参数 ​

Query 参数 ​

请求示例 ​

响应数据结构 ​

响应格式 ​

响应字段说明 ​

data 数组项字段 ​

响应示例 ​

轮询说明 ​

注意事项 ​

数据格式说明 ​

K 线数据字段说明 ​

时间周期说明 ​

通用注意事项 ​

后续优化项 ​

2. 搜索标的接口（后续优化） ​

接口信息 ​

请求参数 ​

Query 参数 ​

请求示例 ​

响应数据结构 ​

响应格式 ​

响应字段说明 ​

data 数组项字段 ​

响应示例 ​

注意事项 ​

3. 实时数据订阅接口（WebSocket）（后续优化） ​

接口信息 ​

连接参数 ​

Query 参数 ​

连接示例 ​

消息格式 ​

接收消息（服务器推送的 K 线数据） ​

消息字段说明 ​

连接流程示例 ​

注意事项 ​

K 线数据源接口文档

接口概述

1. 获取历史 K 线数据接口（核心接口）

参考文档： https://klinecharts.com/guide/data-source

接口信息

请求参数

Query 参数

请求示例

响应数据结构

响应格式

响应字段说明

data 数组项字段

响应示例

轮询说明

注意事项

数据格式说明

K 线数据字段说明

时间周期说明

通用注意事项

后续优化项

2. 搜索标的接口（后续优化）

接口信息

请求参数

Query 参数

请求示例

响应数据结构

响应格式

响应字段说明

data 数组项字段

响应示例

注意事项

3. 实时数据订阅接口（WebSocket）（后续优化）

接口信息

连接参数

Query 参数

连接示例

消息格式

接收消息（服务器推送的 K 线数据）

消息字段说明

连接流程示例

注意事项