Imported from Tsin418/crypto-research-agent (.agents/skills/gate-exchange-flashswap/SKILL.md). Install upstream with npx skills add Tsin418/crypto-research-agent --skill gate-exchange-flashswap. Copyright stays with the author.

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

• 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).
• 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 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, 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:

Workflow

Step 1: Identify User Intent

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

Intent classification:

Key data to extract:

• intent: "one_to_one" / "one_to_one_auto" / "one_to_many" / "one_to_many_split" / "one_to_many_buy" / "many_to_one" / "many_to_one_all" / "many_to_one_preview" / "list_pairs" / "list_orders" / "get_order" / "verify_order"
• sell_asset / buy_asset: currencies involved
• sell_amount / buy_amount: amounts specified by the user

Step 2: Pre-validate Swap Amount (before any preview)

Before calling the preview API, validate the user's amount against the pair's min/max limits to avoid unnecessary API calls.

Call gate-cli cex flash-swap pairs with:

• currency: the sell_asset or buy_asset from the user's request

Key data to extract:

• sell_min_amount / sell_max_amount: allowed range for the sell side
• buy_min_amount / buy_max_amount: allowed range for the buy side

Validation logic:

• If the user's sell_amount < sell_min_amount, inform them the amount is below the minimum and do NOT proceed to preview
• If the user's sell_amount > sell_max_amount, inform them the amount exceeds the maximum
• If the pair is not found, the currency is not supported for flash swap

Skip this step if the user explicitly requests "one-click" or "direct" swap to minimize latency.

Step 3: Preview — One-to-One Swap (if intent = one_to_one or one_to_one_auto)

Call gate-cli cex flash-swap preview-v1 with:

• sell_asset (required, string): asset to sell, e.g. "BTC"
• buy_asset (required, string): asset to buy, e.g. "USDT"
• sell_amount (string): amount to sell. Choose one between sell_amount and buy_amount
• buy_amount (string): amount to buy. Choose one between sell_amount and buy_amount

Key data to extract:

• quote_id: required for creating the order
• sell_asset / sell_amount: confirmed sell side
• buy_asset / buy_amount: calculated buy side
• price: exchange rate
• valid_timestamp: quote expiry time

For one_to_one intent: Present the preview to the user and ask for confirmation before proceeding to create.

For one_to_one_auto intent: The user has pre-authorized the swap by explicitly requesting "direct" or "one-click" execution. Skip the separate confirmation prompt and immediately proceed to Step 4. This is compliant with the Safety Rules as the user's direct request serves as confirmation. However: if the preview returns any error (code != 0), do NOT proceed to Step 4 — report the error to the user immediately.

Step 4: Create — One-to-One Swap (after user confirms Step 3, or auto for one_to_one_auto)

Pre-condition: Step 3 must have returned code == 0 with a valid quote_id. If Step 3 failed (any code != 0), do NOT execute this step. Never fabricate a quote_id.

Call gate-cli cex flash-swap create-v1 with body JSON string:

• quote_id (required, string): from preview response — must be the actual value returned by the API
• sell_asset (required, string): asset to sell
• sell_amount (required, string): amount to sell
• buy_asset (required, string): asset to buy
• buy_amount (required, string): amount to buy

Key data to extract:

• id: created order ID
• status: 1 = success, 2 = failed
• sell_asset / sell_amount / buy_asset / buy_amount: confirmed amounts
• price: executed rate
• create_time: order creation timestamp
• error.code / error.message: check for errors even when HTTP status is 200

Order result verification: After creating, check the status field:

• If status == 1: Inform the user the swap succeeded, show the final buy_amount received
• If status == 2: Inform the user the swap failed, suggest re-previewing and trying again
• If error.code != 0: Report the specific error message to the user

Step 5: Preview — One-to-Many Swap (if intent = one_to_many, one_to_many_split, or one_to_many_buy)

For one_to_many_split: The user specifies a total amount and a distribution ratio (e.g. "split 1000 USDT, half BTC half ETH"). Calculate the per-target sell_amount before calling the API.

For one_to_many_buy: The user specifies target buy_amount per currency (e.g. "buy 0.1 BTC and 1 ETH"). Use the buy_amount field instead of sell_amount in the params array to let the API calculate the required sell amount.

Call gate-cli cex flash-swap preview-one-to-many with body JSON string:

• params (required, array): each element contains:
• sell_asset (required, string): source currency (same for all, e.g. "USDT")
• sell_amount (string): amount of source currency to spend on this target
• buy_asset (required, string): target currency (e.g. "BTC", "ETH")
• buy_amount (string): alternative to sell_amount

Key data to extract:

• orders[]: array of preview results, each containing quote_id, sell_amount, buy_amount, price, and error
• total_consume_amount: total amount of source currency consumed
• Check each order's error.code — if non-zero, that item failed to get a quote

Present the full preview table and highlight any failed items. Ask for confirmation.

Step 6: Create — One-to-Many Swap (after user confirms Step 5)

Important: Exclude any items that failed in preview (where error.code != 0 or quote_id is missing). Call gate-cli cex flash-swap create-one-to-many with body JSON string:

• params (required, array): each element contains:
• sell_asset (required, string): source currency
• sell_amount (required, string): amount to sell
• buy_asset (required, string): target currency
• buy_amount (required, string): amount to buy (from preview)
• quote_id (string): from preview response

Key data to extract:

• orders[]: array of created orders, each with id, status, error
• total_consume_amount: actual total consumed
• Check each order's error.code for per-item failures

Step 7: Preview — Many-to-One Swap (if intent = many_to_one, many_to_one_all, or many_to_one_preview)

For many_to_one_all: The user wants to consolidate all holdings of specified currencies. Before previewing, query the user's spot account balances to determine the actual amount for each currency. Filter out currencies whose balance is below the flash swap minimum amount (sell_min_amount from gate-cli cex flash-swap pairs). Call gate-cli cex flash-swap preview-many-to-one with body JSON string:

• params (required, array): each element contains:
• sell_asset (required, string): source currency (e.g. "BTC", "ETH")
• sell_amount (string): amount to sell
• buy_asset (required, string): target currency (same for all, e.g. "USDT")
• buy_amount (string): alternative to sell_amount

Key data to extract:

• orders[]: array of preview results with quote_id, sell_amount, buy_amount, price, error
• total_acquire_amount: total amount of target currency to receive
• Check each order's error.code — non-zero means that item failed

Present the full preview table and highlight any failed items.

For many_to_one_preview: Present the total expected buy_amount (sum of all successful items) and do NOT proceed to create. Inform the user this is a preview only.

For many_to_one and many_to_one_all: Ask for user confirmation before proceeding to create.

Step 8: Create — Many-to-One Swap (after user confirms Step 7)

Important: Exclude any items that failed in preview. Including a failed item (e.g. buy_amount: "0") will cause the entire request to be rejected with code: 4.

Call gate-cli cex flash-swap create-many-to-one with body JSON string:

• params (required, array): each element contains:
• sell_asset (required, string): source currency
• sell_amount (required, string): amount to sell
• buy_asset (required, string): target currency
• buy_amount (required, string): amount to buy (from preview)
• quote_id (string): from preview response

Key data to extract:

• orders[]: array of created orders with id, status, error
• total_acquire_amount: actual total received

Step 9: Query Flash Swap Pairs (if intent = list_pairs)

Call gate-cli cex flash-swap pairs with:

• currency (optional, string): filter by currency symbol
• limit (optional, number): max items returned (default 1000)
• page (optional, number): page number

Large result set warning: Without a currency filter, this may return thousands of rows. Summarize the total count, show a sample of 20 pairs, and suggest filtering by currency.

Key data to extract:

• items[]: list of currency pairs with currency_pair, sell_currency, buy_currency, sell_min_amount, sell_max_amount, buy_min_amount, buy_max_amount

Step 10: Query Flash Swap Order History (if intent = list_orders)

Before calling, validate the status parameter if provided. Only 1 (success) and 2 (failed) are valid.

Call gate-cli cex flash-swap orders with:

• status (optional, number): 1 = success, 2 = failed
• sell_currency (optional, string): filter by sell currency
• buy_currency (optional, string): filter by buy currency
• limit (optional, number): max records
• page (optional, number): page number
• reverse (optional, boolean): true for newest first (default)

Key data to extract:

• Order list with id, sell_currency, buy_currency, sell_amount, buy_amount, price, status, create_time

Step 11: Query Single Order (if intent = get_order or verify_order)

Call gate-cli cex flash-swap order with:

• order_id (required, number): the order ID to query

If the API returns 404, inform the user the order was not found.

For verify_order: After retrieving the order, check status:

• If status == 1: Confirm the swap succeeded, show the final buy_amount actually received
• If status == 2: Inform the user the swap failed, suggest re-previewing and placing a new order

Key data to extract:

• Full order details: id, sell_currency, buy_currency, sell_amount, buy_amount, price, status, create_time

Step 12: Format and Present Results

Format results using the appropriate Report Template. For swap operations, always show:

1. Preview summary table with quote details
2. After creation, show order IDs, status, and any per-item errors

Error Handling

Safety Rules

• NEVER fabricate results: If any API call returns an error (code != 0), you MUST report the actual error to the user. NEVER fabricate a successful response, fake order ID, fake quote_id, or fake transaction result. This is the most critical safety rule
• NEVER proceed after preview failure: If the preview API returns any error (code != 0, including code -2 for region restriction), you MUST stop immediately. Do NOT call the create API. Do NOT invent a quote_id (e.g. "AUTO-GT-001"). Report the error honestly
• Always preview before creating: Every swap must go through the preview step first. For standard flows, show the quote to the user and wait for explicit confirmation before calling the create API. For one_to_one_auto mode only: the user has explicitly requested a direct swap (e.g. "directly swap", "one-click"), which counts as pre-authorized confirmation — proceed to create immediately after preview without a separate confirmation prompt
• No write operations without confirmation: Never call any create/order API unless (a) the user has explicitly confirmed the preview result, or (b) the user explicitly requested a one-click/direct swap. Query operations (list pairs, list orders, get order) do not require confirmation
• Exclude failed preview items: When creating multi-currency orders, only include items that succeeded in preview (error.code == 0)
• Do not expose sensitive info: Never output API Key, Secret, or authentication tokens
• Display amounts as-is: Do not round or modify amounts from API responses
• Warn on large amounts: If the total swap amount exceeds 10,000 USDT equivalent, remind the user to double-check
• Stale confirmation handling: If the user confirms a previous preview, check whether the current time has exceeded the valid_timestamp from that preview response. If expired, automatically re-preview to get a fresh quote before creating

Judgment Logic Summary

Report Template

Timestamp format: All {timestamp} placeholders use ISO 8601 format: YYYY-MM-DD HH:mm:ss UTC.

One-to-One Preview Report

## Flash Swap Preview (One-to-One)

**Quote ID**: {quote_id}
**Valid Until**: {valid_timestamp}

| Sell | Amount | Buy | Amount | Rate |
|------|--------|-----|--------|------|
| {sell_asset} | {sell_amount} | {buy_asset} | {buy_amount} | {price} |

Proceed with this swap? (Yes/No)

One-to-One Order Report

## Flash Swap Order Created

**Order ID**: {id}
**Status**: {status_text}
**Created At**: {create_time}

| Sell | Amount | Buy | Amount | Rate |
|------|--------|-----|--------|------|
| {sell_asset} | {sell_amount} | {buy_asset} | {buy_amount} | {price} |

Multi-Currency Preview Report (One-to-Many / Many-to-One)

## Flash Swap Preview ({mode})

**Total {direction}**: {total_amount} {currency}

| # | Sell | Sell Amount | Buy | Buy Amount | Rate | Quote ID | Status |
|---|------|-------------|-----|------------|------|----------|--------|
| {n} | {sell_asset} | {sell_amount} | {buy_asset} | {buy_amount} | {price} | {quote_id} | {status} |

{failed_count} item(s) failed to get a quote and will be excluded from the order.
Proceed with {success_count} successful item(s)? (Yes/No)

Multi-Currency Order Report

## Flash Swap Orders Created ({mode})

**Total {direction}**: {total_amount} {currency}

| # | Order ID | Sell | Sell Amount | Buy | Buy Amount | Status | Error |
|---|----------|------|-------------|-----|------------|--------|-------|
| {n} | {id} | {sell_asset} | {sell_amount} | {buy_asset} | {buy_amount} | {status_text} | {error_message} |

{success_count}/{total_count} orders succeeded.

Pair List Report

## Gate Flash Swap Supported Pairs

**Query Time**: {timestamp}
**Filter**: {currency filter or "None"}

| Pair | Sell Currency | Buy Currency | Sell Min | Sell Max |
|------|---------------|--------------|----------|----------|
| {currency_pair} | {sell_currency} | {buy_currency} | {sell_min_amount} | {sell_max_amount} |

Total: {total} pairs.

Order List Report

## Gate Flash Swap Order History

**Query Time**: {timestamp}
**Filters**: Status={status}, Sell={sell_currency}, Buy={buy_currency}

| Order ID | Sell | Sell Amount | Buy | Buy Amount | Status | Created At |
|----------|------|-------------|-----|------------|--------|------------|
| {id} | {sell_currency} | {sell_amount} | {buy_currency} | {buy_amount} | {status_text} | {create_time} |

Total: {total} records.

Order Detail Report

## Gate Flash Swap Order Details

| Field | Value |
|-------|-------|
| Order ID | {id} |
| Sell Currency | {sell_currency} |
| Sell Amount | {sell_amount} |
| Buy Currency | {buy_currency} |
| Buy Amount | {buy_amount} |
| Exchange Rate | {price} |
| Status | {status_text} |
| Created At | {create_time} |