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 Exchange Transfer (Internal Transfer)

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 ./references/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.

Execute same-UID internal transfers between Gate trading accounts: spot, isolated margin, perpetual, delivery, and options. Single execution endpoint: POST /wallet/transfers (MCP: gate-cli cex wallet transfer create). Scope (Phase 1)

• Supported: internal transfer only (same UID, between account types above).
• Not supported: main-to-sub, sub-to-main, sub-to-sub.

Skill Dependencies

gate-cli commands used

Query Operations (Read-only)

• gate-cli cex delivery account book
• gate-cli cex futures account book
• gate-cli cex margin account book
• gate-cli cex options account book
• gate-cli cex spot account book

Execution Operations (Write)

• gate-cli cex wallet transfer create

Authentication

• Interactive file setup: when GATEAPIKEY and GATEAPISECRET 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 GATEAPIKEY and GATEAPISECRET set on the host, or --api-key / --api-secret where supported — never ask the user to paste secrets into chat.
• API Key Required: Yes
• Permissions: Delivery:Read, Fx:Read, Margin:Read, Options:Read, Spot:Read, Wallet: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 GATECLISETUP_MODE=release).
• Add $HOME/.openclaw/skills/bin to PATH if you invoke gate-cli by name (or the directory where [setup.sh](./setup.sh) installs it).
• Credentials: When GATEAPIKEY and GATEAPISECRET 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 GATEAPIKEY / GATEAPISECRET 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](./references/gate-cli.md), then execute this skill's transfer workflow.

• SKILL.md keeps transfer intent routing and account-type mapping.
• references/gate-cli.md is the authoritative gate-cli execution contract for transfer pre-check, confirmation gate, execution, and ledger verification.

Preconditions

The Four Elements

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

Conditional params

• margin: currencypair required (e.g. BTCUSDT) when from or to is margin.
• futures / delivery: settle required (usdt \| btc) when from or to is futures or delivery.

Public API (Phase 1)

Tool Mapping

Case Index

Transfer Draft (Mandatory before execution)

Before calling gate-cli cex wallet transfer create, 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

1. Resolve from, to, currency, amount; add settle or currency_pair if needed.
2. Pre-check: fetch source balance; if balance < amount → case4.
3. Output Transfer Draft.
4. Wait for explicit confirmation.
5. Call gate-cli cex wallet transfer create.
6. Output Transfer Result Report (case3).

Request mapping

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:

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; gate-cli cex wallet transfer create 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 TOOMANYREQUESTS 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

API Reference

Request body example

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

from / to → product name

settle (futures / delivery)

currency_pair (margin)

Required when from or to is margin; e.g. BTC_USDT.

Transfer History Query

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

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

Error Codes

Execution Rules (Summary)

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