Binance API - Local Service Interface Specification

Haiyue

March 15, 2026

8min

Overview

本文档列出 TradingChart 组件使用到的全部 Binance API 接口，用于实现本地替换服务。服务需完全兼容 Binance 接口规范，客户端只需替换 BASE_URL。

Item	Details
REST Base URL	`https://api.binance.com`
WebSocket Base URL	`wss://stream.binance.com:9443`
本地替换目标	替换以上两个 Base URL，接口路径、参数、响应格式完全一致

REST API Endpoints

1. GET `/api/v3/klines` — K线/蜡烛图数据

获取指定交易对的历史K线数据，是整个图表组件最核心的接口。

使用位置

文件	用途
`composables/useBinance.ts:30`	初始加载 500 条K线
`composables/useBinance.ts:136`	向左滚动加载更早的历史数据
`composables/useCustomRange.ts:24`	自定义时间范围查询（分页）
`composables/useComparisonPanes.ts:268`	对比品种初始加载
`composables/useComparisonPanes.ts:547`	切换周期时重新拉取对比品种数据
`composables/useComparisonPanes.ts:578`	对比品种历史回溯
`TradingChart.vue:540`	分时模式（固定 `interval=1m`）

请求参数

参数	类型	必须	说明	示例
`symbol`	string	Yes	交易对名称，大写	`BTCUSDT`
`interval`	string	Yes	K线周期	`1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `6h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M`
`limit`	integer	No	返回条数，默认 500，最大 1000	`500` 或 `1000`
`startTime`	long	No	起始时间戳（毫秒）	`1704067200000`
`endTime`	long	No	结束时间戳（毫秒）	`1704153600000`

请求示例

# 基础查询
GET /api/v3/klines?symbol=BTCUSDT&interval=1d&limit=500

# 带 endTime 的历史回溯
GET /api/v3/klines?symbol=BTCUSDT&interval=4h&endTime=1704067199999&limit=500

# 带 startTime + endTime 的范围查询
GET /api/v3/klines?symbol=ETHUSDT&interval=1h&startTime=1704067200000&endTime=1704326400000&limit=1000

响应格式

返回二维数组，每个子数组代表一根K线：

[
  [
    1704067200000,    // [0]  Open time (毫秒时间戳)
    "42000.00",       // [1]  Open price (string)
    "43500.00",       // [2]  High price (string)
    "41800.00",       // [3]  Low price (string)
    "43200.00",       // [4]  Close price (string)
    "28000.00",       // [5]  Volume (string)
    1704153599999,    // [6]  Close time (毫秒时间戳)
    "1209600000.00",  // [7]  Quote asset volume (string)
    15234,            // [8]  Number of trades (integer)
    "14000.00",       // [9]  Taker buy base asset volume (string)
    "604800000.00",   // [10] Taker buy quote asset volume (string)
    "0"               // [11] Ignore (string)
  ]
]

客户端使用的字段

数组索引	字段名	使用方式
`[0]`	Open time	`formatTime(k[0], interval)` → 日内周期转为 Unix 秒，日线及以上转为 `YYYY-MM-DD` 字符串
`[1]`	Open	`parseFloat(k[1])`
`[2]`	High	`parseFloat(k[2])`
`[3]`	Low	`parseFloat(k[3])`
`[4]`	Close	`parseFloat(k[4])`
`[5]`	Volume	`parseFloat(k[5])`
`[9]`	Taker buy volume	`parseFloat(k[9])` — 用于买卖量指标（仅主图使用，对比品种不使用）

注意：对比品种（useComparisonPanes）不读取 [9]，只使用 [0]-[5]。

分页逻辑

自定义时间范围查询（useCustomRange）使用分页：

首次请求携带 startTime + endTime + limit=1000
若返回 1000 条，取最后一条的 [0]（Open time）+ 1 作为下一页的 startTime
循环直到返回条数 < 1000 或 startTime >= endTime

历史回溯（fetchMoreHistory）使用 endTime：

取当前最早一条数据的 time 转为毫秒时间戳
endTime = 该时间戳 - 1
请求 limit=500

排序

返回数据 必须按 Open time 升序排列。

2. GET `/api/v3/ticker/24hr` — 24小时行情统计

获取指定交易对的24小时滚动窗口行情统计，用于顶部 Ticker 栏展示。

使用位置

文件	用途
`composables/useBinance.ts:39`	每 10 秒轮询获取最新行情

请求参数

参数	类型	必须	说明	示例
`symbol`	string	Yes	交易对名称，大写	`BTCUSDT`

请求示例

GET /api/v3/ticker/24hr?symbol=BTCUSDT

响应格式

返回 JSON 对象：

{
  "symbol": "BTCUSDT",
  "priceChange": "1200.00",
  "priceChangePercent": "2.85",
  "weightedAvgPrice": "42500.00",
  "prevClosePrice": "42000.00",
  "lastPrice": "43200.00",
  "lastQty": "0.015",
  "bidPrice": "43199.00",
  "bidQty": "1.200",
  "askPrice": "43201.00",
  "askQty": "0.800",
  "openPrice": "42000.00",
  "highPrice": "43500.00",
  "lowPrice": "41800.00",
  "volume": "28000.00",
  "quoteVolume": "1192000000.00",
  "openTime": 1704067200000,
  "closeTime": 1704153599999,
  "firstId": 100000,
  "lastId": 200000,
  "count": 100000
}

客户端使用的字段

字段	使用方式
`lastPrice`	`parseFloat()` → 当前价格（大字体展示）
`priceChange`	`parseFloat()` → 24h 价格变动
`priceChangePercent`	`parseFloat().toFixed(2)` → 24h 变动百分比
`highPrice`	`parseFloat()` → 24h 最高价
`lowPrice`	`parseFloat()` → 24h 最低价
`volume`	`parseFloat()` → 24h 成交量

轮询频率：每 10 秒调用一次（setInterval(fetchBinanceTicker, 10000)）。

WebSocket Stream

3. K线数据流 — `{symbol}@kline_{interval}`

实时推送K线数据更新。

使用位置

文件	用途
`composables/useBinance.ts:61`	主图实时K线推送
`composables/useComparisonPanes.ts:471`	每个对比品种各建立一个独立连接

连接 URL

wss://stream.binance.com:9443/ws/{symbol}@kline_{interval}

参数	说明	示例
`{symbol}`	交易对名称，小写	`btcusdt`
`{interval}`	K线周期	`1m`, `4h`, `1d` 等

连接示例

wss://stream.binance.com:9443/ws/btcusdt@kline_1h
wss://stream.binance.com:9443/ws/ethusdt@kline_4h

分时模式下固定使用 1m 周期：ws/btcusdt@kline_1m

推送消息格式

{
  "e": "kline",
  "E": 1704067260000,
  "s": "BTCUSDT",
  "k": {
    "t": 1704067200000,
    "T": 1704070799999,
    "s": "BTCUSDT",
    "i": "1h",
    "f": 100000,
    "L": 100100,
    "o": "42000.00",
    "c": "42150.00",
    "h": "42200.00",
    "l": "41950.00",
    "v": "150.500",
    "n": 101,
    "x": false,
    "q": "6330025.00",
    "V": "75.250",
    "Q": "3165012.50",
    "B": "0"
  }
}

客户端使用的字段

字段路径	说明	使用方式
`e`	事件类型	过滤 `msg.e === 'kline'`
`k.t`	K线开盘时间（毫秒）	`formatTime(k.t, interval)`
`k.o`	开盘价	`parseFloat(k.o)`
`k.h`	最高价	`parseFloat(k.h)`
`k.l`	最低价	`parseFloat(k.l)`
`k.c`	收盘价	`parseFloat(k.c)`
`k.v`	成交量	`parseFloat(k.v)`
`k.V`	买方成交量	`parseFloat(k.V)` — 仅主图使用
`k.x`	K线是否已收盘	布尔值，`true` 时触发指标全量刷新

对比品种 不使用 k.V（买方成交量）。

连接管理

策略	详情
节流	按 `refreshInterval`（默认 2000ms）频率应用 WS 推送到图表
重连	断开后自动重连，最多 5 次，间隔 3 秒
断开时机	切换交易对、切换周期、切换分时模式、自定义范围模式、组件卸载

完整调用关系图

TradingChart.vue
├── useBinance
│   ├── fetchBinanceKlines()        → GET /api/v3/klines (初始 + 历史回溯)
│   ├── fetchBinanceTicker()        → GET /api/v3/ticker/24hr (轮询)
│   └── connectKlineWS()            → WSS kline stream (主图)
├── useCustomRange
│   └── fetchKlinesForRange()       → GET /api/v3/klines (分页范围查询)
├── useComparisonPanes
│   ├── addComparison()             → GET /api/v3/klines (对比品种)
│   ├── refetchAll()                → GET /api/v3/klines (重新拉取)
│   ├── fetchAllHistory()           → GET /api/v3/klines (对比品种历史回溯)
│   └── connectItemWS()             → WSS kline stream (每个对比品种)
└── toggleTimeSharingMode()         → GET /api/v3/klines (分时，interval=1m)

本地服务实现要点

必须实现

GET /api/v3/klines — 完整支持 symbol, interval, limit, startTime, endTime 五个参数的任意组合
GET /api/v3/ticker/24hr — 返回至少包含上述 6 个使用字段的 JSON 对象
WSS /ws/{symbol}@kline_{interval} — 实时推送 kline 事件，格式与 Binance 一致

数据类型注意

REST /api/v3/klines 返回的价格/成交量均为 string 类型（客户端会 parseFloat）
REST /api/v3/ticker/24hr 返回的价格/成交量均为 string 类型
WebSocket 推送的 k.o, k.h, k.l, k.c, k.v, k.V 均为 string 类型
时间戳均为 毫秒级 long

客户端替换

只需修改以下常量即可切换到本地服务：

// REST
const REST_BASE = 'https://api.binance.com'   // → 'http://localhost:8080'

// WebSocket
const WS_BASE = 'wss://stream.binance.com:9443'  // → 'ws://localhost:8080'

Binance API - Local Service Interface Specification

P Info

Project Cards Demo

Trading Chart Demo

Basic Skills

Binance API - Local Service Interface Specification

P Info

Project Cards Demo

Trading Chart Demo

Basic Skills

Binance API - Local Service Interface Specification

Overview

REST API Endpoints

1. GET `/api/v3/klines` — K线/蜡烛图数据

请求参数

请求示例

响应格式

客户端使用的字段

分页逻辑

排序

2. GET `/api/v3/ticker/24hr` — 24小时行情统计

请求参数

请求示例

响应格式

客户端使用的字段

WebSocket Stream

3. K线数据流 — `{symbol}@kline_{interval}`

连接 URL

连接示例

推送消息格式

客户端使用的字段

连接管理

完整调用关系图

本地服务实现要点

必须实现

数据类型注意

客户端替换

Overview

REST API Endpoints

1. GET /api/v3/klines — K线/蜡烛图数据

请求参数

请求示例

响应格式

客户端使用的字段

分页逻辑

排序

2. GET /api/v3/ticker/24hr — 24小时行情统计

请求参数

请求示例

响应格式

客户端使用的字段

WebSocket Stream

3. K线数据流 — {symbol}@kline_{interval}

连接 URL

连接示例

推送消息格式

客户端使用的字段

连接管理

完整调用关系图

本地服务实现要点

必须实现

数据类型注意

客户端替换

1. GET `/api/v3/klines` — K线/蜡烛图数据

2. GET `/api/v3/ticker/24hr` — 24小时行情统计

3. K线数据流 — `{symbol}@kline_{interval}`