gate-exchange-futures

name	gate-exchange-futures
version	2026.3.23-1
updated	2026-03-23
description	Gate Exchange USDT perpetual futures: open/close position, cancel/amend order, take profit, stop loss, conditional open. Use this skill whenever the user wants to trade USDT perpetual futures on Gate. Trigger phrases include open, close, cancel, amend, take profit, stop loss, TP/SL, conditional order, price trigger, when price reaches.

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 Server	Status
Gate (main)	✅ Required

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_fx_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

Module overview

Module	Description	Trigger keywords
Open	Limit/market open long or short, cross/isolated mode, top gainer/loser order	long, short, buy, sell, open, top gainer, top loser
Close	Full close, partial close, reverse position	close, close all, reverse
Cancel	Cancel one or many orders	cancel, revoke
Amend	Change order price or size	amend, modify
TP/SL	Attach take-profit or stop-loss to an existing position; fires a close/reduce order when price is reached	take profit, stop loss, TP, SL, 止盈, 止损
Conditional Open	Place a pending open order that triggers when price hits a level	conditional order, when price reaches, breakout buy, dip buy, 条件单, 触价开仓
Manage Triggers	List, cancel, or amend open price-triggered orders	list triggers, cancel TP, cancel SL, amend trigger, 查询条件单, 取消止盈止损

Routing rules

Intent	Example phrases	Route to
Open position	"BTC long 1 contract", "market short ETH", "10x leverage long", "top gainer long 10U"	Read references/open-position.md
Close position	"close all BTC", "close half", "reverse to short", "close everything"	Read references/close-position.md
Cancel orders	"cancel that buy order", "cancel all orders", "list my orders"	Read references/cancel-order.md
Amend order	"change price to 60000", "change order size"	Read references/amend-order.md
Set TP/SL	"Set BTC TP at 70000", "SL at 58000 for my long", "止损60000"	Read references/tp-sl.md
Conditional open	"Buy BTC when it drops to 60000", "Open short if price breaks above 68000", "条件单做多"	Read references/conditional.md
Manage triggered orders	"List my TP/SL orders", "Cancel that stop loss", "Amend trigger price", "查询条件单"	Read references/manage.md
Unclear	"help with futures", "show my position"	Clarify: query position/orders, then guide user

MCP tools

#	Tool	Purpose
1	cex_fx_get_fx_tickers	Get all futures tickers (for top gainer/loser sorting)
2	cex_fx_get_fx_contract	Get single contract info (precision, multiplier, etc.)
3	cex_fx_get_fx_order_book	Get contract order book (best bid/ask)
4	cex_fx_get_fx_accounts	Get futures account (position mode: single/dual)
5	cex_fx_list_fx_positions	List positions (dual mode)
6	cex_fx_get_fx_dual_position	Get dual-mode position for a contract
7	cex_fx_get_fx_position	Get single-mode position for a contract
8	cex_fx_update_fx_dual_position_cross_mode	Switch margin mode (cross/isolated)
9	cex_fx_update_fx_position_cross_mode	Switch margin mode in single mode (do NOT use in dual)
10	cex_fx_update_fx_dual_position_leverage	Set leverage (dual mode)
11	cex_fx_update_fx_position_leverage	Set leverage (single mode, do NOT use in dual)
12	cex_fx_create_fx_order	Place order (open/close/reverse)
13	cex_fx_list_fx_orders	List orders
14	cex_fx_get_fx_order	Get single order detail
15	cex_fx_cancel_fx_order	Cancel single order
16	cex_fx_cancel_all_fx_orders	Cancel all orders for a contract
17	cex_fx_amend_fx_order	Amend order (price/size)

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).

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 , switch—interrupt and tell user

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 = "<=" (price falls to SL level)
   • Short TP: trigger_rule = "<=" (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.

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 = "<=", "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_fx_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

Code	Action
BALANCE_NOT_ENOUGH	Suggest deposit or lower leverage/size.
PRICE_TOO_DEVIATED	Extract actual valid price range from the error message and show to user (do not rely on contract order_price_deviate; actual limit depends on risk_limit_tier).
POSITION_HOLDING (mode switch)	API returns this (not POSITION_NOT_EMPTY). Ask user to close position first.
CONTRACT_NOT_FOUND	Contract invalid or not tradeable. Confirm contract name (e.g. BTC_USDT) and settle; suggest listing contracts.
ORDER_NOT_FOUND	Order already filled, triggered, cancelled, or wrong order_id. Suggest checking order history or listing triggered orders.
APIOrderNotSupportUpdateTouchOrder	API-created conditional open orders cannot be amended. Cancel and re-create instead. TP/SL orders are not affected and can be amended normally.
SIZE_TOO_LARGE	Order size exceeds limit. Suggest reducing size or check contract order_size_max.
ORDER_FOK	FOK order could not be filled entirely. Suggest different price/size or use GTC/IOC.
ORDER_POC	POC order would have taken liquidity; exchange rejected. Suggest different price for maker-only.
INVALID_PARAM_VALUE	Often in dual mode when wrong API or params used (e.g. cex_fx_update_fx_position_cross_mode or cex_fx_update_fx_position_leverage in dual). Use dual-mode APIs: cex_fx_update_fx_dual_position_cross_mode, cex_fx_update_fx_dual_position_leverage; for position use cex_fx_list_fx_positions or cex_fx_get_fx_dual_position. For price-triggered orders: check trigger_rule, order_size sign, order_price format.