您现在的位置是: 首页 > 文档 文档
HTX API终极指南:掌握交易参数,跑赢机器人!
时间:2025-03-08 94人已围观
HTX API 参数指南
概览
HTX API 提供了一套功能强大的接口,旨在赋能开发者,使其能够无缝地与 HTX(原火币)交易所进行深度交互。通过这些接口,开发者可以实现多种关键操作,例如执行交易订单(包括限价单、市价单等)、实时获取全面的市场数据(如交易对的最新价格、成交量、深度信息等)、安全地管理和监控其 HTX 账户信息、以及程序化地进行资产划转等。熟练地理解并正确运用 HTX API 提供的各种参数是成功构建高效、可靠且安全的交易应用程序的基石。参数配置的任何细微偏差都可能导致交易失败、数据错误或潜在的安全风险。
本指南经过精心设计,旨在对 HTX API 中最常用和最重要的参数进行详尽的介绍和解释,并提供清晰的使用示例。我们将深入探讨每个参数的作用、取值范围、数据类型以及与其他参数之间的关系。通过本指南,开发者将能够更有效地利用 HTX API,构建出满足其特定需求的交易策略和自动化工具。本指南还将强调在使用 API 时需要注意的安全事项和最佳实践,以确保应用程序的安全性和稳定性。
常用参数类型
HTX API的参数传递是与交易所进行数据交互的关键。为了确保请求的有效性和数据的准确性,API定义了一系列常用的参数类型。理解这些类型及其使用方式对于成功调用API至关重要。
- 字符串 (String): 用于表示文本数据,是API中最常用的参数类型之一。字符串参数通常用于传递具有文本含义的信息,例如交易对名称(如"BTCUSDT")、订单类型(如"limit"、"market")、订单方向(如"buy"、"sell")以及各种状态描述等。需要注意的是,字符串参数通常区分大小写,并且可能需要符合特定的格式规范。
- 整数 (Integer): 用于表示整数值,常用于传递数量、索引或ID等信息。例如,订单数量(指定购买或出售的具体数量)、时间戳(表示事件发生的精确时间,通常以Unix时间戳表示,即自1970年1月1日以来的秒数)、以及各种订单ID或账户ID等。在API调用中,确保整数参数的取值范围符合API的限制,避免超出范围导致错误。
- 浮点数 (Float/Decimal): 用于表示浮点数值,用于传递价格、费率等具有小数位的数值信息。在金融交易领域,价格的精度至关重要,因此API通常采用高精度的浮点数或Decimal类型来表示价格和费率,以确保计算的准确性。在处理浮点数时,需要注意精度问题,避免由于舍入误差导致交易异常。不同的API可能对浮点数的精度有不同的要求,需要仔细阅读API文档。
- 布尔值 (Boolean): 用于表示真/假值,通常用于控制API的行为或表示某种状态。例如,是否为市价单(如果为true,则表示市价单;如果为false,则表示限价单)、是否只返回最新的数据、是否启用某个功能等。布尔值通常用`true`或`false`来表示,有些API也可能使用`1`和`0`来表示。
- 数组 (Array): 用于表示一组相同类型的数据,允许一次性传递多个相关的数据。例如,订单ID列表(用于批量查询订单状态)、交易对列表(用于同时订阅多个交易对的市场数据)、或者一组价格数据等。数组中的元素可以是任意合法的参数类型,例如字符串、整数、浮点数等。API文档通常会指定数组中元素的类型和数量限制。
- 对象 (Object): 用于表示复杂的数据结构,包含多个键值对,每个键值对可以表示不同的属性或配置。对象可以嵌套,形成更复杂的数据结构。例如,一个订单对象可能包含订单ID、交易对、订单类型、价格、数量、状态等多个属性。对象参数通常使用JSON格式进行序列化和传递。理解对象参数的结构和每个键的含义对于正确解析API响应至关重要。
关键API参数详解
以下将针对HTX API中常见的API端点,详细介绍其关键参数,并深入解析每个参数的作用和使用场景。理解这些参数对于高效、准确地使用HTX API至关重要。
我们将涵盖不同类型的API端点,例如现货交易、合约交易、账户信息查询等,并分别针对每个端点列出关键参数。对于每个参数,我们将详细说明其数据类型、取值范围、是否必选、以及可能出现的错误代码。我们还将提供一些最佳实践,帮助您避免常见的错误和提高API调用的效率。
例如,对于现货交易API的下单端点,我们将详细介绍
symbol
(交易对)、
type
(订单类型)、
amount
(数量)、
price
(价格)等参数。我们将解释不同订单类型(如市价单、限价单)的区别,以及如何根据不同的市场情况选择合适的订单类型。我们还将讨论如何设置合适的
amount
和
price
,以确保订单能够成功执行。
对于合约交易API,我们将重点介绍
contract_code
(合约代码)、
direction
(买卖方向)、
offset
(开平仓类型)、
lever_rate
(杠杆倍数)等参数。我们将详细解释不同合约代码的含义,以及如何选择合适的合约进行交易。我们还将讨论如何正确设置
direction
和
offset
,以确保交易方向和开平仓类型符合预期。我们还将强调合理使用
lever_rate
的重要性,以避免过度风险。
对于账户信息查询API,我们将重点介绍如何获取账户余额、交易记录、持仓信息等。我们将解释不同类型的账户(如现货账户、合约账户)的区别,以及如何使用不同的API端点查询不同账户的信息。我们还将讨论如何处理API返回的数据,以便进行进一步的分析和处理。
通过深入理解这些关键API参数,您将能够更加自信地使用HTX API,并构建出高效、可靠的交易系统。我们建议您在使用API之前,仔细阅读官方文档,并进行充分的测试,以确保您的API调用能够正常工作。
1. 获取市场行情数据 (GET /market/tickers)
该接口用于获取指定交易对的市场行情快照信息,提供实时的交易数据,是进行交易决策的重要参考。
- symbol (String): 交易对名称,例如 "btcusdt"。 这是唯一必须提供的参数,用于指定您希望获取行情数据的具体交易对。 务必确保交易对名称的准确性,通常由两个币种符号组成,例如 "btcusdt" 代表比特币 (BTC) 兑 USDT 的交易对。不区分大小写,但建议使用小写以保持一致性。
- depth (Integer, 可选): 深度数据档位数量,影响返回的买单和卖单的深度信息。可选值包括 5, 10, 和 20。 数值越大,返回的买卖盘深度越深,可以更全面地了解市场挂单情况。如果不指定该参数,服务器会返回一个默认的深度值,通常为5。 选择合适的深度值可以根据你的交易策略进行调整,例如,高频交易者可能更关注较浅的深度,而长线投资者可能需要更深度的信息。深度值代表了买一到买N和卖一到卖N的档位数量。
注意事项: 请注意,频繁调用该接口可能会受到API频率限制。 建议合理设置调用频率,并缓存数据以减少API调用次数。 通过分析返回的行情数据,您可以了解当前的市场价格、交易量、买卖盘情况等,为您的交易决策提供支持。
示例:
GET /market/tickers?symbol=btcusdt
获取指定交易对,例如 BTC/USDT 的实时行情数据。该接口返回包括最新成交价、24小时涨跌幅、交易量等关键信息。通过修改
symbol
参数,可以查询其他任何支持的交易对,例如
ethusdt
查询 ETH/USDT 的行情,
bnbusdt
查询 BNB/USDT 的行情。返回的数据结构通常包含多个字段,用于详细描述市场状况。客户端可以通过解析这些字段,为用户提供全面的市场分析和交易决策支持。详细的参数定义和返回数据结构应参考具体的API文档。
2. 获取K线数据 (GET /market/history/kline)
- symbol (String): 交易对名称,用于指定您希望检索K线数据的特定交易市场。 例如,"btcusdt" 代表比特币与 USDT 的交易对,"ethbtc" 代表以太坊与比特币的交易对。 务必使用交易所支持的有效交易对代码。 该参数为 必选参数 。
-
period (String):
K线周期,定义了每根K线所代表的时间跨度。 该参数决定了K线图的粒度。 例如:
- "1min" 代表1分钟K线,每根K线包含1分钟内的开盘价、最高价、最低价和收盘价。
- "5min" 代表5分钟K线。
- "15min" 代表15分钟K线。
- "30min" 代表30分钟K线。
- "60min" 或 "1hour" 代表1小时K线。
- "1day" 代表每日K线。
- "1week" 代表每周K线。
- "1mon" 代表每月K线。
- "1year" 代表每年K线。
- size (Integer): 返回K线数据的数量,指定您希望获取的K线数量。 这是一个可选参数,允许您控制API返回的数据量。 默认值为150,意味着如果您不指定该参数,API将返回最近的150根K线。 最大值为2000,超过该值将被截断。 返回数量越多,对服务器的压力越大,但也为您提供更全面的历史数据。 该参数为 可选参数 。
示例:
GET /market/history/kline?symbol=btcusdt&period=1day&size=30
用于获取特定加密货币交易对的历史K线数据。在这个例子中,它请求的是 BTC/USDT 交易对最近30天的日K线数据。具体参数解释如下:
-
/market/history/kline
: API的终结点,指示请求的是市场历史K线数据。 -
symbol=btcusdt
: 指定交易对为比特币 (BTC) 兑泰达币 (USDT)。在不同的交易所,符号的命名可能有所不同,请务必参考交易所的API文档。 -
period=1day
: 定义K线的时间周期为1天。除了1day,常见的周期还包括:1min(1分钟)、5min(5分钟)、15min(15分钟)、30min(30分钟)、1hour(1小时)、4hour(4小时)、1week(1周)、1month(1月)。选择合适的周期取决于你的分析需求。 -
size=30
: 指定返回的K线数量为30。这意味着API将返回最近30个指定周期(这里是日)的K线数据。增加size
可以获取更长时间的历史数据,但也可能增加请求的响应时间。
K线数据通常包含开盘价、收盘价、最高价、最低价和成交量等信息,这些信息对于技术分析和交易策略的制定至关重要。通过调整
symbol
、
period
和
size
参数,可以灵活地获取不同交易对、不同时间跨度的历史数据,从而进行更深入的市场分析。在使用API时,请务必阅读相关API文档,了解参数的具体含义和使用限制,例如请求频率限制等。交易所可能会对 API 请求的频率进行限制,以防止滥用和维护服务器稳定。同时,注意数据来源的可靠性,选择信誉良好且数据准确的交易所API。
3. 下单 (POST /order/orders)
- account-id (Integer): 账户ID。这是您账户的唯一标识符,用于指定哪个账户将执行此订单。该参数为整数类型,且为 必选参数 。您可以通过账户管理接口获取您的账户ID。
- symbol (String): 交易对名称,例如 "btcusdt"。 该参数指定您想要交易的资产对,例如,"btcusdt" 代表比特币兑 USDT 的交易。 务必使用正确的交易对,该参数为字符串类型,且为 必选参数 。请确保该交易对在交易所是有效的。
-
type (String):
订单类型,指定订单的执行方式。 该参数为字符串类型,且为
必选参数
。具体支持的订单类型如下:
- buy-market (市价买入): 以当前市场最优价格立即买入指定数量的标的资产。
- sell-market (市价卖出): 以当前市场最优价格立即卖出指定数量的标的资产。
- buy-limit (限价买入): 以指定的价格或更低的价格买入指定数量的标的资产。只有当市场价格达到或低于指定价格时,订单才会被执行。
- sell-limit (限价卖出): 以指定的价格或更高的价格卖出指定数量的标的资产。只有当市场价格达到或高于指定价格时,订单才会被执行。
- buy-ioc (IOC买入): Immediate-Or-Cancel 买入,指订单提交后,会立即与市场上的卖单进行撮合,如果没有全部成交,剩余部分会被立即取消。
- sell-ioc (IOC卖出): Immediate-Or-Cancel 卖出,指订单提交后,会立即与市场上的买单进行撮合,如果没有全部成交,剩余部分会被立即取消。
- buy-limit-maker (Post Only买入): Post Only 买入,指订单提交后,如果会立即与市场上的卖单进行撮合,那么该订单会被立即取消。 保证只挂单,不吃单。
- sell-limit-maker (Post Only卖出): Post Only 卖出,指订单提交后,如果会立即与市场上的买单进行撮合,那么该订单会被立即取消。 保证只挂单,不吃单。
- amount (String): 交易数量。指定您想要买入或卖出的资产数量。 该参数为字符串类型,且为 必选参数 。对于市价买入 (buy-market) 订单,该参数表示您希望花费的 USDT 数量;对于其他类型的订单,该参数表示您希望买入或卖出的币的数量。
- price (String): 委托价格 (仅限价单需要)。 指定您希望买入或卖出的价格。 该参数为字符串类型,只有当订单类型为限价单(buy-limit, sell-limit, buy-limit-maker, sell-limit-maker)时才为 必选参数 。
- client-order-id (String): 客户端订单ID,用于区分不同的订单。这是一个由客户端生成的唯一标识符,用于在您的系统中跟踪和识别订单。 该参数为字符串类型,是 可选参数 。如果您没有提供该参数,系统会自动生成一个。
- source (String): 订单来源,默认 "api"。 指定订单的来源渠道,默认为 "api",表示通过 API 接口提交的订单。 该参数为字符串类型,是 可选参数 。
- stop-price (String): 止损止盈触发价。当市场价格达到或超过此价格时,将触发止损止盈订单。该参数为字符串类型,是 可选参数 。
-
operator (String):
触发后订单行为,"gte" (>=), "lte" (<=)。 指定触发止损止盈订单的条件。 该参数为字符串类型,是
可选参数
。
- gte (>=): 当市场价格大于或等于止损止盈触发价时,触发订单。
- lte (<=): 当市场价格小于或等于止损止盈触发价时,触发订单。
示例:
以下JSON示例展示了一个典型的交易订单结构,用于在加密货币交易所提交买入限价单:
{
"account-id": 1234567,
"symbol": "btcusdt",
"type": "buy-limit",
"amount": "0.001",
"price": "20000.00"
}
字段解释:
-
account-id
:1234567
。 用户的账户ID,用于标识订单属于哪个账户。这是交易所用来验证身份和追踪交易的关键信息。需要确保账户ID的准确性,避免交易错误归属。 -
symbol
:"btcusdt"
。交易对,代表要交易的加密货币对。btcusdt
表示比特币 (BTC) 兑美元泰达币 (USDT)。 其他常见的交易对包括ethbtc
(以太坊兑比特币) 和ltcusdt
(莱特币兑美元泰达币)。 选择正确的交易对对于成功执行交易至关重要。 -
type
:"buy-limit"
。订单类型。buy-limit
表示一个限价买单,只有当市场价格达到或低于指定价格时才会执行。 其他常见的订单类型包括sell-limit
(限价卖单),buy-market
(市价买单), 和sell-market
(市价卖单)。 限价单允许交易者设定期望的买入价格。 -
amount
:"0.001"
。交易数量。 要购买的symbol
中指定加密货币的数量。 在这个例子中,用户希望购买 0.001 个比特币。 请务必仔细检查交易数量,避免意外的大额交易。 -
price
:"20000.00"
。 订单价格。 用户愿意为每个单位的symbol
支付的最高价格。 对于buy-limit
订单,交易所只有在市场价格达到或低于 20000.00 USDT 时才会执行该订单。 价格的设置需要根据市场分析和交易策略进行。
重要提示:
- 不同的加密货币交易所可能需要不同的字段或采用不同的格式。提交订单前,请务必查阅交易所的API文档。
- 该JSON仅为示例,实际交易中需要根据市场情况和个人交易策略进行调整。
- 务必保证API Key等敏感信息的安全,避免泄露。
4. 撤销订单 (POST /order/orders/{order-id}/submitcancel)
该接口允许用户撤销尚未成交的订单。通过向指定URL发起POST请求,可以取消先前提交的交易指令。 请注意,撤销请求仅适用于尚未完全成交或部分成交的订单。已经完全成交的订单无法撤销。
- order-id (String): 要撤销的订单ID。必选参数,必须作为URL路径的一部分提供。订单ID是系统为每笔订单分配的唯一标识符,用于精确指定需要取消的订单。确保提供的订单ID与需要取消的订单完全匹配,否则可能无法成功撤销订单。
请求示例:
POST /order/orders/1234567890/submitcancel
在这个示例中,
1234567890
就是需要撤销的订单ID。 服务器会验证该订单ID是否存在,并且该订单的状态是否允许撤销操作。
注意事项:
- 撤销请求可能会受到网络延迟和其他因素的影响,导致撤销操作并非立即生效。 用户应关注订单状态的更新。
- 交易所或平台可能对撤销操作设置时间限制或其他规则。请务必查阅相关文档,了解具体限制。
- 频繁提交撤销请求可能会影响交易性能,甚至可能受到平台的限制。 请谨慎使用撤销功能。
- 撤销请求成功后,系统会将订单状态更新为已撤销。 用户可以通过查询订单状态接口确认撤销结果。
示例:
POST /order/orders/1234567890/submitcancel
操作用于提交订单取消请求,针对特定订单ID。在该示例中,订单ID为
1234567890
。此接口允许用户或系统发起取消已提交但尚未完全执行的订单的流程。调用此端点将触发取消流程,具体是否成功取决于订单状态、交易所规则以及系统当前状态等因素。取消请求提交后,系统将尝试按照交易所的规则取消该订单。请注意,即使提交了取消请求,也可能因为市场情况或交易所限制而无法成功取消订单。 在实际应用中,1234567890 只是一个示例订单ID,实际使用时需要替换成真实的、有效的订单ID。
5. 查询订单详情 (GET /order/orders/{order-id})
本接口用于获取指定订单ID的详细信息。通过提供订单ID,您可以查询到该订单的各项属性,包括订单状态、创建时间、交易币种、交易数量、成交价格等。
- order-id (String): 要查询的订单ID。
- 描述: 订单ID是用于唯一标识订单的字符串。每个订单在创建时都会被分配一个唯一的订单ID。
- 必选参数: 此参数为必选,必须作为URL的一部分提供。如果没有提供有效的订单ID,服务器将返回错误。
-
URL示例:
/order/orders/1234567890
,其中1234567890
为订单ID。
请求方法: GET
请求URL: /order/orders/{order-id}
请求头: 通常需要包含身份验证信息,例如API密钥或Token,具体取决于平台的安全策略。
响应: 服务器将返回一个JSON对象,包含订单的详细信息。如果订单不存在,可能会返回404错误。
可能的响应字段 (示例):
-
orderId
: 订单ID (String) -
userId
: 用户ID (String) -
symbol
: 交易对 (String),例如 "BTC/USDT" -
orderType
: 订单类型 (String),例如 "LIMIT" (限价单), "MARKET" (市价单) -
side
: 交易方向 (String), "BUY" (买入), "SELL" (卖出) -
price
: 委托价格 (Number),仅限价单有效 -
quantity
: 委托数量 (Number) -
executedQuantity
: 成交数量 (Number) -
status
: 订单状态 (String),例如 "NEW" (新订单), "PARTIALLY_FILLED" (部分成交), "FILLED" (完全成交), "CANCELED" (已取消), "REJECTED" (已拒绝) -
createTime
: 订单创建时间 (Number,Unix时间戳) -
updateTime
: 订单更新时间 (Number,Unix时间戳)
示例:
GET /order/orders/1234567890
查询特定订单ID的订单详情。此API端点允许用户通过提供唯一的订单ID(在此示例中为 1234567890)来检索与该订单相关的完整信息。返回的数据通常包含订单的状态、创建时间、包含的商品列表、总金额、支付方式以及收货地址等详细信息。该接口设计为只读操作,不允许修改订单数据。
6. 查询当前委托、历史委托订单 (GET /order/openOrders , GET /order/history)
- symbol (String): 交易对名称,用于指定查询的交易市场。例如 "btcusdt" 表示比特币对USDT的交易对。此参数为可选,如果不指定,则返回所有交易对的订单信息。交易对的命名规则通常为"基础货币-计价货币",例如 "ethbtc"。
-
types (String):
订单类型,用于筛选特定类型的订单。可以同时查询多种订单类型,多个类型之间用逗号分隔。例如 "buy-limit,sell-limit" 表示查询限价买单和限价卖单。常见的订单类型包括:
-
buy-market
: 市价买单 -
sell-market
: 市价卖单 -
buy-limit
: 限价买单 -
sell-limit
: 限价卖单 -
buy-ioc
: Immediate-Or-Cancel买单,立即成交剩余撤销 -
sell-ioc
: Immediate-Or-Cancel卖单,立即成交剩余撤销 -
buy-limit-maker
: Post-Only限价买单(只挂单,不吃单) -
sell-limit-maker
: Post-Only限价卖单(只挂单,不吃单) -
buy-stop-limit
: 止盈止损限价买单 -
sell-stop-limit
: 止盈止损限价卖单
-
- account-id (Integer): 账户ID,用于指定查询的账户。每个用户可以拥有多个账户,例如现货账户、合约账户等。此参数为可选。
- start-time (Long): 起始时间戳 (毫秒),用于指定查询订单的起始时间。返回所有创建时间晚于或等于此时间戳的订单。此参数为可选。
- end-time (Long): 结束时间戳 (毫秒),用于指定查询订单的结束时间。返回所有创建时间早于或等于此时间戳的订单。此参数为可选。
- from (String): 起始订单ID,用于分页查询。指定从哪个订单ID开始查询。通常用于在大量订单数据中进行分页浏览。此参数为可选。
- direct (String): 查询方向,可选值为 "prev" (向前) 和 "next" (向后)。配合 `from` 参数使用,指定从起始订单ID向前或向后查询。 "prev" 表示查询ID小于`from`的订单,"next" 表示查询ID大于`from`的订单。此参数为可选。
- size (Integer): 返回订单数量,用于限制每次查询返回的订单数量。最大值为 100。如果查询结果超过 100 条,需要通过分页查询获取所有数据。此参数为可选。
-
states (String):
订单状态,用于筛选特定状态的订单。只有 GET /order/history 接口需要此参数。可以同时查询多种状态的订单,多个状态之间用逗号分隔。常见的订单状态包括:
-
pre-submitted
: 预提交 -
submitted
: 已提交 -
partial-filled
: 部分成交 -
filled
: 完全成交 -
partial-canceled
: 部分撤销 -
canceled
: 已撤销 -
rejected
: 已拒绝
-
示例:
GET /order/openOrders?symbol=btcusdt&size=10
获取 BTC/USDT 交易对的当前委托订单。此API接口允许用户查询指定交易对(此处为BTC/USDT)尚未完全成交的挂单信息。
symbol
参数指定了要查询的交易对,而
size
参数则限定了返回的订单数量,这里设定为最近10个委托订单。
该请求的响应将包含有关这些未结订单的详细信息,例如订单价格、数量、订单类型(限价单或市价单)以及下单时间。
GET /order/history?symbol=btcusdt&states=filled&size=50
获取 BTC/USDT 交易对的历史成交订单。与查询未结订单不同,此API接口用于检索已经成交的历史订单数据。
symbol
参数同样用于指定交易对(BTC/USDT),
states=filled
参数则筛选出已完全成交的订单。
size
参数控制返回的历史订单数量,此处设置为最近50条已成交记录。
返回的数据将包括成交价格、成交数量、成交时间、交易手续费等信息,帮助用户分析历史交易行为。
7. 获取账户信息 (
GET /account/accounts
)
-
此接口允许用户检索其账户信息。 它不需要任何强制性请求参数,这意味着您可以直接调用此端点来获取您的账户概览。
-
请求方法:
GET
-
端点:
/account/accounts
-
请求参数: 无必选参数,但可能支持可选参数以进行过滤或排序,例如:
-
currency
: 筛选特定币种的账户信息。 -
account_type
: 指定账户类型,如现货账户、合约账户等。 -
limit
: 限制返回的账户数量。
-
-
响应: 成功响应通常包含一个JSON数组,其中每个元素代表一个账户,包含以下信息(示例):
-
account_id
: 账户唯一标识符。 -
currency
: 账户中的币种。 -
balance
: 账户余额。 -
available
: 可用余额(可用于交易)。 -
locked
: 冻结余额(例如,因挂单而冻结)。 -
account_type
: 账户类型。
-
-
错误处理: 如果发生错误,服务器会返回一个包含错误代码和消息的JSON对象。 常见的错误包括:
-
400 Bad Request
: 无效的请求参数。 -
401 Unauthorized
: 未授权访问。 -
500 Internal Server Error
: 服务器内部错误。
-
-
安全性: 强烈建议通过HTTPS安全地发送请求,并使用有效的API密钥进行身份验证,以确保账户信息的安全。
示例: 获取账户信息
GET /account/accounts
接口用于检索用户的全部账户信息。通过调用此端点,应用程序可以获取与用户关联的所有账户的详细数据,包括账户ID、账户类型(例如,现货账户、合约账户)、可用余额、冻结余额以及其他相关的账户属性。 开发者可以利用返回的数据进行用户账户管理、余额查询、资金划转等操作。在使用此接口时,请确保已正确配置身份验证,例如 API 密钥和签名,以保障数据的安全性。响应数据通常以 JSON 格式返回,方便解析和处理。 此接口对于需要全面了解用户账户状态的应用程序至关重要。
8. 获取账户余额 (GET /account/accounts/{account-id}/balance)
此API端点用于检索指定账户的余额信息。它允许用户通过提供账户ID来查询该账户当前可用的资金。
-
account-id (Integer):
账户ID是用于唯一标识特定账户的整数值。
这是必需的参数
,必须包含在请求URL中。 例如:
/account/accounts/12345/balance
, 其中12345
就是账户ID。 确保提供的账户ID存在且属于执行请求的用户,否则可能会返回错误。 请注意,无效或不存在的账户ID将导致API返回错误响应。
请求方法: GET
URL格式:
/account/accounts/{account-id}/balance
示例:
GET /account/accounts/56789/balance
此请求将返回账户ID为56789的账户的余额信息,返回的数据通常包含可用余额、冻结余额等详细信息。 返回结果通常为JSON格式,包含账户余额的详细信息,包括但不限于:
-
availableBalance
: 账户中可用于交易或提现的金额。 -
frozenBalance
: 账户中被冻结的金额,通常由于未完成的交易、抵押或其他限制。 -
currency
: 余额的币种,例如:USD, BTC, ETH。
示例:
GET /account/accounts/1234567/balance
用于查询特定账户的余额信息。该接口通过HTTP GET方法访问,目标资源是账户服务中的账户余额端点。
/account
表示账户服务的根路径,
/accounts/{accountId}
指定了要查询的账户资源,
/balance
则指明了获取的是该账户的余额。在示例中,账户ID为
1234567
。此请求会返回该账户当前的可用余额,响应通常采用JSON格式,包含账户ID、币种、余额等字段,并可能包括交易时间和交易ID等附加信息。客户端需要具备访问账户服务的权限,并且请求头中可能需要包含身份验证信息,例如API密钥或JWT(JSON Web Token)。服务端会对请求进行验证,确保请求的合法性和账户ID的有效性,防止未经授权的访问和数据泄露。
9. WebSocket API 参数
HTX WebSocket API 专门设计用于实时推送高频市场数据和用户账户信息,为交易者提供毫秒级的市场动态。
- sub (String): 订阅的主题,用于订阅特定的数据流。例如,"market.btcusdt.depth.step0" 表示订阅 BTC/USDT 交易对的深度数据,采用 step0 级别精度;"market.btcusdt.kline.1min" 则表示订阅 BTC/USDT 交易对的 1 分钟 K 线数据。详细的主题格式和参数定义请参考 HTX 官方 API 文档,不同币对和周期有不同的主题名称。
- id (String): 客户端自定义的 ID,此 ID 用于区分不同的订阅请求。当服务器返回数据时,会包含此 ID,方便客户端识别对应的数据属于哪个订阅,便于多路复用 WebSocket 连接,提高数据处理效率。强烈建议为每个订阅设置唯一的 ID。
- req (String): 请求的主题,与 'sub' 不同,'req' 用于请求历史数据而非订阅实时数据。例如,可以通过 'req' 请求过去一段时间内的 K 线数据。
- from (Long): 起始时间戳,以 Unix 时间戳表示,精确到秒。用于指定请求历史数据的起始时间点。请注意,时间戳必须是整数。
- to (Long): 结束时间戳,同样以 Unix 时间戳表示,精确到秒。用于指定请求历史数据的结束时间点。'to' 必须大于 'from',否则服务器将返回错误。请务必注意时间戳的有效范围,避免请求过大的数据量。
示例:
{ "sub": "market.btcusdt.depth.step0", "id": "depth_btcusdt" }
上述 JSON 对象用于订阅火币全球站(或其他交易所)中 BTC/USDT 交易对的深度数据。
sub
字段指定了订阅的主题,
market.btcusdt.depth.step0
表示订阅的是 BTC/USDT 交易对的市场深度数据,
step0
通常代表深度数据的聚合级别,数值越小,数据粒度越精细,实时性越高,但数据量也越大。不同的交易所可能使用不同的命名规则,但基本原理相同。
id
字段 "depth_btcusdt" 是客户端自定义的标识符,用于区分不同的订阅请求,方便客户端在接收到数据时进行识别和处理。交易所会原样返回此 ID。
更具体地说,交易所会通过 WebSocket 连接推送 BTC/USDT 交易对的买单和卖单的挂单价格和数量信息。客户端可以通过解析收到的深度数据,构建订单簿,并进行各种交易策略的分析和执行。 深度数据是高频交易和量化交易的重要数据来源,对于捕捉市场微观结构变化至关重要。
注意事项
- 所有时间戳均以毫秒为单位,务必注意时间精度,除非API文档另有明确说明。使用不正确的时间格式可能导致API调用失败。
- 请务必仔细阅读并透彻理解 HTX API 的官方文档,特别是关于请求参数、响应格式、错误代码以及签名机制的详细说明。针对每个 API 端点,了解其 specific 的参数类型、范围、是否必选等信息。
- 在进行 API 开发时,务必进行充分的测试,包括单元测试、集成测试和压力测试,确保程序的正确性、稳定性以及在高并发情况下的性能表现。测试应覆盖各种边界条件和异常情况,例如无效参数、网络错误等。
- 密切注意 API 的频率限制(Rate Limiting),避免因超出限制而被限流。 HTX 通常会对不同的 API 端点设置不同的频率限制策略。建议实施熔断机制和重试机制,并使用指数退避算法来处理被限流的情况。 在设计程序时,应考虑采用异步处理方式,避免阻塞主线程。
- 务必安全地保管您的 API Key 和 Secret Key,切勿将其泄露给任何第三方。API Key 和 Secret Key 是访问 HTX API 的唯一凭证,泄露后可能导致资产损失或安全风险。 建议使用环境变量或专门的密钥管理工具来存储 API Key 和 Secret Key,并定期更换密钥。
- 部分 API 需要进行身份验证,需要在请求头中包含 AccessKeyId、Signature 等信息。Signature 的计算方式需要严格按照 HTX API 文档的说明进行,包括参数排序、字符串拼接、哈希算法等步骤。请务必仔细阅读 HTX API 文档,了解具体的签名规则和加密算法。常用的哈希算法包括 HMAC-SHA256。
- 务必正确处理 API 返回的错误码,并根据错误信息进行相应的处理。不同的错误码代表不同的问题,例如参数错误、权限不足、服务器错误等。您的程序应该能够捕获并解析这些错误码,并采取相应的措施,例如重试、记录日志、通知用户等。 HTX API 文档中通常会详细列出所有可能的错误码及其含义。
通过理解和正确使用 HTX API 参数,特别是针对不同API所要求的特定参数类型和数据格式,开发者可以构建强大的自动化交易程序、量化交易策略和专业的数据分析工具。 这些工具能够帮助用户更有效地进行资产管理、风险控制和市场分析。 希望这份指南能够帮助您更好地利用 HTX API,并从中受益。