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

Gate Exchange Transfer (Internal Transfer)

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.

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.

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

Public API (Phase 1)

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

Tool Mapping

Group	Tool ( `jsonrpc: call.method` )
Main account internal transfer	`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

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

Transfer Result Report (After successful API call)

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.

Case Logic and Output

case1: All four elements present

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

case2: Currency missing, auto-complete

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

case3: Transfer completed (API success)

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

case4: Insufficient balance

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

case5: Missing from/to or ambiguous intent

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

case6: Account mode conflict

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

case7: Currency vs To account mismatch

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

case8: Amount missing

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.

case9: User cancels or declines

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

case10: Confirmation ambiguous or stale

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

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

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

API Reference

Request body example

json

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

from / to → product name

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

settle (futures / delivery)

settle	Account
usdt	USDT perpetual
btc	BTC perpetual

currency_pair (margin)

Required when

from

to

margin

; e.g.

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.

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

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.

gate-exchange-transfer

NPX Install

Tags

SKILL.md Content