Binance API：实时行情数据获取指南
如何通过 Binance 的 API 接口获取实时行情数据
加密货币市场瞬息万变，对于交易者和开发者而言，能够实时获取市场行情数据至关重要。 Binance 作为全球领先的加密货币交易所，提供了强大的 API 接口，允许用户以编程方式访问各种市场数据，包括实时价格、交易量、订单簿信息等等。 本文将介绍如何通过 Binance 的 API 接口获取实时行情数据，并提供代码示例供参考。
一、API 概览与认证
币安（Binance）提供了一系列功能强大的 API 接口，开发者可以通过这些接口访问交易所的数据和服务。 这些API端点通常可以归类为以下几种类型：
-
公共 API (Public API):
公共 API 允许匿名访问，无需任何形式的身份验证。 这些 API 端点主要用于获取公开的市场数据，例如：
- 实时价格 (Real-time Prices): 获取特定交易对的当前买一价、卖一价等实时价格信息。
- K 线数据 (Candlestick Data): 获取历史价格数据，通常以 K 线图的形式展示，包含开盘价、最高价、最低价和收盘价。
- 交易量 (Volume Data): 查询特定时间段内的交易量，用于评估市场活跃度。
- 市场深度 (Order Book): 获取买单和卖单的挂单信息，反映市场的供需关系。
- 交易对信息 (Symbol Information): 查询交易对的详细信息，如最小交易数量、价格精度等。
-
私有 API (Private API):
私有 API 需要进行身份验证，才能访问受保护的资源和执行敏感操作。 使用私有 API 前，用户需要创建 API 密钥，并使用该密钥对请求进行签名。 私有 API 主要用于：
- 执行交易 (Trade Execution): 下单、撤单，进行现货或合约交易。
- 查询账户余额 (Account Balance Inquiry): 获取账户中各种加密货币的余额信息。
- 获取订单历史记录 (Order History Retrieval): 查询历史订单的详细信息，包括成交价格、成交数量等。
- 资金划转 (Fund Transfer): 在币安的不同账户之间转移资金，例如从现货账户划转到合约账户。
- 获取 API 使用情况 (API Usage): 查询 API 密钥的使用情况，例如剩余的请求次数等。
本文将重点介绍如何利用币安的公共 API 获取实时的市场行情数据。 由于公共 API 不需要认证，因此您可以直接使用这些端点，无需创建或配置 API 密钥。
二、 获取实时价格
获取单个交易对的实时价格，可以使用
GET /api/v3/ticker/price
端点。该端点提供指定交易对的最新成交价格信息。例如，要获取 BTCUSDT 的实时价格，可以使用以下 URL：
https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT
此请求会向币安服务器发送一个查询，请求 BTCUSDT 交易对的最新价格。请注意，此端点返回的是未经任何聚合或平均的价格，代表的是最新的成交价格。
返回的 JSON 格式数据如下：
{
"symbol": "BTCUSDT",
"price": "29000.00"
}
其中，
symbol
表示交易对，例如 "BTCUSDT"，它代表比特币 (BTC) 兑美元稳定币 USDT 的交易对。
price
表示当前价格，以字符串形式返回，例如 "29000.00"，代表一单位比特币当前价值 29000 USDT。 务必注意，
price
字段返回的是字符串类型，在进行计算时需要转换为数值类型。
还可以使用不同的交易对，例如 ETHUSDT 获取以太坊兑 USDT 的价格，或者 BNBUSDT 获取币安币兑 USDT 的价格。只需将 URL 中的
symbol
参数替换为相应的交易对即可。
请注意，币安API的频率限制可能适用。建议查阅币安API的官方文档，了解具体的频率限制，并合理控制请求频率，避免被限流。
三、 获取多个交易对的实时价格
在加密货币交易中，同时监控多个交易对的价格波动至关重要。为了高效地获取多个交易对的实时价格，可以使用币安API的
GET /api/v3/ticker/price
端点。该端点允许通过
symbols
参数一次性请求多个交易对的价格信息。
symbols
参数的值必须是一个符合 JSON 格式的数组，数组中的每个元素代表一个交易对的名称。
例如，如果需要同时获取 BTCUSDT（比特币/美元）和 ETHUSDT（以太坊/美元）这两个交易对的实时价格，可以使用以下格式的URL发起请求：
https://api.binance.com/api/v3/ticker/price?symbols=["BTCUSDT","ETHUSDT"]
这个URL将发送一个HTTP GET请求到币安API服务器，要求返回BTCUSDT和ETHUSDT的当前价格。服务器会返回一个JSON格式的数据，包含每个交易对的交易代码（symbol）和最新价格（price）。
返回的 JSON 格式数据结构如下：
[
{
"symbol": "BTCUSDT",
"price": "29000.00"
},
{
"symbol": "ETHUSDT",
"price": "1800.00"
}
]
在返回的JSON数据中，每个对象代表一个交易对的价格信息。
symbol
字段表示交易对的名称，例如 "BTCUSDT"。
price
字段则表示该交易对的当前市场价格，例如 "29000.00"。请注意，价格数据通常以字符串形式返回，应用程序可能需要将其转换为数值类型以便进行计算和分析。
通过一次API调用获取多个交易对的价格，可以显著提高数据获取效率，减少网络请求次数，降低延迟，从而为高频交易和实时监控提供更好的支持。开发者可以根据实际需求，在
symbols
数组中添加或删除交易对，灵活地定制需要监控的价格数据。
四、 获取 24 小时行情数据
要获取特定交易对的 24 小时行情数据，涵盖开盘价、最高价、最低价、成交量、成交额以及其他关键指标，可以使用币安 API 的
GET /api/v3/ticker/24hr
端点。此端点提供了一个全面的市场概览，允许开发者和交易者快速评估指定交易对的当前表现。 例如，若要获取 BTCUSDT 交易对的 24 小时行情数据，可以构造并发送以下 HTTP GET 请求：
https://api.binance.com/api/v3/ticker/24hr?symbol=BTCUSDT
该请求会返回一个 JSON 格式的数据对象，其中包含了关于 BTCUSDT 交易对在过去 24 小时内的各项统计数据。返回的 JSON 数据结构示例如下：
{
"symbol": "BTCUSDT",
"priceChange": "-100.00",
"priceChangePercent": "-0.34%",
"weightedAvgPrice": "29050.00",
"prevClosePrice": "29100.00",
"lastPrice": "29000.00",
"lastQty": "0.01",
"bidPrice": "28990.00",
"bidQty": "0.05",
"askPrice": "29010.00",
"askQty": "0.03",
"openPrice": "29100.00",
"highPrice": "29200.00",
"lowPrice": "28800.00",
"volume": "1000.00",
"quoteVolume": "29000000.00",
"openTime": 1678886400000,
"closeTime": 1678972800000,
"firstId": 123456789,
"lastId": 123456799,
"count": 10
}
以下是对上述 JSON 响应中各个字段的详细解释：
-
symbol: 代表交易对的符号，例如 "BTCUSDT"。 -
priceChange: 指示当前价格相对于 24 小时前价格的变动绝对值。 -
priceChangePercent: 表示当前价格相对于 24 小时前价格的变动百分比。 -
weightedAvgPrice: 是一个加权平均价格，它考虑了成交量对价格的影响，能更准确地反映实际交易价格。 -
prevClosePrice: 代表前一日的收盘价格。 -
lastPrice: 指示最新的成交价格。 -
lastQty: 表示最新一笔成交的数量。 -
bidPrice: 指示当前市场上最高的买入价格（买一价）。 -
bidQty: 表示以买一价挂单的买入数量（买一量）。 -
askPrice: 指示当前市场上最低的卖出价格（卖一价）。 -
askQty: 表示以卖一价挂单的卖出数量（卖一量）。 -
openPrice: 指示 24 小时前的开盘价格。 -
highPrice: 指示 24 小时内的最高价格。 -
lowPrice: 指示 24 小时内的最低价格。 -
volume: 指示 24 小时内的成交量，以基础货币计价 (例如，BTCUSDT 中 BTC 的成交量)。 -
quoteVolume: 指示 24 小时内的成交额，以计价货币计价 (例如，BTCUSDT 中 USDT 的成交额)。 -
openTime: 开盘时间的时间戳，以 Unix 毫秒格式表示。 -
closeTime: 收盘时间的时间戳，以 Unix 毫秒格式表示。 -
firstId: 24 小时内第一笔交易的 ID。 -
lastId: 24 小时内最后一笔交易的 ID。 -
count: 24 小时内的成交笔数。
五、 获取 K 线数据 (Candlestick Data)
K 线图，又称蜡烛图，是加密货币技术分析中不可或缺的工具。它以图形化的方式展示了一段时间内资产价格的波动情况，为交易者提供了重要的市场信息。通过币安 API 的
GET /api/v3/klines
端点，开发者和交易者可以轻松获取历史 K 线数据，用于分析市场趋势、制定交易策略和构建自动化交易系统。
例如，要获取 BTCUSDT 交易对的 1 分钟 K 线数据，可以使用以下 URL：
https://api.binance.com/api/v3/klines?symbol=BTCUSDT&interval=1m
该请求将返回一个 JSON 数组，其中每个元素代表一个 K 线，包含该时间周期内的开盘价、最高价、最低价和收盘价等关键信息。以下是一个返回数据的示例：
[
[
1678972800000, // 开盘时间 (Open time) - Unix 时间戳，毫秒级
"29000.00", // 开盘价 (Open) - 此 K 线周期的第一个成交价
"29010.00", // 最高价 (High) - 此 K 线周期内的最高成交价
"28990.00", // 最低价 (Low) - 此 K 线周期内的最低成交价
"29005.00", // 收盘价 (Close) - 此 K 线周期的最后一个成交价
"10.00", // 成交量 (Volume) - 此 K 线周期内交易的标的资产数量
1678972859999, // 收盘时间 (Close time) - Unix 时间戳，毫秒级
"290050.00", // 计价货币成交量 (Quote asset volume) - 此 K 线周期内交易的计价货币数量
10, // 成交笔数 (Number of trades) - 此 K 线周期内的成交订单数量
"5.00", // 主动买入的成交量 (Taker buy base asset volume) - 此 K 线周期内主动买入的标的资产数量
"145025.00", // 主动买入的计价货币成交量 (Taker buy quote asset volume) - 此 K 线周期内主动买入的计价货币数量
"0" // 忽略字段 (Ignore) - 早期版本的遗留字段，当前无意义，始终为 "0"
],
// ...更多数据
]
其中，JSON 数组中的每个元素（即每个 K 线）都包含以下按顺序排列的数据字段，这些字段提供了对该时间周期内市场活动的全面概览：
- 开盘时间 (Open time): K 线的起始时间，以 Unix 时间戳（毫秒）表示。
- 开盘价 (Open): 在此 K 线周期内第一笔交易的价格。
- 最高价 (High): 在此 K 线周期内达到的最高交易价格。
- 最低价 (Low): 在此 K 线周期内达到的最低交易价格。
- 收盘价 (Close): 在此 K 线周期内最后一笔交易的价格。
- 成交量 (Volume): 在此 K 线周期内交易的标的资产总量。例如，对于 BTCUSDT，这是以 BTC 计量的交易量。
- 收盘时间 (Close time): K 线的结束时间，同样以 Unix 时间戳（毫秒）表示。
- 计价货币成交量 (Quote asset volume): 在此 K 线周期内交易的计价货币总量。例如，对于 BTCUSDT，这是以 USDT 计量的交易量。
- 成交笔数 (Number of trades): 在此 K 线周期内发生的交易总次数。
- 主动买入的成交量 (Taker buy base asset volume): 在此 K 线周期内，由主动买入者（Taker）进行的标的资产交易量。这个指标有助于衡量买盘压力。
- 主动买入的计价货币成交量 (Taker buy quote asset volume): 在此 K 线周期内，由主动买入者（Taker）进行的计价货币交易量。这个指标与上一个指标结合使用，可以更全面地了解买卖双方的力量对比。
- 忽略字段 (Ignore): 一个保留字段，通常为 "0"，在当前版本的 API 中没有实际意义。
通过
interval
参数，用户可以灵活地调整 K 线的时间周期，以适应不同的分析需求。常用的时间周期包括：
1m
(1 分钟),
3m
(3 分钟),
5m
(5 分钟),
15m
(15 分钟),
30m
(30 分钟),
1h
(1 小时),
2h
(2 小时),
4h
(4 小时),
6h
(6 小时),
8h
(8 小时),
12h
(12 小时),
1d
(1 天),
3d
(3 天),
1w
(1 周),
1M
(1 月)。选择合适的时间周期对于技术分析至关重要，交易者应根据自身的交易风格和策略进行选择。
六、代码示例 (Python)
以下是一个使用 Python 编程语言获取币安 (Binance) 交易所 BTCUSDT 交易对实时价格的代码示例。该示例演示了如何通过 API 调用获取加密货币的实时市场数据。
import requests
def get_btc_price():
url = "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT"
try:
response = requests.get(url)
response.raise_for_status() # 检查 HTTP 响应状态码，如果不是 200 则抛出异常
data = response.()
return data["price"]
except requests.exceptions.RequestException as e:
print(f"Error: {e}")
return None
if __name__ == "__main__":
price = get_btc_price()
if price:
print(f"BTCUSDT Price: {price}")
else:
print("Failed to retrieve BTCUSDT price.")
这段代码使用
requests
库向币安 API 发送 GET 请求，并解析返回的 JSON 数据。
response.raise_for_status()
用于检查 HTTP 响应是否成功，如果返回错误状态码（如 400 或 500），则会引发异常。该函数随后提取 JSON 响应中的
"price"
字段，该字段包含 BTCUSDT 的实时交易价格。在主程序中，该函数被调用，并将结果打印到控制台。如果请求失败，则会打印一条错误消息。需要注意的是，为了更健壮的程序，建议添加更完善的错误处理机制，例如重试机制和详细的日志记录，以便于调试和监控。
七、流式数据 (WebSocket API)
除了 REST API 之外，币安还提供了 WebSocket API，用于实时推送市场数据。与 REST API 的请求-响应模式不同，WebSocket API 建立持久的双向通信连接，允许服务器主动向客户端推送数据，而无需客户端频繁发送请求。 使用 WebSocket API 可以显著减少数据延迟，并降低因频繁轮询 REST API 造成的资源消耗。
通过 WebSocket，开发者可以订阅特定的市场数据流，例如交易对的实时价格、深度信息、交易量等。 例如，可以通过 WebSocket 连接到
wss://stream.binance.com:9443/ws/btcusdt@ticker
获取 BTCUSDT 的实时行情数据。
btcusdt@ticker
表示订阅 BTCUSDT 交易对的 ticker 数据流，它提供诸如最新价格、24 小时最高价、24 小时最低价、交易量等信息的实时更新。
除了 ticker 数据流，币安 WebSocket API 还支持多种其他数据流，包括：
- kline/candlestick 数据流: 提供不同时间周期 (如 1 分钟、5 分钟、1 小时等) 的 K 线数据。
- 深度数据流: 提供实时更新的订单簿深度信息，包括买单和卖单的价格和数量。
- 交易数据流: 提供实时发生的交易记录，包括交易价格、交易数量和交易方向。
- 用户数据流: 需要 API Key 和 Secret Key 进行身份验证，用于接收与用户账户相关的实时数据，如订单更新、账户余额变动等。
使用 WebSocket API 需要建立 WebSocket 连接，并发送订阅消息以指定需要接收的数据流。 连接建立后，服务器会持续推送数据，直到连接关闭。开发者需要编写相应的客户端代码来处理接收到的数据，并根据需要进行解析和存储。
八、 频率限制 (Rate Limits)
为了确保币安（Binance）API 的稳定运行，保障所有用户的公平访问，币安实施了严格的请求频率限制机制。这意味着在特定时间段内，您可以发送到 API 的请求数量是有限制的。 这些限制旨在防止滥用、恶意攻击以及服务器过载，从而维护整个系统的健康运行。
具体的频率限制规则详尽地记录在币安的官方 API 文档中。您可以通过查阅文档了解不同 API 端点的限制，包括每个端点允许的每分钟、每秒或每天的请求数量。务必仔细阅读并理解这些规则，以便合理规划您的 API 请求策略。
开发者需要特别注意控制 API 请求的频率，避免超出限制。建议采用以下策略：
- 批量处理： 将多个操作合并到一个 API 请求中，而不是发送多个单独的请求。
- 缓存数据： 将经常访问的数据缓存在本地，减少对 API 的重复请求。
- 使用 WebSocket： 对于需要实时数据的场景，考虑使用 WebSocket 连接，而不是轮询 API。
- 实施重试机制： 当遇到频率限制错误时，实施指数退避重试机制，避免立即再次请求，减轻服务器压力。
如果您的应用程序触发了频率限制，API 将返回 HTTP 错误代码
429 Too Many Requests
。收到此错误代码后，您应该暂停发送请求，并在一段合理的时间后重试。 频繁触发频率限制可能会导致您的 API 密钥被临时或永久禁用，因此务必谨慎操作。
除了官方文档中列出的限制外，币安可能会根据系统负载或其他因素动态调整频率限制。因此，您的应用程序应该能够适应这些变化，并优雅地处理频率限制错误。
九、错误处理
在使用 Binance API 进行开发时，错误处理是至关重要的环节。由于网络环境的复杂性、API 自身的限制以及用户输入的错误，各种异常情况都可能发生。因此，构建健壮的应用需要周全的错误处理机制。常见错误包括：
- 网络错误： 例如连接超时、DNS 解析失败、SSL 证书验证错误等。这些通常与网络环境有关，可以通过重试机制或更换网络环境来缓解。
-
API 错误：
Binance API 会返回标准化的错误代码和错误信息，指示请求失败的原因。例如，
HTTP 400错误表示请求参数错误，HTTP 429错误表示请求频率过高。 - 参数错误： 提交给 API 的参数不符合要求，例如缺少必填参数、参数格式错误、数值超出范围等。开发者应仔细检查请求参数，确保其符合 API 文档的规范。
- 权限错误： API Key 权限不足，无法访问某些 API 接口或执行某些操作。开发者应确保 API Key 具有足够的权限。
- 账户错误： 账户余额不足、账户被冻结等，导致交易无法完成。开发者应检查账户状态和余额。
- 交易错误： 交易参数错误（如价格、数量）、市场交易规则限制等，导致交易失败。
Binance API 通常会返回 JSON 格式的错误信息，其中包含
code
和
msg
字段。
code
字段是数字类型的错误代码，
msg
字段是错误信息的描述。开发者可以根据
code
字段编写相应的处理逻辑，例如：
- 重试机制： 对于由于网络波动或服务器临时故障导致的错误，可以尝试自动重试。
- 参数校验： 在发送请求之前，对参数进行严格校验，避免由于参数错误导致的 API 错误。
- 错误日志： 记录所有错误信息，方便排查问题。
- 用户提示： 对于用户可理解的错误，向用户提供友好的提示信息。
- 异常处理： 使用 try-except 语句捕获异常，防止程序崩溃。
除了错误代码，
msg
字段通常包含更详细的错误信息，开发者可以根据
msg
字段进行更精细的错误处理。
掌握 Binance API 的使用方法，并结合周全的错误处理机制，能够帮助开发者构建各种加密货币相关的应用，例如量化交易机器人、行情分析工具、数据分析平台等。务必仔细阅读 Binance 的 API 文档，并注意遵守 API 的使用规则和限制。 除了官方文档，还可以参考社区提供的 SDK 和示例代码，加速开发进程。 同时，关注 Binance API 的更新和变更，及时调整代码以适应新的 API 版本。
