币安API高效交易：参数配置实战指南【限时教程】

日期： 栏目：知识 浏览：15

币安API接口参数设定教程

本教程旨在帮助开发者理解和配置币安API接口的参数，以便更有效地进行交易和数据分析。我们将涵盖常用的API端点和它们的参数设定，以及一些最佳实践。

概述

币安API提供了极为广泛的功能，涵盖实时市场数据检索、高效交易执行、全面的账户管理等多个方面。为了能够充分且高效地利用这些功能，深入理解并掌握如何正确设置API请求的各项参数至关重要。这包括理解不同端点的具体要求、正确构造请求参数、以及妥善处理可能的错误响应。准确的参数设置直接影响到API请求的成功率和返回数据的准确性，因此，务必仔细研究币安API的官方文档，了解每个参数的具体含义、数据类型以及可选范围。例如，在进行交易时，需要精确指定交易对、交易类型（市价单、限价单等）、交易数量和价格等参数。不正确的参数设置可能导致交易失败或产生意想不到的结果。

API 密钥和权限

在使用任何API端点之前，必须先获取有效的API密钥。API密钥是访问加密货币交易所或其他平台API的凭证，它允许您的应用程序以安全的方式与服务器进行通信。您可以在您的币安账户或类似平台的API管理页面创建并管理这些密钥。

在创建API密钥时，务必遵循最小权限原则，只授予您的应用程序完成其特定功能所必需的最低权限集。例如，如果您的应用程序的功能仅限于读取市场数据，如交易对的价格、交易量和其他相关信息，那么绝对不需要启用交易权限。启用交易权限会带来潜在的安全风险，如果密钥泄露，可能会被恶意利用进行未经授权的交易。

常见的API权限包括：

  • 读取数据权限： 允许应用程序获取账户信息、市场数据、交易历史等。
  • 交易权限： 允许应用程序执行交易操作，如买入和卖出加密货币。应谨慎授予此权限。
  • 提现权限： 允许应用程序发起提现请求。这是最敏感的权限之一，必须严格控制。

请定期审查您的API密钥权限，并删除或禁用不再需要的密钥。务必将API密钥保存在安全的地方，例如使用环境变量或加密的配置文件，避免将其直接硬编码到您的应用程序中。如果怀疑密钥已泄露，应立即撤销该密钥并创建一个新的密钥。

启用双重验证（2FA）也是保护您的API密钥的重要措施，即使密钥泄露，攻击者也需要通过2FA验证才能进行操作，从而大大降低风险。

通用参数

以下是一些在多个币安API端点中通用的参数，理解这些参数对于有效地使用币安API至关重要：

  • symbol : 交易对，例如 BTCUSDT 。所有交易对均以字母顺序排列，基础货币在前，计价货币在后。请确保输入正确的交易对，大小写敏感，错误的交易对将导致请求失败。币安支持大量的交易对，涵盖现货、杠杆、合约等多种市场，务必根据您的交易需求选择正确的交易对。
  • limit : 返回结果的数量限制。不同的端点可能允许不同的最大值，例如某些端点可能限制最大值为1000，而另一些端点可能允许更大的值。通常，较大的 limit 值可能会导致更长的响应时间，因为服务器需要处理和返回更多的数据。请根据实际需求合理设置 limit 值，避免不必要的性能开销。
  • startTime : 查询的起始时间戳（毫秒）。用于过滤历史数据。时间戳是从Unix纪元（1970年1月1日00:00:00 UTC）开始经过的毫秒数。通过设置 startTime ，您可以精确地获取特定时间点之后的数据。
  • endTime : 查询的结束时间戳（毫秒）。用于过滤历史数据。 startTime 和 endTime 共同定义了数据查询的时间范围，允许您获取指定时间段内的数据。如果未提供 startTime 或 endTime ，API 将返回默认时间范围的数据，具体取决于端点的实现。
  • recvWindow : 接收窗口，允许请求在指定时间内完成。这是一种防止中间人攻击的安全措施。通常设置为 5000 毫秒，表示请求必须在 5 秒内到达服务器。如果您的服务器时间与币安服务器时间不同步，您可能需要调整此参数。过小的 recvWindow 值可能导致请求超时，过大的值则可能降低安全性。建议根据您的网络环境和服务器时间同步情况进行调整。
  • timestamp : 请求的时间戳（毫秒）。必须在 recvWindow 参数指定的时间范围内。 timestamp 用于验证请求的新鲜度，防止重放攻击。如果 timestamp 超出 recvWindow 范围，请求将被服务器拒绝。确保您的服务器时间与UTC时间同步，并使用当前时间生成 timestamp 。
  • signature : 请求签名。用于验证请求的完整性和来源。签名是使用您的API密钥的 secretKey 对请求参数进行哈希运算的结果（通常使用HMAC SHA256算法）。签名机制确保只有拥有 secretKey 的人才能伪造请求。请务必妥善保管您的 API 密钥，避免泄露。正确的签名生成过程是API安全的关键。

市场数据 API

获取交易对信息

端点： /api/v3/exchangeInfo

描述： 此端点用于检索指定交易对或所有交易对的详细信息。这些信息包括交易对的交易规则、价格精度、交易手续费等重要参数，对于理解和参与交易至关重要。

HTTP 方法： GET

参数：

  • symbol (可选):
    • 类型： 字符串
    • 说明： 指定要查询的交易对。例如， BTCUSDT 表示比特币兑美元的交易对。
    • 用法：
      • 如果提供此参数，则 API 将仅返回指定交易对的相关信息。这对于仅需要特定交易对数据的情况非常有用，可以减少数据传输量，提高效率。
      • 如果省略此参数，API 将返回交易所支持的所有交易对的完整信息列表。这对于构建交易所的行情展示页面或进行全面的数据分析非常有用。

响应示例 (部分): 


{
  "timezone": "UTC",
  "serverTime": 1678886400000,
  "rateLimits": [
    // 速率限制信息，例如每分钟允许的请求数量
  ],
  "exchangeFilters": [
    // 交易所级别过滤器，例如最大订单数量
  ],
  "symbols": [
    {
      "symbol": "BTCUSDT",
      "status": "TRADING",
      "baseAsset": "BTC",
      "baseAssetPrecision": 8,
      "quoteAsset": "USDT",
      "quotePrecision": 8,
      "quoteAssetPrecision": 8,
      "baseCommissionPrecision": 8,
      "quoteCommissionPrecision": 8,
      "orderTypes": [
        "LIMIT",
        "LIMIT_MAKER",
        "MARKET",
        "STOP_LOSS_LIMIT",
        "TAKE_PROFIT_LIMIT"
      ],
      "icebergAllowed": true,
      "ocoAllowed": true,
      "quoteOrderQtyMarketAllowed": true,
      "allowTrailingStop": false,
      "cancelReplaceAllowed": false,
      "isSpotTradingAllowed": true,
      "isMarginTradingAllowed": true,
      "filters": [
        // 交易对级别过滤器，例如最小交易数量、价格精度
      ],
      "permissions": [
        "SPOT",
        "MARGIN"
      ]
    }
    // ... 更多交易对信息
  ]
}

注意事项：

  • 仔细阅读响应中的 filters 数组，它包含了交易对的各种限制，例如最小交易数量、最大交易数量、价格精度等。违反这些限制会导致订单被拒绝。
  • rateLimits 数组包含了 API 的速率限制信息。请务必遵守这些限制，以避免被暂时禁止访问 API。
  • status 字段指示交易对的当前状态。例如， TRADING 表示交易对正在正常交易，而 HALT 表示交易已暂停。

获取市场深度信息

端点： /api/v3/depth

该接口提供指定交易对的市场深度信息，也称为订单簿数据。市场深度反映了当前市场上买单和卖单的分布情况，是交易决策的重要参考。

参数：

  • symbol : 必需，交易对。指定要查询的交易对，例如 BTCUSDT 表示比特币/USDT交易对。此参数区分大小写。
  • limit : 可选，返回的深度级别数量。指定要返回的订单簿深度级别数量，影响返回数据的详细程度。可选值包括：5, 10, 20, 50, 100, 500, 1000, 5000。数值越大，返回的订单簿信息越详细，但同时也可能增加数据传输量。默认值：100。 例如，设置 limit=5 将只返回最佳的5个买单和卖单。

返回值说明： 接口返回的数据将包含买单（bids）和卖单（asks）两个数组。每个数组中的每个元素都代表一个订单，包含价格和数量信息。 买单数组按价格降序排列，卖单数组按价格升序排列，以便快速找到最佳买入和卖出价格。

示例： 请求 /api/v3/depth?symbol=BTCUSDT&limit=20 将返回 BTCUSDT 交易对的最佳20个买单和卖单。

注意事项： 频繁请求高 limit 值的接口可能会对服务器造成压力，请合理控制请求频率和 limit 值。 建议根据实际需求选择合适的 limit 值，避免不必要的资源消耗。

获取近期成交记录

该接口用于查询指定交易对的近期成交历史记录，是了解市场交易活跃度和价格波动情况的重要工具。通过分析成交记录，用户可以更好地评估市场的供需关系，并制定相应的交易策略。

端点： /api/v3/trades

该API端点提供对最新交易信息的直接访问，便于程序化交易和数据分析。它允许开发者快速检索并处理市场数据，以进行实时监控和决策。

参数：

  • symbol : 必需，交易对。指定需要查询的交易对，例如 BTCUSDT 、 ETHBTC 等。该参数区分大小写，必须与交易所支持的交易对名称完全一致。
  • limit : 可选，返回的成交记录数量。默认值：500，最大值：1000。 该参数允许用户控制返回数据的量级，以便根据实际需求平衡数据完整性和响应速度。 如果不指定该参数，则默认返回最新的500条成交记录。 设置过大的 limit 值可能会导致请求处理时间延长。

注意事项：

  • 请注意API的调用频率限制，避免频繁请求导致IP被封禁。
  • 返回的成交记录按照时间顺序排列，最新的成交记录在前。
  • 成交记录中包含成交价格、成交数量、成交时间等关键信息。
  • 建议结合其他API接口，如K线数据接口，进行更全面的市场分析。

获取K线数据

端点： /api/v3/klines

此端点用于获取指定交易对和时间间隔的K线数据，对于历史数据分析和实时行情监控至关重要。务必正确理解和使用各项参数。

参数：

  • symbol : 必需，交易对。指明需要查询的交易对，例如 BTCUSDT 表示比特币兑泰达币。务必使用交易所支持的正确交易对标识。
  • interval : 必需，K线时间间隔。定义每个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月)。选择合适的时间间隔取决于分析周期。
  • startTime : 可选，起始时间戳（毫秒）。指定K线数据的起始时间。若不指定，则从最早可获取的数据开始。时间戳以自1970年1月1日午夜（格林威治标准时间/协调世界时）以来的毫秒数表示。
  • endTime : 可选，结束时间戳（毫秒）。指定K线数据的结束时间。若不指定，则返回到当前时间的K线数据。同样使用毫秒级时间戳。
  • limit : 可选，返回的K线数量。控制每次API调用返回的K线数量。默认值：500，最大值：1000。若所需数据超过1000条，需要分多次调用API，并使用 startTime 和 endTime 参数进行分页。

获取平均价格

端点： /api/v3/avgPrice

描述：此端点用于获取指定交易对的平均价格。平均价格的计算基于最近一段时间内的交易数据，能够反映市场对该交易对的整体估值水平。此接口通常用于风控、策略执行等场景，辅助用户做出更明智的决策。

参数：

  • symbol : 必需，交易对。例如： BTCUSDT , ETHBTC 。交易对区分大小写，必须使用交易所支持的交易对代码。 错误的交易对会导致请求失败。请确保输入正确的交易对代码。

示例：

假设您想获取 BTCUSDT 的平均价格，您可以向 /api/v3/avgPrice?symbol=BTCUSDT 发送GET请求。返回的数据将包含 BTCUSDT 的当前平均价格。

返回数据结构： 


{
  "mins": 5,
  "price": "45000.00"
}

字段说明：

  • mins : 用于计算平均价格的时间窗口（分钟）。
  • price : 指定交易对的平均价格，以字符串形式返回，避免精度丢失。

注意事项：

  • 频率限制：请注意API的使用频率限制，避免因频繁请求而被限制访问。
  • 数据准确性：虽然平均价格反映了市场趋势，但并不能完全代表实时价格。请结合其他市场数据进行分析。
  • 网络延迟：网络延迟可能会影响获取平均价格的速度。

交易 API

下单

端点： /api/v3/order

参数：

  • symbol : 必需，交易对。指定进行交易的两种资产的组合，例如： BTCUSDT 表示比特币兑 USDT 的交易对。务必确保交易对的拼写正确，并且平台支持该交易对的交易。
  • side : 必需，交易方向。 BUY (买入) 或 SELL (卖出)。 BUY 指示希望以指定价格或市场价格购买指定数量的交易对中的基础资产。 SELL 指示希望以指定价格或市场价格出售指定数量的交易对中的基础资产。
  • type : 必需，订单类型。 LIMIT (限价单), MARKET (市价单), STOP_LOSS (止损单), STOP_LOSS_LIMIT (限价止损单), TAKE_PROFIT (止盈单), TAKE_PROFIT_LIMIT (限价止盈单), LIMIT_MAKER (只挂单)。
    • LIMIT ：限价单允许您指定希望购买或出售资产的特定价格。只有当市场价格达到或超过指定价格时，订单才会执行。
    • MARKET ：市价单会立即以当前市场上的最佳可用价格执行。
    • STOP_LOSS ：止损单在市场价格达到指定止损价格时变为市价单。
    • STOP_LOSS_LIMIT ：限价止损单在市场价格达到指定止损价格时变为限价单。
    • TAKE_PROFIT ：止盈单在市场价格达到指定止盈价格时变为市价单。
    • TAKE_PROFIT_LIMIT ：限价止盈单在市场价格达到指定止盈价格时变为限价单。
    • LIMIT_MAKER ：只挂单（也称为被动限价单）将立即被取消，而不是与现有订单匹配。这用于确保您始终是做市商，而不是吃单者，这通常会带来更低的交易费用。
  • timeInForce : 可选，订单有效方式。 GTC (Good Till Cancelled，一直有效), IOC (Immediate Or Cancel，立即成交否则取消), FOK (Fill Or Kill，全部成交否则取消)。仅 LIMIT 和 LIMIT_MAKER 订单需要此参数。
    • GTC ：订单将保持有效，直到被完全执行或手动取消。
    • IOC ：订单尝试立即以可用价格全部或部分执行。任何未成交的部分将被立即取消。
    • FOK ：订单必须立即以指定的价格和数量完全成交，否则整个订单将被取消。
  • quantity : 必需，下单数量。指定要购买或出售的基础资产的数量。数量通常以基础资产的单位表示，例如，购买 1 个 BTC 需要数量为 1。
  • price : 可选，限价单价格。指定希望购买或出售资产的价格。仅在订单类型为 LIMIT 或 STOP_LOSS_LIMIT 或 TAKE_PROFIT_LIMIT 时有效。
  • stopPrice : 可选，触发价格。用于 STOP_LOSS , STOP_LOSS_LIMIT , TAKE_PROFIT , TAKE_PROFIT_LIMIT 订单。当市场价格达到或超过止损价格时，止损单将被触发。对于买入止损单，止损价格必须高于当前市场价格。对于卖出止损单，止损价格必须低于当前市场价格。
  • icebergQty : 可选，冰山订单数量。允许将大额订单拆分成多个较小的订单，以避免对市场价格产生重大影响。只有显示的这部分数量会被挂单，成交后，剩余的数量会自动挂出。
  • newClientOrderId : 可选，自定义订单ID。允许您为订单分配一个唯一的ID，方便跟踪和识别。如果您不提供此参数，系统会自动生成一个ID。
  • newOrderRespType : 可选，订单响应类型。 ACK , RESULT , FULL . 默认值： RESULT 。
    • ACK ：仅返回订单已被接受的确认信息。
    • RESULT ：返回有关订单执行的详细信息，例如成交数量和平均成交价格。
    • FULL ：返回订单的完整详细信息，包括所有交易和费用信息。
  • recvWindow : 可选，接收窗口。指定请求被服务器接受的最长时间（以毫秒为单位）。如果请求在指定时间内未被接受，则会被拒绝。这有助于防止网络延迟导致的问题。
  • timestamp : 必需，时间戳。发送请求时的时间戳（以毫秒为单位）。用于确保请求的时效性，防止重放攻击。

查询订单

端点： /api/v3/order

本端点允许用户查询特定订单的详细信息。通过提供不同的参数组合，可以根据交易对、订单ID或客户端订单ID来检索订单状态。

参数：

  • symbol : 必需，交易对。指定要查询订单的交易对，例如 "BTCUSDT"。该参数区分大小写。
  • orderId : 可选，订单ID。交易所分配的唯一订单标识符，类型为长整型。如果提供了此参数，将仅返回与此ID匹配的订单。
  • origClientOrderId : 可选，原始客户端订单ID。客户端在创建订单时指定的唯一标识符。如果提供了此参数，将返回与此客户端订单ID匹配的订单。通常用于在客户端跟踪订单。
  • recvWindow : 可选，接收窗口。指定请求被服务器接受的有效时间范围（毫秒）。如果请求时间与服务器时间偏差过大，服务器将拒绝该请求。建议设置为小于或等于 5000 毫秒的值，以防止重放攻击。如果未指定，则使用默认值。
  • timestamp : 必需，时间戳。发送请求时的 Unix 时间戳（毫秒）。时间戳必须在 recvWindow 指定的有效范围内。用于验证请求的有效性。

重要提示： 必须同时提供 orderId 或 origClientOrderId 之一，才能成功查询订单信息。如果两者都没有提供，服务器将返回错误。

取消订单

端点： /api/v3/order

描述：此端点允许用户取消一个挂单。用户可以通过提供订单ID、原始客户端订单ID或新的客户端订单ID来指定要取消的订单。如果同时提供多个ID，系统会按照特定优先级处理（通常是 orderId 优先）。成功取消订单后，服务器会返回取消订单的详细信息。

参数：

  • symbol : 必需，交易对。指定要取消订单的交易对。例如， BTCUSDT 表示比特币对泰达币的交易对。确保交易对的格式正确，并且是交易所支持的有效交易对。
  • orderId : 可选，订单ID。交易所分配的唯一订单标识符。如果提供了 orderId ，系统将优先使用此参数来查找并取消订单。此ID是整数类型。
  • origClientOrderId : 可选，原始客户端订单ID。用户在创建订单时指定的自定义订单ID。如果用户在创建订单时设置了 origClientOrderId ，则可以使用此参数来取消订单。使用此参数允许用户通过自己的ID来管理订单。
  • newClientOrderId : 可选，新的客户端订单ID。用于在取消订单时更新客户端订单ID。这允许用户在取消订单的同时更新其内部订单跟踪系统。如果提供此参数，取消成功后，返回的订单信息中将会包含此新的客户端订单ID。
  • recvWindow : 可选，接收窗口。指定请求被接受的最长时间窗口（毫秒）。如果服务器接收请求的时间超过此窗口，请求将被拒绝。这有助于防止由于网络延迟导致的重放攻击。默认值和最大值通常由交易所设置，例如5000毫秒。
  • timestamp : 必需，时间戳。发送请求的时间戳（Unix时间，毫秒）。时间戳必须在 recvWindow 允许的范围内。提供准确的时间戳对于确保请求的有效性至关重要。

注意事项：

  • 取消订单需要有效的API密钥，并且该API密钥需要具有取消订单的权限。
  • 如果订单已经完全成交或已经被取消，则无法再次取消。
  • 取消订单可能会产生费用，具体费用规则请参考交易所的费用说明。
  • 在高市场波动期间，取消订单请求可能会受到延迟。

查询所有未成交订单

接口描述： 该接口允许用户检索其账户中所有未完全成交的订单。未成交订单是指那些已经提交到交易所，但尚未完全成交或被取消的订单。

端点： /api/v3/openOrders

HTTP 方法： GET

请求参数：

  • symbol : (可选) 交易对。指定要查询的交易对，例如 "BTCUSDT"。如果未提供此参数，则接口将返回所有交易对的未成交订单。建议在查询特定交易对的未成交订单时使用此参数，以提高查询效率。
  • recvWindow : (可选) 接收窗口。表示请求被服务器接受的有效时间范围，单位为毫秒。如果服务器接收到请求的时间超出此窗口，则请求将被拒绝。这是一种安全措施，用于防止网络延迟或重放攻击。默认值和最大值通常由交易所设置，例如 5000 毫秒。
  • timestamp : (必需) 时间戳。请求发送时的 Unix 时间戳，单位为毫秒。必须提供此参数以确保请求的时效性。时间戳必须在服务器允许的接收窗口范围内。

安全注意事项：

  • 所有通过此接口返回的数据都与用户的账户安全密切相关。务必保护好您的 API 密钥，不要将其泄露给任何人。
  • 使用 recvWindow 参数可以提高API请求的安全性，防止潜在的重放攻击。

返回数据：

接口将返回一个 JSON 数组，每个元素代表一个未成交订单。每个订单对象包含以下字段（部分）：

  • symbol : 交易对。
  • orderId : 订单ID。
  • clientOrderId : 用户自定义的订单ID。
  • price : 订单价格。
  • origQty : 原始订单数量。
  • executedQty : 已成交数量。
  • cummulativeQuoteQty : 累计成交额。
  • status : 订单状态 (NEW, PARTIALLY_FILLED, FILLED, CANCELED, PENDING_CANCEL, REJECTED, EXPIRED)。
  • timeInForce : 有效方式 (GTC, IOC, FOK)。
  • type : 订单类型 (LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT, LIMIT_MAKER)。
  • side : 订单方向 (BUY, SELL)。
  • stopPrice : 止损价格 (仅限止损订单)。
  • icebergQty : 冰山订单数量。
  • time : 订单创建时间戳。
  • updateTime : 订单更新时间戳。
  • isWorking : 订单是否在工作。
  • origQuoteOrderQty : 原始报价订单数量（如果适用）。

错误处理：

如果请求出现错误，API 将返回包含错误代码和错误消息的 JSON 对象。常见的错误包括：

  • -1000 : 未知错误。
  • -1002 : 未授权的请求。
  • -1013 : 参数错误。
  • -1021 : 时间戳无效。
  • -2013 : 订单不存在。

查询所有订单

端点： /api/v3/allOrders

描述：此端点允许您检索指定交易对的所有订单历史记录。通过提供可选参数，您可以进一步筛选和分页结果。

参数：

  • symbol : 必需，交易对。指定要查询的交易对，例如： BTCUSDT 。务必使用大写字母。
  • orderId : 可选，起始订单ID。用于分页查询。如果提供了此参数，则仅返回订单ID大于此值的订单。通常用于从上次查询中断的地方继续检索后续订单。
  • startTime : 可选，起始时间戳（毫秒）。仅返回在此时间戳之后创建的订单。时间戳应为Unix时间戳，精确到毫秒。
  • endTime : 可选，结束时间戳（毫秒）。仅返回在此时间戳之前创建的订单。时间戳应为Unix时间戳，精确到毫秒。 startTime 和 endTime 参数可用于指定时间范围。
  • limit : 可选，返回的订单数量。默认值：500，最大值：1000。指定每次API调用返回的订单数量。较大的 limit 值可能会影响响应时间。
  • recvWindow : 可选，接收窗口（毫秒）。指定请求被接受的处理时间范围，防止重放攻击。建议设置为小于或等于5000毫秒的值。
  • timestamp : 必需，时间戳（毫秒）。发送请求时的时间戳，用于验证请求的有效性。时间戳应为Unix时间戳，精确到毫秒。

安全注意事项：

  • 所有请求都必须经过身份验证，通常通过API密钥和签名。
  • recvWindow 参数对于防止重放攻击至关重要。

返回数据格式：

返回的是一个JSON数组，其中每个元素代表一个订单。每个订单对象包含订单的详细信息，如订单ID、交易对、价格、数量、状态等。

账户 API

获取账户信息

功能描述： 此端点用于检索用户的账户信息，包括余额、交易权限等关键数据。安全起见，所有请求都需要进行身份验证。

端点： /api/v3/account

请求方式： GET

参数：

  • recvWindow : 可选，接收窗口，单位为毫秒。此参数用于指定请求被接受的处理时间范围。如果服务器在指定的时间窗口之外收到请求，则会拒绝该请求。建议设置一个合理的较小的值，如 5000 (5秒)，以防止潜在的重放攻击。未提供此参数时，服务器会使用默认值。
  • timestamp : 必需，时间戳，代表请求发送时的 Unix 时间戳（毫秒）。此参数与 recvWindow 配合使用，确保请求的时效性，防止重放攻击。时间戳必须在服务器允许的 recvWindow 范围内。
  • signature : 必需，签名。使用您的 API 密钥的密钥（secret key）对请求参数进行签名。签名用于验证请求的完整性和来源。签名算法通常为 HMAC SHA256。

请求示例： 


GET /api/v3/account?recvWindow=5000&timestamp=1678886400000&signature=YOUR_SIGNATURE HTTP/1.1

响应示例： 


{
  "makerCommission": 0,
  "takerCommission": 0,
  "buyerCommission": 0,
  "sellerCommission": 0,
  "canTrade": true,
  "canWithdraw": true,
  "canDeposit": true,
  "updateTime": 1678886400000,
  "accountType": "SPOT",
  "balances": [
    {
      "asset": "BTC",
      "free": "0.005",
      "locked": "0.001"
    },
    {
      "asset": "USDT",
      "free": "1000.00",
      "locked": "100.00"
    }
  ],
  "permissions": [
    "SPOT"
  ]
}

响应字段说明：

  • makerCommission : maker 手续费费率。
  • takerCommission : taker 手续费费率。
  • buyerCommission : 买方手续费费率。
  • sellerCommission : 卖方手续费费率。
  • canTrade : 是否可以交易。
  • canWithdraw : 是否可以提现。
  • canDeposit : 是否可以充值。
  • updateTime : 账户更新时间（Unix 时间戳）。
  • accountType : 账户类型 (例如: SPOT)。
  • balances : 资产余额数组。
    • asset : 资产代码 (例如: BTC, USDT)。
    • free : 可用余额。
    • locked : 锁定余额。
  • permissions : 账户权限列表。

错误处理：

如果请求失败，服务器将返回包含错误代码和消息的 JSON 响应。常见的错误包括无效的 API 密钥、无效的签名、时间戳过期等。请根据错误消息进行相应的调整。

安全注意事项：

  • 始终保护您的 API 密钥，不要将其泄露给他人。
  • 使用安全的网络连接 (HTTPS) 发送请求。
  • 验证服务器的响应签名，以确保响应的真实性。
  • 仔细阅读并理解 API 文档，确保正确使用 API。

获取账户历史交易记录

端点： /api/v3/myTrades

该端点用于检索特定交易对的账户历史成交记录。 为了确保数据安全，所有请求都需要进行签名认证。

参数：

  • symbol : 必需 ，交易对。指定需要查询历史交易记录的交易对，例如： BTCUSDT 。这是必填参数，否则服务器将返回错误。
  • orderId : 可选 ，订单ID。如果指定了订单ID，则仅返回与该订单相关的交易记录。如果没有指定，则返回所有历史交易记录。
  • startTime : 可选 ，起始时间戳（毫秒）。指定返回交易记录的起始时间，精确到毫秒。如果没有指定，则从最早的交易记录开始返回。
  • endTime : 可选 ，结束时间戳（毫秒）。指定返回交易记录的结束时间，精确到毫秒。如果没有指定，则返回到最新的交易记录。
  • fromId : 可选 ，交易ID，用于分页。如果需要分页查询交易记录，可以使用此参数指定起始交易ID。返回的交易记录将从指定的交易ID之后开始。
  • limit : 可选 ，返回的交易记录数量。指定每次请求返回的交易记录数量。默认值为 500 ，最大值为 1000 。如果请求的交易记录数量超过最大值，服务器将只返回 1000 条记录。
  • recvWindow : 可选 ，接收窗口。指定请求被接受的处理时限，单位为毫秒。如果服务器在指定的时间内没有收到请求，则请求将被拒绝。建议设置为小于或等于 5000 的值。
  • timestamp : 必需 ，时间戳。发送请求时的Unix时间戳（毫秒），用于验证请求的有效性。时间戳必须在服务器允许的 recvWindow 范围内，否则请求将被拒绝。

安全注意事项

  • API 密钥安全至关重要： 始终将您的 API 密钥视为高度敏感信息。 绝对不要将其硬编码到客户端应用程序（例如，移动应用程序或前端 JavaScript 代码）中，因为这些应用程序可以被反编译或检查。 不要将其存储在公共代码仓库中，例如 GitHub 或 GitLab。 不要通过不安全的渠道（例如，电子邮件或即时消息）与他人共享。 考虑使用环境变量或安全的密钥管理系统来存储和访问 API 密钥。
  • 强制执行 HTTPS： 使用 HTTPS (HTTP Secure) 对所有 API 请求进行加密。 HTTPS 使用 TLS/SSL 协议对客户端和服务器之间的通信进行加密，从而防止中间人窃听和篡改数据。 确保您的 API 端点仅通过 HTTPS 提供服务。
  • API 响应签名验证： 验证所有 API 响应的签名。 许多交易所 API 使用数字签名来确保响应的完整性和真实性。 验证签名可以帮助您检测响应是否被篡改或伪造。 请仔细阅读 API 文档，了解如何验证签名。通常涉及使用 API 密钥和私钥进行哈希和加密操作。
  • 利用 recvWindow 参数防御中间人攻击： 使用 recvWindow 参数来指定请求被接受的处理时间窗口（以毫秒为单位）。 这有助于防止中间人攻击，攻击者可能会尝试重放旧的请求。 将 recvWindow 设置为合理的值，以允许网络延迟，但要足够小以防止重放攻击。
  • 权限最小化原则： 限制您的 API 密钥的权限，只授予您的应用程序所需的最低权限。 例如，如果您的应用程序只需要读取市场数据，则不要授予其交易或提款的权限。 大多数交易所 API 允许您创建具有特定权限的 API 密钥。 定期审查和调整您的 API 密钥权限，以确保它们仍然满足您的应用程序的需求。
  • API 使用监控和异常检测： 持续监控您的 API 使用情况，以检测任何异常活动。 监控指标包括请求数量、错误率、延迟和数据量。 设置警报，以便在检测到可疑活动时收到通知。 例如，如果您的 API 密钥突然开始生成大量错误或发送大量请求，则可能表明存在安全漏洞。
  • 定期密钥轮换： 定期更新您的 API 密钥。 密钥轮换是一种安全最佳实践，可以降低 API 密钥被盗或泄露的风险。 交易所API通常允许你生成新的密钥对。一旦生成新的密钥对，确保平滑过渡，更新你的应用以使用新密钥，同时吊销旧密钥以避免潜在的安全风险。

签名计算

为了确保API请求的安全性与完整性，所有需要授权的API请求都必须包含 signature 参数。此签名通过标准的 HMAC SHA256 算法生成，它使用您的 secretKey 作为密钥，对经过特定处理的请求查询字符串进行哈希计算。

signature 参数允许服务器验证请求是否来自授权用户，并且在传输过程中未被篡改。正确实现签名计算是使用API的关键部分。

以下是生成和使用签名参数的详细步骤：

  1. 参数排序： 收集所有请求参数，包括强制性的时间戳参数 timestamp 和可选的接收窗口参数 recvWindow 。然后，按照参数名称的字母顺序对这些参数进行排序。例如， symbol 应排在 timestamp 之前。
  2. 字符串拼接： 将排序后的参数及其对应的值拼接成一个查询字符串格式的字符串。键值对之间使用等号 = 连接，不同的键值对之间使用 & 连接符分隔。 请务必确保URL编码的正确性。示例： key1=value1&key2=value2&recvWindow=5000&timestamp=1678886400000 。
  3. HMAC SHA256 哈希： 使用您的 secretKey 作为密钥（secretKey是您私有的API密钥，请妥善保管，切勿泄露），对上一步中拼接生成的字符串进行 HMAC SHA256 哈希运算。此步骤将生成一个唯一的哈希值，该哈希值将作为您的签名。
  4. 添加签名参数： 将生成的哈希值作为 signature 参数的值添加到您的API请求中。此 signature 参数也应该包含在发送到服务器的最终URL或请求体中。

几乎所有主流编程语言都提供了用于计算 HMAC SHA256 哈希值的库。 请务必查阅您所使用的编程语言的官方文档或相关资源，以了解如何正确使用这些库。以下是一个Python示例，展示了如何使用 hashlib 和 hmac 模块来生成签名。

以下是一个Python示例，展示了如何使用 hashlib 和 hmac 模块来生成签名。 

import hashlib
import hmac
import urllib.parse

api_secret = "YOUR_API_SECRET"  # 替换为您的真实secretKey

def sign_request(params):
    """Calculates the signature for a Binance API request."""
    query_string = urllib.parse.urlencode(sorted(params.items()))
    signature = hmac.new(api_secret.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha256).hexdigest()
    return signature

重要提示：

  • 请务必妥善保管您的 secretKey ，不要将其泄露给任何第三方。
  • 在生成签名之前，请确保所有参数都已正确编码，尤其是特殊字符。
  • 确保您的系统时钟与服务器时间同步，因为 timestamp 参数的准确性对于验证签名至关重要。
  • 在实际应用中，替换代码示例中的 "YOUR_API_SECRET" 为您的实际 API secret key.
  • 不同的API可能对于签名算法的要求略有不同，请仔细阅读相关API文档。

示例：币安API请求参数详解

以下是一个使用币安API进行交易的参数示例，展示了构建有效请求所需的核心字段。每个参数都扮演着至关重要的角色，确保交易能够准确、安全地执行。

params 示例: 

  
    {
      "symbol": "BTCUSDT",
      "side": "BUY",
      "type": "MARKET",
      "quantity": 0.01,
      "timestamp": 1678886400000,
      "recvWindow": 5000
    }

参数说明：

  • symbol : 交易对，指定交易的资产。例如， "BTCUSDT" 表示比特币 (BTC) 与 USDT 的交易对。请确保使用的交易对在币安平台上有效且可用。
  • side : 交易方向，指定是买入还是卖出。 "BUY" 表示买入， "SELL" 表示卖出。
  • type : 订单类型，指定订单的执行方式。 "MARKET" 表示市价单，将以当前市场最优价格立即执行。其他常见的订单类型还包括限价单 ( "LIMIT" ) 和止损单 ( "STOP_LOSS" )。
  • quantity : 交易数量，指定交易的资产数量。例如， 0.01 表示买入或卖出 0.01 个 BTC。请注意，币安对不同的交易对有最小交易数量限制，请确保您的交易数量满足这些限制。
  • timestamp : 请求时间戳，以毫秒为单位的 Unix 时间戳。用于验证请求的时效性，防止重放攻击。可以使用编程语言的内置函数或在线工具生成当前时间戳。
  • recvWindow : 接收窗口，指定请求在服务器端有效的时间范围（毫秒）。用于防止网络延迟导致的请求过期。如果服务器接收到请求的时间超过了 recvWindow 指定的时间范围，则该请求将被拒绝。合理设置 recvWindow 可以提高API请求的稳定性。

签名生成：

为了确保API请求的安全性，需要对请求参数进行签名。签名是使用您的 API secretKey 对参数进行哈希运算的结果。 

  
    signature = sign_request(params)
    params['signature'] = signature

其中， sign_request 函数是一个自定义函数，用于根据币安的签名规则生成签名。通常使用 HMAC-SHA256 算法，并使用您的 API secretKey 作为密钥。

将生成的签名添加到 params 中： 

  
    print(params)

API SecretKey：

请务必将 YOUR_API_SECRET 替换为您从币安官方获取的实际 API secretKey。API secretKey 是用于签名请求的密钥，请妥善保管，切勿泄露。

正确构建并签名API请求是与币安API交互的关键步骤。理解每个参数的作用，并确保签名的正确性，是成功进行交易的基础。

相关推荐