本文档描述了市场数据服务的 RESTful API 和 WebSocket 协议，用于获取历史 K 线数据、当前价格、实时报价以及订阅实时市场数据。数据返回格式基于 Kline 类定义，适用于金融市场数据查询（如贵金属、能源等）。

基础 URL (HTTP): http://llbuildding.icu/api/v1/market WebSocket URL: ws://llbuildding.icu/ws

数据格式说明

Kline 对象

K 线数据通过 Kline 类序列化为 JSON，字段名由 @JSONField 注解定义：

json

{
  "T": Long,      // 时间戳（毫秒）
  "o": Double,    // 开盘价
  "h": Double,    // 最高价
  "l": Double,    // 最低价
  "c": Double,    // 收盘价
  "v": Double,    // 交易量
  "t": Double,    // 成交额（默认 0.0）
  "p": String,    // K 线周期（如 "1min", "1h"）
  "s": String     // 交易对符号（如 "GOLD"）
}

历史 K 线数据 (HTTP)

  1. 端点信息

  2. URL: http://llbuildding.icu/api/v1/market/kline

  3. 方法: POST
  4. Content-Type: application/json
  5. 协议: HTTP/1.1
  6. 描述: 查询指定币种的历史 K 线数据，支持多种周期和数据量限制。
  7. 请求格式

请求体为 JSON 格式，基于 KlineParamVO，包含以下字段：

json

{
  "symbol": "string",
  "interval": "string",
  "limit": integer
}

参数说明

参数 类型 是否必填 描述 示例值
symbol String 是 币种标识，代表交易对或资产。见 SYMBOL 编码列表 (#支持的币种) "GOLD"
interval String 是 K 线周期，表示数据时间间隔。见 支持的周期 (#支持的周期) "1min"
limit Integer 否 返回的 K 线数据条数，默认 1000，最大 1000（服务器强制限制） 1000

支持的周期

  • 1min (1 分钟)
  • 3min (3 分钟)
  • 5min (5 分钟)
  • 15min (15 分钟)
  • 30min (30 分钟)
  • 1hours (1 小时)
  • 2hours (2 小时)
  • 4hours (4 小时)
  • 6hours (6 小时)
  • 8hours (8 小时)
  • 12hours (12 小时)
  • 1day (1 天)
  • 3day (3 天)
  • 1week (1 周)
  • 1month (1 个月)

支持的币种

根据提供的 SYMBOL 编码列表：

币种标识 描述
GOLD 金 (Gold)
Silver 银 (Silver)
COPPER 铜 (Copper)
NGAS 天然气 (Natural Gas)
USOIL 美国原油 (US Oil)
UKOIL 英国原油 (UK Oil)

  1. 注意事项

  2. 默认 limit: 未提供 limit 时，默认返回 1000 条数据。

  3. 查询最近一条数据: 为兼容旧版系统，查询最新一条 K 线数据需设置 interval="1day" 和 limit=1。

  4. 示例：查询最新金 (GOLD) 的 K 线数据：

    json

    json { "symbol": "GOLD", "interval": "1day", "limit": 1 }

  5. 数据顺序: 返回的 K 线数据按时间升序排列（从早到晚）。

  6. 错误处理: 无效的 symbol 或 interval 将返回错误响应（如 400 Bad Request）。

  7. 请求示例

示例 1：查询金 (GOLD) 的最近 1000 条 1 分钟 K 线数据

bash

curl --location 'http://llbuildding.icu/api/v1/market/kline' \
--header 'Content-Type: application/json' \
--data '{"symbol":"GOLD","interval":"1min","limit":1000}'

示例 2：查询美国原油 (USOIL) 的最近一条 K 线数据

bash

curl --location 'http://llbuildding.icu/api/v1/market/kline' \
--header 'Content-Type: application/json' \
--data '{"symbol":"USOIL","interval":"1day","limit":1}'
  1. 响应格式

响应为 JSON 格式，结构如下：

json

{
  "code": Integer,
  "msg": String,
  "data": {
    "historyKline": [
      {
        "T": Long,    // 时间戳（毫秒）
        "o": Double,  // 开盘价
        "h": Double,  // 最高价
        "l": Double,  // 最低价
        "c": Double,  // 收盘价
        "v": Double,  // 交易量
        "t": Double,  // 成交额（默认 0.0）
        "p": String,  // K 线周期
        "s": String   // 交易对符号
      }
    ]
  }
}

成功示例

json

{
  "code": 200,
  "msg": "K线数据获取成功",
  "data": {
    "historyKline": [
      {
        "T": 1697059200000,
        "o": 30000.0,
        "h": 30100.0,
        "l": 29950.0,
        "c": 30050.0,
        "v": 100.5,
        "t": 0.0,
        "p": "1min",
        "s": "GOLD"
      }
    ]
  }
}

空数据示例

json

{
  "code": 200,
  "msg": "K线数据获取成功但为空",
  "data": {
    "historyKline": []
  }
}

错误响应示例

json

{
  "code": 400,
  "msg": "无效的 symbol 或 interval",
  "data": null
}

  1. 使用注意事项

  2. 参数验证: 确保 symbol 和 interval 使用支持的值。

  3. 数据量限制: limit 最大为 1000。
  4. 兼容性: 查询最新一条数据时，必须使用 interval="1day" 和 limit=1。
  5. 频率控制: 避免高频请求，建议根据业务需求设置合理间隔。
  6. 时区: 时间戳为 UTC 时间，客户端需自行转换为本地时区。

当前价格 (HTTP)

  1. 端点信息

  2. URL: http://llbuildding.icu/api/v1/market/nowPrice/{symbol}

  3. 方法: GET
  4. 描述: 获取指定币种的当前价格。
  5. 路径参数
参数 类型 是否必填 描述 示例值
symbol String 是 币种标识，见 支持的币种 (#支持的币种) "GOLD"
  1. 响应格式

json

{
  "code": Integer,
  "msg": String,
  "data": {
    "price": String
  }
}

成功示例

json

{
  "code": 200,
  "msg": "价格获取成功",
  "data": {
    "price": "30000.0"
  }
}

错误示例

json

{
  "code": 500,
  "msg": "未找到符号 GOLD 的价格数据",
  "data": null
}
  1. 请求示例

bash

curl -X GET http://llbuildding.icu/api/v1/market/nowPrice/GOLD

实时报价 (HTTP)

  1. 端点信息

  2. URL: http://llbuildding.icu/api/v1/market/realtime/Quotes/{symbol}

  3. 方法: GET
  4. 描述: 获取指定币种的最新 K 线数据（实时报价）。
  5. 路径参数
参数 类型 是否必填 描述 示例值
symbol String 是 币种标识，见 支持的币种 (#支持的币种) "GOLD"
  1. 响应格式

json

{
  "code": Integer,
  "msg": String,
  "data": {
    "T": Long,
    "o": Double,
    "h": Double,
    "l": Double,
    "c": Double,
    "v": Double,
    "t": Double,
    "p": String,
    "s": String
  }
}

成功示例

json

{
  "code": 200,
  "msg": "实时报价获取成功",
  "data": {
    "T": 1697059200000,
    "o": 30000.0,
    "h": 30100.0,
    "l": 29950.0,
    "c": 30050.0,
    "v": 100.5,
    "t": 0.0,
    "p": "1min",
    "s": "GOLD"
  }
}

错误示例

json

{
  "code": 500,
  "msg": "未找到符号 GOLD 的实时报价",
  "data": null
}
  1. 请求示例

bash

curl -X GET http://llbuildding.icu/api/v1/market/realtime/Quotes/GOLD

附件