您现在的位置是：首页 > 解答

Upbit WebSocket实时行情获取指南：API应用详解

时间：2025-02-26 07:04:41 分类：解答浏览：5

Upbit WebSocket 实时行情数据获取指南

Upbit作为韩国领先的加密货币交易所，提供了强大的API接口，方便开发者获取实时行情数据并进行自动化交易。其中，WebSocket API以其低延迟和高效率的特性，成为了实时数据获取的首选方案。本文将详细介绍如何使用Upbit WebSocket API获取实时行情数据，并提供一些实用技巧。

1. WebSocket API 概述

Upbit WebSocket API 允许客户端与交易所建立一个 双向、实时的通信管道 ，从而实现数据的即时传输。传统的HTTP请求-响应模式需要客户端频繁轮询服务器以获取最新信息，而WebSocket则通过建立持久连接，使交易所能够主动推送最新的行情数据，无需客户端不断发送请求。这种 推送模式 极大地降低了数据延迟，显著提高了信息传递效率，并有效减少了服务器负载和客户端资源消耗。

WebSocket API 支持多种关键数据类型的实时订阅，包括：

Ticker (当前价/行情快照): 提供最近成交的价格、成交量、最高价、最低价等关键行情指标，帮助用户快速了解市场动态。Ticker数据是进行高频交易和算法交易的基础。
Trade (成交): 实时推送每一笔成功的交易信息，包含成交价格、成交数量、成交时间等。通过分析成交数据，用户可以了解市场供需关系和交易活跃度。
Orderbook (订单簿): 提供实时的买单和卖单挂单信息，深度展示市场买卖力量的分布情况。用户可以通过观察订单簿的变化，预测价格走势和支撑阻力位。订单簿通常分为L1（最佳买卖盘）和L2（深度订单簿）两种，L2提供更详细的挂单信息。

除了上述核心数据类型，Upbit WebSocket API 可能还支持其他数据流，例如：

成交统计数据： 如分时成交量、大单成交等，用于分析市场情绪和资金流向。
指数数据： 跟踪特定数字资产组合的表现，反映市场整体趋势。
账户信息： 如余额、持仓等，方便用户监控自己的交易状态。

通过灵活订阅所需的数据流，用户可以构建各种实时交易应用，例如：自动化交易机器人、实时行情监控系统、以及风险管理工具。选择合适的编程语言（如Python、JavaScript）和WebSocket客户端库可以简化开发过程。

2. 连接 WebSocket 服务器

你需要建立与 Upbit WebSocket 服务器的稳定连接。官方服务器地址为 wss://api.upbit.com/websocket/v1 。可以使用任何支持 WebSocket 协议的编程语言和相应的库来建立连接，例如 Python、JavaScript、Go 等。选择合适的库取决于你的项目需求和技术栈。

在建立连接之前，需要理解 Upbit WebSocket API 的特性。它是一个基于事件驱动的实时数据流服务，通过发送订阅消息来接收特定类型的数据。所有的数据交换都以 JSON 格式进行，因此你需要能够解析和生成 JSON 数据的库。

以下是一个使用 Python 和 websockets 库的示例 (你需要事先安装 websockets 库: pip install websockets ):

websockets 是一个流行的 Python 库，专门用于处理 WebSocket 连接。它提供了异步的 API，非常适合构建高性能的实时应用。下面的代码展示了如何连接到 Upbit WebSocket API, 发送订阅请求，并接收实时数据。

asyncio 模块是 Python 的异步 IO 框架，允许你编写并发代码。

import asyncio
import websockets
import

async def connect_to_upbit():
uri = "wss://api.upbit.com/websocket/v1"
async with websockets.connect(uri) as websocket:
print("Connected to Upbit WebSocket API")

# 发送订阅消息
subscribe_message = [
  {
    "ticket": "UNIQUE_TICKET_1", # 替换为一个唯一的字符串，用于区分不同的订阅
    "type": "ticker",          # 订阅当前价信息
    "codes": ["KRW-BTC", "KRW-ETH"]  # 订阅 BTC 和 ETH 的当前价，可以添加更多交易对
  },
  {
    "ticket": "UNIQUE_TICKET_2", # 替换为一个唯一的字符串
    "type": "trade",           # 订阅成交信息
    "codes": ["KRW-BTC", "KRW-ETH"]  # 订阅 BTC 和 ETH 的成交信息，可以添加更多交易对
  },
  {
     "ticket": "UNIQUE_TICKET_3",
     "type": "orderbook",
     "codes": ["KRW-BTC", "KRW-ETH"]   # 订阅 BTC  和 ETH  的订单簿快照信息
   }
]
await websocket.send(.dumps(subscribe_message))

# 接收数据
try:
    while True:
        data = await websocket.recv()
        data_ = .loads(data)
        print(data_)
except websockets.ConnectionClosed:
    print("Connection closed.")

这段代码首先定义了一个 `subscribe_message` 变量，它是一个包含订阅信息的列表。每个订阅信息都需要一个唯一的 `ticket`，`type` 指定了订阅的数据类型 (例如 `ticker` 表示当前价，`trade` 表示成交信息)，`codes` 指定了订阅的交易对。可以根据需要订阅更多的数据类型，例如订单簿信息(`orderbook`)。

使用 `.dumps()` 将 Python 对象转换为 JSON 字符串，然后通过 WebSocket 连接发送给 Upbit 服务器。

在 `try` 块中，代码循环接收来自 Upbit 服务器的数据。`websocket.recv()` 方法会阻塞，直到收到新的数据。收到数据后，使用 `.loads()` 将 JSON 字符串转换为 Python 对象，然后打印出来。

如果 WebSocket 连接关闭，会抛出 `websockets.ConnectionClosed` 异常，代码会捕获这个异常并打印 "Connection closed."。

if __name__ == "__main__":
asyncio.get_event_loop().run_until_complete(connect_to_upbit())

以上代码使用 Python 的 `asyncio` 库来运行异步的 WebSocket 连接。`asyncio.get_event_loop()` 获取事件循环，`run_until_complete()` 运行指定的协程直到完成。

请注意替换 `UNIQUE_TICKET` 为唯一的字符串，例如 `"my_unique_ticket_123"`，确保每个订阅都有唯一的标识。实际应用中，需要处理更复杂的错误情况，例如网络错误、API 限制等。

建议仔细阅读 Upbit WebSocket API 的官方文档，了解所有可用的数据类型和参数。可以通过调整订阅消息来获取你需要的实时数据。

代码解释:

websockets.connect(uri) : 此函数用于建立与 Upbit WebSocket 服务器的安全连接。 uri 参数指定了 WebSocket 服务器的地址，通常以 wss:// 开头，表示加密的 WebSocket 连接。连接建立后，你可以通过此连接实时接收来自 Upbit 服务器的市场数据。
subscribe_message : 这是一个包含订阅信息的 JSON 数组，用于告知 Upbit 服务器你希望接收哪些市场的数据。该数组中通常包含一个或多个订阅对象。
- ticket : 一个唯一的字符串，用于标识你的订阅请求。强烈建议使用 UUID (通用唯一识别码) 等方法生成全局唯一的标识符，以确保你的订阅不会与其他用户的订阅冲突。这有助于 Upbit 服务器区分不同的订阅请求并正确地路由数据。例如： "ticket": "a1b2c3d4-e5f6-7788-9900-aabbccddeeff" 。
- type : 定义了你希望订阅的数据类型。常见的类型包括 "ticker" (实时行情，包含最新成交价、涨跌幅等), "trade" (成交历史，包含每笔成交的价格、数量和时间), 以及 "orderbook" (订单簿，包含买单和卖单的价格和数量)。根据你的需求选择合适的类型。 Upbit 还可能提供其他数据类型，请参考 Upbit API 文档获取完整列表。
- codes : 一个字符串数组，指定你希望订阅的具体市场代码。每个市场代码代表一个交易对，例如 "KRW-BTC" 代表韩元计价的比特币市场。你可以在 Upbit 网站或者 API 文档中找到完整的市场代码列表。你可以订阅多个市场，例如 ["KRW-BTC", "KRW-ETH"] 可以同时订阅比特币和以太坊的行情。
websocket.send(.dumps(subscribe_message)) : 该函数用于将订阅消息发送到 Upbit WebSocket 服务器。由于 WebSocket 连接只能传输字符串数据，因此需要将 Python 字典（或列表）转换为 JSON 字符串。 .dumps() 函数是 Python 模块中的一个函数，用于将 Python 对象序列化为 JSON 格式的字符串。
websocket.recv() : 此函数用于从 Upbit WebSocket 服务器接收推送的数据。这是一个阻塞操作，会一直等待直到接收到数据为止。接收到的数据通常是 JSON 格式的字符串，包含了你订阅的市场数据。
.loads(data) : 该函数用于将从 Upbit 服务器接收到的 JSON 字符串反序列化为 Python 字典（或列表）。 .loads() 是 Python 模块中的一个函数，用于将 JSON 字符串解析为 Python 对象。解析后的数据可以方便地在 Python 代码中进行处理和分析。

3. 订阅消息格式详解

订阅消息是一个 JSON 数组，数组中的每个元素代表一个独立的订阅请求。每个订阅请求必须精心构造，以确保能够准确地接收所需的市场数据。

ticket : 这是一个至关重要的字段，必须包含一个唯一的字符串，用于在客户端和服务器端之间明确区分不同的订阅。强烈建议采用 UUID（通用唯一识别码）生成算法或其他可靠的唯一标识符生成方法来创建 ticket ，从而最大限度地确保其唯一性，并有效避免因重复 ticket 导致的潜在订阅冲突。重复使用相同的 ticket 会导致不可预测的行为，例如覆盖现有订阅或无法正确接收数据。
type : 该字段用于指定您希望订阅的数据类型。Upbit WebSocket API 支持多种数据类型，允许您根据需求选择最合适的数据流：
- ticker : 提供当前市场最新价格的快照信息，包含诸如最新成交价、最高价、最低价、交易量等关键指标。
- trade : 传输最新的成交信息，记录每一笔成功撮合的交易细节，包括成交价格、成交数量和成交时间。
- orderbook : 广播实时的订单簿信息，展示当前市场挂单的分布情况，包括买单和卖单的价格和数量。
- orderbookdepth : 提供比 orderbook 更详细的订单簿深度信息。它通常包含更深层次的订单簿数据，例如不同价格级别的累积挂单量，有助于更全面地分析市场供需关系。
codes : 这是一个包含市场代码的字符串数组。每个市场代码都唯一地代表一个交易对，例如 "KRW-BTC" 代表以韩元（KRW）计价的比特币（BTC）交易市场。您可以在 Upbit 官方网站或 API 文档中找到完整的市场代码列表。通过在 codes 数组中包含多个市场代码，您可以同时订阅多个交易对的行情数据，实现多市场监控。
format : 该字段定义了数据的格式。它允许您在 "SIMPLE" 和 "DEFAULT" 两种格式之间进行选择。默认值为 "DEFAULT"。
- "SIMPLE" 格式的数据量较小，传输速度更快，但可能只包含最核心的信息，省略了一些辅助字段。
- "DEFAULT" 格式则包含所有可用的字段，提供更全面的市场数据，但数据量相对较大。选择哪种格式取决于您的应用场景和对数据完整性的需求。

例如，以下 JSON 数组展示了如何同时订阅 BTC/KRW 和 ETH/KRW 交易对的当前价 ( ticker ) 和成交信息 ( trade )：

[ { "ticket": "my unique ticket 1", "type": "ticker", "codes": ["KRW-BTC", "KRW-ETH"] }, { "ticket": "my unique ticket 2", "type": "trade", "codes": ["KRW-BTC", "KRW-ETH"] } ]

4. 数据格式解析

Upbit WebSocket API返回的数据格式具有多样性，其结构取决于您所订阅的具体数据类型以及在请求时指定的 format 参数。 format 参数允许您选择接收JSON或Protocol Buffer (protobuf)格式的数据，选择合适的格式可以优化性能和数据解析效率。如果未指定 format 参数，默认情况下Upbit会返回JSON格式的数据。

JSON格式： 当选择JSON格式时，数据将以易于阅读和解析的键值对形式呈现。这种格式的优点是通用性强，几乎所有编程语言都内置了JSON解析库，方便开发者快速集成。然而，JSON格式的数据包体积相对较大，在网络传输中可能会占用更多的带宽。

Protocol Buffer (protobuf)格式： Protobuf是由Google开发的一种高效的数据序列化协议。与JSON相比，Protobuf采用二进制格式，数据包体积更小，解析速度更快，尤其适合对性能要求较高的应用场景。要使用Protobuf格式，您需要在项目中引入相应的protobuf库，并定义与Upbit API数据结构相匹配的.proto文件。使用protobuf能够有效降低网络延迟和CPU消耗。

理解Upbit WebSocket API返回数据的具体结构至关重要，您需要参考Upbit官方API文档中关于不同数据类型的定义。例如，ticker（当前价）数据、orderbook（订单簿）数据、trade（成交）数据等，都有其特定的字段和含义。正确解析这些数据字段，才能构建出稳定可靠的交易应用。

Ticker (当前价) 数据格式:

Ticker数据，或称市场行情快照，提供加密货币交易对的实时关键数据。以下JSON格式展示了一个示例，详细解释了各字段的含义：


{
  "type": "ticker",
  "code": "KRW-BTC",
  "opening_price": 50000000.0,
  "high_price": 51000000.0,
  "low_price": 49000000.0,
  "trade_price": 50500000.0,
  "prev_closing_price": 49500000.0,
  "acc_trade_price_24h": 1000.0,
  "acc_trade_volume_24h": 20.0,
  "highest_52_week_price": 60000000.0,
  "highest_52_week_date": "2023-01-01",
  "lowest_52_week_price": 30000000.0,
  "lowest_52_week_date": "2022-07-01",
  "timestamp": 1678886400000
}

字段解释:

type : 数据类型，固定值为 "ticker"，表明该数据是市场行情快照数据。
code : 交易对代码，例如 "KRW-BTC" 表示韩元/比特币交易对。通常格式为 [计价货币]-[标的货币]。
opening_price : 开盘价，指当前交易日（UTC 00:00）的第一个成交价格。
high_price : 最高价，指当前交易日内的最高成交价格。
low_price : 最低价，指当前交易日内的最低成交价格。
trade_price : 最新成交价，指最近一笔成交的价格。
prev_closing_price : 前日收盘价，指前一个交易日的收盘价格。
acc_trade_price_24h : 24小时累计成交额，以计价货币为单位，代表过去24小时内所有成交订单的总金额。
acc_trade_volume_24h : 24小时累计成交量，以标的货币为单位，代表过去24小时内所有成交订单的总数量。
highest_52_week_price : 52周最高价，过去一年内的最高成交价格。
highest_52_week_date : 52周最高价日期，52周最高价对应的日期。
lowest_52_week_price : 52周最低价，过去一年内的最低成交价格。
lowest_52_week_date : 52周最低价日期，52周最低价对应的日期。
timestamp : 时间戳，表示数据生成的时间，为 Unix 时间戳，单位为毫秒。

重要提示: 不同交易所的数据字段命名和单位可能存在差异，使用时请务必参考交易所的官方API文档。时间戳的精度也可能不同，需要根据具体情况进行调整。

Trade (成交) 数据格式：

成交数据是加密货币交易中最为基础且关键的信息之一，它记录了每一笔成功撮合的交易详情。以下是一个典型的成交数据格式示例，展示了关键字段及其含义，以便开发者和交易者能够理解和利用这些数据。

{

"type": "trade",
type 字段表明了数据的类型，此处为 "trade"，表示这是一条成交数据。不同的数据源可能使用不同的类型标识符，但 "trade" 是一个常见的约定。

"code": "KRW-BTC",
code 字段代表交易对的代码，例如 "KRW-BTC" 表示韩元 (KRW) 交易比特币 (BTC)。不同的交易所使用不同的代码规范，但通常由两种加密货币的符号组成，中间用连接符分隔。该字段对于识别交易发生的市场至关重要。

"trade_price": 50500000.0,
trade_price 字段表示成交价格，即实际交易发生的单价。在此示例中，价格为 50500000.0，单位通常是报价货币 (本例中为韩元)。它是评估交易价值和进行价格分析的关键数据点。

"trade_volume": 0.01,
trade_volume 字段表示成交数量，即交易的加密货币数量。在此示例中，数量为 0.01，单位通常是基础货币 (本例中为比特币)。它与成交价格一起决定了交易的总价值。

"ask_bid": "ASK",
ask_bid 字段表示交易方向，"ASK" 代表卖出 (也称为 "卖方" 或 "出价")，"BID" 代表买入 (也称为 "买方" 或 "要价")。"ASK" 表明这笔交易是由卖方主动以该价格出售，而 "BID" 表明这笔交易是由买方主动以该价格购买。

"timestamp": 1678886400000
timestamp 字段表示成交时间戳，通常以 Unix 时间戳 (自 1970 年 1 月 1 日 00:00:00 UTC 起经过的毫秒数) 的形式表示。在此示例中，时间戳为 1678886400000。通过时间戳，可以追踪交易发生的准确时间，进行时间序列分析和回溯测试。

}

Orderbook (订单簿) 数据格式:

订单簿数据是加密货币交易所的核心组成部分，它实时反映了市场上的买卖盘情况。理解订单簿的数据结构对于进行有效的交易决策至关重要。以下是一个示例的JSON格式订单簿数据，用于展示买卖盘的价格和数量信息：


{
  "type": "orderbook",
  "code": "KRW-BTC",
  "total_ask_size": 10.0,
  "total_bid_size": 12.0,
  "orderbook_units": [
    {
      "ask_price": 50600000.0,
      "bid_price": 50500000.0,
      "ask_size": 2.0,
      "bid_size": 3.0
    },
    {
      "ask_price": 50700000.0,
      "bid_price": 50400000.0,
      "ask_size": 1.5,
      "bid_size": 2.5
    }
  ],
  "timestamp": 1678886400000
}

该JSON对象包含以下关键字段：

type : 数据的类型，这里为 "orderbook"，表明这是一个订单簿数据快照。
code : 交易对代码，例如 "KRW-BTC"，表示韩元（KRW）与比特币（BTC）的交易对。
total_ask_size : 市场上所有卖单（ask）的总量，以指定货币单位计，例如本例中为 10.0 BTC。
total_bid_size : 市场上所有买单（bid）的总量，以指定货币单位计，例如本例中为 12.0 BTC。
orderbook_units : 一个包含多个订单簿单元的数组。每个单元代表一个特定价格的买卖盘情况。

每个订单簿单元（orderbook_unit）包含：

ask_price : 卖单的价格，例如 50600000.0 KRW/BTC。
bid_price : 买单的价格，例如 50500000.0 KRW/BTC。
ask_size : 在该价格上的卖单数量，例如 2.0 BTC。
bid_size : 在该价格上的买单数量，例如 3.0 BTC。

timestamp : 数据生成的时间戳，以 Unix 时间戳格式表示（毫秒）。例如，1678886400000 对应于 2023年3月15日。时间戳的准确性至关重要，因为它允许用户跟踪订单簿随时间的变化。

通过分析`orderbook_units`数组，可以了解不同价格水平上的买卖压力，这对于确定潜在的支撑位和阻力位至关重要。较低的`ask_price`和较高的`bid_price`通常更具吸引力，反映了市场的供需关系。

你需要根据订阅的数据类型解析相应的 JSON 数据。每个数据类型包含不同的字段，具体字段含义可以参考 Upbit API 文档或其他交易所的API文档，文档通常会详细说明每个字段的含义、数据类型和单位。

5. 常见问题和注意事项

连接错误： 确保你的网络连接稳定可靠，并且检查是否存在任何防火墙或代理服务器阻止 WebSocket 连接的建立。特别注意公司或公共网络环境，这些环境通常具有更严格的网络策略。检查端口是否被阻止，WebSocket 通常使用 80 端口 (HTTP) 或 443 端口 (HTTPS)，但有时可能需要特定端口。如果使用代理服务器，需要在 WebSocket 客户端配置代理设置。
数据丢失： WebSocket 连接本质上可能受到网络波动的影响而中断，导致数据流的不完整。为了应对这种情况，强烈建议在客户端实现自动重连机制，并在连接意外中断后立即尝试重新建立连接。在客户端缓存接收到的数据，以便在重新连接后能够检测和处理可能丢失的数据。可以考虑使用心跳机制来定期检查连接的活跃性，并在检测到连接问题时主动触发重连。
数据频率： Upbit WebSocket API 提供高频率的实时数据更新，这可能会对客户端的处理能力造成压力。为避免程序过载，你需要仔细评估你的应用场景，并选择最适合你需求的订阅类型和市场代码。例如，如果只需要分钟级别的K线数据，则无需订阅 Tick 数据。同时，优化数据处理逻辑至关重要。使用高效的数据结构和算法，减少不必要的计算和存储开销。考虑使用多线程或异步编程来并行处理数据，提高处理速度。如果数据量仍然过大，可以考虑对数据进行抽样或聚合，只保留必要的信息。
身份验证： Upbit WebSocket API 的设计特性是不需要身份验证。这简化了客户端的开发流程，但也意味着任何人都可能连接到 API 并获取数据。因此，请务必注意保护你的 API 密钥和其他敏感信息，避免泄露。
流量限制： Upbit 为了维护平台的稳定性和公平性，可能会对 WebSocket API 的流量进行限制。如果你的程序在短时间内发送过多的请求，可能会被限制访问。为了避免触发流量限制，建议合理控制请求频率。可以通过添加延迟或使用令牌桶算法来限制请求速率。监控你的程序的请求量，并在接近限制时采取措施。仔细阅读 Upbit 的 API 文档，了解具体的流量限制策略。
Unique Ticket 的重要性： 每次建立 WebSocket 连接时，务必生成并使用一个唯一的 unique ticket。重复使用相同的 ticket 可能会导致数据混乱，因为 Upbit 服务器可能会将来自不同连接的数据混合在一起。为了保证 ticket 的唯一性，建议使用 UUID (Universally Unique Identifier) 库来生成随机字符串。 UUID 保证了在极大概率上，即使在不同的系统和时间生成，生成的字符串也是唯一的。确保你的代码能够正确处理 UUID 的生成和传递，避免出现潜在的数据一致性问题。

6. 其他实用技巧

使用心跳机制: 为了确保 WebSocket 连接的长期稳定和活跃，建议实施心跳机制。尽管 Upbit WebSocket API 本身没有内置的心跳功能，但可以通过定期发送特定类型的消息来模拟，例如，可以定期发送一个结构简单的订阅请求或一个包含占位符数据的订阅消息。这样的定期消息可以有效地告诉服务器客户端仍然在线并保持连接的有效性，避免因网络空闲或其他原因导致连接中断。
错误处理: WebSocket 连接在实际应用中可能会遇到多种类型的错误，例如连接超时、服务器无响应、意外断开、数据校验失败等。为了保证应用程序的健壮性和可靠性，必须实现完善的错误处理机制。这包括捕获和记录错误信息，自动重连机制，以及在发生严重错误时向用户发出警报。同时，还需要对接收到的数据进行有效性验证，防止因数据错误导致程序崩溃或产生不正确的计算结果。
多线程/异步编程: 为了充分利用计算资源并提高程序的整体性能，特别是在高并发场景下，强烈建议使用多线程或异步编程模型来处理 WebSocket 数据流。通过将数据接收、解析和处理任务分配给不同的线程或异步任务，可以避免阻塞主线程，从而提高程序的响应速度和数据处理效率。选择合适的并发模型取决于具体的应用场景和性能需求。
数据存储: 为了支持后续的数据分析、挖掘、回测和可视化，可以将从 WebSocket 接收到的实时行情数据存储到关系型数据库（如 MySQL, PostgreSQL）、NoSQL 数据库（如 MongoDB, Cassandra）或文件中（如 CSV, Parquet）。选择合适的数据存储方案取决于数据量的大小、查询的复杂度和性能要求。对于需要快速查询和分析的大规模数据，建议选择具有高性能和可扩展性的数据库解决方案。
利用缓存机制: 针对那些更新频率较低或不经常变化的数据，例如交易所的交易对列表、静态配置参数等，可以采用缓存机制来显著减少对 Upbit WebSocket API 的直接请求次数，从而降低服务器负载并提高程序的响应速度。可以使用内存缓存（如 Redis, Memcached）或本地文件缓存来实现。需要注意的是，缓存数据需要设置合适的过期时间，并定期更新，以确保数据的准确性和一致性。

上一篇: 币安新手指南：从入门到精通的加密货币交易之旅

下一篇: 抹茶交易所止盈策略：深度剖析与实战技巧，助您穿越牛熊