Install
openclaw skills install gate-exchange-flashswapGate Flash Swap skill. Use when the user asks to instantly convert or exchange cryptocurrencies without placing an order book trade. Triggers on 'flash swap'...
openclaw skills install gate-exchange-flashswap⚠️ 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
| MCP Server | Status |
|---|---|
| Gate (main) | ✅ Required |
Query Operations (Read-only)
Execution Operations (Write)
gate-mcp-cursor-installergate-mcp-codex-installergate-mcp-claude-installergate-mcp-openclaw-installerRead and strictly follow references/mcp.md, then execute this skill's flashswap workflow.
SKILL.md keeps routing and scenario boundaries.references/mcp.md is the authoritative MCP execution layer for preview/create sequencing, confirmation gates, and degraded handling.This Skill is activated when the user's request matches any of the following:
Common usage examples:
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:
Key Concepts:
sell_amount per target; for many-to-one, use sell_amount per sourcevalid_timestamp in the response. Always check this field — do not assume a fixed duration1 = success, 2 = failedAPI Field Naming:
cex_fc_list_fc_currency_pairs returns snake_case fields: sell_min_amount, sell_max_amount, buy_min_amount, buy_max_amount, currency_pair, sell_currency, buy_currencycex_fc_preview_fc_order_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 conventioncex_fc_list_fc_orders and cex_fc_get_fc_order return snake_case: sell_currency, buy_currency, sell_amount, buy_amount, create_timeData type note: order_id is returned as a string in API responses. quote_id is also a string.
MCP Tool Inventory:
| Tool | Type | Description |
|---|---|---|
cex_fc_preview_fc_order_v1 | Preview | One-to-one swap quote preview |
cex_fc_create_fc_order_v1 | Create | One-to-one swap order creation (requires quote_id) |
cex_fc_preview_fc_multi_currency_one_to_many_order | Preview | One-to-many swap quote preview |
cex_fc_create_fc_multi_currency_one_to_many_order | Create | One-to-many swap order creation |
cex_fc_preview_fc_multi_currency_many_to_one_order | Preview | Many-to-one swap quote preview |
cex_fc_create_fc_multi_currency_many_to_one_order | Create | Many-to-one swap order creation |
cex_fc_list_fc_currency_pairs | Query | List supported flash swap pairs and limits |
cex_fc_list_fc_orders | Query | Query flash swap order history |
cex_fc_get_fc_order | Query | Query single flash swap order by ID |
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 | cex_fc_preview_fc_order_v1 | cex_fc_create_fc_order_v1 |
| One-click swap without separate confirmation (e.g. "directly swap 100 USDT to GT") | one-to-one-auto | cex_fc_preview_fc_order_v1 → cex_fc_create_fc_order_v1 | — |
| Buy multiple coins with one currency (e.g. "buy 1u BTC, 2u ETH") | one-to-many | cex_fc_preview_fc_multi_currency_one_to_many_order | cex_fc_create_fc_multi_currency_one_to_many_order |
| Split one currency into multiple by ratio (e.g. "split 1000 USDT, half BTC half ETH") | one-to-many-split | cex_fc_preview_fc_multi_currency_one_to_many_order | cex_fc_create_fc_multi_currency_one_to_many_order |
| Buy specific quantities of multiple coins (e.g. "buy 0.1 BTC and 1 ETH with USDT") | one-to-many-buy | cex_fc_preview_fc_multi_currency_one_to_many_order | cex_fc_create_fc_multi_currency_one_to_many_order |
| Sell multiple coins into one currency (e.g. "sell 1 BTC, 2 ETH for USDT") | many-to-one | cex_fc_preview_fc_multi_currency_many_to_one_order | cex_fc_create_fc_multi_currency_many_to_one_order |
| Consolidate all holdings of certain coins into one (e.g. "convert all my BTC, ETH, DOGE to USDT") | many-to-one-all | cex_fc_preview_fc_multi_currency_many_to_one_order | cex_fc_create_fc_multi_currency_many_to_one_order |
| Preview-only for multi-currency (e.g. "how much GT can I get for my BTC and ETH?") | many-to-one-preview | cex_fc_preview_fc_multi_currency_many_to_one_order | — |
| Query supported flash swap pairs | query | cex_fc_list_fc_currency_pairs | — |
| Query flash swap order list | query | cex_fc_list_fc_orders | — |
| Query single flash swap order by ID | query | cex_fc_get_fc_order | — |
| Verify latest order result (e.g. "did my swap succeed?") | verify-order | cex_fc_get_fc_order | — |
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 involvedsell_amount / buy_amount: amounts specified by the userBefore calling the preview API, validate the user's amount against the pair's min/max limits to avoid unnecessary API calls.
Call cex_fc_list_fc_currency_pairs with:
currency: the sell_asset or buy_asset from the user's requestKey data to extract:
sell_min_amount / sell_max_amount: allowed range for the sell sidebuy_min_amount / buy_max_amount: allowed range for the buy sideValidation logic:
sell_amount < sell_min_amount, inform them the amount is below the minimum and do NOT proceed to previewsell_amount > sell_max_amount, inform them the amount exceeds the maximumSkip this step if the user explicitly requests "one-click" or "direct" swap to minimize latency.
Call cex_fc_preview_fc_order_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_amountbuy_amount (string): amount to buy. Choose one between sell_amount and buy_amountKey data to extract:
quote_id: required for creating the ordersell_asset / sell_amount: confirmed sell sidebuy_asset / buy_amount: calculated buy sideprice: exchange ratevalid_timestamp: quote expiry timeFor 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.
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 cex_fc_create_fc_order_v1 with body JSON string:
quote_id (required, string): from preview response — must be the actual value returned by the APIsell_asset (required, string): asset to sellsell_amount (required, string): amount to sellbuy_asset (required, string): asset to buybuy_amount (required, string): amount to buyKey data to extract:
id: created order IDstatus: 1 = success, 2 = failedsell_asset / sell_amount / buy_asset / buy_amount: confirmed amountsprice: executed ratecreate_time: order creation timestamperror.code / error.message: check for errors even when HTTP status is 200Order result verification: After creating, check the status field:
status == 1: Inform the user the swap succeeded, show the final buy_amount receivedstatus == 2: Inform the user the swap failed, suggest re-previewing and trying againerror.code != 0: Report the specific error message to the userFor 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 cex_fc_preview_fc_multi_currency_one_to_many_order 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 targetbuy_asset (required, string): target currency (e.g. "BTC", "ETH")buy_amount (string): alternative to sell_amountKey data to extract:
orders[]: array of preview results, each containing quote_id, sell_amount, buy_amount, price, and errortotal_consume_amount: total amount of source currency consumederror.code — if non-zero, that item failed to get a quotePresent the full preview table and highlight any failed items. Ask for confirmation.
Important: Exclude any items that failed in preview (where error.code != 0 or quote_id is missing).
Call cex_fc_create_fc_multi_currency_one_to_many_order with body JSON string:
params (required, array): each element contains:
sell_asset (required, string): source currencysell_amount (required, string): amount to sellbuy_asset (required, string): target currencybuy_amount (required, string): amount to buy (from preview)quote_id (string): from preview responseKey data to extract:
orders[]: array of created orders, each with id, status, errortotal_consume_amount: actual total consumederror.code for per-item failuresFor 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 cex_fc_list_fc_currency_pairs).
Call cex_fc_preview_fc_multi_currency_many_to_one_order 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 sellbuy_asset (required, string): target currency (same for all, e.g. "USDT")buy_amount (string): alternative to sell_amountKey data to extract:
orders[]: array of preview results with quote_id, sell_amount, buy_amount, price, errortotal_acquire_amount: total amount of target currency to receiveerror.code — non-zero means that item failedPresent 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.
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 cex_fc_create_fc_multi_currency_many_to_one_order with body JSON string:
params (required, array): each element contains:
sell_asset (required, string): source currencysell_amount (required, string): amount to sellbuy_asset (required, string): target currencybuy_amount (required, string): amount to buy (from preview)quote_id (string): from preview responseKey data to extract:
orders[]: array of created orders with id, status, errortotal_acquire_amount: actual total receivedCall cex_fc_list_fc_currency_pairs with:
currency (optional, string): filter by currency symbollimit (optional, number): max items returned (default 1000)page (optional, number): page numberLarge 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_amountBefore calling, validate the status parameter if provided. Only 1 (success) and 2 (failed) are valid.
Call cex_fc_list_fc_orders with:
status (optional, number): 1 = success, 2 = failedsell_currency (optional, string): filter by sell currencybuy_currency (optional, string): filter by buy currencylimit (optional, number): max recordspage (optional, number): page numberreverse (optional, boolean): true for newest first (default)Key data to extract:
id, sell_currency, buy_currency, sell_amount, buy_amount, price, status, create_timeCall cex_fc_get_fc_order with:
order_id (required, number): the order ID to queryIf the API returns 404, inform the user the order was not found.
For verify_order: After retrieving the order, check status:
status == 1: Confirm the swap succeeded, show the final buy_amount actually receivedstatus == 2: Inform the user the swap failed, suggest re-previewing and placing a new orderKey data to extract:
id, sell_currency, buy_currency, sell_amount, buy_amount, price, status, create_timeFormat results using the appropriate Report Template. For swap operations, always show:
| Error Scenario | Handling |
|---|---|
| Region/compliance restriction (code -2) | CRITICAL: The API returns {"code":-2,"message":"This service is not supported in your region"}. This means flash swap is not available for this user's region. Immediately stop all operations, do NOT proceed to create, and inform the user: "Flash swap is not available in your region due to compliance restrictions." Do NOT fabricate any results |
| Preview failed (any non-zero code) | CRITICAL: If the preview API returns any code != 0, the operation has FAILED. Do NOT proceed to the create step. Do NOT fabricate a quote_id. Report the exact error code and message to the user. Never show "success" when the API returned an error |
| Amount below minimum (sell_amount < sell_min_amount) | Query cex_fc_list_fc_currency_pairs first. If below minimum, inform the user with the exact minimum and do NOT call preview |
| Amount above maximum (sell_amount > sell_max_amount) | Inform the user the amount exceeds the maximum allowed, show the limit |
| Quote expired (code 1052) | The quote_id has expired. Re-run the preview to get a fresh quote, then immediately create the order |
| Unable to get accurate quote (code 4 / 400001 / 400007) | These are quote-related errors from the server. code 4 is a top-level rejection (often caused by including a failed item). 400001 and 400007 are per-item errors meaning the server cannot price this pair/amount. Suggest adjusting the amount, trying a different pair, or removing the failed item |
| Multi-currency create: entire request rejected (code 4) | Likely caused by including a preview-failed item with buy_amount: "0". Remove all items where preview error.code != 0 and retry |
| Order status == 2 (failed) | Inform the user the swap failed. Suggest re-previewing with adjusted parameters and trying again |
| Order not found (404) | The order_id does not exist. Suggest verifying the ID or querying the order list first |
| MCP service connection failure | Prompt user to check network or VPN, suggest retrying later |
| order_id not provided | Prompt user to provide an order ID, or use the order list query first |
| Empty query results | Inform user no data was found, suggest adjusting filters |
| Currency not supported | Inform user that the specified currency is not available for flash swap |
| Invalid status value | Status only accepts 1 (success) or 2 (failed). Reject other values before calling the API |
| Large result set (thousands of rows) | Summarize total count, show sample of 20, suggest filtering by currency |
| Balance below minimum for many_to_one_all | When consolidating all holdings, skip currencies whose balance < sell_min_amount and inform the user which were excluded |
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 prompterror.code == 0)valid_timestamp from that preview response. If expired, automatically re-preview to get a fresh quote before creating| Condition | Action | Tool |
|---|---|---|
| User wants to swap one coin for another | Preview one-to-one, then create after confirmation | cex_fc_preview_fc_order_v1 → cex_fc_create_fc_order_v1 |
| User says "directly" or "one-click" swap | Preview + create automatically without separate confirmation | cex_fc_preview_fc_order_v1 → cex_fc_create_fc_order_v1 |
| User references a previous quote_id for confirmation | Create order using the referenced quote_id | cex_fc_create_fc_order_v1 |
| Swap amount is suspiciously small | Pre-validate against pair min amount before preview | cex_fc_list_fc_currency_pairs |
| User wants to buy multiple coins with one currency | Preview one-to-many, then create | cex_fc_preview_fc_multi_currency_one_to_many_order → cex_fc_create_fc_multi_currency_one_to_many_order |
| User wants to split one currency by ratio (e.g. "half and half") | Calculate per-target sell_amount, then preview one-to-many | cex_fc_preview_fc_multi_currency_one_to_many_order → cex_fc_create_fc_multi_currency_one_to_many_order |
| User specifies buy quantities (e.g. "buy 0.1 BTC and 1 ETH") | Use buy_amount in params, preview one-to-many | cex_fc_preview_fc_multi_currency_one_to_many_order → cex_fc_create_fc_multi_currency_one_to_many_order |
| User wants to sell multiple coins into one currency | Preview many-to-one, then create | cex_fc_preview_fc_multi_currency_many_to_one_order → cex_fc_create_fc_multi_currency_many_to_one_order |
| User wants to consolidate "all" of certain holdings | Query balances, filter by min amounts, preview many-to-one, then create | cex_fc_list_fc_currency_pairs → cex_fc_preview_fc_multi_currency_many_to_one_order → cex_fc_create_fc_multi_currency_many_to_one_order |
| User asks "how much can I get" without wanting to execute | Preview-only many-to-one, sum buy_amounts, do NOT create | cex_fc_preview_fc_multi_currency_many_to_one_order |
Preview returns items with error.code != 0 | Warn user, exclude failed items before creating | — |
| Preview returns code -2 (region restriction) | STOP immediately. Do NOT create. Inform user flash swap is not available in their region | — |
| Preview returns any non-zero code | STOP. Do NOT create. Do NOT fabricate quote_id. Report exact error to user | — |
| Create returns code 1052 (quote expired) | Re-run preview to get fresh quote | Preview tool |
| Create returns per-item error (400001/400007) | Report which items failed, suggest adjusting amounts | — |
| Multi-currency create rejected with code 4 | Remove failed preview items and retry | Create tool |
| Order status == 2 after create | Inform user swap failed, suggest retrying | — |
| User asks "did my swap succeed?" | Query order by ID, check status field | cex_fc_get_fc_order |
| User asks about supported pairs or limits | Query pair list | cex_fc_list_fc_currency_pairs |
| User queries order history | Query order list | cex_fc_list_fc_orders |
| User queries specific order by ID | Query single order | cex_fc_get_fc_order |
| Order not found (404) | Inform user, suggest checking ID | — |
| User provides invalid status filter | Reject and inform valid values are 1 or 2 | — |
Timestamp format: All {timestamp} placeholders use ISO 8601 format: YYYY-MM-DD HH:mm:ss UTC.
## 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)
## 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} |
## 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)
## 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.
## 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.
## 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.
## 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} |