HTX API终极指南：新手也能轻松上手！

2025-03-08 研究 82℃

HTX官网API教程

简介

本文档旨在为开发者提供HTX（火币）交易所API的全面且详细的技术指南。本指南将协助开发者深入理解并高效利用HTX API进行各种操作，包括但不限于自动化交易策略的执行、实时市场数据的获取、账户管理、以及其他相关交易所功能的程序化访问。HTX API提供了一套功能完备的应用程序编程接口，开发者可以通过编程方式，安全、可靠地与HTX交易所进行交互，实现定制化的交易和数据分析需求。

该API允许开发者创建自动交易机器人、集成交易功能到现有应用程序中，或者构建自定义的交易界面。文档内容涵盖了API的认证方式、请求格式、响应解析、以及错误处理机制，力求为开发者提供清晰、易懂的参考资料，从而降低开发门槛，加速应用开发进程。通过深入学习本指南，开发者将能够充分利用HTX API的强大功能，在数字资产交易领域取得更大的成功。

API概述

HTX API采用RESTful架构设计，旨在为开发者提供高效、便捷的数字资产管理和交易接口。所有API通信均通过HTTPS协议加密，确保数据传输的安全性。API请求和响应的数据格式主要采用JSON（JavaScript Object Notation），便于解析和处理。为保障账户安全和API调用权限，开发者必须首先在HTX平台注册账户，并在账户设置中生成API密钥对，其中包括Access Key（用于标识身份）和Secret Key（用于签名请求）。只有拥有有效的API密钥，开发者才能成功访问和使用HTX API进行各种操作，例如查询账户余额、下单交易、获取市场数据等。密钥的安全保管至关重要，应避免泄露给他人，以防止未经授权的访问。

API Endpoint

HTX（火币）API提供了一系列接口，允许开发者访问平台上的各种功能，包括现货交易、合约交易、账户信息查询等。这些API的基础Endpoint（接入点）如下所示，务必仔细区分并根据您的具体需求选择正确的Endpoint，错误的Endpoint选择会导致请求失败。

公共API (现货交易API): https://api.hbg.com
此Endpoint是访问HTX现货交易市场数据和进行现货交易操作的主要入口。您可以使用此Endpoint获取实时行情、历史数据、账户余额、下单/撤单等功能。 api.hbg.com 处理包括交易对信息、K线数据、深度数据、用户资产查询、现货交易委托等请求。使用该Endpoint前，请确保您的API密钥已启用现货交易权限。
合约API (期货/合约交易API): https://api.hbdm.com (适用于合约交易，例如：币本位合约、USDT本位合约、交割合约和永续合约)
此Endpoint专门用于HTX的合约交易，包括币本位合约、USDT本位合约、交割合约以及永续合约。通过此Endpoint，您可以查询合约市场数据、进行合约交易、管理合约账户等。 api.hbdm.com 处理合约市场数据、指数数据、资金费率、合约下单/撤单、仓位查询、止盈止损设置等请求。使用合约API需要单独申请合约交易权限，并且需要注意合约交易的风险。

重要提示： 在使用HTX API时，Endpoint的选择至关重要。错误的Endpoint会导致请求失败，并可能影响您的交易策略。请仔细阅读HTX官方API文档，确认您使用的Endpoint与您所要进行的操作相符。同时，建议定期检查Endpoint地址是否更新，以确保API连接的稳定性和可靠性。不同Endpoint的请求频率限制可能不同，请注意控制请求频率，避免触发API限流。

认证

HTX API 采用 HMAC-SHA256 算法进行身份验证，确保交易安全和数据完整性。所有需要授权的 API 请求必须包含以下核心参数，以便服务器验证请求的合法性：

AccessKeyId ：您的唯一访问密钥 ID，用于标识您的身份。请务必妥善保管，避免泄露。
SignatureMethod ：指定用于计算签名的算法，在本例中固定为 HMAC-SHA256 。
SignatureVersion ：指定签名协议的版本，确保客户端和服务器使用相同的签名规则。当前版本为 2 。
Timestamp ：请求发送的时间戳，以协调服务器时间并防止重放攻击。时间戳必须是 UTC 时间，精确到秒。

以上参数均需包含在请求中。签名本身需要通过 Signature 参数传递。 Signature 参数是根据请求参数、您的 SecretKey 和 SignatureMethod 使用 HMAC-SHA256 算法计算得出的加密字符串。服务器将使用相同的算法和您的 SecretKey 重新计算签名，并将其与您提供的签名进行比较。如果两者匹配，则请求将被视为有效并进行处理。

签名生成步骤：

构建规范化请求字符串: 将构成API请求的所有要素进行精确组织，形成一个用于签名计算的规范化字符串。这涉及以下几个关键步骤：
- 确定请求方法: 明确HTTP请求的方法，例如 GET 或 POST ，并将其作为规范化字符串的起始部分。通常需要将其转换为大写。
- 指定API Endpoint: 确定API的Endpoint地址，包括域名和端口号（如果非标准端口）。确保Endpoint的格式正确无误，例如 api.example.com 。
- 声明API路径: 精确指定API的访问路径，例如 /v1/user/profile 。务必包含前导斜杠，并确保路径与API文档一致。
- 参数排序与连接: 这是构建规范化字符串的核心环节。将所有请求参数，包括强制性的身份验证参数（如 AccessKeyId 、 SignatureMethod 、 SignatureVersion 和 Timestamp ）以及业务相关的请求参数，按照参数名称的字母顺序进行排序。对排序后的参数，按照 参数名=参数值 的格式进行拼接，并使用 & 符号连接各个参数对。
- URL编码: 对所有参数值进行URL编码，以确保特殊字符（例如空格、斜杠、等号和 & 符号）被正确转义。URL编码使用百分号编码，例如将空格编码为 %20 。同时，需要注意，有些API还会要求对参数名也进行URL编码。
注意：规范化字符串的生成必须严格按照API文档的说明进行，任何偏差都可能导致签名验证失败。
计算签名: 使用 SecretKey 作为对称密钥，对上一步构建的规范化请求字符串进行HMAC-SHA256哈希运算，生成消息认证码。然后，将生成的哈希结果进行Base64编码。
- HMAC-SHA256哈希: 使用 SecretKey 作为密钥，采用HMAC-SHA256算法对规范化请求字符串进行哈希运算。HMAC (Hash-based Message Authentication Code) 是一种消息认证码算法，它使用密钥和哈希函数来生成消息的摘要，以验证消息的完整性和真实性。
- Base64编码: 将HMAC-SHA256哈希运算的结果（通常是二进制数据）进行Base64编码，将其转换为可打印的ASCII字符串。Base64编码是一种将二进制数据转换为文本格式的编码方案，它使用64个不同的字符来表示二进制数据。
- SecretKey的安全: 必须严格保护 SecretKey 的安全，切勿泄露给未授权方。一旦 SecretKey 泄露，攻击者就可以伪造签名，从而冒充合法用户发起API请求。
添加签名参数: 将计算得到的签名添加到请求参数中，作为 Signature 参数的值。该 Signature 参数与其他请求参数一同发送到API服务器，用于验证请求的合法性。
- Signature参数的位置: Signature 参数可以添加到请求的URL查询字符串中，也可以添加到HTTP请求头中（具体取决于API的要求）。
- 确保URL编码: 如果 Signature 参数添加到URL查询字符串中，务必对 Signature 参数的值进行URL编码。
- 服务端验证: API服务器收到请求后，会使用相同的算法和密钥（ SecretKey ）重新计算签名，并将计算得到的签名与请求中携带的 Signature 参数进行比较。如果两个签名一致，则认为请求是合法的；否则，认为请求是非法的。

请求频率限制

为了保障API服务的稳定性与可靠性，HTX实施了API请求频率限制策略。此策略旨在防止恶意攻击、过度占用资源以及确保所有用户都能公平地访问API。不同的API接口由于其功能和资源消耗的不同，具有不同的频率限制。因此，开发者必须仔细查阅每个API接口的官方文档，了解其具体的频率限制要求，并在开发过程中进行相应的调整，以避免触发频率限制。

当API请求超过允许的频率限制时，服务器将会返回相应的错误码，表明请求已被拒绝。最常见的错误码是429 (Too Many Requests)，它明确指出客户端发送的请求过于频繁。收到此错误码后，开发者应当立即停止发送请求，并根据错误信息调整请求频率。

优化API使用，避免触发频率限制的方法包括：合理控制请求频率，例如在发送请求之间增加适当的延迟；实施缓存机制，避免重复请求相同的数据；尽可能地使用批量请求功能，将多个操作合并为一个请求，从而减少请求的总次数；以及采用异步请求方式，避免阻塞主线程，提高程序的响应速度。监控API的响应时间和错误率，有助于及时发现并解决频率限制问题。务必遵守HTX的API使用条款，以确保服务的正常运行。

错误码

HTX API在处理请求过程中，可能会遇到各种问题，从而返回不同的错误码。这些错误码旨在向开发者清晰地传达请求失败的具体原因，以便进行针对性的调试和处理。务必仔细阅读官方API文档，深入理解每一个错误码所代表的含义及其潜在的触发条件。了解错误码的含义是构建健壮且可靠的应用程序的关键一环。常见的错误码包括：

400 Bad Request（错误请求）: 此错误表示客户端发送的请求包含无效的参数。常见的原因包括：参数缺失、参数类型错误、参数值超出允许范围、JSON格式不正确等。开发者应仔细检查请求参数，确保其符合API文档的规范。
401 Unauthorized（未授权）: 此错误表明请求缺少有效的身份验证凭据，或者提供的凭据无效。通常，这意味着API密钥未提供，或者API密钥不正确、过期、已被禁用。开发者需要检查API密钥是否正确配置，并且具有访问所需资源的权限。另外，也需要检查时间戳是否同步，避免因时间偏差过大导致认证失败。
403 Forbidden（已禁止）: 此错误表示客户端已通过身份验证，但没有权限访问请求的资源。这可能是由于账户权限不足、IP地址被限制、或者请求访问了受限的API接口。开发者应检查账户权限，确认是否有权访问该资源。还需要检查IP地址是否被列入黑名单，并确保请求符合API的使用条款。
404 Not Found（未找到）: 此错误表示请求的资源在服务器上不存在。这可能是由于URL地址错误、资源已被删除、或者资源尚未创建。开发者应仔细检查URL地址，确保其指向正确的资源。
429 Too Many Requests（请求过多）: 此错误表明客户端在短时间内发送了过多的请求，超过了API的速率限制。为了保护服务器的稳定性，HTX API会限制每个账户的请求频率。开发者应实施速率限制策略，例如使用令牌桶算法或漏桶算法，避免超过API的限制。如果需要更高的请求频率，请联系HTX官方申请。
500 Internal Server Error（服务器内部错误）: 此错误表示服务器在处理请求时遇到了未知的内部错误。这通常是由于服务器端的bug、配置错误、或者资源不足导致的。如果遇到此错误，建议稍后重试。如果问题持续存在，请联系HTX官方技术支持，并提供相关请求信息，以便他们进行排查。

常用API接口

以下介绍一些常用的HTX API接口，这些接口为开发者提供了访问HTX交易所各种功能的途径，包括市场数据查询、交易执行、账户管理等。通过合理使用这些API，可以构建自动化交易系统、行情监控工具以及数据分析平台。

获取市场行情

GET /market/tickers: 获取所有交易对的最新行情数据快照。此接口提供了一个全局视角，让您快速掌握市场整体动态。返回信息包括每个交易对的最新成交价格、当日最高价、当日最低价、24小时成交量（以基础货币计价）、24小时成交额（以报价货币计价）等关键指标，帮助您高效评估市场活跃度和潜在机会。
GET /market/detail/merged: 获取特定交易对的深度聚合行情数据，以便进行更细致的分析。此接口将多个交易深度合并，提供更流畅的价格走势图。返回数据包含指定交易对的实时行情快照，以及关键的24小时成交量、最高成交价格、最低成交价格等统计信息。还提供买一价、卖一价以及对应的挂单量，揭示市场微观结构。
GET /market/depth: 获取特定交易对的实时盘口深度数据，洞察市场买卖力量分布。返回的盘口信息包括买一价、卖一价，以及买方和卖方各个价格档位的挂单量。通过指定深度范围参数，您可以自定义需要观察的盘口深度，聚焦特定价格区间的供需情况。此接口有助于识别潜在支撑位和阻力位，并预测短期价格走势。
GET /market/trade: 获取特定交易对的最新成交记录，追踪市场实时交易动态。返回的信息包含成交时间（精确到毫秒级）、成交价格、成交数量、以及明确的买卖方向（买入或卖出）。通过分析历史成交记录，您可以了解市场参与者的交易行为，并判断价格上涨或下跌的趋势是否真实。
GET /market/history/kline: 获取特定交易对的历史K线数据，进行技术分析和趋势预测。此接口允许您指定K线类型，例如1分钟K线、5分钟K线、15分钟K线、30分钟K线、1小时K线、4小时K线、1天K线、1周K线、1月K线等，满足不同时间周期的分析需求。您还可以指定数据范围，获取特定时间段内的K线数据。K线数据包括开盘价、收盘价、最高价、最低价以及成交量，是技术分析的重要工具。

账户信息

GET /v1/account/accounts: 获取用户所有账户信息的API接口。该接口返回一个包含用户所有账户的列表，每个账户包含以下关键信息：唯一的账户ID，用于在其他API调用中标识该账户；账户类型，明确指出账户的用途，例如现货交易账户、杠杆保证金账户、合约账户、储蓄账户等；账户状态，指示账户的当前状态，例如正常、已冻结、已禁用等，用于判断账户是否可用于交易或转账。
GET /v1/account/accounts/{account-id}/balance: 获取指定账户ID的余额信息的API接口。该接口允许用户查询特定账户中各种加密货币的余额详情。返回的信息包括：可用余额，表示可以立即用于交易或转账的金额；冻结余额，表示由于挂单或其他原因被暂时锁定的金额，不可用于交易或转账；总余额，是可用余额和冻结余额的总和，代表账户中该币种的总资产；币种类型，指明余额对应的加密货币种类，例如BTC、ETH、USDT等。该接口对于用户了解账户资金状况至关重要。

交易操作

POST /v1/order/orders/place: 创建新的订单，提交至交易平台。此接口允许用户根据市场情况和交易策略，构建包含交易对（如BTC/USDT）、订单类型（限价单limit order、市价单market order、止损单stop-loss order等）、买卖方向（buy或sell）、指定价格（对于限价单）、交易数量等关键参数的订单请求。订单提交后，系统将验证参数，并将订单挂至交易簿，等待撮合。
POST /v1/order/orders/{order-id}/submitcancel: 撤销指定的订单。此接口接受订单ID作为参数，允许用户取消尚未完全成交的挂单。撤单请求提交后，系统将从交易簿中移除该订单。需要注意的是，部分已部分成交的订单可能无法完全撤销，或者撤销请求可能需要一段时间才能生效，具体取决于交易所的系统处理速度和当前的市场交易活跃程度。
GET /v1/order/orders/{order-id}: 获取指定订单的详细信息。通过提供订单ID，用户可以查询特定订单的完整信息，包括订单状态（例如，pending、partially filled、filled、canceled）、订单类型、下单时间、成交均价、剩余数量以及任何相关的附加信息。这有助于用户监控订单执行情况，并进行交易决策。
GET /v1/order/openOrders: 获取用户的当前挂单信息。此接口返回用户所有未成交或部分成交的有效订单列表。用户可以通过指定交易对、订单类型等参数进行筛选，以便更有效地管理和监控其持仓情况。返回的信息通常包括订单ID、交易对、订单类型、买卖方向、价格、数量、下单时间等。
GET /v1/order/history: 获取用户的历史成交记录。此接口允许用户查询其历史交易数据，包括所有已成交的订单。通过指定交易对、时间范围、订单状态（如filled、canceled）等参数，用户可以对历史交易记录进行过滤和分析。返回的信息通常包括订单ID、交易对、成交价格、成交数量、手续费、成交时间等。历史成交记录对于审计、税务申报以及交易策略的回测至关重要。

合约交易API

HTX为满足专业交易者的需求，提供了专门的合约交易API。这些API接口与现货交易API有所区别，旨在提供更精细化的合约交易功能。合约交易API允许用户通过程序化方式进行下单、撤单、查询账户信息以及管理持仓，实现自动化交易策略。

POST /linear-swap-api/v1/swap_order: 合约下单。此API接口允许用户提交合约交易订单，包括市价单、限价单等多种订单类型。用户需指定合约代码、交易方向（买入或卖出）、委托价格（限价单时）、委托数量等参数。服务器将验证订单参数并尝试撮合交易。成功的订单将进入成交队列。
POST /linear-swap-api/v1/swap_cancel: 合约撤单。用于取消尚未成交的合约订单。用户需提供要取消的订单ID。此接口允许用户快速调整交易策略，避免因市场波动造成不必要的损失。
GET /linear-swap-api/v1/swap account info: 获取合约账户信息。该API接口返回用户的合约账户余额、可用保证金、冻结保证金、未实现盈亏等重要信息。这些信息对于评估账户风险、调整仓位至关重要。用户可根据账户信息制定合理的风险管理策略。
GET /linear-swap-api/v1/swap position info: 获取合约持仓信息。此接口提供用户当前持有的合约仓位信息，包括持仓数量、平均持仓成本、当前盈亏、保证金占用等。通过此接口，用户可以实时监控仓位状态，及时采取止盈止损措施。

代码示例 (Python)

以下是一个使用Python编写的示例，展示了如何从HTX（火币全球站）交易所获取实时市场行情数据。此代码片段涉及API密钥的安全管理、请求签名生成以及数据解析，旨在提供一个可靠的API交互基础。

import requests ：引入requests库，用于发起HTTP请求，是Python进行网络编程的标准库之一。

import urllib.parse ：导入urllib.parse模块，用于URL的编码和解析，在构造带参数的API请求时非常有用。

import hashlib ：引入hashlib库，提供多种哈希算法，如SHA256，用于数据完整性校验和安全签名生成。

import hmac ：导入hmac模块，用于创建哈希消息认证码，结合密钥对请求进行签名，保证请求的真实性和防止篡改。

import base64 ：引入base64库，用于进行Base64编码，常用于将二进制数据转换为文本格式，方便在HTTP头中传输签名信息。

import time ：导入time模块，用于获取当前时间戳，时间戳通常作为API请求的参数，防止重放攻击。

API 密钥

进行API调用时，身份验证至关重要。您需要配置以下密钥和端点才能成功连接到交易所的API。请注意妥善保管您的 SECRET_KEY ，避免泄露，以防止资产损失。

ACCESS_KEY = "YOUR_ACCESS_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
ENDPOINT = "https://api.hbg.com"

上述代码段定义了三个关键变量： ACCESS_KEY ，用于标识您的账户； SECRET_KEY ，用于生成安全签名；以及 ENDPOINT ，指定API服务器的地址。请务必将 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 替换为您从交易所获得的实际API密钥。

generate_signature(method, url, params) 函数用于创建API请求的数字签名，确保请求的完整性和真实性。

def generate_signature(method, url, params):
    """生成API签名"""
    timestamp = str(int(time.time()))
    params["AccessKeyId"] = ACCESS_KEY
    params["SignatureMethod"] = "HmacSHA256"
    params["SignatureVersion"] = "2"
    params["Timestamp"] = timestamp

    sorted_params = sorted(params.items(), key=lambda x: x[0])
    query_string = urllib.parse.urlencode(sorted_params)

    payload = f"{method}\n{url}\n/\n{query_string}"

    digester = hmac.new(SECRET_KEY.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256)
    signature = base64.b64encode(digester.digest()).decode()
    return signature

该函数首先添加必要的认证参数到请求参数中，例如 AccessKeyId ， SignatureMethod ， SignatureVersion 和 Timestamp 。然后，它对参数进行排序并将其编码为URL查询字符串。接下来，它使用HMAC-SHA256算法对包含HTTP方法、URL和查询字符串的payload进行签名，并将签名进行Base64编码。生成的签名将附加到API请求中，以供服务器验证。

get_market_tickers() 函数展示了如何使用上述签名函数来获取市场行情数据。

def get_market_tickers():
    """获取市场行情数据"""
    method = "GET"
    url = ENDPOINT
    path = "/market/tickers"
    params = {}

    signature = generate_signature(method, url, params)
    params["Signature"] = signature

    full_url = url + path + "?" + urllib.parse.urlencode(params)

    try:
        response = requests.get(full_url)
        response.raise_for_status()  # 检查HTTP错误

        data = response.()
        print(.dumps(data, indent=4))

    except requests.exceptions.RequestException as e:
        print(f"请求出错: {e}")
    except .JSONDecodeError as e:
        print(f"JSON解析出错: {e}")

此函数构造完整的API请求URL，包括路径和签名后的查询参数。然后，它使用 requests 库发送GET请求，并处理可能出现的HTTP错误和JSON解析错误。成功获取的数据将以格式化的JSON格式打印到控制台。

主程序入口：

if __name__ == "__main__":
    get_market_tickers()

这段代码确保只有在直接运行脚本时才执行 get_market_tickers() 函数。当脚本作为模块导入时，不会执行此函数。

请务必替换 YOUR_ACCESS_KEY 和 YOUR_SECRET_KEY 为您的实际API密钥。此代码只是一个基本示例，您可以根据需要进行修改和扩展。例如，您可以添加错误处理、数据验证和重试机制，以提高代码的健壮性和可靠性。

注意事项

API密钥安全至关重要： 务必妥善保管您的API密钥，切勿将其泄露给任何未经授权的第三方。建议使用环境变量或专门的密钥管理服务来存储和访问密钥，并定期审查访问权限。泄漏的API密钥可能导致账户被盗用，造成数据泄露或经济损失。
深入理解API文档： 在使用API之前，务必仔细阅读官方提供的API文档。透彻理解每个接口的功能、所需的参数类型、参数的取值范围以及返回值的结构。这有助于您正确地调用API，避免因参数错误或数据格式不匹配而导致的问题。
全面处理错误码： API调用并非总是成功，因此必须认真处理API返回的各种错误码。根据不同的错误码采取相应的措施，例如重试、记录日志或向用户显示错误信息。完善的错误处理机制能够提高程序的健壮性，避免因API错误而导致程序崩溃或数据丢失。
遵守频率限制策略： 大多数API都设有频率限制，以防止滥用和保证服务质量。务必遵守API的频率限制，避免在短时间内发送过多的请求。如果需要高频率的API调用，可以考虑使用批量请求或缓存机制，或者与API提供商协商更高的频率限制。违反频率限制可能导致您的API密钥被暂停或禁用。
采用HTTPS安全通信： 为了确保数据在传输过程中的安全性，强烈建议使用HTTPS协议进行API通信。HTTPS协议通过SSL/TLS加密数据，防止数据被窃听或篡改。请确保您的代码中所有API请求都使用HTTPS协议，并在服务器端配置正确的SSL证书。
定期轮换API密钥： 为了降低API密钥泄露的风险，建议定期更换您的API密钥。密钥轮换周期可以根据安全需求和风险评估来确定。在更换密钥后，务必更新所有使用该密钥的应用程序和配置文件。
充分的测试环境验证： 在将API集成到生产环境之前，务必先在测试环境进行充分的测试。模拟各种使用场景和错误情况，验证API调用的正确性和性能。这可以帮助您及早发现潜在的问题，避免在生产环境中出现意外情况。