币安API终极指南：手把手教你玩转交易接口！💰

时间： 分类：资讯 阅读：75

币安交易所API接口文档详解

本文档旨在详细解析币安交易所的API接口，帮助开发者更好地理解和使用这些接口，从而构建自己的交易策略、数据分析工具或集成到现有系统中。币安API提供了广泛的功能，包括现货交易、合约交易、杠杆交易、账户信息查询、市场数据获取等。

1. API 概览

币安API是连接用户与币安交易所的桥梁，允许开发者和交易者以编程方式访问和管理其账户、获取市场数据并执行交易。它主要分为以下几类，每类都提供特定的功能和服务：

  • 现货API: 涵盖现货交易的所有关键接口。该API允许用户进行现货交易活动，包括创建和管理订单（例如限价单、市价单等）、取消未成交订单、查询订单的当前状态（已成交、部分成交、已取消等）、获取账户中各种币种的余额信息。它还提供访问交易历史记录和计算交易费用的功能。
  • 合约API: 专注于合约交易功能，允许用户参与永续合约和交割合约的交易。除了下单和订单管理功能外，它还提供风险控制工具，例如设置止损和止盈订单，以及访问仓位信息。资金划转功能允许用户在合约账户和现货账户之间转移资金。合约API还支持获取合约的市场深度数据、指数价格和标记价格。
  • 杠杆API: 允许用户使用杠杆进行现货交易，从而放大潜在利润（以及潜在损失）。该API提供调整杠杆倍数的接口，用户可以根据自己的风险承受能力选择不同的杠杆比例。它还提供利息计算功能，以便用户了解使用杠杆的成本。杠杆API通常包含对用户可以借入的资产数量的限制。
  • Market Data API: 提供全面的市场数据接口，是获取实时和历史交易信息的关键。它提供实时的行情数据，例如最新成交价、最高价、最低价和成交量。用户还可以获取历史K线数据（不同时间周期，如1分钟、5分钟、1小时、1天等），用于技术分析。交易深度数据（订单簿）显示了市场上买单和卖单的价格和数量分布，帮助用户评估市场流动性。
  • 用户数据流API: 提供实时的用户账户数据更新，采用推送机制，无需用户主动轮询。通过WebSocket连接，用户可以接收订单状态的实时变化，包括订单的创建、修改、成交和取消。它还提供账户余额变化的实时通知，例如充值、提现、交易费用扣除等。这些实时数据更新对于构建自动化交易策略和监控账户活动至关重要。

2. 身份验证机制详解

访问币安API的每一位用户都必须进行身份验证，这是保障账户安全和数据完整性的首要措施。币安采用双密钥认证机制，即API Key（公钥）和Secret Key（私钥）。API Key用于标识您的身份，类似于用户名，而Secret Key则用于验证请求的真实性，如同密码，必须严格保密。

请务必将您的Secret Key妥善保管，切勿以任何形式泄露给任何第三方。任何持有您Secret Key的人都可以模拟您的身份进行交易和其他操作，造成不可挽回的损失。建议启用API访问的IP限制，进一步增强安全性。

对于需要身份验证的API接口，您需要在HTTP请求的Header中添加 X-MBX-APIKEY 字段，并将其值设置为您的API Key。 例如： X-MBX-APIKEY: YOUR_API_KEY 。这向币安服务器表明该请求来自于经过授权的用户。

除了API Key，大部分需要身份验证的API接口还需要数字签名。签名机制旨在防止恶意篡改请求参数，确保请求在传输过程中未被修改。币安的签名计算过程涉及以下关键步骤：

  1. 参数排序： 将所有请求参数，包括Query String中的参数和Body中的参数，按照字母顺序进行升序排列。务必保持参数名称的字母大小写一致，因为参数名称区分大小写。
  2. 参数拼接： 将排序后的所有参数键值对拼接成一个字符串。参数名和参数值之间用等号（=）连接，参数键值对之间直接连接，不使用任何分隔符。例如： symbol=BTCUSDTside=BUYtype=LIMIT 。
  3. HMAC SHA256加密： 使用您的Secret Key作为密钥，对拼接后的参数字符串进行HMAC SHA256加密。HMAC SHA256是一种单向散列函数，能够生成固定长度的哈希值，用于验证数据的完整性。不同的编程语言有不同的HMAC SHA256实现方式，请参考币安官方文档提供的示例代码。
  4. 添加签名参数： 将加密后的哈希值作为 signature 参数添加到您的请求中。通常， signature 参数会添加到Query String中，与其它请求参数一起发送。

3. 现货API详解

现货API是连接加密货币交易所的核心桥梁，它允许开发者和交易者以编程方式进行现货交易。通过这些API接口，用户可以自动化交易策略、构建交易机器人，并实时监控市场动态。以下是一些常用的现货API接口，详细介绍了其功能和关键参数：

  • POST /api/v3/order (Place Order): 下单接口，用于创建买入或卖出订单。该接口是执行交易的核心，必须提供精确的参数。
    • 交易对 (symbol): 指定交易的两种加密货币，例如：BTCUSDT。
    • 交易方向 (side): 指定买入 (BUY) 或卖出 (SELL)。
    • 订单类型 (type): 定义订单的执行方式，常见的包括：
      • 市价单 (MARKET): 以当前市场最优价格立即成交。
      • 限价单 (LIMIT): 以指定的价格挂单，等待市场价格达到该价格时成交。需要指定价格 (price)。
      • 止损单 (STOP_LOSS): 当市场价格达到指定止损价格时，自动以市价卖出。需要指定止损价格 (stopPrice)。
      • 止损限价单 (STOP_LOSS_LIMIT): 当市场价格达到指定止损价格时，自动以指定限价挂单。需要指定止损价格 (stopPrice) 和限价 (price)。
      • 限价止盈单 (TAKE_PROFIT_LIMIT): 当市场价格达到指定止盈价格时，自动以指定限价挂单。需要指定止盈价格 (stopPrice) 和限价 (price)。
    • 数量 (quantity): 指定交易的加密货币数量。
    • 价格 (price): 仅限价单需要指定，表示期望成交的价格。
    • 时间有效性 (timeInForce): 仅限价单需要指定，定义订单的有效时间，常见的有：
      • GTC (Good Till Canceled): 订单一直有效，直到被完全成交或手动取消。
      • IOC (Immediate Or Cancel): 订单立即成交，未成交部分立即取消。
      • FOK (Fill Or Kill): 订单必须全部立即成交，否则立即取消。
  • DELETE /api/v3/order (Cancel Order): 撤单接口，用于取消尚未完全成交的订单。
    • 交易对 (symbol): 指定交易对。
    • 订单ID (orderId): 指定要取消的订单的唯一标识符。
    • 原始客户端订单ID (origClientOrderId): 如果下单时指定了客户端订单ID，也可以使用此ID来取消订单。
  • GET /api/v3/order (Query Order): 查询订单接口，用于查询特定订单的状态。
    • 交易对 (symbol): 指定交易对。
    • 订单ID (orderId): 指定要查询的订单的唯一标识符。
    • 原始客户端订单ID (origClientOrderId): 如果下单时指定了客户端订单ID，也可以使用此ID来查询订单。

    该接口返回订单的详细信息，包括订单状态 (NEW, PARTIALLY_FILLED, FILLED, CANCELED, REJECTED, EXPIRED)、已成交数量、平均成交价格等。

  • GET /api/v3/openOrders (Current Open Orders): 查询当前未成交订单接口，用于获取所有或指定交易对的未成交订单列表。
    • 交易对 (symbol): 可选参数，指定交易对。如果不指定，则返回所有交易对的未成交订单。

    该接口返回一个包含所有未成交订单信息的数组。

  • GET /api/v3/account (Account Information): 查询账户信息接口，用于获取账户的余额信息。
    • 返回账户中所有资产的余额信息，包括可用余额 (free) 和冻结余额 (locked)。

    可用余额是指可以用于交易的余额，冻结余额是指已经被订单占用的余额。

  • GET /api/v3/myTrades (Account Trade List): 查询历史交易记录接口，用于获取账户的历史交易记录。
    • 交易对 (symbol): 指定交易对。
    • 起始时间 (startTime): 可选参数，指定查询的起始时间戳（毫秒）。
    • 结束时间 (endTime): 可选参数，指定查询的结束时间戳（毫秒）。
    • 限制 (limit): 可选参数，指定返回的交易记录数量，默认为500，最大为1000。
    • fromId: 可选参数， 从某个交易ID开始查询。

    该接口返回一个包含历史交易记录信息的数组，包括成交价格、成交数量、手续费等。

4. 合约API详解

合约API允许用户通过程序化方式与加密货币合约交易所进行交互，执行合约交易操作。 掌握并熟练运用这些API接口是量化交易策略开发和自动化交易系统构建的关键。 以下是一些常用的合约API接口，以及对每个接口的详细说明：

  • POST /dapi/v1/order (Place Order): 下单接口，用于创建合约订单。此接口是合约交易的核心，允许用户提交买入或卖出指定合约的订单。除了基本的交易对 ( symbol )、交易方向 ( side ，例如 BUY 或 SELL)、订单类型 ( type ，例如 LIMIT、MARKET、STOP_MARKET 等)、数量 ( quantity ) 和价格 ( price ，仅限限价单)，还应提供杠杆倍数 ( leverage ) 和时间有效性策略 ( timeInForce )。时间有效性策略规定了订单在市场中的存活时间以及如何被执行，例如GTC (Good-Til-Cancelled)、IOC (Immediate-Or-Cancel) 或 FOK (Fill-Or-Kill)。 部分交易所还支持指定止损价 ( stopPrice ) 和触发条件 ( triggerCondition )，方便设置止损单和止盈单。
  • DELETE /dapi/v1/order (Cancel Order): 撤单接口，用于取消尚未完全成交的合约订单。取消订单对于风险管理和策略调整至关重要。要取消订单，需要提供交易对 ( symbol ) 和订单 ID ( orderId )。有些交易所还支持通过客户端订单 ID ( origClientOrderId ) 来取消订单，这允许用户在无需服务器存储订单 ID 的情况下取消订单。批量撤单功能可以一次性取消多个订单，提高效率。
  • GET /dapi/v1/order (Query Order): 查询订单接口，用于查询指定合约订单的当前状态。 通过提供交易对 ( symbol ) 和订单 ID ( orderId )，可以获取订单的详细信息，包括订单状态 ( status ，例如 NEW、FILLED、PARTIALLY_FILLED、CANCELED 等)、已成交数量 ( executedQty )、平均成交价格 ( avgPrice ) 和手续费 ( commission )。此接口对于监控订单执行情况和调试交易策略非常有用。
  • GET /dapi/v1/openOrders (Current Open Orders): 查询当前未成交合约订单接口，用于获取所有或指定交易对的未成交订单列表。 通过指定交易对 ( symbol )，可以筛选特定合约的未成交订单。该接口返回的订单信息与查询单个订单接口类似，包括订单 ID、订单类型、数量、价格和状态等。这个接口对于追踪未完成的订单和实施风控策略非常重要。
  • GET /dapi/v1/account (Account Information): 查询合约账户信息接口，用于获取用户的合约账户余额、可用余额、保证金、已实现盈亏 ( realizedPnl ) 和未实现盈亏 ( unrealizedPnl ) 等关键信息。 此接口是监控账户健康状况和评估风险敞口的重要工具。通过定期查询账户信息，用户可以及时调整交易策略，避免爆仓风险。 该接口还会返回账户的风险等级和维持保证金率，帮助用户更好地理解账户的风险状况。
  • GET /dapi/v1/positionRisk (Position Information): 查询仓位信息接口，用于获取当前持仓的详细信息，包括仓位方向 ( positionSide ，LONG 或 SHORT)、持仓数量 ( positionAmt )、开仓均价 ( entryPrice )、盈亏 ( unrealizedProfit )、杠杆倍数 ( leverage ) 和爆仓价格 ( liquidationPrice )。 该接口是风险管理的关键，可以帮助用户评估当前持仓的风险水平。通过监控仓位信息，用户可以及时止损止盈，降低交易风险。 某些交易所还会提供仓位保证金率等信息，方便用户更全面地了解仓位风险。
  • POST /dapi/v1/leverage (Change Leverage): 调整杠杆倍数接口，用于动态调整合约账户的杠杆倍数。 合理使用杠杆可以放大收益，但也增加了风险。调整杠杆时需要谨慎，避免因杠杆过高导致爆仓。 通过此接口，用户可以根据市场情况和风险偏好灵活调整杠杆倍数。 需要注意的是，调整杠杆可能会影响账户的可用保证金和爆仓价格，因此在调整前务必仔细评估风险。 不同的交易所对杠杆倍数的调整规则可能有所不同，需要仔细阅读API文档。

5. 市场数据API详解

市场数据API允许用户获取实时和历史市场数据，是构建交易机器人、数据分析平台和投资决策工具的关键组件。通过这些API，开发者可以访问包括价格、交易量、深度图等多种数据，从而进行更深入的市场分析和预测。以下是一些常用的市场数据API接口，涵盖了不同类型的数据需求：

  • GET /api/v3/ticker/price (Symbol Price Ticker): 获取单个交易对的最新成交价格。这个接口返回的数据简洁明了，只包含交易对的最新价格，非常适合需要快速获取价格信息的应用场景。必须提供交易对参数，例如 symbol=BTCUSDT ，才能指定需要查询的交易对。
  • GET /api/v3/ticker/bookTicker (Symbol Order Book Ticker): 获取单个交易对的当前最佳买一价、买一量、卖一价和卖一量。此接口提供的最佳买卖盘信息对于高频交易和套利策略至关重要。同样需要指定交易对，例如 symbol=ETHBTC ，以便获取对应交易对的深度信息。
  • GET /api/v3/klines (Kline/Candlestick Data): 获取指定交易对在特定时间周期内的K线（蜡烛图）数据。K线数据是技术分析的基础，可以用于识别趋势、支撑位和阻力位等。需要提供交易对、时间周期（例如 1m 表示1分钟， 1h 表示1小时， 1d 表示1天）和可选的时间范围参数。例如， symbol=BNBBTC&interval=1h&limit=100 将获取BNBBTC交易对最近100个1小时的K线数据。参数 startTime 和 endTime 可用于指定K线数据的起始和结束时间戳。
  • GET /api/v3/depth (Order Book): 获取指定交易对的交易深度数据，显示了不同价格级别的买单和卖单数量。深度数据反映了市场的供需关系，可以用于评估市场流动性和潜在的价格波动。需要提供交易对和深度数量参数，例如 symbol=LTCUSDT&limit=20 将获取LTCUSDT交易对的前20个买单和卖单。 limit 参数的取值通常有不同的限制，需参考API文档。

6. 用户数据流API详解

用户数据流API提供了一种机制，允许开发者实时接收与其账户活动相关的关键数据更新，无需轮询，极大地提高了效率和响应速度。

  1. POST /api/v3/userDataStream (启动用户数据流): 此API端点用于创建一个新的用户数据流会话。成功调用后，服务器会返回一个唯一的 listenKey 。这个 listenKey 是后续所有数据接收操作的凭证，必须妥善保存。每次启动数据流会话都会生成一个新的 listenKey 。
  2. PUT /api/v3/userDataStream (保持用户数据流): 为了维持用户数据流的活跃状态，需要定期发送 "心跳" 请求到此端点。如果没有定期发送，服务器会在一段时间后自动断开连接，导致数据流中断。建议按照API文档推荐的频率发送心跳包，确保连接的稳定性。心跳请求只需携带之前获取的 listenKey 。
  3. DELETE /api/v3/userDataStream (关闭用户数据流): 当不再需要接收数据流时，应调用此端点来显式地关闭连接。这将释放服务器资源，并停止发送不必要的数据。关闭数据流同样需要提供有效的 listenKey 。

用户可以通过WebSocket协议连接到币安服务器，并使用之前获取的 listenKey 进行身份验证。身份验证成功后，即可接收实时推送的用户账户数据更新，包括但不限于：订单状态变化（例如，订单创建、部分成交、完全成交、取消等）、账户余额变动（包括可用余额和冻结余额的更新）、以及其他与账户相关的事件。WebSocket连接允许双向通信，虽然主要用于接收推送数据，但也能用于发送少量控制信息。

7. 错误处理

在使用币安API进行交易或数据查询时，可能会遇到各种错误。为了确保程序的健壮性和稳定性，有效地处理API返回的错误至关重要。当API请求发生错误时，币安API通常会返回一个JSON对象，该对象包含了详细的错误码和描述性的错误信息，以便开发者能够诊断问题并采取适当的应对措施。理解这些错误码及其含义是开发可靠的交易应用的基础。

以下是一些常见的币安API错误码，以及对它们可能原因的详细解释：

  • -1000 : 未知错误 (Unknown error)。这通常是一个笼统的错误代码，可能表明服务器端发生了未预料到的问题。建议开发者记录下请求的详细信息，例如请求的URL、参数和时间戳，以便后续排查。如果问题持续存在，应考虑联系币安的技术支持。
  • -1002 : API Key 格式错误 (Incorrect API key format)。这意味着您提供的API Key不符合币安要求的格式。API Key通常是一串由字母和数字组成的字符串。请仔细检查您使用的API Key是否正确复制，并且没有包含任何额外的空格或其他字符。同时，确认您使用的API Key与您在币安账户中生成的API Key完全一致。
  • -1013 : 请求过多 (Too many requests)。币安API对请求频率有限制，以防止滥用。如果您的程序在短时间内发送了过多的请求，就会触发此错误。为了避免此错误，您应该实施请求频率限制（Rate Limiting）机制。例如，您可以使用令牌桶算法或漏桶算法来控制请求的发送速率。币安API的文档通常会详细说明各个接口的请求频率限制，您应该根据这些限制来调整您的程序。
  • -2010 : 新订单被拒绝 (New order rejected)。这个错误表明您提交的新订单由于某种原因被币安的交易引擎拒绝了。可能的原因包括：账户余额不足、订单参数不符合要求（例如，价格或数量超出限制）、市场处于维护状态、API Key的权限不足等。错误信息通常会提供更详细的拒绝原因，例如"Insufficient balance"（余额不足）或"PRICE_FILTER"（价格超出限制）。开发者应该根据这些信息调整订单参数或采取其他必要的措施。
  • 其他错误码：币安API还定义了许多其他的错误码，涵盖了各种可能发生的问题，包括但不限于网络连接问题、数据验证失败、服务器内部错误等。详细的错误码列表请参考币安API官方文档。

作为开发者，您需要根据API返回的错误码和错误信息，制定相应的错误处理策略。这可能包括重试失败的请求、记录错误日志、向用户发出警告、或停止程序执行。良好的错误处理机制可以提高程序的健壮性，并帮助您快速定位和解决问题。

8. 限流机制

为了确保币安API平台的稳定性和可用性，防止恶意或过度使用对服务器造成负荷，币安实施了严格的请求频率限制，即限流机制。开发者在使用API时必须高度重视并遵守这些限制，合理控制请求频率，避免触发限流保护措施，否则可能会导致API访问被暂时或永久阻止。

不同的API接口，由于其功能复杂度和服务器资源消耗程度不同，可能具有不同的限流规则。这些规则通常基于权重（weight）或订单数量（order count）进行限制。开发者应仔细查阅每个API接口的文档，了解其具体的限流标准，并据此进行相应的程序设计。

币安API通过HTTP响应头中的 X-MBX-USED-WEIGHT-* 和 X-MBX-ORDER-COUNT-* 字段，向开发者提供实时的请求权重和订单数量信息。 X-MBX-USED-WEIGHT-* 字段反映了在特定时间窗口内，你的API密钥所消耗的请求权重总和。 X-MBX-ORDER-COUNT-* 字段则指示了你的API密钥在特定时间窗口内提交的订单总数。

通过监控这些响应头字段，开发者可以实时了解当前的请求状态，并根据反馈动态调整请求频率，从而有效地避免触发限流。例如，可以设置一个监控线程，定期检查这些字段的值，并在接近限制阈值时主动降低请求速度。开发者还可以使用缓存机制来减少不必要的API调用，或者采用批量处理的方式，一次性提交多个操作，从而降低请求频率。

当API请求被限流时，服务器会返回HTTP 429状态码（Too Many Requests）。开发者应该捕获这个错误，并采用退避策略（exponential backoff），即逐渐增加重试请求的间隔时间，直到成功为止。盲目地快速重试只会加剧服务器的压力，并延长被限流的时间。

9. 安全注意事项

  • API Key与Secret Key的妥善保管： 务必将您的API Key和Secret Key视为最高机密。切勿以任何形式泄露给第三方，包括但不限于口头告知、邮件发送、代码提交至公开仓库等。任何持有您API Key和Secret Key的人都可以代表您执行交易和其他操作。
  • 强制使用HTTPS协议： 始终使用HTTPS协议发起API请求。HTTPS通过SSL/TLS加密连接，有效防止中间人攻击，保障您的数据在传输过程中不被窃听或篡改。非HTTPS连接存在极高的安全风险。
  • API请求签名验证机制： 务必对所有API请求进行签名。签名是使用您的Secret Key对请求参数进行加密计算后生成的一串字符串，币安服务器会验证此签名，确保请求的完整性和真实性。未经签名的请求将被拒绝，从而有效防止恶意请求的伪造和篡改。具体签名算法请参考币安API文档。
  • 定期轮换API Key与Secret Key： 建议您定期更换API Key和Secret Key，例如每月或每季度。这可以降低因Key泄露而造成的潜在损失。更换Key后，务必更新所有使用旧Key的应用程序和脚本。
  • 严格控制API请求频率： 密切监控您的API请求频率，避免超出币安设定的限流阈值。过高的请求频率可能导致您的IP被暂时或永久封禁。可以通过设置合理的请求间隔或使用异步请求来避免触发限流。币安API文档详细说明了各种接口的请求频率限制。
  • 深入了解并积极应用币安的安全措施： 熟悉币安平台提供的各项安全措施，例如双因素认证（2FA）、反钓鱼码等，并积极应用到您的账户中。同时，关注币安官方发布的最新安全公告和建议，及时采取相应的安全措施。
  • 使用IP白名单限制访问： 配置IP白名单，仅允许特定的IP地址访问您的API Key。这可以有效防止未经授权的访问，即使API Key泄露，攻击者也无法使用。
  • 权限控制： 根据您的实际需求，配置API Key的权限。例如，如果您的应用程序只需要读取市场数据，则无需授予交易权限。最小化权限原则可以降低Key泄露带来的风险。
  • 使用专用网络： 尽量在安全的网络环境下使用API，避免在公共Wi-Fi等不安全网络下进行操作。考虑使用VPN或专线连接，以提高安全性。

希望本文档能够帮助你更好地理解和使用币安API接口。

相关推荐：