Gate Futures Trading Suite

General Rules

⚠️ STOP — You MUST read and strictly follow the shared runtime rules before proceeding. Do NOT select or call any tool until all rules are read. These rules have the highest priority. → Read gate-runtime-rules.md

• Only call MCP tools explicitly listed in this skill. Tools not documented here must NOT be called, even if they exist in the MCP server.

MCP Dependencies

Required MCP Servers

MCP Tools Used

Query Operations (Read-only)

• cex_fx_get_fx_accounts
• cex_fx_get_fx_contract
• cex_fx_get_fx_dual_position
• cex_fx_get_fx_order
• cex_fx_get_fx_order_book
• cex_fx_get_fx_position
• cex_fx_get_fx_price_triggered_order
• cex_fx_get_fx_tickers
• cex_fx_list_fx_orders
• cex_fx_list_fx_positions
• cex_fx_list_price_triggered_orders

Execution Operations (Write)

• cex_fx_amend_fx_order
• cex_fx_cancel_all_fx_orders
• cex_fx_cancel_fx_order
• cex_fx_cancel_fx_price_triggered_order
• cex_fx_cancel_fx_price_triggered_order_list
• cex_fx_create_fx_order
• cex_fx_create_fx_price_triggered_order
• cex_fx_update_fx_dual_position_cross_mode
• cex_fx_update_fx_dual_position_leverage
• cex_fx_update_fx_position_cross_mode
• cex_fx_update_fx_position_leverage
• cex_fx_update_fx_price_triggered_order

Authentication

• API Key Required: Yes (see skill doc/runtime MCP deployment)
• Permissions: Fx:Write
• Get API Key: https://www.gate.io/myaccount/profile/api-key/manage

Installation Check

• Required: Gate (main)
• Install: Run installer skill for your IDE
  • Cursor: gate-mcp-cursor-installer
  • Codex: gate-mcp-codex-installer
  • Claude: gate-mcp-claude-installer
  • OpenClaw: gate-mcp-openclaw-installer

MCP Mode

Read and strictly follow references/mcp.md, then execute module-specific routes in this SKILL.md.

• SKILL.md keeps routing logic (Open/Close/Cancel/Amend/TP-SL/Conditional/Manage).
• references/mcp.md is the authoritative MCP execution layer for tool contracts, mode switching safeguards, confirmation gates, and degraded handling.

Module overview

Routing rules

MCP tools

Execution workflow

1. Intent and parameters

• Determine module (Open/Close/Cancel/Amend/TP-SL/Conditional/Manage).
• Extract: contract, side, size, price, leverage (for Open/Close); trigger_price, trigger_rule, order_size, order_price, order_tif (for TP/SL/Conditional).
• 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.

• Settle currency: always usdt unless user explicitly specifies BTC-settled contract.

• 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_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/cex_fx_update_fx_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 (dual) or cex_fx_update_fx_position_cross_mode (single) 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.

Module E: Take Profit / Stop Loss

Read references/tp-sl.md for full logic. Key points:

1. Position check: get current position to confirm side and size (dual/single mode rules from pre-flight checks apply).
2. Trigger rule auto-selection:
   • Long TP: trigger_rule = ">=" (price rises to TP level)
   • Long SL: trigger_rule = "\x3C=" (price falls to SL level)
   • Short TP: trigger_rule = "\x3C=" (price falls to TP level)
   • Short SL: trigger_rule = ">=" (price rises to SL level)
3. Close flags (close, auto_size, and order_type depend on position mode and side):
   • Single mode, full close long: order_type = "close-long-position", close = true, no auto_size, order_reduce_only = true.
   • Single mode, full close short: order_type = "close-short-position", close = true, no auto_size, order_reduce_only = true.
   • Single mode, partial close long: order_type = "plan-close-long-position", close = false, no auto_size, order_reduce_only = true.
   • Single mode, partial close short: order_type = "plan-close-short-position", close = false, no auto_size, order_reduce_only = true.
   • Dual mode, full close long: order_type = "close-long-position", close = false, auto_size = "close_long", order_reduce_only = true.
   • Dual mode, full close short: order_type = "close-short-position", close = false, auto_size = "close_short", order_reduce_only = true.
   • Dual mode, partial close long: order_type = "plan-close-long-position", close = false, no auto_size, order_reduce_only = true.
   • Dual mode, partial close short: order_type = "plan-close-short-position", close = false, no auto_size, order_reduce_only = true.
4. Size: if user says "close all" or does not specify size, use full close (size = 0) with mode-appropriate flags above; if partial, compute size and set order_reduce_only = true.
5. Market vs limit: if user does not specify execution price, use market (order_price = "0", order_tif = "ioc"); otherwise limit (order_tif = "gtc").
6. Confirmation: show summary (contract, side, trigger price, trigger rule, execution type, size or "close all") and ask user to confirm before calling cex_fx_create_fx_price_triggered_order.

Module F: Conditional Open

Read references/conditional.md for full logic. Key points:

1. No position required: this opens a new position when triggered.
2. Trigger rule: user specifies direction — "buy when drops to X" → trigger_rule = "\x3C=", "buy when breaks above X" → trigger_rule = ">=".
3. Size conversion: same unit conversion rules as Module A (contracts, USDT cost, USDT value, base amount). Use cex_fx_get_fx_contract for quanto_multiplier and cex_fx_get_fx_order_book for best bid/ask. For cost-based conversion, use trigger_price as reference order_price when user has not specified an execution limit price.
4. Order size sign: positive = long, negative = short.
5. Confirmation: show full summary before placing.

Module G: Manage Triggered Orders

Read references/manage.md for full logic. Supports:

• List: cex_fx_list_price_triggered_orders
• Get detail: cex_fx_get_fx_price_triggered_order
• Cancel single: cex_fx_cancel_fx_price_triggered_order
• Cancel all: cex_fx_cancel_fx_price_triggered_order_list
• Amend: cex_fx_update_fx_price_triggered_order

Amend limitation: only TP/SL orders (order_type contains plan-close-* or has reduce_only/close flag) support direct amendment via cex_fx_update_fx_price_triggered_order. Conditional open orders created via API return APIOrderNotSupportUpdateTouchOrder and cannot be amended — must cancel and re-create instead.

Report template

After each operation, output a short standardized result.

For price-triggered orders:

✓ [Operation] [Contract]
  Trigger: [rule] [trigger_price]
  Execute: [market/limit price] × [size or "close all"] [reduce_only/close]
  Order ID: [id]

Domain Knowledge

• USDT perpetual futures: linear contracts settled in USDT. Position size is measured in contracts; each contract represents quanto_multiplier units of the base asset (e.g. 0.001 BTC).
• Cross vs Isolated margin: cross mode shares the entire account balance as margin; isolated mode limits margin to the amount allocated to this position.
• Single vs Dual position mode: single mode holds one net position per contract; dual mode (hedge) allows simultaneous long and short positions on the same contract. API endpoints differ between modes.
• Price-triggered orders: conditional orders that fire when market price crosses a trigger level. Used for TP/SL (close existing position) and conditional open (open new position). The trigger is server-side; no client needs to be online.
• Reduce-only: ensures the order only reduces an existing position and does not accidentally open a new one. Always set for TP/SL orders.
• Order size sign: for price-triggered close orders, negative size = sell (close long), positive size = buy (close short). For open orders, positive = long, negative = short.

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?"
• Create TP/SL / Conditional: show full summary (contract, trigger rule + price, execution price/type, size), then ask "Reply 'confirm' to place this order."
• Cancel all triggered orders: show scope (contract or all) and ask "Cancel all triggered orders for [contract]? Reply to confirm."
• Amend triggered order: show old vs new values and ask for confirmation.

Order ID precision

Gate order IDs are 64-bit integers that exceed Number.MAX_SAFE_INTEGER (2^53-1). Standard JSON parsers silently corrupt them.

• Always pass order_id as a string (e.g. "728451920374819843", not 728451920374819843).
• When reading an order ID from an API response, copy it as the raw string token, never as a parsed number.
• When displaying order IDs to the user, always render as a string with no formatting (no commas or scientific notation).

Errors