gate-exchange-transfer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Read and follow the shared runtime rules before proceeding: → exchange-runtime-rules.md

在操作前请阅读并遵循共享的运行时规则： → exchange-runtime-rules.md

Gate Exchange Transfer (Internal Transfer)

Gate Exchange 内部转账（同UID划转）

Execute same-UID internal transfers between Gate trading accounts: spot, isolated margin, perpetual, delivery, and options. Single execution endpoint:

POST /wallet/transfers

(MCP:

cex_wallet_create_transfer

Scope (Phase 1)

Supported: internal transfer only (same UID, between account types above).
Not supported: main-to-sub, sub-to-main, sub-to-sub. See
```
references/scenarios.md
```
for future scenario coverage.

执行Gate交易账户间的同UID内部转账：现货、逐仓保证金、永续合约、交割合约、期权账户。统一执行端点：

POST /wallet/transfers

（对应MCP工具：

cex_wallet_create_transfer

）。

适用范围（第一阶段）

支持：仅同UID内部转账（上述账户类型之间）。
不支持：主账户转子账户、子账户转主账户、子账户转子账户。未来支持场景请参考
```
references/scenarios.md
```
。

Preconditions

前置条件

Precondition	If not met
User logged in	Do not call API; prompt to log in (exception flow).
Account mode known	Infer from context or assume classic: Spot ↔ USDT perpetual. For unified/trading account advanced mode: Trading account ↔ BTC perpetual.
Source balance verifiable	Call balance API for `from` account before showing draft; if unavailable, prompt user to check on web.

前置条件	不满足时的处理
用户已登录	不调用API；提示用户登录（异常流程）。
已知账户模式	从上下文推断，或默认使用经典模式：现货 ↔ USDT永续合约。对于统一交易账户/交易账户高级模式：交易账户 ↔ BTC永续合约。
可验证转出账户余额	在展示转账草稿前调用余额API查询转出账户；若无法查询，提示用户通过网页端查看。

The Four Elements

四大核心要素

Every internal transfer is fully specified by four elements. The assistant must resolve or infer them before showing a Transfer Draft.

Element	API param	Required when	Notes
From	`from`	Always	spot \| margin \| futures \| delivery \| options
To	`to`	Always	Same enum as `from`
Currency	`currency`	Always	USDT, BTC, etc. (platform-supported). Missing → auto-complete by target (case2).
Amount	`amount`	Always	String, > 0, up to 8 decimals. Missing → ask user (case8).

Conditional params

margin:
```
currency_pair
```
required (e.g.
```
BTC_USDT
```
) when
```
from
```
or
```
to
```
is
```
margin
```
.
futures / delivery:
```
settle
```
required (
```
usdt
```
|
```
btc
```
) when
```
from
```
or
```
to
```
is
```
futures
```
or
```
delivery
```
.

每笔内部转账需明确四大要素。助手必须先解析或推断出这些要素，再展示转账草稿。

要素	API参数	必填场景	说明
转出账户	`from`	始终必填	spot \| margin \| futures \| delivery \| options
转入账户	`to`	始终必填	与 `from` 的可选值一致
币种	`currency`	始终必填	USDT、BTC等（平台支持的币种）。缺失时→按目标账户自动补全（见场景2）。
金额	`amount`	始终必填	字符串格式，大于0，最多保留8位小数。缺失时→询问用户（见场景8）。

条件必填参数

保证金账户：当
```
from
```
或
```
to
```
为
```
margin
```
时，需填写
```
currency_pair
```
（例如
```
BTC_USDT
```
）。
永续/交割合约：当
```
from
```
或
```
to
```
为
```
futures
```
或
```
delivery
```
时，需填写
```
settle
```
（
```
usdt
```
|
```
btc
```
）。

Public API (Phase 1)

公开API（第一阶段）

Endpoint	Method	Meaning	Rate limit
`/wallet/transfers`	POST	Same-UID internal transfer	80 req/10s

端点	请求方法	用途	调用频率限制
`/wallet/transfers`	POST	同UID内部转账	10秒内最多80次请求

Tool Mapping

工具映射

Group	Tool ( `jsonrpc: call.method` )
Main account internal transfer	`cex_wallet_create_transfer`

分组	工具（ `jsonrpc: call.method` ）
主账户内部转账	`cex_wallet_create_transfer`

Case Index

场景索引

Case	Scenario	Action
case1	All four elements present	Show Transfer Draft → confirm → call API → Transfer Result Report
case2	Currency missing	Auto-complete currency by target account → same as case1
case3	Transfer completed (API success)	Output Transfer Result Report + product suggestion
case4	Insufficient balance	Pre-check fails; no API call; show shortfall and suggest deposit/adjust
case5	Missing from/to or ambiguous intent	Show missing-info card; do not call API
case6	Account mode conflict (e.g. trading account → USDT perpetual not allowed)	Explain and suggest alternative path
case7	Currency vs To mismatch (e.g. USDT to BTC perpetual)	Auto-correct or prompt correction → then case1
case8	Amount missing	Ask for amount; after user provides, proceed to case1/case2
case9	User cancels or declines after draft	Acknowledge; do not call API
case10	Confirmation ambiguous or stale	Re-present draft; ask for explicit "Confirm" / "Yes"; do not execute
case11	Rate limit / service error	Do not retry blindly; prompt retry later or use web UI

场景	触发条件	操作
场景1	四大要素齐全	展示转账草稿 → 等待确认 → 调用API → 展示转账结果报告
场景2	币种缺失	按目标账户自动补全币种 → 按场景1处理
场景3	转账完成（API调用成功）	输出转账结果报告 + 产品使用建议
场景4	余额不足	前置检查失败；不调用API；展示差额并建议充值或调整金额
场景5	转出/转入账户缺失或意图模糊	展示信息缺失提示卡片；不调用API
场景6	账户模式冲突（例如交易账户→USDT永续合约不被允许）	说明原因并建议替代方案
场景7	币种与转入账户不匹配（例如USDT转入BTC永续合约）	自动修正或提示用户修正 → 按场景1处理
场景8	金额缺失	询问用户金额；用户提供后，按场景1/场景2处理
场景9	用户在草稿展示后取消或拒绝	确认取消；不调用API
场景10	确认信息模糊或失效	重新展示草稿；要求用户明确回复“确认”/“是”；不执行转账
场景11	调用频率超限 / 服务错误	不盲目重试；提示用户稍后重试或使用网页端操作

Transfer Draft (Mandatory before execution)

转账草稿（执行前必填）

Before calling

cex_wallet_create_transfer

, output a Transfer Draft and wait for explicit confirmation in the immediately following user turn.

Draft contents

```
from
```
(account name)
```
to
```
(account name)
```
currency
```
```
amount
```
If applicable:
```
settle
```
(for futures/delivery),
```
currency_pair
```
(for margin)

Confirmation rule

Treat confirmation as single-use. If user changes amount, currency, or direction, show a new draft and re-confirm.
If user does not clearly confirm (e.g. "Confirm", "Yes", "Proceed"), do not execute (case10).

调用

cex_wallet_create_transfer

前，必须输出转账草稿，并等待用户在下一轮对话中明确确认。

草稿内容

```
from
```
（转出账户名称）
```
to
```
（转入账户名称）
```
currency
```
（币种）
```
amount
```
（金额）
若适用：
```
settle
```
（针对永续/交割合约）、
```
currency_pair
```
（针对保证金账户）

确认规则

确认仅单次有效。若用户修改金额、币种或转账方向，需展示新的草稿并重新确认。
若用户未明确确认（例如仅回复“确认”“是”“继续”之外的内容），不得执行转账（见场景10）。

Transfer Result Report (After successful API call)

转账结果报告（API调用成功后）

Confirm success: e.g. "Transfer successful. {amount} {currency} has arrived in your {to account name}."
Optionally suggest next step by destination: Spot → spot trading; USDT perpetual → USDT-margined perpetual; etc.
Mention transfer history: e.g. transfer/historyV2 or equivalent MCP tool.

确认成功：例如“转账成功。{amount} {currency}已转入您的{转入账户名称}。”
可选：根据转入账户类型提供下一步建议：现货账户→现货交易；USDT永续合约→USDT本位永续合约交易；等等。
提及转账历史查询：例如transfer/historyV2或对应的MCP工具。

Case Logic and Output

场景逻辑与输出

case1: All four elements present

场景1：四大要素齐全

Trigger
"Transfer 100 USDT from my spot account to perpetual futures account" / "Transfer 1000 USDT from spot to USDT-margined futures" / "Transfer 0.5 BTC from coin-margined to spot"

Steps

Resolve
```
from
```
,
```
to
```
,
```
currency
```
,
```
amount
```
; add
```
settle
```
or
```
currency_pair
```
if needed.
Pre-check: fetch source balance; if balance < amount → case4.
Output Transfer Draft.
Wait for explicit confirmation.
Call
```
cex_wallet_create_transfer
```
.
Output Transfer Result Report (case3).

Request mapping

Intent	API parameter	Values
Source account	`from`	spot \| margin \| futures \| delivery \| options
Target account	`to`	spot \| margin \| futures \| delivery \| options
Currency	`currency`	USDT, BTC, etc.
Amount	`amount`	String, > 0, up to 8 decimals
Margin pair	`currency_pair`	Required if from/to is margin, e.g. BTC_USDT
Settlement	`settle`	Required if from/to is futures or delivery: usdt \| btc

触发语句
“把我的现货账户里的100 USDT转到永续合约账户” / “划转1000 USDT从现货到USDT本位合约” / “把0.5 BTC从币本位合约转到现货”

步骤

解析
```
from
```
、
```
to
```
、
```
currency
```
、
```
amount
```
；若需要，补充
```
settle
```
或
```
currency_pair
```
。
前置检查：查询转出账户余额；若余额 < 转账金额 → 按场景4处理。
输出转账草稿。
等待用户明确确认。
调用
```
cex_wallet_create_transfer
```
。
输出转账结果报告（场景3）。

请求参数映射

意图	API参数	可选值
转出账户	`from`	spot \| margin \| futures \| delivery \| options
转入账户	`to`	spot \| margin \| futures \| delivery \| options
币种	`currency`	USDT、BTC等
金额	`amount`	字符串格式，大于0，最多保留8位小数
保证金交易对	`currency_pair`	当转出/转入账户为margin时必填，例如BTC_USDT
结算类型	`settle`	当转出/转入账户为futures或delivery时必填：usdt \| btc

case2: Currency missing, auto-complete

场景2：币种缺失，自动补全

Trigger
"Transfer 100 to my USDT-margined account" / "Transfer 500 to futures" / "Transfer 1000 to perpetual"

Logic
Set

currency

by target account:

Target account	Default currency
USDT perpetual (futures settle=usdt)	USDT
BTC perpetual (futures settle=btc)	BTC
TradFi	USDT
Delivery	USDT
Options	USDT
Spot / margin	Infer from context or ask

Steps
Same as case1 after

currency

is set.

Output (draft)
"Detected transfer of {amount} to {to account name}. Based on account type, default currency is {currency}. Please confirm."

触发语句
“转100到我的USDT本位账户” / “转500到合约账户” / “转1000到永续合约”

逻辑
根据转入账户类型设置

currency

：

转入账户	默认币种
USDT永续合约（futures settle=usdt）	USDT
BTC永续合约（futures settle=btc）	BTC
传统金融账户	USDT
交割合约	USDT
期权账户	USDT
现货 / 保证金账户	从上下文推断或询问用户

步骤
补全币种后，按场景1处理。

草稿输出
“检测到您要划转{amount}到{转入账户名称}。根据账户类型，默认币种为{currency}。请确认。”

case3: Transfer completed (API success)

场景3：转账完成（API调用成功）

Trigger
User confirmed;

cex_wallet_create_transfer

returned success.

Output

"Transfer successful. {amount} {currency} has arrived in your {to account name}."
Optional: product suggestion by destination (spot / USDT perpetual / BTC perpetual / delivery / margin / TradFi / options).
"Transfer history: transfer/historyV2" (or equivalent).

触发条件
用户已确认；

cex_wallet_create_transfer

返回成功。

输出内容

“转账成功。{amount} {currency}已转入您的{转入账户名称}。”
可选：根据转入账户类型提供产品使用建议（现货 / USDT永续合约 / BTC永续合约 / 交割合约 / 保证金 / 传统金融 / 期权）。
“转账历史查询：transfer/historyV2”（或对应工具）。

case4: Insufficient balance

场景4：余额不足

Trigger
Pre-check: source available balance < transfer amount.

Action
Do not call transfer API.

Output
"Your {from account name} has insufficient balance (available: {available} {currency}). Please adjust the amount or deposit first."

触发条件
前置检查：转出账户可用余额 < 转账金额。

操作
不得调用转账API。

输出内容
“您的{转出账户名称}余额不足（可用余额：{available} {currency}）。请调整转账金额或先充值。”

case5: Missing from/to or ambiguous intent

场景5：转出/转入账户缺失或意图模糊

Trigger
"Contract is about to be liquidated, transfer some funds for margin" / "Top up my futures margin" / "How do I adjust account funds"

Logic

If missing ≥ 2 of from, to, currency, amount: show missing-info card and ask user to provide.
Defaults when only one side is clear:
- Unified/trading account advanced mode: default from = Trading account, to = BTC perpetual.
- Classic: default from = Spot, to = USDT perpetual.
Do not call API until four elements are clear.

Output
"I can help with margin top-up. Please specify: from account, to account, and currency (and amount if you know it)."

触发语句
“合约即将爆仓，转点资金到保证金账户” / “给我的合约保证金补仓” / “怎么调整账户资金”

逻辑

若from、to、currency、amount中缺失≥2项：展示信息缺失提示卡片并请用户补充。
仅明确一方时的默认值：
- 统一交易账户/交易账户高级模式：默认转出账户=交易账户，转入账户=BTC永续合约。
- 经典模式：默认转出账户=现货账户，转入账户=USDT永续合约。
四大要素明确前不得调用API。

输出内容
“我可以帮您进行保证金补仓。请提供：转出账户、转入账户、币种（若知道金额也请告知）。”

case6: Account mode conflict

场景6：账户模式冲突

Trigger
User in trading account advanced mode asks to transfer to USDT perpetual. In this mode, direct transfer to USDT perpetual may be disallowed (path not available).

Output
"You are in trading account mode; direct transfer to USDT perpetual is not available. You can transfer to BTC perpetual (coin-margined) instead, or adjust account mode on the web."

触发条件
用户处于交易账户高级模式，要求转账到USDT永续合约。该模式下可能不允许直接转账到USDT永续合约（无对应路径）。

输出内容
“您当前处于交易账户模式；无法直接转账到USDT永续合约。您可以选择转账到BTC永续合约（币本位），或通过网页端调整账户模式。”

case7: Currency vs To account mismatch

场景7：币种与转入账户不匹配

Trigger
"Transfer some USDT to my BTC perpetual account"

Logic
BTC perpetual settles in BTC; USDT is inconsistent.

Option A: Correct to BTC amount (if user intent allows).
Option B: Explain that BTC perpetual uses BTC; suggest transferring BTC or using USDT perpetual for USDT.
If user confirms a corrected draft (e.g. spot → BTC perpetual with BTC), proceed as case1.

Output
"BTC perpetual uses BTC settlement. I've corrected the transfer to use BTC (or: please specify amount in BTC). Please confirm." Or: "For USDT, use USDT perpetual account instead."

触发语句
“转一些USDT到我的BTC永续合约账户”

逻辑
BTC永续合约以BTC结算；USDT与该账户不匹配。

选项A：若用户意图允许，修正为BTC金额。
选项B：说明BTC永续合约使用BTC结算，建议用户划转BTC或使用USDT永续合约账户接收USDT。
若用户确认修正后的草稿（例如现货→BTC永续合约，币种为BTC），按场景1处理。

输出内容
“BTC永续合约采用BTC结算。我已将转账币种修正为BTC（或：请告知BTC转账金额）。请确认。” 或：“若要划转USDT，请使用USDT永续合约账户。”

case8: Amount missing

场景8：金额缺失

Trigger
"Transfer USDT from spot to futures" / "Move my USDT to perpetual" (no amount).

Action
Ask: "How much {currency} do you want to transfer from {from} to {to}?" After user provides amount, resolve currency if still missing (case2), then proceed to case1.

触发语句
“把USDT从现货转到合约” / “把我的USDT转到永续合约”（未提及金额）

操作
询问用户：“您要从{转出账户}划转多少{币种}到{转入账户}？” 用户提供金额后，若币种仍缺失则按场景2处理，之后按场景1处理。

case9: User cancels or declines

场景9：用户取消或拒绝

Trigger
After Transfer Draft, user says "No" / "Cancel" / "Don't do it" / "Never mind".

Action
Do not call API. Acknowledge: "Transfer cancelled. No changes made."

触发条件
展示转账草稿后，用户回复“不” / “取消” / “别转了” / “算了”。

操作
不得调用API。回复：“转账已取消。未进行任何操作。”

case10: Confirmation ambiguous or stale

场景10：确认信息模糊或失效

Trigger
After draft, user replies with something other than clear confirmation (e.g. new question, different amount, or vague "ok" in a long thread).

Action
Do not execute. Re-present the Transfer Draft and say: "To execute this transfer, please confirm explicitly (e.g. 'Confirm' or 'Yes')."

触发条件
展示草稿后，用户回复非明确确认内容（例如新问题、修改金额，或在长对话中模糊回复“好的”）。

操作
不得执行转账。重新展示转账草稿并回复：“如需执行此转账，请明确确认（例如回复‘确认’或‘是’）。”

case11: Rate limit or service error

场景11：调用频率超限或服务错误

Trigger
API returns

TOO_MANY_REQUESTS

or server/network error.

Action
Do not retry automatically in the same turn.
Output
"Request failed (rate limit / service error). Please try again later or use the web app to transfer."

触发条件
API返回

TOO_MANY_REQUESTS

或服务器/网络错误。

操作
同一轮对话中不自动重试。
输出内容
“请求失败（调用频率超限 / 服务错误）。请稍后重试或通过网页端进行转账。”

Exception Flow Summary

异常流程汇总

Exception	Handling	Block execution
Not logged in	Prompt to log in	Yes
Insufficient balance	Show shortfall + suggest deposit/adjust (case4)	Yes
Invalid account path (e.g. from/to not allowed)	Guide user to correct (case5/case6)	No, guide
User cancel / decline	Acknowledge (case9)	Yes
Confirmation missing/ambiguous	Re-present draft, ask explicit confirm (case10)	Yes
Rate limit / service error	Retry later or use web (case11)	Yes
Risk control / quota	Show clear reason	Yes

异常情况	处理方式	是否阻止执行
未登录	提示用户登录	是
余额不足	展示差额并建议充值或调整金额（场景4）	是
无效账户路径（例如转出/转入账户不允许）	引导用户修正（场景5/场景6）	否，仅引导
用户取消/拒绝	确认取消（场景9）	是
确认信息缺失/模糊	重新展示草稿，要求明确确认（场景10）	是
调用频率超限/服务错误	建议稍后重试或使用网页端（场景11）	是
风控/额度限制	展示明确原因	是

API Reference

API参考

Request body example

请求体示例

json

{
  "currency": "USDT",
  "from": "spot",
  "to": "futures",
  "amount": "100",
  "currency_pair": "",
  "settle": "usdt"
}

json

{
  "currency": "USDT",
  "from": "spot",
  "to": "futures",
  "amount": "100",
  "currency_pair": "",
  "settle": "usdt"
}

from / to → product name

from / to → 产品名称映射

API value	Product name
spot	Spot
margin	Isolated margin
futures	Perpetual (use `settle` )
delivery	Delivery
options	Options

API值	产品名称
spot	现货
margin	逐仓保证金
futures	永续合约（需结合 `settle` 值）
delivery	交割合约
options	期权

settle (futures / delivery)

settle（永续/交割合约）

settle	Account
usdt	USDT perpetual
btc	BTC perpetual

settle值	对应账户
usdt	USDT永续合约
btc	BTC永续合约

currency_pair (margin)

currency_pair（保证金账户）

Required when

from

to

margin

; e.g.

BTC_USDT

当

from

或

to

为

margin

时必填；例如

BTC_USDT

。

Transfer History Query

转账历史查询

After a transfer, user may ask for history. By account type:

Account	Query tool (if MCP provides)	Notes
Spot	`cex_spot_list_spot_account_book`	currency, time, limit
Perpetual	`cex_fx_list_futures_account_book`	settle, type=dnw
Delivery	`cex_delivery_list_delivery_account_book`	settle, type=dnw
Margin	`cex_margin_list_margin_account_book`	currency_pair, time, limit
Options	`cex_options_list_options_account_book`	per MCP docs

REST: Delivery GET /delivery/{settle}/account_book?type=dnw; Perpetual GET /futures/{settle}/account_book?type=dnw; Margin GET /margin/account_book.

转账完成后，用户可能询问历史记录。按账户类型查询：

账户类型	查询工具（若MCP提供）	说明
现货	`cex_spot_list_spot_account_book`	支持按币种、时间、条数筛选
永续合约	`cex_fx_list_futures_account_book`	需指定settle，type=dnw
交割合约	`cex_delivery_list_delivery_account_book`	需指定settle，type=dnw
保证金	`cex_margin_list_margin_account_book`	支持按交易对、时间、条数筛选
期权	`cex_options_list_options_account_book`	参考MCP文档

REST接口：交割合约 GET /delivery/{settle}/account_book?type=dnw；永续合约 GET /futures/{settle}/account_book?type=dnw；保证金账户 GET /margin/account_book。

Error Codes

错误码

Code	Meaning
BALANCE_NOT_ENOUGH	Insufficient balance; do not retry same amount
TOO_MANY_REQUESTS	Rate limit; prompt retry later (case11)
QUOTA_NOT_ENOUGH	Quota exceeded; show message

错误码	含义
BALANCE_NOT_ENOUGH	余额不足；请勿重试相同金额
TOO_MANY_REQUESTS	调用频率超限；提示用户稍后重试（场景11）
QUOTA_NOT_ENOUGH	额度不足；展示提示信息

Execution Rules (Summary)

执行规则汇总

Single endpoint: Internal transfer only via
```
POST /wallet/transfers
```
(
```
cex_wallet_create_transfer
```
). No main-sub in Phase 1.
Always show Transfer Draft with from, to, currency, amount (and settle/currency_pair if needed).
Require explicit confirmation in the next user turn; single-use; re-confirm if params change.
Pre-check balance before calling API; on insufficient balance, follow case4 and do not call.
Conditional params:
```
currency_pair
```
for margin;
```
settle
```
for futures/delivery.
Missing currency: case2 default table. Missing amount: case8 ask.
Account mode / currency mismatch: case6 and case7; resolve or correct before executing.
On cancel or ambiguous confirm: case9/case10; do not execute.

统一端点：仅通过
```
POST /wallet/transfers
```
（
```
cex_wallet_create_transfer
```
）执行内部转账。第一阶段不支持主账户与子账户间转账。
始终展示转账草稿：需包含转出账户、转入账户、币种、金额（若需要，包含settle/currency_pair）。
需明确确认：等待用户下一轮对话中的明确确认；确认仅单次有效；若参数变更，需重新展示草稿并确认。
前置余额检查：调用API前预先检查转出账户余额；若余额不足，按场景4处理，不调用API。
条件必填参数：保证金账户需
```
currency_pair
```
；永续/交割合约需
```
settle
```
。
缺失信息处理：币种缺失→场景2默认补全；金额缺失→场景8询问用户。
账户模式/币种不匹配：场景6和场景7；执行前需解决或修正问题。
取消或模糊确认：场景9/场景10；不执行转账。