🔥HTX API深度揭秘：解锁你的交易超能力！🚀

社区 2025-03-08 50 次浏览

本文详细介绍了HTX交易所提供的API文档，涵盖现货、合约等交易领域，以及市场数据、账户管理、交易执行等各个方面。助您快速构建高效稳定的交易应用。

HTX平台API开发文档详解

HTX（原Huobi）作为全球领先的加密货币交易所之一，为开发者提供了全面的API开发文档，旨在帮助开发者高效地构建和集成各种交易应用程序。这些API涵盖了市场数据、账户管理、交易执行等多个方面，使得开发者能够充分利用HTX平台的功能。本文将详细介绍HTX平台提供的API开发文档，并对各个主要模块进行解析。

HTX API文档概述

HTX API文档提供了全面的接口，方便开发者接入和集成HTX的各项交易功能。 文档主要分为以下几个大类，每个类别都提供了详细的接口说明、请求参数、响应示例和错误代码：

  • 现货API (Spot API): 提供现货交易所需的所有接口，允许用户获取实时的市场数据，包括最新成交价、交易量、深度数据等。用户可以通过该API进行限价单、市价单等多种类型的下单操作，并能实时查询订单状态（如已成交、部分成交、已撤销），以及获取详细的账户余额信息，包括可用余额、冻结余额和总资产。
  • 合约API (Futures API): 专门为合约交易设计的API，功能与现货API类似，但针对的是永续合约和交割合约市场。 除了提供市场数据和下单功能外，还支持设置止盈止损、调整杠杆倍数等合约特有的操作。API文档详细描述了不同合约类型（如USDT本位合约、币本位合约）的接口差异。
  • 期权API (Options API): 用于期权交易的API，功能包括获取期权链信息，即特定标的资产在不同行权价格和到期日下的所有期权合约列表。用户可以使用此API进行期权合约的买入和卖出操作，并查询订单状态。 文档详细说明了期权合约的结构和参数含义。
  • 杠杆API (Margin API): 允许用户通过借入资金进行杠杆交易。 该API提供了借币、还币、划转保证金等功能，用户可以利用杠杆放大收益，但也需注意控制风险。 文档中详细说明了杠杆利率、借币额度等相关参数。
  • 币币杠杆API (Isolated Margin API): 与普通杠杆交易不同，币币杠杆采用隔离保证金模式，针对特定的交易对提供杠杆服务。 每个交易对的保证金独立计算，降低了爆仓风险。 API文档详细说明了不同交易对的杠杆倍数和保证金要求。
  • WebSocket API: 提供实时的、双向的数据通信通道，允许用户订阅各种市场数据流，例如实时行情（Ticker Data）、深度数据（Order Book Data）、成交明细（Trade Data）和个人订单更新（Order Updates）。 通过WebSocket API，用户可以构建高频交易策略或实时监控市场动态。
  • 公共API (Public API): 提供无需身份验证即可访问的公共数据，例如K线数据（Candlestick Data）、交易对信息（Symbol Information）、服务器时间等。 这些数据对于了解市场整体情况和构建交易策略至关重要。公共API通常有访问频率限制。
  • REST API: 基于HTTP协议的API，采用请求-响应模式进行数据交互。 HTX的绝大多数API都是基于RESTful架构实现的，用户可以通过发送HTTP请求（GET、POST、PUT、DELETE等）来获取数据和执行操作。 REST API易于使用和集成，是与HTX平台交互的主要方式。 文档详细说明了每个接口的HTTP方法、URL、请求头、请求体和响应格式。

现货API (Spot API)

现货API是HTX平台最常用的API之一，为用户提供程序化访问HTX现货交易市场的强大工具。 它提供了一整套功能，允许开发者和交易者通过编程方式执行各种操作，包括查询市场数据、管理账户信息、下单交易等。 利用现货API，用户可以构建自动化交易策略、量化交易系统，以及与其他应用程序集成。

具体来说，通过现货API，用户可以实时获取包括最新成交价、买卖盘口深度、历史交易记录在内的市场数据。用户还可以查询账户余额、持仓情况，确保资金安全和交易决策的有效性。 现货API支持多种订单类型，如限价单、市价单、止损单等，满足不同交易场景的需求。 开发者可以根据自身策略，选择合适的订单类型，实现精确的交易控制。

HTX平台的现货API通常提供详细的文档和示例代码，帮助开发者快速上手。 开发者可以通过API密钥进行身份验证，确保交易安全。同时，HTX平台通常会提供API使用的频率限制，以保证系统的稳定性和公平性。了解并遵守这些限制是使用API进行高效交易的关键。

市场数据

  • 获取交易对信息 (GET /v1/common/symbols): 获取所有可交易的现货交易对的详细信息，这是进行交易决策的基础。返回的信息包括交易对名称（如BTC/USDT），最小交易数量（限制单笔交易的最小单位，防止微小订单），价格精度（小数点后位数，影响挂单和成交价格的准确性），交易手续费率（影响交易成本），以及交易对的状态（是否可交易，是否暂停等）。通过此接口，开发者可以全面了解交易所支持的交易品种及其交易规则。
  • 获取K线数据 (GET /market/history/kline): 获取指定交易对的历史K线数据，这是技术分析的基础。可指定时间周期（如1分钟、5分钟、15分钟、30分钟、1小时、4小时、1天、1周、1月等，不同的时间周期反映不同时间跨度的价格波动）和数量（一次请求获取多少根K线）。关键参数包括 symbol (交易对，例如btc/usdt), period (时间周期，例如1min, 5min, 1h, 1d), 和 size (K线数量，最大值通常有限制)。每根K线包含开盘价（open）、最高价（high）、最低价（low）、收盘价（close）以及成交量（volume）。利用K线数据，可以进行趋势分析、形态识别等技术分析操作。
  • 获取聚合行情数据 (GET /market/detail/merged): 获取指定交易对的实时聚合行情数据，这是快速了解市场整体状况的关键接口。返回数据包括最新价格（当前成交价）、最高价（24小时内最高价）、最低价（24小时内最低价）、成交量（24小时内成交的币的数量）、成交额（24小时内成交的总金额）、买一价和买一量（当前最佳买入价格和数量）、卖一价和卖一量（当前最佳卖出价格和数量）等。聚合行情数据经过交易所汇总处理，信息量大，响应速度快，适合高频交易和快速决策。
  • 获取市场深度数据 (GET /market/depth): 获取指定交易对的市场深度数据，也称为订单簿数据，它反映了买卖双方的挂单情况。返回数据包括多个买单和卖单的价格和数量，按照价格从优到劣排序。可指定深度级别 (例如：step0, step1, step2, step3, step4, step5，不同的级别代表价格的精度和深度)。更精细的深度级别提供更详细的订单簿信息，但数据量也更大。通过分析市场深度数据，可以了解市场的买卖力量对比，判断支撑位和阻力位，并预测价格走势。
  • 获取最近成交记录 (GET /market/trade): 获取指定交易对的最近成交记录，也称为逐笔成交数据，它记录了每一笔成交的具体信息。返回数据包括成交价格、成交时间（精确到毫秒级别）、成交方向（买入或卖出，buy或sell）、成交量等。通过分析成交记录，可以了解市场的实时交易情况，例如大额成交的发生时间、买卖盘的主动性等。高频交易者通常会使用成交记录数据来优化交易策略。
  • 获取最近24小时行情数据 (GET /market/detail): 获取指定交易对的最近24小时行情数据，这是了解市场整体表现的重要指标。返回数据包括开盘价（24小时前开盘价格）、收盘价（当前价格）、最高价（24小时内最高价）、最低价（24小时内最低价）、成交量（24小时内成交的币的数量）、成交额（24小时内成交的总金额）、以及24小时内价格变动百分比等。此接口提供的数据可以帮助投资者快速评估市场的整体表现和潜在风险。

账户管理

  • 获取账户信息 ( GET /v1/account/accounts ): 获取用户的账户信息，此操作需要有效的API密钥进行身份验证，以确保账户安全。返回的信息通常包括账户ID、账户类型（例如现货账户、合约账户）以及与该账户关联的其他关键属性。API密钥必须正确配置，并在请求头中以符合规范的方式传递，否则将收到授权失败的错误。
  • 获取指定账户余额 ( GET /v1/account/accounts/{account-id}/balance ): 获取指定账户ID的余额信息。该接口返回详细的余额快照，包括可用余额（可用于交易）、冻结余额（因挂单或其他原因被暂时锁定的资金）、以及总余额。 {account-id} 需要替换为实际的账户ID。 此API调用对于监控账户资金状况至关重要，有助于制定交易策略和风险管理。返回数据通常会包含货币种类（例如BTC、ETH、USDT）以及对应的余额数值，精确到小数点后若干位。

交易执行

  • 下单 (POST /v1/order/orders/place): 下单接口，用于创建买入或卖出订单，是进行加密货币交易的关键步骤。此接口允许用户向交易所提交订单请求，指定具体的交易参数。需要指定交易对、订单类型（限价单、市价单）、价格（仅限价单）、数量等关键参数。交易平台会根据这些参数尝试撮合交易。
    • account-id : 账户ID。指定用于交易的账户，确保交易操作在正确的账户下执行。不同的账户可能拥有不同的权限和资金。
    • symbol : 交易对。指定要交易的两种加密货币，例如 BTC/USDT。交易对是市场报价的基础，确定了交易的币种组合。
    • type : 订单类型。定义订单的执行方式，常见的类型包括：
      • buy-limit : 限价买入。以指定的价格或更低的价格买入。订单只有在市场价格达到或低于指定价格时才会成交。
      • sell-limit : 限价卖出。以指定的价格或更高的价格卖出。订单只有在市场价格达到或高于指定价格时才会成交。
      • buy-market : 市价买入。以当前市场最优价格立即买入。订单会尽快成交，但成交价格可能略有波动。
      • sell-market : 市价卖出。以当前市场最优价格立即卖出。订单会尽快成交，但成交价格可能略有波动。
    • price : 价格 (仅限价单)。指定限价订单的价格。这是订单成交的最高买入价或最低卖出价。市价单不需要指定价格。
    • amount : 数量。指定要买入或卖出的加密货币数量。数量是交易规模的体现，直接影响交易成本和潜在收益。
  • 撤销订单 (POST /v1/order/orders/{order-id}/submitcancel): 撤销指定订单。用户可以通过此接口取消尚未成交的订单。订单一旦撤销，将不再参与市场撮合。撤销订单可以帮助用户灵活调整交易策略，避免不必要的损失。
  • 批量撤销订单 (POST /v1/order/orders/batchcancel): 批量撤销订单。此接口允许用户一次性撤销多个订单，提高操作效率。可以根据订单ID列表进行批量撤销。批量撤销适用于需要快速调整交易策略或处理大量未成交订单的情况。
  • 查询订单详情 (GET /v1/order/orders/{order-id}): 查询指定订单的详细信息。此接口提供订单的全面信息，包括订单状态、下单时间、成交价格、成交数量、手续费等。订单状态可以反映订单的当前执行情况，例如：待成交、部分成交、完全成交、已撤销等。
  • 查询未成交订单 (GET /v1/order/openOrders): 查询当前账户的未成交订单。此接口返回账户中所有尚未完全成交的订单列表，方便用户监控和管理未完成的交易。用户可以根据未成交订单的情况，及时调整交易策略。

合约API (Futures API)

合约API与现货API类似，但专门用于合约交易，也称为期货交易。与现货交易直接买卖资产不同，合约交易允许用户通过预测资产未来价格变动进行交易，无需实际持有该资产。这为交易者提供了做多（预期价格上涨）或做空（预期价格下跌）的机会，从而在不同市场条件下都能参与交易。

合约交易涉及更加复杂的概念，例如：

  • 合约类型： 主要包括交割合约和永续合约。交割合约具有预定的到期日，到期时合约将按照结算价格进行结算。永续合约则没有到期日，交易者可以无限期地持有合约，但需要注意资金费用（Funding Rate），资金费用是多头和空头之间定期支付的费用，旨在使永续合约的价格接近标的资产的现货价格。
  • 杠杆倍数： 杠杆允许交易者以较小的保证金控制更大的头寸。例如，使用10倍杠杆，交易者可以用100美元控制价值1000美元的合约。虽然杠杆可以放大盈利，但也会放大亏损，因此风险管理至关重要。交易者应谨慎选择杠杆倍数，并了解其潜在影响。
  • 保证金： 用于开立和维持合约头寸所需的资金。交易所通常要求初始保证金和维持保证金。初始保证金是开仓所需的最低金额，而维持保证金是保持头寸开放所需的最低金额。如果账户余额低于维持保证金水平，可能会触发强制平仓（Liquidation），导致资金损失。
  • 强平价格： 当市场价格朝着不利于交易者头寸的方向移动时，如果账户余额不足以支付潜在亏损，交易所将强制平仓以防止进一步的损失。强平价格的计算取决于杠杆倍数、保证金水平和其他因素。
  • 资金费率 (Funding Rate)： 永续合约交易中的一种机制，多头和空头之间会定期支付费用。如果永续合约价格高于现货价格，则资金费率为正，多头向空头支付费用，反之亦然。资金费率有助于保持永续合约价格与现货价格的锚定。

理解这些概念对于成功使用合约API至关重要。 交易者应充分了解合约交易的风险和回报，并采取适当的风险管理措施，例如设置止损单和止盈单，以限制潜在的损失并锁定利润。 合约API通常提供各种功能，包括下单、查询订单状态、获取市场数据和管理账户余额。

市场数据

  • 获取合约信息 (GET /api/v1/contract contract info): 获取指定合约的详细信息，包括合约代码（例如 BTCUSDT）、结算币种（如 USDT、BTC）、合约乘数（也称为合约面值）、最小变动单位、以及其他与合约规范相关的关键参数。通过此接口，开发者可以准确了解合约的属性，为交易策略的制定提供基础数据。
  • 获取合约指数信息 (GET /api/v1/contract_index): 获取反映一系列现货价格的加权平均值，是合约定价的重要参考。指数构成成分、权重、以及计算方法都会影响指数的准确性。API返回的指数信息通常包括指数值、时间戳以及相关元数据，帮助用户判断合约的合理价格，并进行套利交易。
  • 获取合约最高限价和最低限价 (GET /api/v1/contract price limit): 获取当前合约允许交易的最高价格和最低价格，这是交易所风控机制的一部分，旨在防止市场操纵和极端波动。超出此范围的订单将被拒绝执行。了解价格限制有助于交易者避免不必要的交易失败，并规划风险管理策略。
  • 获取合约K线数据 (GET /api/v1/contract_kline): 获取指定时间周期内的开盘价、最高价、最低价、收盘价和成交量，是技术分析的基础数据。K线周期可以包括分钟级别（如 1m, 5m, 15m）、小时级别（如 1h, 4h）、日级别（1d）、周级别（1w）甚至月级别（1M）。K线数据常用于识别趋势、支撑位、阻力位等重要市场信号。
  • 获取合约市场深度数据 (GET /api/v1/contract_depth): 获取买单和卖单的挂单信息，反映市场买卖力量的分布情况。通常以买一价、买一量、卖一价、卖一量等形式展示，并可扩展到更深层次的挂单数据。市场深度数据有助于判断市场的流动性和潜在的价格变动方向。
  • 获取合约最近成交记录 (GET /api/v1/contract_trade): 获取最近发生的交易记录，包括成交价格、成交数量、交易方向（买入或卖出）和成交时间。通过分析成交记录，可以了解市场的实时交易情况，判断市场情绪和交易活跃度。
  • 获取合约聚合行情数据 (GET /api/v1/contract detail merged): 获取将多个数据源（例如交易所的不同档位）聚合后的行情数据，提供更加全面的市场概览。通常包括最新成交价、最高价、最低价、成交量、持仓量、资金费率等关键指标，便于快速了解市场整体状况。

账户管理

  • 获取账户信息 ( POST /api/v1/contract_account_info ): 获取指定合约账户的详细信息，此操作需要提供有效的API密钥进行身份验证，以确保只有授权用户才能访问账户敏感数据。返回的信息通常包括账户余额、可用保证金、已用保证金等。通过定期查询账户信息，用户可以实时监控账户状态，及时调整交易策略。
  • 获取持仓信息 ( POST /api/v1/contract_position_info ): 获取合约持仓的详细信息，涵盖多仓和空仓的数量、平均开仓价格、以及未实现盈亏等关键指标。持仓信息对于风险管理至关重要，通过监控持仓数据，用户可以评估当前持仓的风险敞口，并根据市场变化及时调整仓位。平均开仓价格是计算盈亏的重要依据，而未实现盈亏则反映了当前持仓的潜在收益或损失。
  • 获取订单限额信息 ( POST /api/v1/contract_order_limit ): 查询特定合约的订单数量和金额限制。订单限额的设定旨在防止市场操纵和过度交易，保障交易平台的稳定运行。通过了解订单限额，用户可以合理规划交易策略，避免因超出限额而导致交易失败。返回的信息通常包括每个订单的最大数量、每日的总订单数量限制等。

交易执行

  • 下单 ( POST /api/v1/contract_order ): 下单接口允许用户提交买入或卖出合约的请求，从而在市场上建立头寸。此接口需要提供一系列参数来精确定义订单。需要指定交易的合约代码，明确订单类型（例如，限价单或市价单），设定价格（仅对限价单有效），确定交易数量，并选择适当的杠杆倍数以控制风险和潜在回报。
    • contract_code : 合约代码，用于唯一标识要交易的合约产品，例如"BTC_USDT"代表比特币兑USDT的合约。
    • volume : 数量，指定交易的合约数量，代表用户希望买入或卖出的合约单位数量。
    • price : 价格 (仅限价单)，只有当订单类型为限价单时才需要指定价格，代表用户愿意买入或卖出的最高或最低价格。
    • direction : 买卖方向 ( buy , sell )，指示交易的方向， buy 表示买入开多或买入平空， sell 表示卖出开空或卖出平多。
    • offset : 开平仓方向 ( open , close )，指定订单是用于开立新仓位还是平掉现有仓位， open 表示开仓， close 表示平仓。
    • lever_rate : 杠杆倍数，允许用户放大其交易头寸，从而放大潜在收益和损失。选择合适的杠杆倍数至关重要，需谨慎评估风险承受能力。
    • order_price_type : 订单价格类型，指定订单的执行方式，常见的类型包括：
      • limit : 限价单，以指定的价格或更好的价格成交。
      • opponent : 对手价，以当前市场上最优的对手方价格成交。
      • post_only : 只挂单，如果订单会立即成交，则会被取消，确保订单始终作为挂单存在，通常用于享受maker手续费。
      • ioc (Immediate-or-Cancel): 立即成交或取消，订单必须立即全部成交，否则将被取消。
      • fok (Fill-or-Kill): 全部成交或取消，订单必须立即全部成交，否则将被取消。与IOC类似，但要求订单必须一次性全部成交。
  • 批量下单 ( POST /api/v1/contract_batchorder ): 批量下单接口允许用户一次性提交多个订单，从而简化交易流程，提高效率。通过此接口，用户可以同时执行多个交易策略或对冲风险。
  • 撤销订单 ( POST /api/v1/contract_cancel ): 撤销订单接口允许用户取消尚未成交的订单。如果市场价格发生变化或交易策略需要调整，用户可以使用此接口及时取消订单，避免不必要的损失。
  • 全部撤单 ( POST /api/v1/contract_cancelall ): 全部撤单接口允许用户一次性取消所有未成交的订单。在市场出现剧烈波动或需要快速调整交易策略时，此接口非常有用。
  • 查询订单详情 ( POST /api/v1/contract_order_info ): 查询订单详情接口允许用户查询指定订单的详细信息，包括订单状态、成交价格、成交数量等。通过此接口，用户可以全面了解订单的执行情况。
  • 查询未成交订单 ( POST /api/v1/contract_openorders ): 查询未成交订单接口允许用户查询当前账户所有未成交的订单。用户可以通过此接口监控未成交订单的状态，并根据市场情况进行调整或取消。

WebSocket API

WebSocket API 提供了一种全双工通信协议，用于在客户端和服务器之间建立持久连接，实现实时数据流传输。在加密货币领域，这意味着开发者可以利用 WebSocket API 无需频繁发起 HTTP 请求，即可即时获取市场行情、订单簿深度、交易执行情况以及账户状态等关键信息，从而对市场变化做出更快速、更灵敏的反应。这种实时性对于量化交易、高频交易以及需要持续监控市场动态的应用至关重要。

  • 订阅行情数据 (market.*.kline.*) : 订阅 K 线数据。 K 线数据包含了特定时间段内的开盘价、收盘价、最高价和最低价，是技术分析的基础。通过订阅不同时间周期的 K 线数据（例如，market.BTC.kline.1min, market.ETH.kline.1hour），开发者可以构建各种技术指标和交易策略，实时追踪价格走势。 * 符号代表通配符，允许订阅所有交易对或特定交易对的 K 线数据。
  • 订阅市场深度数据 (market.*.depth.*) : 订阅市场深度数据，也称为订单簿数据。订单簿展示了市场上买单和卖单的分布情况，包括每个价格级别的订单数量。通过分析市场深度数据，开发者可以了解市场的供需关系、支撑位和阻力位，以及潜在的价格波动方向。 * 通配符允许订阅所有交易对或特定交易对的深度数据。不同的深度级别，例如depth.5, depth.20， 表示返回订单簿前5名或者前20名的买卖盘信息。
  • 订阅交易详情数据 (market.*.trade.detail) : 订阅交易详情数据，也称为逐笔成交数据。每次交易发生时，都会生成一条交易详情数据，包含成交时间、成交价格、成交数量和交易方向（买入或卖出）。通过订阅交易详情数据，开发者可以实时追踪市场的交易活动，分析交易量变化和价格波动之间的关系，识别大额交易，并及时调整交易策略。 * 符号同样表示通配符，允许开发者订阅所有交易对或特定交易对的交易详情。
  • 订阅账户数据 (accounts.update) : 订阅账户数据更新。账户数据包括用户的资产余额、可用余额、冻结余额等信息。通过订阅账户数据，开发者可以实时监控账户资金变动，及时调整交易策略，避免因资金不足而导致交易失败，同时也有助于进行风险管理。
  • 订阅订单数据 (orders.update) : 订阅订单数据更新。订单数据包括订单的状态（例如，已提交、已成交、已撤销）、委托价格、委托数量、成交数量等信息。通过订阅订单数据，开发者可以实时追踪订单执行情况，及时调整未成交订单的价格和数量，优化交易执行效果，同时也能监控订单是否存在异常情况。

公共API (Public API)

公共API提供无需身份验证即可访问的公共数据，例如实时K线数据、交易对的详细参数信息等。这类API通常用于获取市场概览、构建行情看板或进行初步的数据分析，开发者无需申请API密钥即可直接调用，极大地方便了数据获取和应用开发。

  • 获取服务器时间 (GET /v1/common/timestamp) : 获取交易所服务器当前时间戳，以Unix时间戳格式返回。该接口可用于同步客户端与服务器的时间，确保数据请求的时效性和准确性，尤其在需要高精度时间戳的交易策略中至关重要。
  • 获取所有交易对信息 (GET /v1/common/symbols) : 获取平台上所有交易对的详细信息，包括交易对名称、基础货币、计价货币、最小交易数量、价格精度、交易状态等。这些信息对于了解市场结构、筛选特定交易对、构建交易机器人至关重要，方便开发者根据自身需求选择合适的交易市场。
  • 获取所有可用币种 (GET /v1/common/currencys) : 获取平台上所有可用的币种信息，包括币种名称、币种符号、精度等。此接口允许开发者了解平台支持的全部币种，从而进行更广泛的数据分析和资产管理。此接口常用于构建资产列表或支持用户选择交易币种。

HTX平台提供的API文档覆盖了现货、合约、期权、杠杆等多个交易领域，以及市场数据、账户管理、交易执行等各个方面。开发者可以根据自己的需求选择合适的API进行开发，构建高效、稳定的交易应用程序。 需要注意的是，在使用API时，务必仔细阅读API文档，了解各个接口的参数、返回值、错误码等信息，并严格遵守HTX平台的API使用规则，以确保应用程序的正常运行和数据的安全。 此外，HTX平台也会不定期更新API文档，增加新的功能和接口，开发者需要及时关注API文档的更新，以便能够充分利用HTX平台的功能。