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

Reference Data (Public & Private)

Endpoint Method Auth Description

/linear-swap-api/v3/swap_unified_account_type

GET Yes Account type query

/linear-swap-api/v3/swap_switch_account_type

POST Yes Account type change

/linear-swap-api/v1/swap_funding_rate

GET No Query funding rate

/linear-swap-api/v1/swap_batch_funding_rate

GET No Query a batch of funding rate

/linear-swap-api/v1/swap_historical_funding_rate

GET No Query historical funding rate

/linear-swap-api/v3/swap_liquidation_orders

GET No Query liquidation orders

/linear-swap-api/v1/swap_settlement_records

GET No Query historical settlement records

/linear-swap-api/v1/swap_elite_account_ratio

GET No Query top trader sentiment index (account)

/linear-swap-api/v1/swap_elite_position_ratio

GET No Query top trader sentiment index (position)

/linear-swap-api/v1/swap_api_state

GET No Query information on system status

/linear-swap-api/v1/swap_cross_ladder_margin

GET No Query information on tiered margin (cross)

/linear-swap-api/v1/swap_ladder_margin

GET No Query information on tiered margin (isolated)

/linear-swap-api/v1/swap_estimated_settlement_price

GET No Get the estimated settlement price

/linear-swap-api/v1/swap_adjustfactor

GET No Query information on tiered adjustment factor (isolated)

/linear-swap-api/v1/swap_cross_adjustfactor

GET No Query information on tiered adjustment factor (cross)

/v1/insurance_fund_info

GET No Query risk reserve balance information

/v1/insurance_fund_history

GET No Query historical risk reserves

/linear-swap-api/v1/swap_price_limit

GET No Query swap price limitation

/linear-swap-api/v1/swap_open_interest

GET No Get swap open interest information

/linear-swap-api/v1/swap_contract_info

GET No Query contract info

/linear-swap-api/v1/swap_index

GET No Query swap index price information

/linear-swap-api/market/swap_contract_constituents

GET No Get index components

/linear-swap-api/v1/swap_query_elements

GET No Contract elements

https://api.hbdm.com/api/v1/timestamp

GET No Get current system timestamp

https://api.hbdm.com/heartbeat/

GET No Query whether the system is available

https://api.hbdm.com/heartbeat

GET Yes Maintenance with service suspended

Market Data (Public)

Endpoint Method Auth Description

/linear-swap-ex/market/depth

GET No Get market depth

/linear-swap-ex/market/bbo

GET No Get market BBO data

/linear-swap-ex/market/history/kline

GET No Get KLine data

/index/market/history/linear_swap_mark_price_kline

GET No Get kline data of mark price

/linear-swap-ex/market/detail/merged

GET No Get market data overview

/v2/linear-swap-ex/market/detail/batch_merged

GET No Get a batch of market data overview (V2)

/linear-swap-ex/market/trade

GET No Query the last trade of a contract

/linear-swap-ex/market/history/trade

GET No Query a batch of trade records

/linear-swap-api/v1/swap_his_open_interest

GET No Query information on open interest

/index/market/history/linear_swap_premium_index_kline

GET No Query premium index kline data

/index/market/history/linear_swap_estimated_rate_kline

GET No Query estimated funding rate kline data

/index/market/history/linear_swap_basis

GET No Query basis data

Account Interface (Private)

Endpoint Method Auth Description

/linear-swap-api/v1/swap_balance_valuation

POST Yes Query asset valuation

/linear-swap-api/v1/swap_account_info

POST Yes Query user's account information (isolated)

/linear-swap-api/v1/swap_cross_account_info

POST Yes Query user's account information (cross)

/linear-swap-api/v1/swap_position_info

POST Yes Query user's position information (isolated)

/linear-swap-api/v1/swap_cross_position_info

POST Yes Query user's position information (cross)

/linear-swap-api/v1/swap_account_position_info

POST Yes Query assets and positions (isolated)

/linear-swap-api/v1/swap_cross_account_position_info

POST Yes Query assets and positions (cross)

/linear-swap-api/v1/swap_sub_auth

POST Yes Set a batch of sub-account trading permissions

/linear-swap-api/v1/swap_sub_auth_list

GET Yes Query sub-account transaction permissions

/linear-swap-api/v1/swap_sub_account_list

POST Yes Query assets information of all sub-accounts (isolated)

/linear-swap-api/v1/swap_cross_sub_account_list

POST Yes Query assets information of all sub-accounts (cross)

/linear-swap-api/v1/swap_sub_account_info_list

POST Yes Query a batch of sub-account's assets information (isolated)

/linear-swap-api/v1/swap_cross_sub_account_info_list

POST Yes Query a batch of sub-account's assets information (cross)

/linear-swap-api/v1/swap_sub_account_info

POST Yes Query a single sub-account's assets information

/linear-swap-api/v1/swap_cross_sub_account_info

POST Yes Query a sub-account's assets information (cross)

/linear-swap-api/v1/swap_sub_position_info

POST Yes Query a single sub-account's position information (isolated)

/linear-swap-api/v1/swap_cross_sub_position_info

POST Yes Query a sub-account's position information (cross)

/linear-swap-api/v3/swap_financial_record

POST Yes Query account financial records

/linear-swap-api/v3/swap_financial_record_exact

POST Yes Query account financial records via multiple fields

/linear-swap-api/v1/swap_available_level_rate

POST Yes Query user's available leverage (isolated)

/linear-swap-api/v1/swap_cross_available_level_rate

POST Yes Query user's available leverage (cross)

/linear-swap-api/v1/swap_order_limit

POST Yes Query swap information on order limit

/linear-swap-api/v1/swap_fee

POST Yes Query information on swap trading fee

/linear-swap-api/v1/swap_transfer_limit

POST Yes Query information on transfer limit (isolated)

/linear-swap-api/v1/swap_cross_transfer_limit

POST Yes Query information on transfer limit (cross)

/linear-swap-api/v1/swap_position_limit

POST Yes Query information on position limit (isolated)

/linear-swap-api/v1/swap_cross_position_limit

POST Yes Query information on position limit (cross)

/linear-swap-api/v1/swap_lever_position_limit

POST Yes Query users' position limit for all leverages (isolated)

/linear-swap-api/v1/swap_cross_lever_position_limit

POST Yes Query users' position limit for all leverages (cross)

/linear-swap-api/v1/swap_master_sub_transfer

POST Yes Transfer between master and sub account

/linear-swap-api/v1/swap_master_sub_transfer_record

POST Yes Query transfer records between master and sub account

/linear-swap-api/v1/swap_transfer_inner

POST Yes Transfer between different margin accounts

/linear-swap-api/v1/swap_api_trading_status

GET Yes Query user's API indicator disable information

Trade Interface (Private)

Endpoint Method Auth Description

/linear-swap-api/v1/swap_cross_trade_state

GET No Query information on trade state (cross)

/linear-swap-api/v1/swap_switch_position_mode

POST Yes Switch position mode (isolated)

/linear-swap-api/v1/swap_cross_switch_position_mode

POST Yes Switch position mode (cross)

/linear-swap-api/v1/swap_order

POST Yes Place an order (isolated)

/linear-swap-api/v1/swap_cross_order

POST Yes Place an order (cross)

/linear-swap-api/v1/swap_batchorder

POST Yes Place a batch of orders (isolated)

/linear-swap-api/v1/swap_cross_batchorder

POST Yes Place a batch of orders (cross)

/linear-swap-api/v1/swap_cancel

POST Yes Cancel an order (isolated)

/linear-swap-api/v1/swap_cross_cancel

POST Yes Cancel an order (cross)

/linear-swap-api/v1/swap_cancelall

POST Yes Cancel all orders (isolated)

/linear-swap-api/v1/swap_cross_cancelall

POST Yes Cancel all orders (cross)

/linear-swap-api/v1/swap_switch_lever_rate

POST Yes Switch leverage (isolated)

/linear-swap-api/v1/swap_cross_switch_lever_rate

POST Yes Switch leverage (cross)

/linear-swap-api/v1/swap_order_info

POST Yes Get information of an order (isolated)

/linear-swap-api/v1/swap_cross_order_info

POST Yes Get information of an order (cross)

/linear-swap-api/v1/swap_order_detail

POST Yes Order details acquisition (isolated)

/linear-swap-api/v1/swap_cross_order_detail

POST Yes Get detail information of order (cross)

/linear-swap-api/v1/swap_openorders

POST Yes Current unfilled order acquisition (isolated)

/linear-swap-api/v1/swap_cross_openorders

POST Yes Current unfilled order acquisition (cross)

/linear-swap-api/v3/swap_hisorders

POST Yes Get history orders (isolated)

/linear-swap-api/v3/swap_cross_hisorders

POST Yes Get history orders (cross)

/linear-swap-api/v3/swap_hisorders_exact

POST Yes Get history orders via multiple fields (isolated)

/linear-swap-api/v3/swap_cross_hisorders_exact

POST Yes Get history orders via multiple fields (cross)

/linear-swap-api/v3/swap_matchresults

POST Yes Acquire history match results (isolated)

/linear-swap-api/v3/swap_cross_matchresults

POST Yes Get history match results (cross)

/linear-swap-api/v3/swap_matchresults_exact

POST Yes Get history match results via multiple fields (isolated)

/linear-swap-api/v3/swap_cross_matchresults_exact

POST Yes Get history match results via multiple fields (cross)

/linear-swap-api/v1/swap_lightning_close_position

POST Yes Place lightning close order (isolated)

/linear-swap-api/v1/swap_cross_lightning_close_position

POST Yes Place lightning close position (cross)

/linear-swap-api/v1/swap_position_side

GET Yes Query position mode (isolated)

/linear-swap-api/v1/swap_cross_position_side

GET Yes Query position mode (cross)

Strategy Order Interface (Private)

Endpoint Method Auth Description

/linear-swap-api/v1/swap_trigger_order

POST Yes Place trigger order (isolated)

/linear-swap-api/v1/swap_cross_trigger_order

POST Yes Place trigger order (cross)

/linear-swap-api/v1/swap_trigger_cancel

POST Yes Cancel trigger order (isolated)

/linear-swap-api/v1/swap_cross_trigger_cancel

POST Yes Cancel trigger order (cross)

/linear-swap-api/v1/swap_trigger_cancelall

POST Yes Cancel all trigger orders (isolated)

/linear-swap-api/v1/swap_cross_trigger_cancelall

POST Yes Cancel all trigger orders (cross)

/linear-swap-api/v1/swap_trigger_openorders

POST Yes Query trigger order open orders (isolated)

/linear-swap-api/v1/swap_cross_trigger_openorders

POST Yes Query trigger order open orders (cross)

/linear-swap-api/v1/swap_trigger_hisorders

POST Yes Query trigger order history (isolated)

/linear-swap-api/v1/swap_cross_trigger_hisorders

POST Yes Query trigger order history (cross)

/linear-swap-api/v1/swap_tpsl_order

POST Yes Set a take-profit and stop-loss order (isolated)

/linear-swap-api/v1/swap_cross_tpsl_order

POST Yes Set a take-profit and stop-loss order (cross)

/linear-swap-api/v1/swap_tpsl_cancel

POST Yes Cancel a take-profit and stop-loss order (isolated)

/linear-swap-api/v1/swap_cross_tpsl_cancel

POST Yes Cancel a take-profit and stop-loss order (cross)

/linear-swap-api/v1/swap_tpsl_cancelall

POST Yes Cancel all take-profit and stop-loss orders (isolated)

/linear-swap-api/v1/swap_cross_tpsl_cancelall

POST Yes Cancel all take-profit and stop-loss orders (cross)

/linear-swap-api/v1/swap_tpsl_openorders

POST Yes Query open take-profit and stop-loss orders (isolated)

/linear-swap-api/v1/swap_cross_tpsl_openorders

POST Yes Query open take-profit and stop-loss orders (cross)

/linear-swap-api/v1/swap_tpsl_hisorders

POST Yes Query take-profit and stop-loss history orders (isolated)

/linear-swap-api/v1/swap_cross_tpsl_hisorders

POST Yes Query take-profit and stop-loss history orders (cross)

/linear-swap-api/v1/swap_relation_tpsl_order

POST Yes Query info of take-profit and stop-loss order (isolated)

/linear-swap-api/v1/swap_cross_relation_tpsl_order

POST Yes Query info of take-profit and stop-loss order (cross)

/linear-swap-api/v1/swap_track_order

POST Yes Place a trailing order (isolated)

/linear-swap-api/v1/swap_cross_track_order

POST Yes Place a trailing order (cross)

/linear-swap-api/v1/swap_track_cancel

POST Yes Cancel a trailing order (isolated)

/linear-swap-api/v1/swap_cross_track_cancel

POST Yes Cancel a trailing order (cross)

/linear-swap-api/v1/swap_track_cancelall

POST Yes Cancel all trailing orders (isolated)

/linear-swap-api/v1/swap_cross_track_cancelall

POST Yes Cancel all trailing orders (cross)

/linear-swap-api/v1/swap_track_openorders

POST Yes Current unfilled trailing order acquisition (isolated)

/linear-swap-api/v1/swap_cross_track_openorders

POST Yes Current unfilled trailing order acquisition (cross)

/linear-swap-api/v1/swap_track_hisorders

POST Yes Get history trailing orders (isolated)

/linear-swap-api/v1/swap_cross_track_hisorders

POST Yes Get history trailing orders (cross)

Transferring Interface

Endpoint Method Auth Description

/linear-swap-api/v1/swap_cross_transfer_state

GET No Query information on transfer state

/v2/account/transfer

POST Yes Transfer margin between Spot account and USDT Margined Contracts account

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:

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

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

Sign the pre-sign string with secretKey using HMAC SHA256

Append signature to query string as Signature parameter

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

• Credentials requested: Mask secrets (show last 5 chars only)

• Listing accounts: Show names and environment, never keys

• Account selection: Ask if ambiguous, default to main

• When doing a transaction in mainnet, confirm with user before by asking to write "CONFIRM" to proceed

• 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