Binance API 交易指南

简介

Binance API 为用户提供了一种程序化的访问 Binance 交易平台的方式，极大地扩展了交易的可能性。 通过 API，开发者可以摆脱手动操作的限制，构建自动化交易系统， 实时获取市场数据，并以高效的方式管理其 Binance 账户。 这种程序化的访问能力使得量化交易、算法交易以及其他高级交易策略成为可能。

该 API 允许开发者通过编写代码与 Binance 交易所进行交互， 实现自动化交易策略的执行、获取实时的市场行情数据、以及便捷的账户管理。 无论是构建复杂的交易机器人，还是仅仅需要批量获取历史数据， Binance API 都提供了强大的支持。

本指南旨在介绍 Binance API 的基本概念，详细阐述各种认证方式， 并提供常见的交易操作示例，帮助开发者快速上手并有效利用 Binance API。 我们将涵盖 API 密钥的生成与管理、不同认证方式的选择与配置，以及如何使用 API 进行下单、查询订单状态、获取账户余额等核心操作。

API 密钥

使用 Binance API 进行交易和数据访问的第一步是生成 API 密钥。API 密钥是您与 Binance 平台进行安全交互的凭证。 登录您的 Binance 账户，导航至 "API 管理" 页面。通常，该页面位于您的账户设置或个人资料区域。 在该页面，您将看到创建新的 API 密钥的选项。

创建 API 密钥时，请务必选择一个易于识别的标签，以便日后管理。 生成 API 密钥后，Binance 会提供两个关键信息：API 密钥（API Key）和密钥（Secret Key）。 请务必妥善保管 API 密钥和密钥（Secret Key），避免泄露。 API 密钥用于识别您的账户，而密钥用于验证您的请求。 密钥泄露可能导致您的账户被恶意利用，造成资金损失。建议使用密码管理器安全存储这些密钥。

在创建 API 密钥时，您需要配置相应的权限。常见的权限包括：

• 启用交易权限： 允许通过 API 进行买卖交易。如果您的目的是进行量化交易或自动化交易，则必须启用此权限。
• 启用读取权限： 允许通过 API 获取市场数据、账户信息等。即使您不进行交易，也可能需要此权限来分析市场数据。
• 启用提现权限： 允许通过API进行提现操作，高风险，不建议开启，如需开启请务必设置IP限制。

创建 API 密钥后，强烈建议配置 IP 访问限制，以增加安全性。 这意味着只有来自特定 IP 地址的请求才会被接受。 通过限制 IP 访问，即使您的 API 密钥泄露，攻击者也无法从未经授权的 IP 地址访问您的账户。 建议只允许您服务器或本地机器的 IP 地址访问 API。 Binance 允许您添加多个 IP 地址到白名单。请定期审查和更新您的 IP 白名单，确保其准确性和安全性。

定期更换 API 密钥也是一种良好的安全实践。您可以定期删除旧的 API 密钥并创建新的 API 密钥。 请密切监控您的 API 使用情况，及时发现任何异常活动。 Binance 提供 API 使用统计信息，可以帮助您识别潜在的安全问题。

API Endpoint 和 REST API

Binance API 采用 REST（Representational State Transfer）架构风格，这是一种广泛应用于构建网络服务的架构模式。REST API 通过标准的 HTTP 请求进行数据交互，实现了客户端与服务器之间的通信。理解 REST 架构对于有效使用 Binance API 至关重要。

API Endpoint 是构成 API 功能的所有 HTTP 请求的基础 URL。可以将 Endpoint 理解为 API 服务的入口点。对于现货交易，常用的公共 Endpoint 是 https://api.binance.com 。所有针对现货市场的 API 调用都会以这个 URL 作为前缀。 为了满足不同的交易需求和产品线，Binance 也提供了专门的 Endpoint，例如，用于币安期货交易的 Endpoint，以及用于测试目的的沙盒环境 Endpoint。 了解并正确使用对应的 Endpoint 是进行高效 API 开发的关键。

REST API 利用 HTTP 协议中定义的多种方法（也称为动词）来执行不同的操作。常见的 HTTP 方法包括： GET 、 POST 、 PUT 和 DELETE 。每种方法都对应着特定的操作语义。 例如，使用 GET 请求从服务器获取市场数据，如最新的交易价格、交易量和订单簿信息。 POST 请求通常用于向服务器发送数据，比如提交新的订单。 在 Binance API 的上下文中，提交买单或卖单通常会使用 POST 方法。 PUT 请求用于更新服务器上的资源，而 DELETE 请求用于删除资源。 掌握这些 HTTP 方法的使用是正确调用 Binance API 的基础。

身份验证

在加密货币交易平台中，为了确保账户和交易的安全，所有需要身份验证的 API 请求都必须包含签名。这个签名是一种安全机制，用于验证请求的来源和内容的完整性。签名本质上是基于请求参数和您的私有 Secret Key 生成的哈希值。通过验证签名，服务器可以确认请求是否来自授权用户，以及请求内容是否被篡改。

以下是生成签名的详细步骤，务必严格按照以下流程操作：

1. 收集所有请求参数： 收集所有需要发送给 API 的请求参数，包括 API 密钥 (通常名为 apiKey 或类似名称)。请务必包含所有参数，遗漏任何参数都会导致签名验证失败。
2. 参数排序： 将收集到的所有请求参数按照其键 (Key) 的字母顺序进行排序。排序是区分大小写的，并且必须与平台的要求一致。例如，参数 symbol 应该在 timestamp 之前。正确的排序是生成有效签名的关键。
3. 构建参数字符串： 将排序后的参数和它们对应的值连接成一个单独的字符串。参数名和参数值之间通常用等号 ( = ) 连接，不同的参数对之间通常使用与符号 ( & ) 连接。例如： apiKey=your_api_key&symbol=BTCUSDT&timestamp=1678886400000 。
4. HMAC-SHA256 哈希运算： 使用 HMAC-SHA256 算法，以您的 Secret Key 作为密钥，对上一步骤中构建的字符串进行哈希运算。HMAC-SHA256 是一种安全的哈希算法，它结合了密钥和消息内容，生成一个唯一的哈希值。Secret Key 必须妥善保管，绝对不能泄露给他人，因为它相当于您的账户密码。
5. 添加签名参数： 将生成的哈希值作为 signature 参数添加到请求中。这个 signature 参数将与其他的请求参数一起发送给 API 服务器。服务器会使用相同的算法和密钥，对接收到的参数重新计算签名，并与您发送的签名进行比较。如果两个签名一致，则表明请求是有效的。

不同的编程语言提供了不同的 HMAC-SHA256 库来实现签名生成。务必选择可靠且经过验证的库。建议参考您所使用的加密货币交易平台的 API 文档中提供的代码示例，以确保签名生成的正确性。例如，Python 中可以使用 hmac 和 hashlib 模块，Java 中可以使用 javax.crypto 包，JavaScript 中可以使用 crypto 模块。

常用 API 操作

获取账户信息

使用 GET /api/v3/account 端点可以获取账户的详细信息。这些信息包括您的可用余额、当前持仓情况、账户状态、以及其他重要的账户参数。请注意，为了保障账户安全，此请求需要进行身份验证，未经授权的访问将被拒绝。

GET /api/v3/account?timestamp= &signature=

上述请求示例展示了如何构建一个获取账户信息的请求。其中， 代表当前时间戳，时间戳是以 Unix 时间表示的自 Epoch（1970 年 1 月 1 日 00:00:00 UTC）以来的秒数。 则是根据请求参数（包括时间戳等）以及您的 Secret Key 通过 HMAC-SHA256 等加密算法生成的数字签名。这个签名用于验证请求的完整性和真实性，防止恶意篡改。请务必妥善保管您的 Secret Key，切勿泄露给他人，避免资产损失。签名生成的具体流程和算法请参考交易所的API文档。

获取市场数据

• 获取行情： 使用 GET /api/v3/ticker/price Endpoint 可以获取指定交易对的实时最新价格。此接口提供快速访问当前市场价格的途径，无需复杂的参数配置。

  示例： GET /api/v3/ticker/price?symbol=BTCUSDT 此请求将返回BTCUSDT交易对的当前价格。

  说明： 通过更改 symbol 参数，可以查询任何支持的交易对价格。例如，查询ETHUSDT的价格，可以将 symbol 设置为 ETHUSDT 。

• 获取 K 线数据： 使用 GET /api/v3/klines Endpoint 可以获取指定交易对的历史K线数据，用于技术分析和趋势预测。

  示例： GET /api/v3/klines?symbol=BTCUSDT&interval=1m 此请求将返回BTCUSDT交易对的1分钟K线数据。

  interval 参数指定 K 线的时间间隔，常见的选项包括 1m (1 分钟), 5m (5 分钟), 15m (15分钟), 30m (30分钟), 1h (1 小时), 4h (4 小时), 12h (12 小时), 1d (1 天), 1w (1 周), 1M (1 月)。选择合适的 interval 取决于你的分析周期。

  补充说明： 还可以通过添加 startTime 和 endTime 参数来指定返回 K 线数据的时间范围，时间戳单位为毫秒。例如： GET /api/v3/klines?symbol=BTCUSDT&interval=1h&startTime=1672531200000&endTime=1672617600000 将返回2023年1月1日0点到2023年1月2日0点的BTCUSDT的1小时K线数据。

• 获取深度数据： 使用 GET /api/v3/depth Endpoint 可以获取指定交易对的订单簿深度数据，包括买单（Bid）和卖单（Ask）信息，用于评估市场流动性和潜在的价格支撑/阻力位。

  示例： GET /api/v3/depth?symbol=BTCUSDT&limit=100 此请求将返回BTCUSDT交易对的买卖盘各100条数据。

  limit 参数指定返回的订单数量，范围通常在1到5000之间。更高的 limit 值提供更详细的订单簿视图，但会增加响应时间。选择合适的 limit 取决于你的分析需求。

  注意事项： 深度数据是动态变化的，需要实时更新才能反映市场的真实状况。一些交易所提供WebSocket API，允许客户端订阅深度数据更新，实现实时监控。

下单

使用 POST /api/v3/order Endpoint 可以提交新的订单。此请求必须进行身份验证，需要有效的API密钥和签名。

POST /api/v3/order 请求的基本结构如下：

POST /api/v3/order?symbol= &side= &type= &quantity= [&price= ]&timestamp= &signature= [&timeInForce= ][&stopPrice= ][&icebergQty= ][&newClientOrderId= ][&newOrderRespType= ]

• symbol : 交易对，指定要交易的资产对，例如 BTCUSDT ，表示比特币兑美元。必须为平台支持的有效交易对。
• side : 交易方向，指定交易意图。 BUY 表示买入， SELL 表示卖出。
• type : 订单类型，定义订单的执行方式。支持的订单类型包括：
  • LIMIT : 限价单，以指定的价格买入或卖出。只有当市场价格达到或优于指定价格时，订单才会被执行。需要指定 price 和 quantity 。
  • MARKET : 市价单，以当前市场最优价格立即买入或卖出。只需指定 quantity 。
  • STOP_LOSS : 止损单，当市场价格达到指定的止损价格时，订单会以市价单的形式执行。需要指定 stopPrice 和 quantity 。
  • STOP_LOSS_LIMIT : 止损限价单，当市场价格达到指定的止损价格时，订单会以限价单的形式挂出。需要指定 stopPrice , price 和 quantity 。
  • TAKE_PROFIT : 止盈单，当市场价格达到指定的止盈价格时，订单会以市价单的形式执行。需要指定 stopPrice 和 quantity 。
  • TAKE_PROFIT_LIMIT : 止盈限价单，当市场价格达到指定的止盈价格时，订单会以限价单的形式挂出。需要指定 stopPrice , price 和 quantity 。
  • LIMIT_MAKER : 限价挂单，一种特殊的限价单，如果订单立即成交，则会被取消。用于提供流动性，避免吃单。需要指定 price 和 quantity 。
• quantity : 交易数量，指定要买入或卖出的资产数量。
• price : 订单价格，仅用于限价单 ( LIMIT , STOP_LOSS_LIMIT , TAKE_PROFIT_LIMIT , LIMIT_MAKER )。指定希望买入或卖出的价格。
• timeInForce : 有效时间，指定订单的有效时长。仅用于限价单 ( LIMIT , STOP_LOSS_LIMIT , TAKE_PROFIT_LIMIT )。
  • GTC : Good Till Cancelled (持续有效)，订单会一直有效，直到被完全执行或手动取消。
  • IOC : Immediate Or Cancel (立即执行或取消)，订单尝试立即以指定价格成交，任何未成交的部分会被立即取消。
  • FOK : Fill Or Kill (全部成交或取消)，订单必须立即以指定价格全部成交，否则整个订单会被取消。
• stopPrice : 止损/止盈价格，用于止损单 ( STOP_LOSS , STOP_LOSS_LIMIT ) 和止盈单 ( TAKE_PROFIT , TAKE_PROFIT_LIMIT )。
• icebergQty : 冰山委托数量，用于隐藏大额订单，仅显示一部分数量。
• newClientOrderId : 用户自定义的订单ID，方便用户跟踪订单。
• newOrderRespType : 订单响应类型。指定服务器返回的订单信息类型。可选值包括 ACK , RESULT , FULL 。

示例:

• 市价买入:

POST /api/v3/order?symbol=BTCUSDT&side=BUY&type=MARKET&quantity=0.01&timestamp= &signature=

• 限价卖出:

POST /api/v3/order?symbol=BTCUSDT&side=SELL&type=LIMIT&quantity=0.01&price=50000&timeInForce=GTC&timestamp= &signature=

• 止损限价卖出:

POST /api/v3/order?symbol=BTCUSDT&side=SELL&type=STOP_LOSS_LIMIT&quantity=0.01&price=49000&stopPrice=49500&timeInForce=GTC&timestamp= &signature=

查询订单状态

使用 GET /api/v3/order Endpoint 可以查询订单的当前状态。访问此接口需要进行身份验证，以确保交易安全。

GET /api/v3/order?symbol= &orderId= &timestamp= &signature=

• symbol : 交易对的标识符，例如 BTCUSDT ，明确指定要查询的订单所属的交易市场。
• orderId : 订单的唯一数字标识符，用于在交易所系统中精确定位目标订单。

参数说明：

• timestamp : 发起请求的时间戳，以 Unix 毫秒为单位。这有助于防止重放攻击，提高安全性。
• signature : 使用您的 API 密钥的密钥（secret key）对请求参数生成的数字签名。 该签名用于验证请求的完整性和真实性。 生成签名是确保API请求安全的关键步骤。请参阅API文档中的签名生成部分，了解详细的签名算法和实现方法。

请求示例：

假设要查询交易对为 ETHBTC ，订单ID为 123456789 的订单，并且当前时间戳为 1678886400000 。 你需要计算包含必要的参数的签名。

注意事项：

• 务必提供正确的 symbol 和 orderId ，否则将无法找到对应的订单。
• 时间戳 timestamp 必须在服务器允许的时间范围内，以防止重放攻击。
• 签名 signature 必须正确计算，否则请求将被服务器拒绝。有关详细的签名计算方法，请参考API文档。
• 出于安全考虑，请勿在客户端代码中硬编码您的 API 密钥的密钥 (secret key)。 使用服务器端代码来处理签名生成过程。

取消订单

使用 DELETE /api/v3/order Endpoint 可以取消现有的挂单。为了确保交易安全，该请求需要通过API密钥进行身份验证，以验证请求的合法性。

取消订单的请求格式如下：

DELETE /api/v3/order?symbol=&orderId=&timestamp=&signature=

其中，各个参数的含义如下：

• symbol : 指定要取消订单的交易对，例如 BTCUSDT 表示比特币兑换泰达币的交易对。这是必填参数。
• orderId : 需要取消的订单的唯一标识符。每个订单在创建时都会被分配一个唯一的 ID，通过指定此 ID 可以精确取消特定订单。这也是必填参数。
• timestamp : 发送请求时的时间戳（Unix 时间，毫秒）。时间戳用于验证请求的有效性，防止重放攻击。
• signature : 使用您的 API 密钥的私钥生成的签名，用于验证请求的完整性和身份。签名需要包含所有请求参数（包括 timestamp ）以及您的 API 密钥的私钥。 签名算法通常使用 HMAC-SHA256。

注意事项:

• 请务必确保您的API密钥具有取消订单的权限。
• 时间戳的有效窗口通常很短，如果请求的时间戳与服务器时间相差太远，请求可能会失败。
• 错误的签名将导致请求失败。请仔细检查您的签名生成代码。
• 订单取消成功后，您会收到一个确认响应。

Rate Limits (速率限制)

币安 (Binance) API 为了保障系统稳定运行，防止恶意攻击及资源滥用，实施了严格的速率限制机制。这些限制并非全局统一，而是针对不同的 Endpoint (端点) 和 API 密钥进行差异化配置。这意味着访问特定接口或使用特定API密钥的用户，其请求频率上限可能有所不同。

一旦超过预设的速率限制，API 将返回明确的错误代码，通常是 HTTP 状态码 429 (Too Many Requests)，并可能包含描述性信息，告知开发者超出了允许的请求频率。开发者必须密切关注这些错误信息，以便及时调整请求策略。

为了避免触及速率限制，开发者需要仔细研读 Binance API 官方文档，特别是关于速率限制部分的详细说明。文档会明确指出每个 Endpoint 的请求频率上限，以及可能影响速率限制的因素，例如请求权重 (request weight)。

实际开发中，开发者可以采取多种策略来有效控制请求频率。一种常见做法是使用缓存机制，将 API 返回的数据缓存一段时间，减少对 API 的直接请求次数。另一种方法是采用请求队列，将所有 API 请求放入队列中，按照预设的频率逐个发送，避免突发的大量请求同时发送。还可以考虑优化 API 请求的结构，减少不必要的数据传输，从而降低请求权重。开发者应该根据自身应用的特点和需求，灵活选择合适的策略，确保API请求在允许的范围内，并保证应用程序的正常运行。还可以使用指数退避(Exponential Backoff)策略，在收到速率限制错误后，逐渐增加重试请求的间隔，避免持续触发速率限制。

WebSocket API

除了传统的 REST API，币安还提供强大的 WebSocket API，专门用于实时数据推送。WebSocket API 允许开发者以极低的延迟获取关键的市场数据、用户账户信息以及订单状态更新。与需要频繁请求的 REST API 相比，WebSocket API 通过建立持久连接，显著提升了数据传输效率，尤其适用于高频交易和对数据实时性要求极高的交易策略。

通过 WebSocket API，您可以订阅多种实时数据流，包括但不限于：

• 市场行情数据： 实时价格、交易量、深度数据等，覆盖币安交易所的所有交易对。
• K线数据： 提供不同时间周期的K线图数据，满足技术分析的需求。
• 交易数据： 实时发生的交易信息，包括成交价、成交量和交易方向。
• 个人账户信息： 账户余额、持仓信息、交易历史等，方便用户监控账户状态。
• 订单状态更新： 订单的创建、挂单、成交、撤销等状态变化，确保用户及时了解订单执行情况。

使用 WebSocket API 的优势体现在以下几个方面：

• 低延迟： 数据以推送方式实时传输，避免了轮询带来的延迟，对高频交易至关重要。
• 高效率： 减少了不必要的网络请求，降低了服务器负载，提高了数据传输效率。
• 实时性： 确保用户能够第一时间获取最新的市场动态和账户信息，做出快速决策。

总而言之，对于需要实时数据驱动的交易策略，例如量化交易、程序化交易等，WebSocket API 是一个不可或缺的工具。开发者可以利用 WebSocket API 构建更加智能、高效的交易系统。

错误处理

Binance API 接口交互过程中，错误处理至关重要。通过分析 API 返回的错误代码，开发者能够有效地诊断并解决问题，确保交易流程的稳定性和可靠性。理解和正确处理这些错误代码是构建健壮应用程序的基础。

Binance API 返回的错误代码是数字化的错误标识符，每个代码对应着特定的错误类型。开发者应参考官方 API 文档，详细了解每个错误代码的具体含义和可能的原因。以下是一些常见的错误代码示例，以及相应的处理建议：

• -1000 : 未知错误。表示服务器遇到了未预料到的问题，无法明确指示错误原因。开发者应记录详细的请求信息，例如请求参数、时间戳等，并尝试重试。如果问题持续存在，应联系 Binance 技术支持，提供相关日志以便进一步排查。
• -1002 : 身份验证失败。通常表示 API 密钥 (API Key) 或密钥安全码 (Secret Key) 不正确，或者 IP 地址访问权限受限。请仔细检查 API 密钥是否正确配置，以及 IP 地址是否已添加到 Binance API 的白名单中。请确保 API 密钥已启用，并具有足够的权限。
• -1013 : 订单失败。可能的原因包括订单参数无效（如价格、数量超出范围）、交易规则限制（如最小交易数量）、账户状态异常等。开发者应仔细检查订单参数是否符合 Binance 的交易规则，并确保账户处于正常状态。API 文档会详细说明各种订单参数的限制。
• -2010 : 账户余额不足。表明您的账户没有足够的可用资金来执行交易。请检查账户余额，确保有足够的资金支付交易费用和满足订单金额。可以通过 Binance API 获取账户余额信息。
• -2011 : 订单不存在。通常发生在尝试取消或查询一个不存在的订单时。请确认订单 ID 是否正确，或者订单是否已被成功取消或成交。在取消订单前，最好先查询订单状态，确认订单仍然存在。

开发者应该根据不同的错误代码，采取相应的处理措施。建议在代码中实现完善的错误处理机制，例如使用 try-except 语句捕获 API 返回的异常，并根据错误代码进行相应的处理。对于可能影响用户体验的错误，应向用户提供友好的错误提示信息。建议记录详细的错误日志，以便追踪和分析问题。

安全注意事项

• 务必妥善保管 API 密钥和 Secret Key。 API 密钥和 Secret Key 是访问您账户的关键凭证，一旦泄露，可能导致资产损失或未经授权的操作。请使用高强度随机密码，并将其存储在安全的地方，例如硬件钱包或加密的密码管理器中。切勿将 API 密钥和 Secret Key 存储在代码库、公共存储库或以任何其他不安全的方式共享。
• 启用 IP 访问限制。 通过限制可以访问您的 API 密钥的 IP 地址，可以有效防止未经授权的访问。只允许来自您信任的服务器或应用程序的 IP 地址访问 API。 大多数交易所或 API 提供商都允许您在账户设置中配置 IP 访问限制。
• 定期检查 API 密钥的权限。 确保您的 API 密钥仅具有执行必要操作的最低权限。例如，如果您的应用程序只需要读取市场数据，则不要授予 API 密钥提款权限。定期审查 API 密钥的权限，并根据需要进行调整。
• 使用安全的编程实践，防止代码漏洞。 不安全的编码实践可能导致漏洞，攻击者可以利用这些漏洞来访问您的 API 密钥或执行其他恶意操作。使用参数化查询来防止 SQL 注入，并验证所有用户输入以防止跨站点脚本 (XSS) 攻击。使用最新的安全库和框架，并定期更新您的代码。
• 监控 API 请求的频率，避免超过速率限制。 API 提供商通常会实施速率限制，以防止滥用并确保所有用户的服务质量。超过速率限制可能会导致 API 密钥被暂时或永久禁用。监控您的 API 请求的频率，并实施重试机制以处理速率限制错误。
• 在生产环境中使用 API 之前，先在测试环境中进行充分测试。 在将您的应用程序部署到生产环境之前，请务必在测试环境中进行充分测试。使用模拟数据和测试 API 密钥来验证您的应用程序是否按预期工作，并且不会出现任何错误或漏洞。