gate-exchange-futures

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gate Futures Trading Suite

Gate期货交易套件

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.

本Skill是Gate USDT永续合约的唯一入口。它仅支持四种操作：开仓、平仓、撤单、改单。用户的意图会被路由到对应的工作流中。

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`

模块	描述	触发关键词
Open	限价/市价开多或开空，全仓/逐仓模式，领涨/领跌合约下单	`long` , `short` , `buy` , `sell` , `open` , `top gainer` , `top loser`
Close	全部平仓、部分平仓、反向仓位	`close` , `close all` , `reverse`
Cancel	撤销单个或多个订单	`cancel` , `revoke`
Amend	修改订单价格或数量	`amend` , `modify`

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`
Unclear	"help with futures", "show my position"	Clarify: query position/orders, then guide user

意图	示例短语	路由至
开仓	"BTC long 1 contract", "market short ETH", "10x leverage long", "top gainer long 10U"	阅读 `references/open-position.md`
平仓	"close all BTC", "close half", "reverse to short", "close everything"	阅读 `references/close-position.md`
撤单	"cancel that buy order", "cancel all orders", "list my orders"	阅读 `references/cancel-order.md`
改单	"change price to 60000", "change order size"	阅读 `references/amend-order.md`
意图不明确	"help with futures", "show my position"	澄清：查询仓位/订单，然后引导用户

Execution workflow

执行工作流

1. Intent and parameters

1. 意图与参数

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

确定对应的模块（Open/Close/Cancel/Amend）。
提取参数：
```
contract
```
、
```
side
```
、
```
size
```
、
```
price
```
、
```
leverage
```
。
领涨/领跌合约：如果用户请求"top gainer"/"top loser"（或等效表述）而非指定具体合约，则调用
```
list_futures_tickers(settle="usdt")
```
接口，按
```
changePercentage
```
（涨跌幅）排序（领涨合约降序，领跌合约升序），选取排名第一的合约。之后使用该合约继续开仓流程。
参数缺失：如果必填参数缺失（如数量），则询问用户（澄清模式）。

2. Pre-flight checks

2. 前置检查

Contract: call
```
get_futures_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 get_futures_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 get_futures_accounts(settle)
first. If position_mode === "dual"
(or in_dual_mode === true
):

Position / leverage query: use list_futures_positions(settle, holding=true)
or get_futures_dual_mode_position(settle, contract)
. Do not use

get_futures_position

in dual mode (API returns an array and causes parse error).

Margin mode switch: use update_futures_dual_comp_position_cross_mode(settle, contract, mode)
(do not use

update_futures_position_cross_mode

in dual mode).

Leverage: use update_futures_dual_mode_position_leverage(settle, contract, leverage)
(do not use

update_futures_position_leverage

in dual mode; it returns array and causes parse error). If single mode: use get_futures_position(settle, contract)
for position; update_futures_dual_comp_position_cross_mode
for mode switch; update_futures_position_leverage
for leverage.

合约验证：调用
```
get_futures_contract
```
接口确保合约存在且可交易。
账户检查：检查账户余额及冲突仓位（如切换保证金模式时）。
风险检查：不要通过
```
order_price_deviate
```
预先计算有效限价（实际偏差限制取决于risk_limit_tier）。当出现
```
PRICE_TOO_DEVIATED
```
错误时，从错误信息中提取并展示有效价格范围。
保证金模式与仓位模式（仅当用户明确请求的保证金模式与当前模式不同时）：调用**
```
get_futures_accounts(settle)
```
接口获取仓位模式**。从返回结果的**
```
position_mode
```
**字段判断：
```
single
```
=单向持仓模式，
```
dual
```
=双向（对冲）持仓模式。仓位的保证金模式：根据上述单向/双向模式查询仓位 →
```
pos_margin_mode
```
（全仓/逐仓）。如果用户未指定保证金模式，请勿切换；使用当前模式下单。
- 单向持仓（
```
position_mode === "single"
```
  ）：不要中断流程。提示用户："您已持有{currency}仓位；切换保证金模式将同时应用于该仓位。是否继续？"（例如：合约BTC_USDT对应currency为BTC）。等待用户确认后继续。
- 双向持仓（
```
position_mode === "dual"
```
  ）：中断流程。告知用户："请先平仓，再开新仓。"

双向模式与单向模式（API选择）：先调用**

get_futures_accounts(settle)

接口。如果

position_mode === "dual"

（或

in_dual_mode === true

**）：

仓位/杠杆查询：使用**
```
list_futures_positions(settle, holding=true)
```
或
```
get_futures_dual_mode_position(settle, contract)
```
**。不要在双向模式下使用
```
get_futures_position
```
接口（API返回数组会导致解析错误）。

保证金模式切换：使用**

update_futures_dual_comp_position_cross_mode(settle, contract, mode)

**（不要在双向模式下使用

update_futures_position_cross_mode

）。

杠杆调整：使用**

update_futures_dual_mode_position_leverage(settle, contract, leverage)

（不要在双向模式下使用
update_futures_position_leverage
；该接口返回数组会导致解析错误）。如果是单向模式：使用

get_futures_position(settle, contract)

查询仓位；使用

update_futures_dual_comp_position_cross_mode

切换模式；使用

update_futures_position_leverage

**调整杠杆。

3. Module logic

3. 模块逻辑

Module A: Open position

模块A：开仓

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
```
get_futures_contract
```
and best bid/ask from
```
list_futures_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
```
  .
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.
Mode switch: only when user explicitly requested a margin mode and it differs from current (current from position:
```
pos_margin_mode
```
), then before calling
```
update_futures_dual_comp_position_cross_mode
```
: get position mode via
```
get_futures_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."
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
```
update_futures_dual_comp_position_cross_mode(settle, contract, mode)
```
with mode
```
"CROSS"
```
or
```
"ISOLATED"
```
. Do not switch if the user did not explicitly request a margin mode.
Leverage: if user specified leverage and it differs from current (from position query per dual/single above), call update_futures_dual_mode_position_leverage
in dual mode or update_futures_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).
Pre-order confirmation: get current leverage from position query (dual:
```
list_futures_positions
```
or
```
get_futures_dual_mode_position
```
; single:
```
get_futures_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.
Place order: call
```
create_futures_order
```
(market:
```
tif=ioc
```
,
```
price=0
```
).

Verify: confirm position via position query (dual:

list_futures_positions(holding=true)

get_futures_dual_mode_position

; single:

get_futures_position

单位转换：如果用户未以合约数指定数量，需区分USDT成本（基于保证金）和USDT面值（基于名义价值），从
```
get_futures_contract
```
接口获取
```
quanto_multiplier
```
，从
```
list_futures_order_book(settle, contract, limit=1)
```
接口获取最优买卖价：
- USDT成本（基于保证金）：开多：
```
contracts = cost / (0.0015 + 1/leverage) / quanto_multiplier / order_price
```
  ；开空：
```
contracts = cost / (0.0015 + 1.00075/leverage) / quanto_multiplier / max(order_price, best_bid)
```
  。
```
order_price
```
  ：限价→指定价格；市价→最优卖价（开多）或最优买价（开空）。leverage
  必须来自当前仓位查询结果（步骤5）；请勿使用默认值。
- USDT面值（基于名义价值）：买入/开多：
```
contracts = usdt_value / price / quanto_multiplier
```
  ；卖出/开空：
```
contracts = usdt_value / max(best_bid, order_price) / quanto_multiplier
```
  。
```
price
```
  ：限价→指定价格；市价→最优卖价（买入）或最优买价（卖出）。
- 基础货币（如BTC、ETH）：合约数 = 基础货币数量 ÷ quanto_multiplier
- 向下取整为整数；必须满足
```
order_size_min
```
  要求。
模式设置：仅当用户明确请求时才切换保证金模式：仅当用户明确要求逐仓时切换为逐仓（如提到"isolated"）；仅当用户明确要求全仓时切换为全仓（如提到"cross"）。如果用户未指定保证金模式，请勿切换 — 使用当前仓位的
pos_margin_mode
模式下单。如果用户明确要求逐仓，需检查杠杆。
模式切换（冲突处理）：仅当用户明确请求的保证金模式与当前模式（从仓位查询的
```
pos_margin_mode
```
获取）不同时，在调用
```
update_futures_dual_comp_position_cross_mode
```
接口之前：通过
```
get_futures_accounts(settle)
```
接口获取仓位模式→position_mode
（单向/双向）；如果
```
position_mode === "single"
```
，显示提示信息*"您已持有{currency}仓位；切换保证金模式将同时应用于该仓位。是否继续？"，仅在用户确认后继续；如果
position_mode === "dual"
，请勿切换—中断流程并告知用户"请先平仓，再开新仓。"*
模式切换（无冲突）：仅当用户明确请求全仓或逐仓且目标模式与当前模式不同时：如果无仓位，或单向持仓且用户已确认，调用
```
update_futures_dual_comp_position_cross_mode(settle, contract, mode)
```
接口，**
```
mode
```
**参数设为
```
"CROSS"
```
或
```
"ISOLATED"
```
。如果用户未明确请求保证金模式，请勿切换。
杠杆调整：如果用户指定的杠杆与当前杠杆（根据双向/单向模式的仓位查询结果）不同，先调用双向模式下的**
```
update_futures_dual_mode_position_leverage
```
接口或单向模式下的
```
update_futures_position_leverage
```
**接口，再继续流程。如果用户未指定杠杆，请勿修改 — 使用仓位查询得到的当前杠杆进行所有计算（如USDT成本公式）。请勿使用默认值（如10倍或20倍）。
下单前确认：从仓位查询（双向模式：
```
list_futures_positions
```
或
```
get_futures_dual_mode_position
```
；单向模式：
```
get_futures_position
```
）获取合约+方向的当前杠杆。展示最终订单摘要（合约、方向、数量、价格或市价、模式、杠杆、预估保证金/强平价格）。请求用户确认（例如："回复'confirm'以下单。"）。仅在用户确认后下单。
下单：调用
```
create_futures_order
```
接口（市价单：
```
tif=ioc
```
，
```
price=0
```
）。

验证：通过仓位查询确认仓位（双向模式：

list_futures_positions(holding=true)

或

get_futures_dual_mode_position

；单向模式：

get_futures_position

）。

Module B: Close position

模块B：平仓

Position: get current

size

and side via position query (dual:

list_futures_positions(settle, holding=true)

get_futures_dual_mode_position(settle, contract)

; single:

get_futures_position(settle, contract)

Branch: full close (query then close with reduce_only); partial (compute size,
```
create_futures_order
```
reduce_only); reverse (close then open opposite in two steps).
Verify: confirm remaining position via same position query as step 1.

仓位查询：通过仓位查询获取当前

size

和方向（双向模式：

list_futures_positions(settle, holding=true)

或

get_futures_dual_mode_position(settle, contract)

；单向模式：

get_futures_position(settle, contract)

）。

分支处理：全部平仓（查询后以reduce_only方式平仓）；部分平仓（计算数量，调用
```
create_futures_order
```
接口并设置reduce_only）；反向操作（分两步：先平仓再开反向仓位）。
验证：通过步骤1的同一仓位查询接口确认剩余仓位。

Module C: Cancel order

模块C：撤单

Locate: by order_id, or
```
list_futures_orders
```
and let user choose.
Cancel: single
```
cancel_futures_order
```
only (no batch cancel).
Verify:
```
finish_as
```
==
```
cancelled
```
.

定位订单：通过order_id定位，或调用
```
list_futures_orders
```
接口让用户选择。
撤单：仅调用单个
```
cancel_futures_order
```
接口（不支持批量撤单）。
验证：确认
```
finish_as
```
==
```
cancelled
```
。

Module D: Amend order

模块D：改单

Check: order status must be
```
open
```
.
Precision: validate new price/size against contract.
Amend: call
```
amend_futures_order
```
to update price or size.

状态检查：订单状态必须为
```
open
```
。
精度验证：验证新价格/数量是否符合合约要求。
改单：调用
```
amend_futures_order
```
接口更新价格或数量。

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
```
create_futures_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_futures_order
```
接口前请求用户确认。不要添加标记价格 vs 限价、order_price_deviate或建议调整价格的文字。示例："回复'confirm'以下单。"
全部平仓、反向操作、批量撤单：展示操作范围并请求确认。示例："是否全部平仓？回复确认。" / "撤销该合约的所有订单。是否继续？"

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, cancelled, or wrong order_id. Suggest checking order history.
`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. `update_futures_position_cross_mode` or `update_futures_position_leverage` in dual). Use dual-mode APIs: `update_futures_dual_comp_position_cross_mode` , `update_futures_dual_mode_position_leverage` ; for position use `list_futures_positions` or `get_futures_dual_mode_position` .

错误码	处理方式
`BALANCE_NOT_ENOUGH`	建议充值或降低杠杆/数量。
`PRICE_TOO_DEVIATED`	从错误信息中提取实际有效价格范围并展示给用户（不要依赖合约的 `order_price_deviate` ；实际限制取决于risk_limit_tier）。
`POSITION_HOLDING` （模式切换时）	API返回该错误（而非 `POSITION_NOT_EMPTY` ）。请用户先平仓。
`CONTRACT_NOT_FOUND`	合约无效或不可交易。确认合约名称（如BTC_USDT）和结算货币；建议列出可交易合约。
`ORDER_NOT_FOUND`	订单已成交、已撤销或order_id错误。建议查看订单历史。
`SIZE_TOO_LARGE`	订单数量超过限制。建议减少数量或查看合约的 `order_size_max` 。
`ORDER_FOK`	FOK订单无法全部成交。建议调整价格/数量或使用GTC/IOC订单。
`ORDER_POC`	POC订单将占用流动性；交易所拒绝该订单。建议调整价格以满足maker-only要求。
`INVALID_PARAM_VALUE`	通常在双向模式下使用错误API或参数时出现（如在双向模式下使用 `update_futures_position_cross_mode` 或 `update_futures_position_leverage` ）。请使用双向模式专用API： `update_futures_dual_comp_position_cross_mode` 、 `update_futures_dual_mode_position_leverage` ；仓位查询使用 `list_futures_positions` 或 `get_futures_dual_mode_position` 。