gate-exchange-flashswap

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 Flash Swap

## 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 [gate-runtime-rules.md](https://github.com/gate/gate-skills/blob/master/skills/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.

## Skill Dependencies


### gate-cli commands used

**Query Operations (Read-only)**

- `gate-cli cex flash-swap order`
- `gate-cli cex flash-swap pairs`
- `gate-cli cex flash-swap orders`
- `gate-cli cex flash-swap preview-many-to-one`
- `gate-cli cex flash-swap preview-one-to-many`
- `gate-cli cex flash-swap preview-v1`

**Execution Operations (Write)**

- `gate-cli cex flash-swap create-many-to-one`
- `gate-cli cex flash-swap create-one-to-many`
- `gate-cli cex flash-swap create-v1`

### 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.
- **Permissions:** Fc: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 flashswap workflow.

- `SKILL.md` keeps routing and scenario boundaries.
- `references/gate-cli.md` is the authoritative `gate-cli` execution contract for preview/create sequencing, confirmation gates, and degraded handling.

## Trigger Conditions

This Skill is activated when the user's request matches any of the following:
- Wants to swap/convert/exchange one cryptocurrency for another
- Wants to buy multiple cryptocurrencies at once using one currency (e.g. "buy 1u BTC, 2u ETH")
- Wants to sell multiple cryptocurrencies into one target currency (e.g. "sell 1 BTC, 2 ETH for USDT")
- Asks which currencies support flash swap
- Asks about minimum/maximum swap amounts or limits
- Requests flash swap order history or specific order details
- Uses keywords: "flash swap", "convert", "quick exchange", "swap", "instant swap"

## Quick Start

Common usage examples:

1. **One-to-one swap**: "Sell 1 BTC for USDT"
2. **Buy multiple coins**: "Buy 1u BTC, 2u ETH, 3u SOL"
3. **Sell multiple coins**: "Sell 1 BTC, 2 ETH, 3 SOL for USDT"
4. **Check pairs**: "Show me flash swap supported pairs"
5. **Order history**: "Show me my flash swap orders"

## Domain Knowledge

**Flash Swap** is a quick crypto exchange service provided by Gate. Users can instantly convert one cryptocurrency to another at the real-time exchange rate without placing orders and waiting for matching.

**Swap Modes**:
- **One-to-One**: Swap a single currency for another single currency (e.g. BTC → USDT)
- **One-to-Many**: Swap one currency into multiple target currencies (e.g. USDT → BTC + ETH + SOL)
- **Many-to-One**: Swap multiple currencies into one target currency (e.g. BTC + ETH + SOL → USDT)

**Key Concepts**:
- **sell_asset / buy_asset**: The currency symbols for the sell side and buy side
- **sell_amount / buy_amount**: Specify one of them; the API calculates the other. For one-to-many, use `sell_amount` per target; for many-to-one, use `sell_amount` per source
- **quote_id**: A unique identifier returned by the preview API, required for order creation. The exact validity period is indicated by `valid_timestamp` in the response. Always check this field — do not assume a fixed duration
- **Order Status**: `1` = success, `2` = failed

**API Field Naming**:

- `gate-cli cex flash-swap pairs` returns **snake_case** fields: `sell_min_amount`, `sell_max_amount`, `buy_min_amount`, `buy_max_amount`, `currency_pair`, `sell_currency`, `buy_currency`
- `gate-cli cex flash-swap preview-v1` and multi-currency preview APIs return **camelCase** fields in some environments (e.g. `sellMinAmount`). Always read the actual field names from the response — do not assume a fixed naming convention
- `gate-cli cex flash-swap orders` and `gate-cli cex flash-swap order` return snake_case: `sell_currency`, `buy_currency`, `sell_amount`, `buy_amount`, `create_time`

**Data type note**: `order_id` is returned as a **string** in API responses. `quote_id` is also a string.

**MCP Tool Inventory**:

| Tool | Type | Description |
|------|------|-------------|
| `gate-cli cex flash-swap preview-v1` | Preview | One-to-one swap quote preview |
| `gate-cli cex flash-swap create-v1` | Create | One-to-one swap order creation (requires `quote_id`) |
| `gate-cli cex flash-swap preview-one-to-many` | Preview | One-to-many swap quote preview |
| `gate-cli cex flash-swap create-one-to-many` | Create | One-to-many swap order creation |
| `gate-cli cex flash-swap preview-many-to-one` | Preview | Many-to-one swap quote preview |
| `gate-cli cex flash-swap create-many-to-one` | Create | Many-to-one swap order creation |
| `gate-cli cex flash-swap pairs` | Query | List supported flash swap pairs and limits |
| `gate-cli cex flash-swap orders` | Query | Query flash swap order history |
| `gate-cli cex flash-swap order` | Query | Query single flash swap order by ID |

## Workflow

### Step 1: Identify User Intent

Analyze the user's request to determine which flash swap operation to perform.

**Intent classification**:

| User Intent | Mode | Preview Tool | Create Tool |
|-------------|------|-------------|-------------|
| Swap one coin for another (e.g. "sell 1 BTC for USDT") | one-to-one | `gate-cli cex flash-swap preview-v1` | `gate-cli cex flash-swap create-v1` |
| One-click swap without separate confirmation (e.g. "directly swap 100 USDT to GT") | one-to-one-auto | `gate-cli cex flash-swap preview-v1` → `gate-cli cex flash-swap create-v1` | — |
| Buy multiple coins with one currency (e.g. "buy 1u BTC, 2u ETH") | one-to-many | `gate-cli cex flash-swap preview-one-to-many` | `gate-cli cex flash-swap create-one-to-many` |
| Split one currency into multip