gate-dex-trade

What this skill does

# Gate DEX Trade


> **Pure Routing Layer** — Swap EXECUTION only. Every operation produces an on-chain transaction. All specifications in `references/`.

## 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 call MCP tools explicitly listed in this skill.** Tools not documented here must NOT be called, even if they
  exist in the MCP server.

**Trigger Scenarios**: Use when the user wants to **execute a token exchange** that modifies blockchain state:
- Swap: "swap ETH for USDT", "exchange 100 USDC to DAI", "convert my BNB"
- Buy/Sell: "buy ETH", "sell my USDT", "purchase SOL"
- Cross-chain: "bridge ETH from Arbitrum to Base", "cross-chain swap"
- Swap quote: "how much USDT will I get for 1 ETH" (with intent to trade)

## Project convention — MCP only (this workspace)

**Do not use OpenAPI** for swap unless user explicitly asks OpenAPI/AK/SK. MCP unavailable → `references/setup.md` only.

---

**NOT this skill** (common misroutes):
- "what is the price of ETH" → `gate-dex-market` (read-only lookup, no trade intent)
- "check my swap history" → `gate-dex-wallet` (account query)
- "transfer ETH to 0xABC..." → `gate-dex-wallet` (direct transfer, not swap)
- "approve contract" (outside swap context) → `gate-dex-wallet` (DApp interaction)

---

## Routing Flow

```text
User triggers trading intent
  ↓
Step 1: Has user explicitly specified a mode?
  ├─ Explicitly mentions "OpenAPI" / "AK/SK" / "API Key" → OpenAPI mode
  ├─ Otherwise → MCP only (Step 2)
  └─ Not specified → Step 2
  ↓
Step 2: Is this a cross-chain swap?
  ├─ Cross-chain → Must use MCP mode (OpenAPI doesn't support cross-chain), proceed to Step 3
  └─ Same-chain / uncertain → Step 3
  ↓
Step 3: Gate Wallet MCP Server Discovery & Detection
  a) Scan configured MCP Server list for Servers providing `dex_tx_swap_quote`, `dex_tx_swap_prepare`, and staged swap signing tools (and the Gate GV MCP that exposes `tx_checkin` for staged check-in; see MCP Mode below)
  b) If found → Record server identifier, verify with:
     CallMcpTool(server="<identifier>", toolName="dex_chain_config", arguments={chain: "ETH"})
     ├─ Success → MCP mode
     └─ Failed → Step 4
  c) No matching Server → Step 4
  ↓
Step 4: MCP unavailable → setup guide only (`references/setup.md`), no OpenAPI fallback
```

---

## Mode Dispatch

### MCP Mode

**Read and strictly follow** `references/mcp.md`, execute according to its complete workflow.

Includes: connection detection, authentication (mcp_token), MCP Resource/tool calls (`dex_tx_swap_quote` / `dex_tx_swap_prepare` / `dex_tx_swap_checkin_preview` / staged sign-submit / `dex_tx_swap_detail`), token address resolution, native_in/native_out rules, three-step confirmation gateway (SOP), quote templates, risk warnings, cross-Skill collaboration, security rules.

**Staged swap check-in** — after each `dex_tx_swap_checkin_preview` (per stage: `approve` then `swap` as required), call the **Gate Web3 GV MCP** tool **`tx_checkin`** using the preview fields. The user environment must include that MCP server (discover via `tools/list`). **Parameter mapping:** `references/mcp.md` §4.3 — map preview `mcp_token` → `authorization` as `Bearer <token>`; `user_wallet` → `wallet_address`; `checkin_message` → `message`; set `source` to **integer `3`**; pass `chain` / `chain_category` as returned; set `type` to **`""`** unless GV/product documents a required non-empty value. Read **`data.checkin_token`** (and handle **`need_otp`**) from the tool result, then call `dex_tx_swap_sign_approve` / `dex_tx_swap_sign_swap`. **Do not** reimplement GV check-in with raw `curl` or custom signing.

### OpenAPI Mode (Progressive Loading)

**Default off in this workspace** — explicit OpenAPI request only.

**Limitation: OpenAPI mode only supports same-chain Swap, does not support cross-chain exchanges.**

Load files progressively — only load what the current step needs:

1. **Always load first**: `references/openapi/_shared.md` — env detection, credentials, API call method (via helper script)
2. **Then load based on swap stage**:

| Stage | Load File | When |
|-------|-----------|------|
| Query (chain/gas) | `references/openapi/quote.md` | User asks about chains or gas |
| Swap: get quote | `references/openapi/quote.md` + `references/openapi/sop.md` | User initiates swap |
| Swap: build tx | `references/openapi/build.md` | After quote confirmed (SOP Step 2) |
| Swap: sign tx | `references/openapi/sign.md` | After build confirmed (SOP Step 3) |
| Swap: submit | `references/openapi/submit.md` | After signing complete |
| History | `references/openapi/submit.md` | User asks for swap history |

3. **On error**: `references/openapi/errors.md`

> Legacy monolithic file preserved at `references/openapi.md` for backward compatibility.

### MCP Server Setup Guide

When MCP detection fails and a setup guide is needed, **read and display** `references/setup.md`. Show only the configuration for the user's current platform when identifiable. Display at most once per session.

---

## Supported Chains

Actual supported chains are determined by runtime API/Resource returns:
- **MCP Mode**: `swap://supported_chains` Resource
- **OpenAPI Mode**: `trade.swap.chain` interface

For uncommon chains: MCP calls `dex_chain_config`, OpenAPI calls `trade.swap.chain`.

---

## Security Rules

1. **Three-step confirmation gateway**: Trading pair confirmation → quote display → signature authorization — cannot be skipped
2. **Balance pre-check**: Mandatory verification of asset and Gas token sufficiency before trading
3. **Risk warnings**: Forced warning for exchange value difference > 5%, high slippage (> 5%) MEV attack warnings
4. **Authentication & credentials**: Follow §3 of [gate-runtime-rules.md](https://github.com/gate/gate-skills/blob/master/skills/gate-runtime-rules.md); MCP uses `mcp_token`, OpenAPI uses AK/SK — never mix
5. **No OpenAPI fallback** when MCP fails (this project)
6. **Risk disclosure (mandatory in trade output)**: Digital asset trading involves significant risk and may result in partial or total loss of your investment. Outputs from this skill are for informational purposes only and do not constitute investment, financial, tax, or legal advice.