usdt-m-futures
Originally fromhtx-exchange/htx-skills-hub
SKILL.md
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.mdwith 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
volumeparameter 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
Weekly Installs
10
Repository
sunxiongkun/skills0311First Seen
4 days ago
Security Audits
Installed on
opencode10
gemini-cli10
github-copilot10
codex10
kimi-cli10
cursor10