币安API接口详解：使用方法、身份验证与Python示例

2025-03-04 研究 32℃

币安 API 接口使用方法详解及示例

币安作为全球领先的加密货币交易所，其 API 接口为开发者提供了强大的工具，可以用于自动化交易、数据分析、资产管理等多种应用。本文将详细介绍币安 API 接口的使用方法，并提供示例代码帮助读者快速上手。

API 概述

币安 API 允许开发者和交易者通过编程方式与币安平台进行交互，从而自动化交易策略、获取市场数据以及管理账户。它提供了两种主要的访问方式：REST API 和 WebSocket API，分别适用于不同的应用场景。

REST API: REST (Representational State Transfer) API 采用请求-响应模式，通过发送 HTTP 请求到指定的端点来执行特定操作。它通常用于发送同步请求，这意味着客户端发送请求后需要等待服务器返回响应。REST API 非常适合执行交易订单（如买入或卖出加密货币）、查询账户信息（如余额、交易历史）以及获取历史市场数据等操作。每个请求都需要经过身份验证，确保只有授权的用户才能访问和修改其账户信息。
WebSocket API: WebSocket API 则提供了一种全双工通信通道，允许服务器主动向客户端推送数据，而无需客户端频繁发送请求。它建立的是一种持久连接，客户端和服务器可以在连接保持活动状态期间实时交换数据。WebSocket API 主要用于实时接收市场数据（如实时价格更新、深度行情）、账户更新（如订单状态变化、交易执行情况）以及其他需要即时通知的事件。由于其低延迟和高效率的特点，WebSocket API 在高频交易和实时监控等场景中得到广泛应用。

为了保护用户账户的安全，币安 API 访问受保护的资源需要进行身份验证。身份验证过程主要依赖于 API Key 和 Secret Key，这两组密钥都可以在币安官网的用户 API 管理页面生成。API Key 用于标识您的身份，而 Secret Key 则用于对请求进行签名，以验证请求的来源和完整性。在使用 API Key 和 Secret Key 时，务必妥善保管，切勿泄露给他人，以防止未经授权的访问。

身份验证

在使用币安 API 之前，务必完成 API Key 和 Secret Key 的配置。API Key 用于标识你的账户，而 Secret Key 则用于生成签名，对请求进行身份验证。请务必高度重视 Secret Key 的安全性，如同保管银行密码一般，切勿以任何方式泄露给任何第三方。一旦泄露，可能会导致未经授权的访问和资金损失。

API Key 和 Secret Key 的组合是访问币安 API 的凭证。API Key 允许服务器识别请求的来源，而 Secret Key 则用于通过加密签名确保请求的完整性和真实性。签名生成过程采用业界标准的 HMAC-SHA256 算法，该算法结合了请求参数和 Secret Key，产生一个唯一的哈希值，作为请求的数字签名。

以下是 Python 示例代码，详细展示了如何使用用户的 Secret Key 和请求参数，利用 HMAC-SHA256 算法生成符合币安 API 规范的签名：

import hashlib import hmac import urllib.parse

def generate_signature(data, secret_key): """ 生成币安 API 请求的数字签名。 Args: data: 请求参数的字典，包含所有需要传递给 API 的数据。 secret_key: 用户的 Secret Key，用于生成签名。务必妥善保管，切勿泄露！ Returns: 签名字符串，用于附加到 API 请求中。 """ query_string = urllib.parse.urlencode(data) signature = hmac.new(secret_key.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha256).hexdigest() return signature

示例

在加密货币交易API的交互中，安全地生成和使用签名至关重要。以下代码段展示了如何使用密钥（Secret Key）和交易参数创建消息签名，确保交易请求的完整性和真实性。请务必将 "your_secret_key" 替换为您实际的Secret Key。Secret Key 通常由交易所提供，用于验证您的身份并授权交易。

api_secret = "your_secret_key" # 替换为你的 Secret Key

params = { "symbol": "BTCUSDT", "side": "BUY", "type": "MARKET", "quantity": 0.001, "timestamp": 1678886400000 }

params 字典包含了交易所需的关键信息：

symbol : 指定交易的交易对，例如 "BTCUSDT" 表示比特币兑美元。
side : 指示交易方向，"BUY" 表示买入。相对地，"SELL" 则表示卖出。
type : 定义订单类型，"MARKET" 表示市价单，将以当前市场最优价格立即成交。其他常见的订单类型还包括 "LIMIT" (限价单) 等。
quantity : 指定交易数量，例如 0.001 表示买入 0.001 个比特币。注意交易所有最小交易数量限制。
timestamp : 记录交易时间戳，以毫秒为单位。确保时间戳的准确性对于防止重放攻击至关重要。不同的交易所可能对时间戳的格式和精确度有不同的要求。

为了确保API请求的安全性，需要对请求参数进行签名。签名过程通常涉及将请求参数与您的Secret Key组合，并使用哈希算法（例如 HMAC-SHA256）生成唯一的签名字符串。

signature = generate_signature(params, api_secret)

generate_signature 函数（未在此处提供）负责根据交易所要求的特定算法生成签名。该函数通常会将参数按照特定规则排序，然后使用 Secret Key 对排序后的参数进行哈希处理。

print(f"签名: {signature}")

生成的签名将作为请求的一部分发送到交易所。交易所会使用相同的算法和您的Secret Key重新计算签名，并将其与您发送的签名进行比较。如果两个签名匹配，则表示请求未被篡改，可以安全地执行。

REST API 使用示例：查询账户余额

以下示例展示如何使用 Python 发送 REST API 请求来查询账户余额。该示例使用币安交易所的 API 作为演示，但概念适用于其他支持 REST API 的加密货币交易所。

import requests import time import urllib.parse import hashlib # 导入 hashlib 库，用于生成签名

api_key = "your_api_key" # 替换为你的 API Key，通常在交易所的 API 管理页面获取 api_secret = "your_secret_key" # 替换为你的 Secret Key，务必妥善保管，避免泄露 base_url = "https://api.binance.com" # 币安 API 基础 URL，根据交易所的不同而变化

def generate_signature(params, secret_key): """ 使用 HMAC-SHA256 算法生成 API 请求签名。 Args: params (dict): 请求参数字典。 secret_key (str): 用户的 Secret Key。 Returns: str: 生成的签名字符串。 """ query_string = urllib.parse.urlencode(params) signature = hashlib.hmac(secret_key.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha256).hexdigest() return signature

def get_account_balance(api_key, api_secret): """ 查询账户余额。 Args: api_key (str): 用户的 API Key。 api_secret (str): 用户的 Secret Key。 Returns: dict: 账户余额信息，如果请求失败则返回 None。 """ endpoint = "/api/v3/account" # API 端点，指定要访问的资源 timestamp = int(time.time() * 1000) # 获取当前时间戳，精确到毫秒 params = {"timestamp": timestamp} # 构造请求参数，包含时间戳 signature = generate_signature(params, api_secret) # 生成请求签名，保证请求的安全性 params["signature"] = signature # 将签名添加到请求参数中 headers = {"X-MBX-APIKEY": api_key} # 设置请求头，包含 API Key url = base_url + endpoint + "?" + urllib.parse.urlencode(params) # 构造完整的 URL try: response = requests.get(url, headers=headers) # 发送 GET 请求 response.raise_for_status() # 检查 HTTP 状态码，如果不是 200 则抛出异常 return response.() # 将响应内容解析为 JSON 格式并返回 except requests.exceptions.RequestException as e: print(f"请求失败: {e}") # 打印错误信息 return None

# 使用示例 if __name__ == '__main__': account_info = get_account_balance(api_key, api_secret) if account_info: print("账户信息:") for balance in account_info["balances"]: if float(balance["free"]) > 0 or float(balance["locked"]) > 0: #仅显示有余额的币种 print(f"{balance['asset']}: Free = {balance['free']}, Locked = {balance['locked']}") else: print("获取账户信息失败。")

注意事项：

请务必替换 api_key 和 api_secret 为你自己的真实值。
api_secret 必须妥善保管，切勿泄露给他人。
不同的交易所的 API 使用方式可能略有不同，请参考相应的 API 文档。
本示例仅为演示用途，实际应用中需要根据业务需求进行修改。
可以添加异常处理，比如网络超时、API 频率限制等情况。

执行查询

account_info = get_account_balance(api_key, api_secret)

这段代码片段展示了如何调用一个名为 get_account_balance 的函数，该函数用于从交易所或其他金融服务平台获取账户余额信息。它接收两个参数： api_key 和 api_secret ，这两个参数是用于身份验证和授权的关键凭证。 api_key 通常标识用户或应用程序，而 api_secret 则用于生成请求签名，确保请求的完整性和真实性。函数调用后，返回值被赋值给变量 account_info ，该变量预计包含账户余额的详细信息。

if account_info:
如果 account_info 返回值有效（例如，不是 None 或空值，表明成功获取了账户信息），则执行后续代码块，打印账户信息。
print("账户信息:")
此语句打印一个简单的标题，表明即将输出的是账户信息。
for balance in account_info['balances']:
假设 account_info 是一个字典，其中键 'balances' 对应的值是一个列表，列表中的每个元素代表一种资产的余额信息。此循环遍历该列表，对每种资产执行后续操作。
if float(balance['free']) > 0 or float(balance['locked']) > 0 :
此条件语句检查特定资产的可用余额（ balance['free'] ）或锁定余额（ balance['locked'] ）是否大于 0。使用 float() 函数确保将余额值转换为浮点数进行比较。如果任何一个余额大于 0，则执行后续的打印语句。这可以过滤掉余额为 0 的资产，只显示有实际余额的资产。
print(f" {balance['asset']}: Free = {balance['free']}, Locked = {balance['locked']}")
如果资产的可用余额或锁定余额大于 0，则使用 f-string 打印该资产的名称（ balance['asset'] ）以及其可用余额和锁定余额。这种格式化的输出方式使得账户信息更易于阅读和理解。

else:
如果 account_info 返回值无效（例如， None 或空值），则执行此 else 代码块。这通常表示获取账户信息失败。
print("未能获取账户信息。")
打印一条错误消息，提示用户未能成功获取账户信息。这可能是由于 API 密钥无效、网络连接问题或其他错误导致的。

这段代码的核心功能是从指定的交易所或金融服务平台获取用户的账户余额信息，并以易于理解的格式打印出来。 get_account_balance 函数负责与 API 交互，进行身份验证、请求数据和解析响应。后续代码则负责处理返回的数据，过滤零余额资产，并以清晰的格式展示账户信息，同时处理获取账户信息失败的情况。 API Key 和 Secret Key 是进行安全 API 调用的必要凭证， get_account_balance 函数的实现细节涉及构建带有正确签名的 HTTP 请求，并将响应解析为可用的 JSON 格式数据。该函数还会处理可能的 API 错误和速率限制。

WebSocket API 使用示例

WebSocket API 允许客户端与币安服务器建立持久的双向通信连接，实现实时市场数据的接收。该技术相较于传统的 HTTP 请求，具有更低的延迟和更高的效率，尤其适用于对数据更新速度有较高要求的应用场景。以下是一个使用 Python 编写的简单示例，展示如何使用 WebSocket 连接到币安 API 并接收 BTCUSDT 交易对的实时交易数据。

需要安装 websocket-client 库。可以使用 pip 包管理器进行安装： pip install websocket-client 。此库简化了 WebSocket 连接的建立和数据处理。

接下来，是示例代码：

import websocket import

def on_open(ws): """ WebSocket 连接建立成功时调用的回调函数。 """ print("WebSocket 连接已打开")

def on_message(ws, message): """ 接收到服务器推送的消息时调用的回调函数。 """ try: data = .loads(message) # 打印交易数据，包含价格和数量。实际应用中，可以根据需要对数据进行处理和存储。 print(f"交易价格: {data['p']}, 交易数量: {data['q']}") except .JSONDecodeError as e: print(f"JSON 解析错误: {e}") print(f"原始消息: {message}")

def on_close(ws, close_status_code, close_msg): """ WebSocket 连接关闭时调用的回调函数。可以根据 close_status_code 和 close_msg 判断连接关闭的原因。 """ print("WebSocket 连接已关闭") print(f"关闭状态码: {close_status_code}, 关闭消息: {close_msg}")

def on_error(ws, error): """ 发生错误时调用的回调函数。 """ print(f"WebSocket 错误: {error}")

if __name__ == "__main__": socket = "wss://stream.binance.com:9443/ws/btcusdt@trade" # 币安 WebSocket API 的 BTCUSDT 交易数据流地址 ws = websocket.WebSocketApp(socket, on_open=on_open, on_message=on_message, on_close=on_close, on_error=on_error)

ws.run_forever()

这段代码创建了一个 WebSocket 客户端，并连接到币安的 WebSocket 服务器，订阅 BTCUSDT 交易对的实时交易数据流。 on_open 函数在 WebSocket 连接成功建立时被调用， on_message 函数在接收到服务器推送的消息时被调用， on_close 函数在 WebSocket 连接关闭时被调用，而 on_error 函数则在发生错误时被调用。 ws.run_forever() 保持连接并持续接收数据，直到手动停止程序。需要注意的是，实际应用中可能需要处理连接中断和重连的逻辑，以保证程序的稳定性。

错误处理

币安 API 交互过程中，服务器会返回状态码，以此告知客户端请求的处理结果。状态码是开发者判断请求是否成功的重要依据。常见的状态码及其含义如下：

200 : 请求成功。服务器已成功接收、理解并处理了客户端的请求。
400 : 客户端错误。通常表示请求参数存在错误，例如缺少必要的参数、参数格式不正确、参数值超出范围等。开发者应仔细检查请求参数，确保其符合API文档的要求。
401 : 未授权。通常是由于API Key 未提供或无效，或者签名验证失败导致的。开发者应确保API Key 已正确配置，并且签名算法正确无误。确保 API Key 已启用，并具有访问相应端点的权限。
403 : 禁止访问。表示客户端没有足够的权限访问请求的资源。即使API Key有效，也可能因为权限不足而返回此状态码。请检查您的 API Key 权限设置，确保其包含访问该资源的权限。
429 : 请求过于频繁，触发限流。币安 API 为了防止滥用，对请求频率进行了限制。当请求频率超过限制时，服务器会返回此状态码。开发者应控制请求频率，避免触发限流。
500 : 服务器内部错误。表示服务器在处理请求时发生了未知的错误。这通常不是客户端的问题，开发者可以稍后重试请求，或者联系币安客服寻求帮助。如果问题持续存在，可能需要向币安报告此错误。

开发者应针对不同的状态码采取相应的处理策略。例如，对于 400 错误，应检查并修正请求参数；对于 401 错误，应检查 API Key 和签名；对于 429 错误，应降低请求频率；对于 500 错误，可以重试请求或联系币安客服。

币安 API 实施了速率限制机制，旨在防止恶意滥用，保障服务的稳定性和可用性。开发者需要严格遵守这些限制，避免触发限流。可以通过检查币安 API 响应头部中的 X-MBX-USED-WEIGHT-* 信息来监测当前的速率限制使用情况。 X-MBX-USED-WEIGHT-1M 表示过去一分钟内使用的权重， X-MBX-USED-WEIGHT-1M 的值越高，代表请求消耗的资源越多。开发者应根据这些信息动态调整请求频率，避免超过限制。