Gate Futures Trading Suite

This skill is the single entry for Gate USDT perpetual futures. It supports four operations only: open position, close position, cancel order, amend order. User intent is routed to the matching workflow.

Module overview

Routing rules

MCP tools

Execution workflow

1. Intent and parameters

• Determine module (Open/Close/Cancel/Amend).
• Extract: contract, side, size, price, leverage.
• Top gainer/loser: if user requests "top gainer" / "top loser" (or equivalent) instead of a specific contract, call cex_fx_get_fx_tickers(settle="usdt"), sort by changePercentage (descending for gainer, ascending for loser), pick the top contract. Then continue the open flow with that contract.
• Missing: if required params missing (e.g. size), ask user (clarify mode).

2. Pre-flight checks

• Contract: call cex_fx_get_fx_contract to ensure contract exists and is tradeable.

• Account: check balance and conflicting positions (e.g. when switching margin mode).

• Risk: do not pre-calculate valid limit price from order_price_deviate (actual deviation limit depends on risk_limit_tier). On PRICE_TOO_DEVIATED, show the valid range from the error message.

• Margin mode vs position mode (only when user explicitly requested a margin mode and it differs from current): call cex_fx_get_fx_accounts(settle) to get position mode. From response position_mode: single = single position mode, dual = dual (hedge) position mode. Margin mode from position: use position query per dual/single above → pos_margin_mode (cross/isolated). If user did not specify margin mode, do not switch; place order in current mode.

  • Single position (position_mode === "single"): do not interrupt. Prompt user: "You already have a {currency} position; switching margin mode will apply to this position too. Continue?" (e.g. currency from contract: BTC_USDT → BTC). Wait for user confirmation, then continue.
  • Dual position (position_mode === "dual"): interrupt flow. Tell user: "Please close the position first, then open a new one."

• Dual mode vs single mode (API choice): call cex_fx_get_fx_accounts(settle) first. If position_mode === "dual" (or in_dual_mode === true):

  • Position / leverage query: use cex_fx_list_fx_positions(settle, holding=true) or cex_fx_get_fx_dual_position(settle, contract). Do not use cex_fx_get_fx_position in dual mode (API returns an array and causes parse error).
  • Margin mode switch: use cex_fx_update_fx_dual_position_cross_mode(settle, contract, mode) (do not use cex_fx_update_fx_position_cross_mode in dual mode).
  • Leverage: use cex_fx_update_fx_dual_position_leverage(settle, contract, leverage) (do not use cex_fx_update_fx_position_leverage in dual mode; it returns array and causes parse error). If single mode: use cex_fx_get_fx_position(settle, contract) for position; cex_fx_update_fx_dual_position_cross_mode for mode switch; cex_fx_update_fx_position_leverage for leverage.

3. Module logic

Module A: Open position

1. Unit conversion: if user does not specify size in contracts, distinguish between USDT cost ("spend 100U") and USDT value ("100U worth"), get quanto_multiplier from cex_fx_get_fx_contract and best bid/ask from cex_fx_get_fx_order_book(settle, contract, limit=1):
   • USDT cost (margin-based): open long: contracts = cost / (0.0015 + 1/leverage) / quanto_multiplier / order_price; open short: contracts = cost / (0.0015 + 1.00075/leverage) / quanto_multiplier / max(order_price, best_bid). order_price: limit → specified price; market → best ask (long) or best bid (short). leverage must come from the current position query (step 5); do not assume a default.
   • USDT value (notional-based): buy/open long: contracts = usdt_value / price / quanto_multiplier; sell/open short: contracts = usdt_value / max(best_bid, order_price) / quanto_multiplier. price: limit → specified price; market → best ask (buy) or best bid (sell).
   • Base (e.g. BTC, ETH): contracts = base_amount ÷ quanto_multiplier
   • Floor to integer; must satisfy order_size_min.
2. Mode: Switch margin mode only when the user explicitly requests it: switch to isolated only when user explicitly asks for isolated (e.g. "isolated"); switch to cross only when user explicitly asks for cross (e.g. "cross"). If the user does not specify margin mode, do not switch — place the order in the current margin mode (from position pos_margin_mode). If user explicitly wants isolated, check leverage.
3. Mode switch: only when user explicitly requested a margin mode and it differs from current (current from position: pos_margin_mode), then before calling cex_fx_update_fx_dual_position_cross_mode: get position mode via cex_fx_get_fx_accounts(settle) → position_mode (single/dual); if position_mode === "single", show prompt "You already have a {currency} position; switching margin mode will apply to this position too. Continue?" and continue only after user confirms; if position_mode === "dual", do not switch—interrupt and tell user "Please close the position first, then open a new one."
4. Mode switch (no conflict): only when user explicitly requested cross or isolated and that target differs from current: if no position, or single position and user confirmed, call cex_fx_update_fx_dual_position_cross_mode(settle, contract, mode) with mode "CROSS" or "ISOLATED". Do not switch if the user did not explicitly request a margin mode.
5. Leverage: if user specified leverage and it differs from current (from position query per dual/single above), call cex_fx_update_fx_dual_position_leverage in dual mode or cex_fx_update_fx_position_leverage in single mode first, then proceed. If user did not specify leverage, do not change it — use the current leverage from the position query for all calculations (e.g. USDT cost formula). Do not default to any value (e.g. 10x or 20x).
6. Pre-order confirmation: get current leverage from position query (dual: cex_fx_list_fx_positions or cex_fx_get_fx_dual_position; single: cex_fx_get_fx_position) for contract + side. Show final order summary (contract, side, size, price or market, mode, leverage, estimated margin/liq price). Ask user to confirm (e.g. "Reply 'confirm' to place the order."). Only after user confirms, place order.
7. Place order: call cex_fx_create_fx_order (market: tif=ioc, price=0).
8. Verify: confirm position via position query (dual: cex_fx_list_fx_positions(holding=true) or cex_fx_get_fx_dual_position; single: cex_fx_get_fx_position).

Module B: Close position

1. Position: get current size and side via position query (dual: cex_fx_list_fx_positions(settle, holding=true) or cex_fx_get_fx_dual_position(settle, contract); single: cex_fx_get_fx_position(settle, contract)).
2. Branch: full close (query then close with reduce_only); partial (compute size, cex_fx_create_fx_order reduce_only); reverse (close then open opposite in two steps).
3. Verify: confirm remaining position via same position query as step 1.

Module C: Cancel order

1. Locate: by order_id, or cex_fx_list_fx_orders and let user choose.
2. Cancel: single cex_fx_cancel_fx_order only (no batch cancel).
3. Verify: finish_as == cancelled.

Module D: Amend order

1. Check: order status must be open.
2. Precision: validate new price/size against contract.
3. Amend: call cex_fx_amend_fx_order to update price or size.

Report template

After each operation, output a short standardized result.

Safety rules

Confirmation

• Open: show final order summary (contract, side, size, price/market, mode, leverage, estimated liq/margin), then ask for confirmation before cex_fx_create_fx_order. Do not add text about mark price vs limit price, order_price_deviate, or suggesting to adjust price. Example: "Reply 'confirm' to place the order."
• Close all, reverse, batch cancel: show scope and ask for confirmation. Example: "Close all positions? Reply to confirm." / "Cancel all orders for this contract. Continue?"

Errors