速看！币安API接口终极指南：轻松上手，玩转交易！

目录： 案例 阅读：107

币安交易所API接口开发指南

简介

币安（Binance）作为全球领先的加密货币交易所，拥有庞大的用户群体和极高的交易量。为满足日益增长的自动化交易和数据分析需求，币安提供了功能强大的应用程序编程接口（API）。这些API接口允许开发者通过编写代码，以编程方式安全高效地访问币安交易所的实时市场数据、交易历史、账户信息以及执行交易等功能。本文档旨在提供一个简明的指南，帮助经验丰富的开发者以及对加密货币API感兴趣的新手快速理解和有效使用币安交易所的API接口，并强调使用API​​密钥进行安全访问的重要性。

API类型

币安提供多种类型的应用程序编程接口（API），旨在满足不同用户的多样化需求，从简单的信息查询到复杂的自动化交易，都能找到合适的接口。

  • REST API： 用于获取历史和实时市场数据、管理账户信息、执行交易指令等核心功能。REST API遵循表述性状态转移（Representational State Transfer）架构风格，基于HTTP协议，并采用JavaScript对象简谱（JSON）格式进行数据交互。这意味着开发者可以使用标准的HTTP方法（如GET、POST、PUT、DELETE）与币安服务器进行通信，并通过JSON格式高效地发送和接收数据。API密钥用于身份验证，确保账户安全。
  • WebSocket API： 用于实时订阅并接收市场数据和账户更新，例如最新的交易价格、订单簿变化以及账户余额变动。WebSocket API提供低延迟、双向通信的数据流，避免了频繁轮询服务器的开销，显著降低了网络延迟，因此尤其适用于需要快速响应的应用场景，如高频交易机器人、实时行情监控系统和自动化交易平台。通过WebSocket连接，可以实时获取市场动态和账户状态，及时调整交易策略。

身份验证

访问币安API中某些特定端点，特别是那些涉及用户账户信息查询、资金划转以及交易执行的端点，必须通过身份验证机制进行授权。币安采用API Key和Secret Key这对密钥组合来实现身份验证，确保只有授权用户才能访问敏感数据和功能。

  1. 生成API Key： 要开始使用API，首先需要登录您的币安账户。然后，导航至“API管理”页面，在这里您可以创建新的API Key。在创建过程中，系统会同时生成一个API Key和一个Secret Key。务必高度重视Secret Key的安全性，切勿将其泄露给任何第三方，因为泄露Secret Key可能导致您的账户遭受未经授权的访问和操作。请将其视为密码一样妥善保管。
  2. 请求签名： 对于需要身份验证的REST API请求，为了验证请求的真实性和完整性，需要对请求参数进行签名。签名过程涉及一系列步骤，确保请求在传输过程中未被篡改。签名算法如下：
    • 参数排序： 将所有请求参数（包括 timestamp ）按照其参数名称的字母顺序进行字典排序。这一步至关重要，因为签名算法对参数顺序非常敏感。
    • 字符串拼接： 将排序后的参数名称和对应的值拼接成一个单一的字符串。注意，参数名和参数值之间通常使用等号（=）连接，而不同的参数对之间则使用&符号连接。确保所有参数都包含在此字符串中。
    • HMAC-SHA256加密： 使用您的Secret Key作为密钥，对拼接后的参数字符串执行HMAC-SHA256加密算法。HMAC-SHA256是一种安全的哈希算法，可确保签名的唯一性和不可伪造性。
    • 添加签名参数： 将加密后生成的哈希值作为名为 signature 的参数添加到请求参数中。这个 signature 参数是验证请求身份的关键。

    需要特别注意的是， timestamp 参数是所有需要身份验证的API请求中必不可少的参数。它表示请求被创建的时间戳，以毫秒为单位。 timestamp 参数用于防止重放攻击，即攻击者截获并重新发送先前有效的请求。币安服务器会验证 timestamp 的有效性，如果请求的时间戳与服务器当前时间相差过大，则该请求将被视为无效。

REST API

基础URL

币安REST API是访问币安交易所各种功能的入口。根据您交易的产品类型，需要使用不同的基础URL。对于现货交易，使用以下URL： https://api.binance.com 。此URL提供现货交易对的相关数据和交易接口。

如果您进行的是U本位合约交易，则应使用： https://fapi.binance.com 。U本位合约是指以USDT或其他稳定币作为保证金的合约。通过此URL，您可以访问与U本位合约相关的市场数据、下单接口以及账户信息。

对于币本位合约交易，则需要使用： https://dapi.binance.com 。币本位合约是指以加密货币（如BTC）作为保证金的合约。此URL提供币本位合约的市场数据、交易接口及账户管理功能。

公共Endpoint

公共Endpoint无需进行API密钥验证，任何人都可以访问，主要用于获取实时市场数据，例如交易对价格、交易深度等信息，方便用户进行行情分析和交易决策。

  • GET /api/v3/ping： 用于测试与API服务器的连接是否正常，确认服务可用性。如果API服务器正常运行，将返回一个简单的JSON响应，表明连接成功。

    GET https://api.binance.com/api/v3/ping

  • GET /api/v3/time： 获取服务器当前的时间戳，以毫秒为单位。此Endpoint对于同步客户端时间至关重要，确保交易请求的时效性，避免因时间偏差导致的请求失败。

    GET https://api.binance.com/api/v3/time

  • GET /api/v3/depth： 获取指定交易对的实时深度信息（Order Book），展示买单和卖单的挂单价格和数量，帮助用户了解市场供需关系和流动性状况。

    GET https://api.binance.com/api.com/api/v3/depth?symbol=BTCUSDT&limit=100

    • symbol ：指定需要查询的交易对，例如 BTCUSDT ，代表比特币与USDT的交易对。大小写敏感。
    • limit ：限制返回的深度信息的数量，可选值为 5, 10, 20, 50, 100, 500, 1000, 5000。数值越小，响应速度越快，但包含的信息越少；数值越大，信息越全面，但响应时间可能较长。
  • GET /api/v3/trades： 获取指定交易对的最近成交记录，展示历史成交的价格和数量，帮助用户追踪市场交易动态和趋势。

    GET https://api.binance.com/api/v3/trades?symbol=BTCUSDT&limit=100

    • symbol ：指定需要查询的交易对，例如 BTCUSDT 。
    • limit ：限制返回的成交记录的数量，默认值为500，最大值为1000。如果未指定此参数，API将默认返回最近的500条成交记录。
  • GET /api/v3/klines： 获取指定交易对的K线数据（Candlestick Charts），K线图以图形化的方式展示一段时间内的开盘价、最高价、最低价和收盘价，是技术分析的重要工具。

    GET https://api.binance.com/api/v3/klines?symbol=BTCUSDT&interval=1m&limit=100

    • symbol ：指定需要查询的交易对，例如 BTCUSDT 。
    • 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月）。
    • limit ：限制返回的K线数据的数量，默认值为500，最大值为1000。

账户Endpoint

账户Endpoint需要身份验证才能访问，主要用于获取用户账户信息，进行下单交易，查询挂单状态以及撤销订单等操作。所有请求都需要在HTTP请求头中添加 X-MBX-APIKEY ，其值为您在交易所生成的API Key，用于身份验证。

  • GET /api/v3/account：获取账户信息

    该接口用于检索您的账户详情，包括可用余额、已冻结余额以及其他账户相关信息。

    请求示例： GET https://api.binance.com/api/v3/account?timestamp= &signature=

    • timestamp ：请求的时间戳，以毫秒为单位。表示请求发送的具体时间，用于防止重放攻击。
    • signature ：请求签名，通过HMAC SHA256算法对请求参数和密钥进行加密生成，用于验证请求的完整性和身份。

  • POST /api/v3/order：下单

    该接口允许您提交新的交易订单。支持多种订单类型和参数配置。

    请求示例： 

    POST https://api.binance.com/api/v3/order
Content-Type: application/x-www-form-urlencoded
symbol=BTCUSDT&side=BUY&type=MARKET&quantity=0.01&timestamp=&signature=
    • symbol ：交易对，指定您要交易的资产对。例如， BTCUSDT 表示比特币兑美元。
    • side ：交易方向，指示您是买入还是卖出。可选值为 BUY （买入）或 SELL （卖出）。
    • type ：订单类型，定义订单的执行方式。常用的订单类型包括 MARKET （市价单，以当前市场最优价格立即成交）， LIMIT （限价单，以指定价格或更好价格成交）， STOP_LOSS （止损单，当市场价格达到指定止损价时触发市价单）， TAKE_PROFIT （止盈单，当市场价格达到指定止盈价时触发市价单）， STOP_LOSS_LIMIT (止损限价单，当市场价格达到指定止损价时触发限价单), TAKE_PROFIT_LIMIT (止盈限价单，当市场价格达到指定止盈价时触发限价单)。
    • quantity ：交易数量，表示您要买入或卖出的资产数量。
    • price ：限价单的价格，仅当 type 为 LIMIT , STOP_LOSS_LIMIT 或 TAKE_PROFIT_LIMIT 时需要。指定您希望成交的价格。
    • stopPrice ：止损单或止盈单的触发价格，仅当 type 为 STOP_LOSS , TAKE_PROFIT , STOP_LOSS_LIMIT 或 TAKE_PROFIT_LIMIT 时需要。指定触发订单的价格。
    • timeInForce ：订单有效时间，用于限定限价单的有效性。可选值为 GTC （Good Till Cancel，订单持续有效，直到被成交或取消）， IOC （Immediate Or Cancel，订单立即成交，未成交部分立即取消）， FOK （Fill Or Kill，订单必须全部立即成交，否则立即取消）， GTX (Good Till Crossing，仅作为挂单，不会立即吃单)。仅当 type 为 LIMIT 时需要。
    • timestamp ：请求的时间戳（毫秒）。
    • signature ：请求签名。
    • newClientOrderId : 客户端自定义订单ID，用于区分不同的订单，方便追踪。

  • GET /api/v3/openOrders：获取当前挂单

    该接口用于检索您当前所有未成交的挂单信息。

    请求示例： GET https://api.binance.com/api/v3/openOrders?timestamp= &signature=

    • timestamp ：请求的时间戳（毫秒）。
    • signature ：请求签名。
    • symbol (可选)：指定交易对，只返回该交易对的挂单。

  • DELETE /api/v3/order：撤销订单

    该接口允许您取消尚未成交的订单。

    请求示例： DELETE https://api.binance.com/api/v3/order?symbol=BTCUSDT&orderId= &timestamp= &signature=

    • symbol ：交易对，例如 BTCUSDT 。指定要撤销订单的交易对。
    • orderId ：订单ID，指定要撤销的订单的唯一标识符。可以使用 GET /api/v3/openOrders 接口获取。
    • origClientOrderId (可选): 原始客户端自定义订单ID。如果同时提供了 orderId 和 origClientOrderId ，则优先使用 orderId 进行撤单。
    • timestamp ：请求的时间戳（毫秒）。
    • signature ：请求签名。

WebSocket API

连接URL

币安WebSocket API提供实时市场数据和账户信息的访问入口。连接时，需根据交易类型选择不同的URL。

现货交易的WebSocket API连接URL为： wss://stream.binance.com:9443/ws/ 。其中 需要替换为具体的订阅流名称，例如 btcusdt@trade 表示订阅BTC/USDT的实时成交数据流。端口号9443为默认端口，在某些情况下可能会变更，建议参考官方文档。

U本位合约交易的WebSocket API连接URL为： wss://fstream.binance.com/ws/ 。同样， 需要替换为订阅的合约数据流名称。例如，订阅BTCUSDT永续合约的实时成交数据流，可以使用 btcusdt@trade 。

币本位合约交易的WebSocket API连接URL为： wss://dstream.binance.com/ws/ 。与U本位合约类似， 代表需要订阅的具体合约数据流名称。例如，订阅BTCUSD季度合约的实时成交数据流，可以使用 btcusd_231231@trade ，注意这里合约代码与U本位合约有所不同。

连接建立后，客户端需要发送JSON格式的订阅消息才能接收数据。具体的订阅消息格式和可用数据流名称，请参考币安官方API文档，不同类型的数据流有不同的订阅格式和返回数据结构。需要注意API的使用频率限制，避免触发风控策略。

订阅数据流

为了实时获取市场数据，您可以通过发送JSON格式的消息订阅不同的数据流。这些数据流提供了交易、行情和其他关键市场信息，方便您进行量化交易和数据分析。

  • 单个交易对的Trade数据流：

    • 通过订阅单个交易对的Trade数据流，您可以接收该交易对的实时成交数据，包括成交价格、成交数量、成交时间等详细信息。 

    {
   "method": "SUBSCRIBE",
   "params":  [
    "btcusdt@trade"
  ],
   "id": 1
}

    上述JSON消息示例演示了如何订阅 btcusdt 交易对的Trade数据流。 method 字段指定为 SUBSCRIBE ，表示订阅操作。 params 字段包含一个数组，其中包含要订阅的数据流名称，例如 btcusdt@trade 。 id 字段用于标识请求，方便追踪响应。

  • 多个交易对的Trade数据流：

    • 您可以同时订阅多个交易对的Trade数据流，以便同时监控多个市场的实时成交数据。这对于需要跨市场分析和套利的交易者非常有用。 

    {
  "method": "SUBSCRIBE",
  "params": [
     "btcusdt@trade",
    "ethusdt@trade"
  ],
  "id": 1
}

    上述JSON消息示例演示了如何同时订阅 btcusdt 和 ethusdt 交易对的Trade数据流。 在 params 数组中添加多个数据流名称即可实现多交易对订阅。

  • 所有交易对的Trade数据流：

    • 订阅所有交易对的Trade数据流，您可以接收平台上所有交易对的实时成交数据。这对于需要进行全市场监控和数据分析的用户非常有用，但请注意，大量数据可能会对您的系统资源造成较大压力。 

    {
    "method": "SUBSCRIBE",
   "params": [
      "!ticker@arr"
    ],
   "id": 1
}

    上述JSON消息示例演示了如何订阅所有交易对的Trade数据流。 使用通配符 !ticker@arr 可以订阅所有交易对的ticker数据流，该数据流包含了所有交易对的最新价格、成交量等信息。 请谨慎使用此选项，确保您的系统能够处理大量数据。

数据流类型

  • trade： 实时成交数据流，提供市场上最新发生的交易信息。该数据流包含成交价格、成交数量、成交时间以及买卖方向等关键字段，可用于实时监控市场动态，进行高频交易策略的执行，或作为其他分析指标的数据来源。
  • kline： K线数据流，也称为OHLC（Open, High, Low, Close）数据流，以特定时间间隔聚合交易数据。例如： btcusdt@kline_1m 表示BTCUSDT交易对的1分钟K线数据流。除了OHLC之外，通常还会包含成交量数据。K线数据常用于技术分析，帮助交易者识别趋势、支撑位、阻力位，以及评估市场情绪。不同时间周期的K线数据（如1分钟、5分钟、15分钟、1小时、1天）可满足不同交易策略的需求。
  • depth： 深度数据流，也称为订单簿数据流，反映了市场上买单和卖单的分布情况。例如： btcusdt@depth5@100ms 表示BTCUSDT交易对的5档深度数据，更新频率为100毫秒。深度数据包含买方和卖方的挂单价格和数量，档位越深，提供的市场流动性信息越全面。交易者可以通过分析深度数据来评估市场的买卖压力，预测价格的短期走势，以及进行套利交易。更新频率越高，对于高频交易和算法交易越有利。
  • userData： 用户数据流，需要身份验证才能访问。该数据流提供与特定用户账户相关的实时信息，包括账户余额、订单状态、成交记录、资产变动等。用户数据流是构建交易机器人、账户管理工具和风险控制系统的关键数据来源。由于涉及用户隐私和资产安全，访问用户数据流通常需要API密钥和签名验证，以确保只有授权用户才能获取相关数据。

错误处理

币安API在交互过程中，可能会由于多种原因返回错误信息。这些错误信息通常采用JSON格式，便于解析和处理。JSON响应中主要包含两个关键字段： code ，代表错误代码； msg ，则提供错误的详细描述信息，有助于开发者快速定位问题。

以下列出一些常见的币安API错误代码及其含义，但请注意，这并非完整的错误代码列表，实际应用中可能会遇到其他类型的错误。建议开发者参考币安官方API文档，获取最新的错误代码信息。

  • -1000 ： 未知错误 。通常表示服务器遇到了未预料到的问题，建议稍后重试。如果问题持续存在，可能需要联系币安技术支持。
  • -1001 ： 连接超时 。表明与币安服务器的连接在规定时间内未能建立或维持。可能的原因包括网络拥堵、服务器繁忙或客户端网络配置问题。建议检查网络连接，并尝试增加请求超时时间。
  • -1002 ： 身份验证失败 。这意味着提供的API密钥或签名不正确。务必确保API密钥已正确配置，并且用于生成签名的密钥是有效的。检查密钥是否过期或被禁用。
  • -1013 ： 订单数量过低 。说明尝试下单的数量低于交易所允许的最小交易单位。不同的交易对有不同的最小交易量限制，需要根据具体交易对进行调整。务必参考交易所的交易规则。
  • -1021 ： 时间戳超出范围 。 币安API要求请求中包含时间戳（timestamp），并且该时间戳需要在服务器允许的范围内。如果客户端与服务器的时间偏差过大，就会返回此错误。需要同步客户端时间或调整时间戳的计算方式。
  • -2011 ： 订单不存在 。表明尝试取消或查询的订单在系统中不存在。可能是订单已被成交、取消或从未创建。请确认订单ID是否正确。
  • -2015 ： 账户资金不足 。尝试进行交易时，账户中可用余额不足以支付交易所需的资金。请检查账户余额，并确保有足够的资金用于交易。

在开发过程中，务必对API返回的错误进行妥善处理。建议使用 try-catch 等机制捕获异常，并根据错误代码和信息采取相应的处理措施，例如重试、记录日志或通知用户。良好的错误处理能够提高程序的健壮性和用户体验。

Rate Limit

为保障所有用户的稳定访问体验，并防止API接口被恶意滥用或过度请求，币安交易所实施了API频率限制（Rate Limit）机制。该机制旨在确保API服务的公平性和可用性，避免因单一用户的过度请求导致系统资源耗尽，影响其他用户的正常访问。

当您的API请求频率超过预设的Rate Limit时，币安API服务器将会返回HTTP状态码 429 Too Many Requests 错误。这意味着您需要在一定时间内降低请求频率，否则您的请求将被拒绝。不同的API endpoint（例如交易接口、行情数据接口等）往往具有不同的Rate Limit策略，具体限制取决于接口的重要性和服务器负载情况。

建议开发者在程序设计和代码实现过程中，务必充分考虑并妥善处理Rate Limit错误。一种常见的处理方式是实现指数退避（Exponential Backoff）算法，即在接收到 429 错误后，程序暂停一段时间再进行重试，并且每次重试的等待时间递增。开发者还可以监控API响应头中的Rate Limit相关信息（通常包含剩余请求次数、重置时间等），以便动态调整请求频率，避免触发Rate Limit。正确处理Rate Limit错误是构建稳定、可靠的币安API应用程序的关键。

相关推荐：