gate-exchange-transfer

What this skill does

### 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`](https://github.com/gate/gate-skills/blob/master/skills/exchange-runtime-rules.md) §4 (or [`gate-runtime-rules.md`](https://github.com/gate/gate-skills/blob/master/skills/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 **`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](https://github.com/gate/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.
- 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 `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`](./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`](./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

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

---

## 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 `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-marg