Gate Exchange Futures

Resolving gate-cli (binary path)

Resolve gate-cli in order: (1) command -v gate-cli and gate-cli --version succeeds; (2) ${HOME}/.local/bin/gate-cli if executable; (3) ${HOME}/.openclaw/skills/bin/gate-cli if executable. Canonical rules: exchange-runtime-rules.md §4 (or gate-runtime-rules.md §4).

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 use the gate-cli commands explicitly listed in this skill. Commands not documented here must NOT be run for these workflows, even if other interfaces expose them.

Skill Dependencies

gate-cli commands used

Query Operations (Read-only)

• gate-cli cex futures account get
• gate-cli cex futures market contract
• gate-cli cex futures position get-dual
• gate-cli cex futures order get
• gate-cli cex futures market orderbook
• gate-cli cex futures position get
• gate-cli cex futures price-trigger get
• gate-cli cex futures market tickers
• gate-cli cex futures order list
• gate-cli cex futures position list
• gate-cli cex futures price-trigger list

Execution Operations (Write)

• gate-cli cex futures order amend
• gate-cli cex futures order cancel
• gate-cli cex futures order cancel
• gate-cli cex futures price-trigger cancel
• gate-cli cex futures price-trigger cancel-all
• gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short
• gate-cli cex futures price-trigger create
• gate-cli cex futures position update-dual-cross-mode
• gate-cli cex futures position update-dual-leverage
• gate-cli cex futures position update-cross-mode
• gate-cli cex futures position update-leverage
• gate-cli cex futures price-trigger update

Authentication

• Interactive file setup: when GATE_API_KEY and GATE_API_SECRET are not both set on the host, run gate-cli config init to complete the wizard for API key, secret, profiles, and defaults (see gate-cli).
• Env / flags: gate-cli config init is not required when credentials are already supplied — e.g. both GATE_API_KEY and GATE_API_SECRET set on the host, or --api-key / --api-secret where supported — never ask the user to paste secrets into chat.
• Permissions: Fx:Write
• Portal: create or rotate keys outside the chat: https://www.gate.com/myaccount/profile/api-key/manage

Installation Check

• Required: gate-cli (run sh ./setup.sh from this skill directory if missing; optional GATE_CLI_SETUP_MODE=release).
• Add $HOME/.openclaw/skills/bin to PATH if you invoke gate-cli by name (or the directory where setup.sh installs it).
• Credentials: When GATE_API_KEY and GATE_API_SECRET are both set (non-empty) for the host, do not require gate-cli config init — that is equivalent valid config for gate-cli. When both are unset or empty, remind the operator to run gate-cli config init or to configure GATE_API_KEY / GATE_API_SECRET in the matching skill from the skill library (never ask the user to paste secrets into chat).
• Sanity check: Do not proceed with authenticated calls until the CLI behaves as expected (e.g. gate-cli --version or a read-only gate-cli cex ... command from this skill); confirm credentials resolve before mutating operations.

Execution mode

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

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

Module overview

Routing rules

gate-cli command index

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 gate-cli cex futures market tickers, 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 gate-cli cex futures market 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 gate-cli cex futures account get 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 gate-cli cex futures account get first. If position_mode === "dual" (or in_dual_mode === true):

• Position / leverage query: use gate-cli cex futures position list or gate-cli cex futures position get-dual. Do not use gate-cli cex futures position get in dual mode (that is the single-mode API and returns the wrong schema).

• Margin mode switch: use gate-cli cex futures position update-dual-cross-mode (do not use gate-cli cex futures position update-cross-mode in dual mode; that is the single-mode API).

• Leverage: use gate-cli cex futures position update-dual-leverage (do not use gate-cli cex futures position update-leverage in dual mode; that is the single-mode API and returns the wrong schema). If single mode: use gate-cli cex futures position get for position; gate-cli cex futures position update-cross-mode for mode switch; gate-cli cex futures position update-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 gate-cli cex futures market contract and best bid/ask from gate-cli cex futures market orderbook:

• 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 gate-cli cex futures position update-dual-cross-mode/gate-cli cex futures position update-cross-mode: get position mode via gate-cli cex futures account get → 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 gate-cli cex futures position update-dual-cross-mode (dual) or gate-cli cex futures position update-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 gate-cli cex futures position update-dual-leverage in dual mode or gate-cli cex futures position update-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: gate-cli cex futures position list or gate-cli cex futures position get-dual; single: gate-cli cex futures position get) 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 gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short (market: tif=ioc, price=0).
8. Verify: confirm position via position query (dual: gate-cli cex futures position list or gate-cli cex futures position get-dual; single: gate-cli cex futures position get).

Module B: Close position

1. Position: get current size and side via position query (dual: gate-cli cex futures position list or gate-cli cex futures position get-dual; single: gate-cli cex futures position get).
2. Branch: full close (query then close with reduce_only); partial (compute size, gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short 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 gate-cli cex futures order list and let user choose.
2. Cancel: single gate-cli cex futures order cancel 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 gate-cli cex futures order amend 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.
• 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 gate-cli cex futures price-trigger create.

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 gate-cli cex futures market contract for quanto_multiplier and gate-cli cex futures market orderbook 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: gate-cli cex futures price-trigger list
• Get detail: gate-cli cex futures price-trigger get
• Cancel single: gate-cli cex futures price-trigger cancel
• Cancel all: gate-cli cex futures price-trigger cancel-all
• Amend: gate-cli cex futures price-trigger update

Amend limitation: only TP/SL orders (order_type contains plan-close-* or has reduce_only/close flag) support direct amendment via gate-cli cex futures price-trigger update. 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 gate-cli cex futures order add; gate-cli cex futures order close; gate-cli cex futures order long; gate-cli cex futures order remove; gate-cli cex futures order short. 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