usdt-m-futures

HTX USDT-M Futures Skill

USDT-M Futures trading on HTX using authenticated and public API endpoints. Return the result in JSON format.

Base URLs

• Mainnet: https://api.hbdm.com
• Mainnet (AWS): https://api.hbdm.vn

Quick Reference

Complete API endpoints for HTX USDT-M Futures. All endpoints use base URL https://api.hbdm.com (or https://api.hbdm.vn for AWS).

Reference Data

Endpoint	Description	Required	Optional	Authentication
GET /linear-swap-api/v3/swap_unified_account_type	Account type query	None	None	Yes
POST /linear-swap-api/v3/swap_switch_account_type	Account Type Change	account_type	None	Yes
GET /linear-swap-api/v1/swap_funding_rate	Query funding rate	contract_code	None	No
GET /linear-swap-api/v1/swap_batch_funding_rate	Query a Batch of Funding Rate	contract_code	None	No
GET /linear-swap-api/v1/swap_historical_funding_rate	Query historical funding rate	contract_code	page_index, page_size	No
GET /linear-swap-api/v1/swap_liquidation_orders	Query Liquidation Orders	contract_code	trade_type, create_date, page_index, page_size	No
GET /linear-swap-api/v1/swap_settlement_records	Query historical settlement records	contract_code	page_index, page_size	No
GET /linear-swap-api/v1/swap_elite_account_ratio	Query Top Trader Sentiment Index (Account)	contract_code	period	No
GET /linear-swap-api/v1/swap_elite_position_ratio	Query Top Trader Sentiment Index (Position)	contract_code	period	No
GET /linear-swap-api/v1/swap_system_status	Query information on system status (Isolated)	contract_code	None	No
POST /linear-swap-api/v1/swap_cross_tiered_margin_info	Query information on Tiered Margin (Cross)	None	None	Yes
POST /linear-swap-api/v1/swap_tiered_margin_info	Query information on Tiered Margin (Isolated)	contract_code	None	Yes
GET /linear-swap-api/v1/swap_estimated_settlement_price	Get the estimated settlement price	contract_code	None	No
POST /linear-swap-api/v1/swap_adjustment_factor	Query Tiered Adjustment Factor (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_adjustment_factor	Query Tiered Adjustment Factor (Cross)	None	None	Yes
GET /v1/insurance_fund_info	Query risk reserve balance information	contract_code	None	No
GET /v1/insurance_fund_history	Query historical risk reserves	contract_code	page_index, page_size	No
GET /linear-swap-api/v1/swap_price_limit	Query Swap Price Limitation	contract_code	None	No
GET /linear-swap-api/v1/swap_open_interest	Get Swap Open Interest Information	contract_code	None	No
GET /linear-swap-api/v1/swap_contract_info	Query Contract Info	contract_code	None	No
GET /linear-swap-api/v1/swap_index	Query Swap Index Price Information	contract_code	None	No
GET /linear-swap-api/market/swap_contract_constituents	Get index components	index_code	None	No
GET /linear-swap-api/v1/swap_query_elements	Contract Elements	contract_code	None	No
GET /linear-swap-api/v1/swap_timestamp	Get current system timestamp	None	None	No
GET https://api.hbdm.com/heartbeat/	Query whether the system is available	None	None	No

Market Data

Endpoint	Description	Required	Optional	Authentication
GET /linear-swap-ex/market/depth	Get Market Depth	contract_code	type	No
GET /linear-swap-ex/market/bbo	Get Market BBO Data	contract_code	None	No
GET /linear-swap-ex/market/kline	Get KLine Data	contract_code, period	size, from, to	No
GET /linear-swap-ex/market/mark_price_kline	Get Kline Data of Mark Price	contract_code, period	size, from, to	No
GET /linear-swap-ex/market/overview	Get Market Data Overview	contract_code	None	No
GET /linear-swap-ex/market/batch_overview	Get a Batch of Market Data Overview	contract_code	None	No
GET /linear-swap-ex/market/trade	Query The Last Trade of a Contract	contract_code	None	No
GET /linear-swap-ex/market/trades	Query a Batch of Trade Records	contract_code	size	No
GET /linear-swap-ex/market/open_interest	Query information on open interest	contract_code	None	No
GET /linear-swap-ex/market/premium_index_kline	Query Premium Index Kline Data	contract_code, period	size, from, to	No
GET /linear-swap-ex/market/estimated_funding_rate_kline	Query Estimated Funding Rate Kline	contract_code, period	size, from, to	No

Account Interface

Endpoint	Description	Required	Optional	Authentication
POST /linear-swap-api/v1/swap_account_info	Query Asset Valuation	None	valuation_asset	Yes
POST /linear-swap-api/v1/swap_account_info	Query Account Information (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_account_info	Query Account Information (Cross)	None	valuation_asset	Yes
POST /linear-swap-api/v1/swap_position_info	Query Position Information (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_position_info	Query Position Information (Cross)	None	contract_code	Yes
POST /linear-swap-api/v1/swap_account_position_info	Query Assets And Positions (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_account_position_info	Query Assets And Positions (Cross)	None	valuation_asset	Yes
POST /linear-swap-api/v1/swap_sub_account_list	Set Sub-Account Trading Permissions	sub_uid	trades	Yes
POST /linear-swap-api/v1/swap_account_info_list	Query all sub-accounts (Isolated)	None	None	Yes
POST /linear-swap-api/v1/swap_cross_account_info_list	Query all sub-accounts (Cross)	None	valuation_asset	Yes
POST /linear-swap-api/v1/swap_account_info_sub	Query single sub-account (Isolated)	contract_code, sub_uid	None	Yes
POST /linear-swap-api/v1/swap_cross_account_info_sub	Query sub-account (Cross)	sub_uid	valuation_asset	Yes
POST /linear-swap-api/v1/swap_position_info_sub	Query sub-account position (Isolated)	contract_code, sub_uid	None	Yes
POST /linear-swap-api/v1/swap_cross_position_info_sub	Query sub-account position (Cross)	sub_uid	contract_code	Yes
POST /linear-swap-api/v3/swap_financial_record	Query account financial records	None	contract_code, type, start_time, end_time, page_index, page_size, direct	Yes
POST /linear-swap-api/v3/swap_financial_record_exact	Query financial records via fields	None	contract_code, type, start_time, end_time, page_index, page_size, direct	Yes
POST /linear-swap-api/v1/swap_available_level_rate	Query available leverage (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_available_level_rate	Query available leverage (Cross)	None	None	Yes
POST /linear-swap-api/v1/swap_order_limit	Query order limit	None	contract_code, order_price_type	Yes
POST /linear-swap-api/v1/swap_fee	Query swap trading fee	None	contract_code	Yes
POST /linear-swap-api/v1/swap_transfer_limit	Query transfer limit (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_transfer_limit	Query transfer limit (Cross)	None	None	Yes
POST /linear-swap-api/v1/swap_position_limit	Query position limit (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_position_limit	Query position limit (Cross)	None	None	Yes
POST /linear-swap-api/v1/swap_lever_position_limit	Query position limit all leverages (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_lever_position_limit	Query position limit all leverages (Cross)	None	None	Yes
POST /linear-swap-api/v1/swap_master_sub_transfer	Transfer between master and sub	sub_uid, asset, amount, type	client_order_id	Yes
POST /linear-swap-api/v1/swap_master_sub_transfer_record	Query transfer records	None	sub_uid, transfer_type, page_index, page_size, direct, sort_by	Yes
POST /linear-swap-api/v1/swap_transfer_inner	Transfer between margin accounts	asset, amount, from_margin_account, to_margin_account	client_order_id	Yes
GET /linear-swap-api/v1/swap_api_trading_status	Query API indicator disable info	None	None	Yes
POST /linear-swap-api/v1/linear-cancel-after	Automatic Order Cancellation	timeout	contract_code	Yes

Trade Interface

Endpoint	Description	Required	Optional	Authentication
POST /linear-swap-api/v1/swap_cross_query_trade_state	Query Trade State (Cross)	None	None	Yes
POST /linear-swap-api/v1/swap_switch_position_mode	Switch Position Mode (Isolated)	contract_code, mode	None	Yes
POST /linear-swap-api/v1/swap_cross_switch_position_mode	Switch Position Mode (Cross)	mode	contract_code	Yes
POST /linear-swap-api/v1/swap_order	Place an Order (Isolated)	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	Yes
POST /linear-swap-api/v1/swap_cross_order	Place An Order (Cross)	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	Yes
POST /linear-swap-api/v1/swap_cross_batch_orders	Place A Batch Of Orders (Cross)	orders_data	None	Yes
POST /linear-swap-api/v1/swap_cancel	Cancel an Order (Isolated)	contract_code, order_id	client_order_id	Yes
POST /linear-swap-api/v1/swap_cross_cancel	Cancel An Order (Cross)	order_id	contract_code, client_order_id	Yes
POST /linear-swap-api/v1/swap_cancelall	Cancel All Orders (Isolated)	contract_code	direction, offset	Yes
POST /linear-swap-api/v1/swap_cross_cancelall	Cancel All Orders (Cross)	None	contract_code, direction, offset	Yes
POST /linear-swap-api/v1/swap_switch_lever_rate	Switch Leverage (Isolated)	contract_code, lever_rate	None	Yes
POST /linear-swap-api/v1/swap_cross_switch_lever_rate	Switch Leverage (Cross)	lever_rate	contract_code	Yes
POST /linear-swap-api/v1/swap_order_info	Get Information of an Order (Isolated)	contract_code, order_id	client_order_id	Yes
POST /linear-swap-api/v1/swap_cross_order_info	Get Information of order (Cross)	order_id	contract_code, client_order_id	Yes
POST /linear-swap-api/v1/swap_order_detail	Order details acquisition (Isolated)	contract_code, order_id	created_at, page_index, page_size, client_order_id	Yes
POST /linear-swap-api/v1/swap_cross_order_detail	Get Detail Information (Cross)	order_id	contract_code, created_at, page_index, page_size, client_order_id	Yes
POST /linear-swap-api/v1/swap_openorders	Current unfilled orders (Isolated)	contract_code	page_index, page_size	Yes
POST /linear-swap-api/v1/swap_cross_openorders	Current unfilled orders (Cross)	None	contract_code, page_index, page_size	Yes
POST /linear-swap-api/v3/swap_hisorders	Get History Orders (Isolated)	contract_code, trade_type	type, start_time, end_time, direct, page_index, page_size, sort_by	Yes
POST /linear-swap-api/v3/swap_cross_hisorders	Get History Orders (Cross)	trade_type	contract_code, type, start_time, end_time, direct, page_index, page_size, sort_by	Yes
POST /linear-swap-api/v3/swap_hisorders_exact	History Orders via Fields (Isolated)	contract_code, trade_type	type, start_time, end_time, direct, page_index, page_size, sort_by	Yes
POST /linear-swap-api/v3/swap_cross_hisorders_exact	History Orders via Fields (Cross)	trade_type	contract_code, type, start_time, end_time, direct, page_index, page_size, sort_by	Yes
POST /linear-swap-api/v3/swap_matchresults	History Match Results (Isolated)	contract_code, trade_type	start_time, end_time, page_index, page_size, direct	Yes
POST /linear-swap-api/v3/swap_cross_matchresults	History Match Results (Cross)	trade_type	contract_code, start_time, end_time, page_index, page_size, direct	Yes
POST /linear-swap-api/v3/swap_matchresults_exact	Match Results via Fields (Isolated)	contract_code, trade_type	start_time, end_time, page_index, page_size, direct	Yes
POST /linear-swap-api/v3/swap_cross_matchresults_exact	Match Results via Fields (Cross)	trade_type	contract_code, start_time, end_time, page_index, page_size, direct	Yes
POST /linear-swap-api/v1/swap_lightning_close_position	Lightning Close Order (Isolated)	contract_code, volume, direction	client_order_id, order_price_type	Yes
POST /linear-swap-api/v1/swap_cross_lightning_close_position	Lightning Close Position (Cross)	contract_code, volume, direction	client_order_id, order_price_type	Yes
GET /linear-swap-api/v1/swap_position_side	Query position mode (Isolated)	contract_code	None	Yes
GET /linear-swap-api/v1/swap_cross_position_side	Query position mode (Cross)	None	contract_code	Yes

Strategy Order Interface

Endpoint	Description	Required	Optional	Authentication
POST /linear-swap-api/v1/swap_trigger_order	Place Trigger Order (Isolated)	contract_code, trigger_type, trigger_price, order_price, volume, direction, offset, lever_rate, order_price_type	client_order_id	Yes
POST /linear-swap-api/v1/swap_cross_trigger_order	Place Trigger Order (Cross)	contract_code, trigger_type, trigger_price, order_price, volume, direction, offset, lever_rate, order_price_type	client_order_id	Yes
POST /linear-swap-api/v1/swap_trigger_cancel	Cancel Trigger Order (Isolated)	contract_code, order_id	client_order_id	Yes
POST /linear-swap-api/v1/swap_cross_trigger_cancel	Cancel Trigger Order (Cross)	order_id	contract_code, client_order_id	Yes
POST /linear-swap-api/v1/swap_trigger_cancelall	Cancel All Trigger Orders (Isolated)	contract_code	direction, offset	Yes
POST /linear-swap-api/v1/swap_cross_trigger_cancelall	Cancel All Trigger Orders (Cross)	None	contract_code, direction, offset	Yes
POST /linear-swap-api/v1/swap_trigger_openorders	Query Trigger Order Open Orders (Isolated)	contract_code	page_index, page_size	Yes
POST /linear-swap-api/v1/swap_cross_trigger_openorders	Query Trigger Order Open Orders (Cross)	None	contract_code, page_index, page_size	Yes
POST /linear-swap-api/v1/swap_trigger_hisorders	Query Trigger Order History (Isolated)	contract_code	trigger_type, status, page_index, page_size, sort_by, direct	Yes
POST /linear-swap-api/v1/swap_cross_trigger_hisorders	Query Trigger Order History (Cross)	None	contract_code, trigger_type, status, page_index, page_size, sort_by, direct	Yes
POST /linear-swap-api/v1/swap_tpsl_order	Set TP/SL Order (Isolated)	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	Yes
POST /linear-swap-api/v1/swap_cross_tpsl_order	Set TP/SL Order (Cross)	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	Yes
POST /linear-swap-api/v1/swap_tpsl_cancel	Cancel TP/SL Order (Isolated)	contract_code, order_id	client_order_id	Yes
POST /linear-swap-api/v1/swap_cross_tpsl_cancel	Cancel TP/SL Order (Cross)	order_id	contract_code, client_order_id	Yes
POST /linear-swap-api/v1/swap_tpsl_cancelall	Cancel all TP/SL Orders (Isolated)	contract_code	None	Yes
POST /linear-swap-api/v1/swap_cross_tpsl_cancelall	Cancel all TP/SL Orders (Cross)	None	contract_code	Yes
POST /linear-swap-api/v1/swap_tpsl_openorders	Query Open TP/SL Orders (Isolated)	contract_code	page_index, page_size	Yes
POST /linear-swap-api/v1/swap_cross_tpsl_openorders	Query Open TP/SL Orders (Cross)	None	contract_code, page_index, page_size	Yes
POST /linear-swap-api/v1/swap_tpsl_hisorders	Query TP/SL History Orders (Isolated)	contract_code	status, page_index, page_size, sort_by, direct	Yes
POST /linear-swap-api/v1/swap_cross_tpsl_hisorders	Query TP/SL History Orders (Cross)	None	contract_code, status, page_index, page_size, sort_by, direct	Yes

Transferring Interface

Endpoint	Description	Required	Optional	Authentication
POST /linear-swap-api/v1/swap_cross_transfer_state	Query Transfer State (Cross)	None	None	Yes

---

Parameters

Common Parameters

Contract & Symbol

• contract_code: Contract code (e.g., BTC-USDT, ETH-USDT)
• symbol: Symbol name
• pair: Trading pair (e.g., BTC-USDT)
• contract_type: Contract type (swap, this_week, next_week, quarter, next_quarter)
• business_type: Business type (futures, swap, all)

Account & Margin

• margin_account: Margin account identifier
• margin_mode: Margin mode (cross, isolated)
• margin_asset: Margin asset (e.g., USDT)
• account_type: Account type

Order Parameters

• order_id: Order ID (can be comma-separated for multiple orders)
• client_order_id: Client-defined order ID
• order_source: Order source
• order_type: Order type
• order_price_type: Order price type (limit, optimal_5, optimal_10, optimal_20, post_only, fok, ioc, etc.)
• direction: Transaction direction (buy, sell)
• offset: Offset direction (open, close, both)
• volume: Order volume (quantity in contracts)
• price: Order price
• lever_rate: Leverage rate
• reduce_only: Reduce only flag (0: no, 1: yes)

Trigger Order Parameters

• trigger_type: Trigger type (ge: greater than or equal, le: less than or equal)
• trigger_price: Trigger price
• triggered_price: The price when trigger order was executed

Take-Profit & Stop-Loss Parameters

• tp_trigger_price: Trigger price of take-profit order
• tp_order_price: Order price of take-profit order
• tp_order_price_type: Order type of take-profit order
• sl_trigger_price: Trigger price of stop-loss order
• sl_order_price: Order price of stop-loss order
• sl_order_price_type: Order type of stop-loss order
• price_protect: Price protection (boolean)

Trailing Order Parameters

• callback_rate: Callback rate for trailing orders
• active_price: Active price for trailing orders
• is_active: Whether the active price is activated

Query Parameters

• page_index: Page number (default: 1)
• page_size: Page size (default: 20, max: 50)
• start_time: Start time (Unix timestamp in milliseconds)
• end_time: End time (Unix timestamp in milliseconds)
• create_date: Number of days
• direct: Search direction (NEXT: ascending, PREV: descending)
• from_id: Starting ID for pagination
• sort_by: Sort field (descending order)

Sub-account Parameters

• sub_uid: Sub-account UID
• sub_auth: Sub-account authorization (0: disable, 1: enable)

Transfer Parameters

• from: Source account (e.g., spot, linear-swap)
• to: Destination account (e.g., spot, linear-swap)
• currency: Currency to transfer
• amount: Transfer amount
• from_margin_account: Source margin account
• to_margin_account: Destination margin account

Market Data Parameters

• period: K-line period (1min, 5min, 15min, 30min, 60min, 4hour, 1day, 1mon, 1week, 1year)
• type: Depth type (step0-step19)
• size: Number of records to return

Other Parameters

• trade_type: Trade type (0: all, 1: open long, 2: open short, 3: close short, 4: close long)
• status: Order status (multiple statuses can be comma-separated)
• self_match_prevent: Self-match prevention flag
• self_match_prevent_new: Prevent self-trading

Enums

Order Types

• 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

Order States

• status: submitted (3), partial-filled (4), partial-canceled (5), filled (6), canceled (7), ready to submit (1), accepted (2)

Direction & Offset

• direction: buy, sell
• offset: open, close, both

Margin Mode

• margin_mode: isolated, cross

Contract Type

• contract_type: swap (perpetual), this_week, next_week, quarter (current quarter), next_quarter

Position Mode

• position_mode: dual_side (hedge mode), single_side (one-way mode)

---

Authentication

For endpoints that require authentication, you will need to provide HTX API credentials.

Required credentials:

• apiKey: Your HTX API key
• secretKey: Your HTX API secret (for signing)

All authenticated endpoints require HMAC SHA256 signature:

1. Create the pre-sign string in the following order:

   • HTTP method (GET/POST) + "\n"
   • API host (e.g., api.hbdm.com) + "\n"
   • API path (e.g., /linear-swap-api/v1/swap_order) + "\n"
   • Sorted query string parameters

2. Append required parameters to all authenticated requests:

   • AccessKeyId: Your API key
   • SignatureMethod: HmacSHA256
   • SignatureVersion: 2
   • Timestamp: UTC timestamp in format yyyy-MM-ddTHH:mm:ss

3. Sign the pre-sign string with secretKey using HMAC SHA256

4. Append signature to query string as Signature parameter

5. For POST requests, also include signature in the URL query string

Example pre-sign string:

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

Security

Share Credentials

Users can provide HTX API credentials by sending a file where the content is in the following format:

fe45419a...xyz
secretabc...key

Never Display Full Secrets

When showing credentials to users:

• API Key: Show first 5 + last 4 characters: fe45419a...xyz
• Secret Key: Always mask, show only last 5: ***...key1

Example response when asked for credentials:

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

Listing Accounts

When listing accounts, show names and environment only — never keys:

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

Transactions in Mainnet

When performing transactions in mainnet, always confirm with the user before proceeding by asking them to write "CONFIRM" to proceed.

---

HTX Accounts

main

• API Key: your_mainnet_api_key
• Secret: your_mainnet_secret
• Environment: https://api.hbdm.com
• Description: Primary USDT-M Futures trading account

trading

• API Key: your_aws_api_key
• Secret: your_aws_secret
• Environment: https://api.hbdm.vn
• Description: AWS optimized USDT-M Futures trading

TOOLS.md Structure

## 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 Behavior

1. Credentials requested: Mask secrets (show last 5 chars only)
2. Listing accounts: Show names and environment, never keys
3. Account selection: Ask if ambiguous, default to main
4. When doing a transaction in mainnet, confirm with user before by asking to write "CONFIRM" to proceed
5. New credentials: Prompt for name, environment

Adding New Accounts

When user provides new credentials:

• Ask for account name
• Ask: Which environment (Mainnet or Mainnet-AWS)
• Store in TOOLS.md with masked display confirmation

User Agent Header

Include User-Agent header with the following string: htx-usdt-m-futures/1.0.0 (Skill)

Important Notes

• All timestamps are in Unix milliseconds unless specified otherwise
• Contract codes should use uppercase (e.g., BTC-USDT, not btc-usdt)
• For market buy orders, the volume parameter represents the number of contracts
• Account ID must be obtained from appropriate endpoints before trading
• Rate limits apply - see HTX API documentation for details
• Signature must be calculated for every authenticated request
• Timestamp in signature must be within 1 minute of server time
• Both isolated margin and cross margin modes are supported
• Position modes: single_side (one-way) and dual_side (hedge)
• Always use the correct margin mode and margin account for operations
• For cross margin operations, use endpoints with "cross" in their path
• For isolated margin operations, use endpoints without "cross" in their path
• All request endpoints must match the endpoints specified in the documentation.