usdt-m-futures

HTX USDT-M 合约技能

使用经过身份验证的 API 端点和公开 API 端点在 HTX 上交易 USDT-M 合约。以 JSON 格式返回结果。

基础 URL

• 主网：https://api.hbdm.com
• 主网（AWS）：https://api.hbdm.vn

快速参考

HTX USDT-M 合约的完整 API 端点。所有端点均使用基础 URL https://api.hbdm.com（AWS 环境使用 https://api.hbdm.vn）。

参考数据

端点	描述	必填	可选	身份验证
GET /linear-swap-api/v3/swap_unified_account_type	查询账户类型	无	无	是
POST /linear-swap-api/v3/swap_switch_account_type	更改账户类型	account_type	无	是
GET /linear-swap-api/v1/swap_funding_rate	查询资金费率	contract_code	无	否
GET /linear-swap-api/v1/swap_batch_funding_rate	批量查询资金费率	contract_code	无	否
GET /linear-swap-api/v1/swap_historical_funding_rate	查询历史资金费率	contract_code	page_index, page_size	否
GET /linear-swap-api/v1/swap_liquidation_orders	查询强平订单	contract_code	trade_type, create_date, page_index, page_size	否
GET /linear-swap-api/v1/swap_settlement_records	查询历史结算记录	contract_code	page_index, page_size	否
GET /linear-swap-api/v1/swap_elite_account_ratio	查询顶级交易员情绪指数（账户）	contract_code	period	否
GET /linear-swap-api/v1/swap_elite_position_ratio	查询顶级交易员情绪指数（持仓）	contract_code	period	否
GET /linear-swap-api/v1/swap_system_status	查询系统状态信息（逐仓）	contract_code	无	否
POST /linear-swap-api/v1/swap_cross_tiered_margin_info	查询阶梯保证金信息（全仓）	无	无	是
POST /linear-swap-api/v1/swap_tiered_margin_info	查询阶梯保证金信息（逐仓）	contract_code	无	是
GET /linear-swap-api/v1/swap_estimated_settlement_price	获取预估结算价格	contract_code	无	否
POST /linear-swap-api/v1/swap_adjustment_factor	查询阶梯调整系数（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_adjustment_factor	查询阶梯调整系数（全仓）	无	无	是
GET /v1/insurance_fund_info	查询风险准备金余额信息	contract_code	无	否
GET /v1/insurance_fund_history	查询历史风险准备金	contract_code	page_index, page_size	否
GET /linear-swap-api/v1/swap_price_limit	查询合约价格限制	contract_code	无	否
GET /linear-swap-api/v1/swap_open_interest	获取合约未平仓量信息	contract_code	无	否
GET /linear-swap-api/v1/swap_contract_info	查询合约信息	contract_code	无	否
GET /linear-swap-api/v1/swap_index	查询合约指数价格信息	contract_code	无	否
GET /linear-swap-api/market/swap_contract_constituents	获取指数成分	index_code	无	否
GET /linear-swap-api/v1/swap_query_elements	合约要素	contract_code	无	否
GET /linear-swap-api/v1/swap_timestamp	获取当前系统时间戳	无	无	否
GET https://api.hbdm.com/heartbeat/	查询系统是否可用	无	无	否

市场数据

端点	描述	必填	可选	身份验证
GET /linear-swap-ex/market/depth	获取市场深度	contract_code	type	否
GET /linear-swap-ex/market/bbo	获取市场 BBO 数据	contract_code	无	否
GET /linear-swap-ex/market/kline	获取 K 线数据	contract_code, period	size, from, to	否
GET /linear-swap-ex/market/mark_price_kline	获取标记价格 K 线数据	contract_code, period	size, from, to	否
GET /linear-swap-ex/market/overview	获取市场数据概览	contract_code	无	否
GET /linear-swap-ex/market/batch_overview	批量获取市场数据概览	contract_code	无	否
GET /linear-swap-ex/market/trade	查询合约的最新交易	contract_code	无	否
GET /linear-swap-ex/market/trades	查询一批交易记录	contract_code	size	否
GET /linear-swap-ex/market/open_interest	查询未平仓量信息	contract_code	无	否
GET /linear-swap-ex/market/premium_index_kline	查询溢价指数 K 线数据	contract_code, period	size, from, to	否
GET /linear-swap-ex/market/estimated_funding_rate_kline	查询预估资金费率 K 线	contract_code, period	size, from, to	否

账户接口

Endpoint	描述	必填	可选	身份验证
POST /linear-swap-api/v1/swap_account_info	查询资产估值	无	valuation_asset	是
POST /linear-swap-api/v1/swap_account_info	查询账户信息（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_account_info	查询账户信息（全仓）	无	valuation_asset	是
POST /linear-swap-api/v1/swap_position_info	查询持仓信息（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_position_info	查询持仓信息（全仓）	无	contract_code	是
POST /linear-swap-api/v1/swap_account_position_info	查询资产和持仓（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_account_position_info	查询资产和持仓（全仓）	无	valuation_asset	是
POST /linear-swap-api/v1/swap_sub_account_list	设置子账户交易权限	sub_uid	trades	是
POST /linear-swap-api/v1/swap_account_info_list	查询所有子账户（逐仓）	无	无	是
POST /linear-swap-api/v1/swap_cross_account_info_list	查询所有子账户（全仓）	无	valuation_asset	是
POST /linear-swap-api/v1/swap_account_info_sub	查询单个子账户（逐仓）	contract_code, sub_uid	无	是
POST /linear-swap-api/v1/swap_cross_account_info_sub	查询子账户（全仓）	sub_uid	valuation_asset	是
POST /linear-swap-api/v1/swap_position_info_sub	查询子账户持仓（逐仓）	contract_code, sub_uid	无	是
POST /linear-swap-api/v1/swap_cross_position_info_sub	查询子账户持仓（全仓）	sub_uid	contract_code	是
POST /linear-swap-api/v3/swap_financial_record	查询账户财务记录	无	contract_code, type, start_time, end_time, page_index, page_size, direct	是
POST /linear-swap-api/v3/swap_financial_record_exact	按字段查询财务记录	无	contract_code, type, start_time, end_time, page_index, page_size, direct	是
POST /linear-swap-api/v1/swap_available_level_rate	查询可用杠杆（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_available_level_rate	查询可用杠杆（全仓）	无	无	是
POST /linear-swap-api/v1/swap_order_limit	查询下单限制	无	contract_code, order_price_type	是
POST /linear-swap-api/v1/swap_fee	查询合约交易手续费	无	contract_code	是
POST /linear-swap-api/v1/swap_transfer_limit	查询划转限制（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_transfer_limit	查询划转限制（全仓）	无	无	是
POST /linear-swap-api/v1/swap_position_limit	查询持仓限制（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_position_limit	查询持仓限制（全仓）	无	无	是
POST /linear-swap-api/v1/swap_lever_position_limit	查询所有杠杆档位的持仓限制（逐仓）	contract_code	无	是
POST /linear-swap-api/v1/swap_cross_lever_position_limit	查询所有杠杆档位的持仓限制（全仓）	无	无	是
POST /linear-swap-api/v1/swap_master_sub_transfer	主账户与子账户之间划转	sub_uid, asset, amount, type	client_order_id	是
POST /linear-swap-api/v1/swap_master_sub_transfer_record	查询划转记录	无	sub_uid, transfer_type, page_index, page_size, direct, sort_by	是
POST /linear-swap-api/v1/swap_transfer_inner	保证金账户之间划转	asset, amount, from_margin_account, to_margin_account	client_order_id	是
GET /linear-swap-api/v1/swap_api_trading_status	查询 API 指标禁用信息	无	无	是
POST /linear-swap-api/v1/linear-cancel-after	自动撤销订单	timeout	contract_code	是

交易接口

端点	描述	必填	可选	身份验证
POST /linear-swap-api/v1/swap_cross_query_trade_state	查询交易状态（全仓）	无	无	是
POST /linear-swap-api/v1/swap_switch_position_mode	切换持仓模式（逐仓）	contract_code, mode	无	是
POST /linear-swap-api/v1/swap_cross_switch_position_mode	切换持仓模式（全仓）	mode	contract_code	是
POST /linear-swap-api/v1/swap_order	下单（逐仓）	contract_code, client_order_id, price, volume, direction, offset, lever_rate, order_price_type	tp_trigger_price, tp_order_price, tp_order_price_type, sl_trigger_price, sl_order_price, sl_order_price_type, reduce_only, hf_order_type	是
POST /linear-swap-api/v1/swap_cross_order	下单（全仓）	contract_code, client_order_id, price, volume, direction, offset, lever_rate, order_price_type	tp_trigger_price, tp_order_price, tp_order_price_type, sl_trigger_price, sl_order_price, sl_order_price_type, reduce_only, hf_order_type	是
POST /linear-swap-api/v1/swap_cross_batch_orders	批量下单（全仓）	orders_data	无	是
POST /linear-swap-api/v1/swap_cancel	撤销订单（逐仓）	contract_code, order_id	client_order_id	是
POST /linear-swap-api/v1/swap_cross_cancel	撤销订单（全仓）	order_id	contract_code, client_order_id	是
POST /linear-swap-api/v1/swap_cancelall	撤销所有订单（逐仓）	contract_code	direction, offset	是
POST /linear-swap-api/v1/swap_cross_cancelall	撤销所有订单（全仓）	无	contract_code, direction, offset	是
POST /linear-swap-api/v1/swap_switch_lever_rate	切换杠杆（逐仓）	contract_code, lever_rate	无	是
POST /linear-swap-api/v1/swap_cross_switch_lever_rate	切换杠杆（全仓）	lever_rate	contract_code	是
POST /linear-swap-api/v1/swap_order_info	获取订单信息（逐仓）	contract_code, order_id	client_order_id	是
POST /linear-swap-api/v1/swap_cross_order_info	获取订单信息（全仓）	order_id	contract_code, client_order_id	是
POST /linear-swap-api/v1/swap_order_detail	获取订单详情（逐仓）	contract_code, order_id	created_at, page_index, page_size, client_order_id	是
POST /linear-swap-api/v1/swap_cross_order_detail	获取详细信息（全仓）	order_id	contract_code, created_at, page_index, page_size, client_order_id	是
POST /linear-swap-api/v1/swap_openorders	当前未成交订单（逐仓）	contract_code	page_index, page_size	是
POST /linear-swap-api/v1/swap_cross_openorders	当前未成交订单（全仓）	无	contract_code, page_index, page_size	是
POST /linear-swap-api/v3/swap_hisorders	获取历史订单（逐仓）	contract_code, trade_type	type, start_time, end_time, direct, page_index, page_size, sort_by	是
POST /linear-swap-api/v3/swap_cross_hisorders	获取历史订单（全仓）	trade_type	contract_code, type, start_time, end_time, direct, page_index, page_size, sort_by	是
POST /linear-swap-api/v3/swap_hisorders_exact	按字段获取历史订单（逐仓）	contract_code, trade_type	type, start_time, end_time, direct, page_index, page_size, sort_by	是
POST /linear-swap-api/v3/swap_cross_hisorders_exact	按字段获取历史订单（全仓）	trade_type	contract_code, type, start_time, end_time, direct, page_index, page_size, sort_by	是
POST /linear-swap-api/v3/swap_matchresults	历史成交结果（逐仓）	contract_code, trade_type	start_time, end_time, page_index, page_size, direct	是
POST /linear-swap-api/v3/swap_cross_matchresults	历史成交结果（全仓）	trade_type	contract_code, start_time, end_time, page_index, page_size, direct	是
POST /linear-swap-api/v3/swap_matchresults_exact	按字段获取成交结果（逐仓）	contract_code, trade_type	start_time, end_time, page_index, page_size, direct	是
POST /linear-swap-api/v3/swap_cross_matchresults_exact	按字段获取成交结果（全仓）	trade_type	contract_code, start_time, end_time, page_index, page_size, direct	是
POST /linear-swap-api/v1/swap_lightning_close_position	闪电平仓订单（逐仓）	contract_code, volume, direction	client_order_id, order_price_type	是
POST /linear-swap-api/v1/swap_cross_lightning_close_position	闪电平仓（全仓）	contract_code, volume, direction	client_order_id, order_price_type	是
GET /linear-swap-api/v1/swap_position_side	查询持仓模式（逐仓）	contract_code	无	是
GET /linear-swap-api/v1/swap_cross_position_side	查询持仓模式（全仓）	无	contract_code	是

策略订单接口

端点	描述	必填	可选	身份验证
POST /linear-swap-api/v1/swap_trigger_order	下达触发订单（逐仓）	contract_code, trigger_type, trigger_price, order_price, volume, direction, offset, lever_rate, order_price_type	client_order_id	是
POST /linear-swap-api/v1/swap_cross_trigger_order	下达触发订单（全仓）	contract_code, trigger_type, trigger_price, order_price, volume, direction, offset, lever_rate, order_price_type	client_order_id	是
POST /linear-swap-api/v1/swap_trigger_cancel	取消触发订单（逐仓）	contract_code, order_id	client_order_id	是
POST /linear-swap-api/v1/swap_cross_trigger_cancel	取消触发订单（全仓）	order_id	contract_code, client_order_id	是
POST /linear-swap-api/v1/swap_trigger_cancelall	取消所有触发订单（逐仓）	contract_code	direction, offset	是
POST /linear-swap-api/v1/swap_cross_trigger_cancelall	取消所有触发订单（全仓）	None	contract_code, direction, offset	是
POST /linear-swap-api/v1/swap_trigger_openorders	查询未成交触发订单（逐仓）	contract_code	page_index, page_size	是
POST /linear-swap-api/v1/swap_cross_trigger_openorders	查询未成交触发订单（全仓）	None	contract_code, page_index, page_size	是
POST /linear-swap-api/v1/swap_trigger_hisorders	查询触发订单历史记录（逐仓）	contract_code	trigger_type, status, page_index, page_size, sort_by, direct	是
POST /linear-swap-api/v1/swap_cross_trigger_hisorders	查询触发订单历史记录（全仓）	None	contract_code, trigger_type, status, page_index, page_size, sort_by, direct	是
POST /linear-swap-api/v1/swap_tpsl_order	设置止盈/止损订单（逐仓）	contract_code, volume, tp_trigger_price, tp_order_price, sl_trigger_price, sl_order_price, direction	tp_order_price_type, sl_order_price_type, client_order_id	是
POST /linear-swap-api/v1/swap_cross_tpsl_order	设置止盈/止损订单（全仓）	contract_code, volume, tp_trigger_price, tp_order_price, sl_trigger_price, sl_order_price, direction	tp_order_price_type, sl_order_price_type, client_order_id	是
POST /linear-swap-api/v1/swap_tpsl_cancel	取消止盈/止损订单（逐仓）	contract_code, order_id	client_order_id	是
POST /linear-swap-api/v1/swap_cross_tpsl_cancel	取消止盈/止损订单（全仓）	order_id	contract_code, client_order_id	是
POST /linear-swap-api/v1/swap_tpsl_cancelall	取消所有止盈/止损订单（逐仓）	contract_code	None	是
POST /linear-swap-api/v1/swap_cross_tpsl_cancelall	取消所有止盈/止损订单（全仓）	None	contract_code	是
POST /linear-swap-api/v1/swap_tpsl_openorders	查询未成交止盈/止损订单（逐仓）	contract_code	page_index, page_size	是
POST /linear-swap-api/v1/swap_cross_tpsl_openorders	查询未成交止盈/止损订单（全仓）	None	contract_code, page_index, page_size	是
POST /linear-swap-api/v1/swap_tpsl_hisorders	查询止盈/止损订单历史记录（逐仓）	contract_code	status, page_index, page_size, sort_by, direct	是
POST /linear-swap-api/v1/swap_cross_tpsl_hisorders	查询止盈/止损订单历史记录（全仓）	None	contract_code, status, page_index, page_size, sort_by, direct	是

划转接口

端点	描述	必填	可选	身份验证
POST /linear-swap-api/v1/swap_cross_transfer_state	查询划转状态（全仓）	None	None	是

---

参数

通用参数

合约与交易标的

• contract_code：合约代码（例如，BTC-USDT、ETH-USDT）
• symbol：交易标的名称
• pair：交易对（例如，BTC-USDT）
• contract_type：合约类型（swap、this_week、next_week、quarter、next_quarter）
• business_type：业务类型（futures、swap、all）

账户与保证金

• margin_account：保证金账户标识符
• margin_mode：保证金模式（cross、isolated）
• margin_asset：保证金资产（例如，USDT）
• account_type：账户类型

订单参数

• order_id：订单 ID（多个订单时可用逗号分隔）
• client_order_id：由客户端定义的订单 ID
• order_source：订单来源
• order_type：订单类型
• order_price_type：订单价格类型（limit、optimal_5、optimal_10、optimal_20、post_only、fok、ioc 等）
• direction：交易方向（buy、sell）
• offset：开平方向（open、close、both）
• volume：订单数量（以合约为单位）
• price：订单价格
• lever_rate：杠杆倍数
• reduce_only：仅减仓标志（0：否，1：是）

触发订单参数

• trigger_type：触发类型（ge：大于或等于，le：小于或等于）
• trigger_price：触发价格
• triggered_price：触发订单执行时的价格

止盈与止损参数

• tp_trigger_price：止盈订单的触发价格
• tp_order_price：止盈订单的订单价格
• tp_order_price_type：止盈订单的订单类型
• sl_trigger_price：止损订单的触发价格
• sl_order_price：止损订单的订单价格
• sl_order_price_type：止损订单的订单价格类型
• price_protect：价格保护（布尔值）

跟踪订单参数

• callback_rate：跟踪订单的回调率
• active_price：跟踪订单的激活价格
• is_active：是否已激活该激活价格

查询参数

• page_index：页码（默认值：1）
• page_size：每页大小（默认值：20，最大值：50）
• start_time：开始时间（Unix 时间戳，单位为毫秒）
• end_time：结束时间（Unix 时间戳，单位为毫秒）
• create_date：天数
• direct：搜索方向（NEXT：升序，PREV：降序）
• from_id：分页起始 ID
• sort_by：排序字段（降序）

子账户参数

• sub_uid：子账户 UID
• sub_auth：子账户授权（0：禁用，1：启用）

划转参数

• from：来源账户（例如，spot、linear-swap）
• to：目标账户（例如，spot、linear-swap）
• currency：划转币种
• amount：划转金额
• from_margin_account：来源保证金账户
• to_margin_account：目标保证金账户

行情数据参数

• period：K 线周期（1min、5min、15min、30min、60min、4hour、1day、1mon、1week、1year）
• type：深度类型（step0-step19）
• size：返回的记录数

其他参数

• trade_type：交易类型（0：全部，1：开多，2：开空，3：平空，4：平多）
• status：订单状态（多个状态可用逗号分隔）
• self_match_prevent：防止自成交标志
• self_match_prevent_new：防止自我交易

枚举值

订单类型

• order_price_type：limit、optimal_5、optimal_10、optimal_20、post_only、fok、ioc、opponent、lightning、optimal_5_fok、optimal_5_ioc、optimal_10_fok、optimal_10_ioc、optimal_20_fok、optimal_20_ioc、opponent_ioc、opponent_fok

订单状态

• status：已提交（3）、部分成交（4）、部分撤销（5）、已成交（6）、已撤销（7）、待提交（1）、已受理（2）

方向与开平方向

• direction：buy、sell
• offset：open、close、both

保证金模式

• margin_mode：isolated、cross

合约类型

• contract_type：swap（永续）、this_week、next_week、quarter（当季）、next_quarter

持仓模式

• position_mode：dual_side（双向持仓模式），single_side（单向持仓模式）

---

身份验证

对于需要身份验证的端点，你需要提供 HTX API 凭据。

所需凭据：

• apiKey：你的 HTX API 密钥
• secretKey：你的 HTX API 密钥密文（用于签名）

所有需要身份验证的端点都要求使用 HMAC SHA256 签名：

1. 按以下顺序创建预签名字符串：

   • HTTP 方法（GET/POST）+ "\n"
   • API 主机（例如 api.hbdm.com）+ "\n"
   • API 路径（例如 /linear-swap-api/v1/swap_order）+ "\n"
   • 排序后的查询字符串参数

2. 在所有需要身份验证的请求中添加必需参数：

   • AccessKeyId：你的 API 密钥
   • SignatureMethod：HmacSHA256
   • SignatureVersion：2
   • Timestamp：格式为 yyyy-MM-ddTHH:mm:ss 的 UTC 时间戳

3. 使用 secretKey 通过 HMAC SHA256 对预签名字符串进行签名

4. 将签名作为 Signature 参数附加到查询字符串

5. 对于 POST 请求，还要将签名包含在 URL 查询字符串中

预签名字符串示例：

POST\\n
api.hbdm.com\\n
/linear-swap-api/v1/swap_order\\n
AccessKeyId=xxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15:19:30

安全

分享凭据

用户可以通过发送文件来提供 HTX API 凭据，文件内容格式如下：

fe45419a...xyz
secretabc...key

绝不显示完整密钥

向用户显示凭据时：

• API 密钥： 显示前 5 位和后 4 位字符：fe45419a...xyz
• 密钥密文： 始终隐藏，仅显示最后 5 位：***...key1

用户询问凭据时的回复示例：

Account: main
API Key: fe45419a...xyz
Secret: ***...key1
Environment: Mainnet

列出账户

列出账户时，仅显示名称和环境，绝不显示密钥：

HTX Accounts:
* main (Mainnet)
* trading (Mainnet - AWS)

在主网上进行交易

在主网上进行交易时，继续操作前始终先要求用户输入“CONFIRM”进行确认。

---

HTX 账户

main

• API 密钥：your_mainnet_api_key
• 密钥密文：your_mainnet_secret
• 环境：https://api.hbdm.com
• 描述：主要的 USDT-M 期货交易账户

trading

• API 密钥：your_aws_api_key
• 密钥密文：your_aws_secret
• 环境：https://api.hbdm.vn
• 描述：针对 AWS 优化的 USDT-M 期货交易

TOOLS.md 结构

## HTX Accounts

### main
- API Key: fe45419a...xyz
- Secret: secretabc...key
- Environment: https://api.hbdm.com
- Description: Primary USDT-M Futures trading account

### trading
- API Key: test456...abc
- Secret: testsecret...xyz
- Environment: https://api.hbdm.vn
- Description: AWS optimized USDT-M Futures trading

Agent 行为

1. 请求凭据时：隐藏密钥（仅显示最后 5 个字符）
2. 列出账户时：显示名称和环境，绝不显示密钥
3. 选择账户时：如有歧义则询问，默认选择 main
4. 在主网上进行交易时，继续操作前先要求用户输入“CONFIRM”进行确认
5. 添加新凭据时：提示输入名称和环境

添加新账户

用户提供新凭据时：

• 询问账户名称
• 询问：使用哪个环境（Mainnet 或 Mainnet-AWS）
• 将信息保存到 TOOLS.md，并确认时隐藏密钥

User Agent 请求头

将 User-Agent 请求头设为以下字符串：htx-usdt-m-futures/1.0.0 (Skill)

重要说明

• 除非另有说明，所有时间戳均以 Unix 毫秒为单位
• 合约代码应使用大写（例如 BTC-USDT，而非 btc-usdt）
• 对于市价买单，volume 参数表示合约数量
• 交易前必须通过相应端点获取账户 ID
• 存在速率限制，详情请参阅 HTX API 文档
• 每个需要身份验证的请求都必须计算签名
• 签名中的时间戳必须与服务器时间相差不超过 1 分钟
• 支持逐仓和全仓模式
• 持仓模式：single_side（单向持仓）和 dual_side（双向持仓）
• 操作时始终使用正确的保证金模式和保证金账户
• 全仓操作使用路径中包含 "cross" 的端点
• 逐仓操作使用路径中不包含 "cross" 的端点
• 所有请求端点必须与文档中指定的端点一致。