gate-dex-trade-cli

What this skill does

# Gate DEX CLI — 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 call MCP tools explicitly listed in this skill.** Tools not documented here must NOT be called, even if they
  exist in the MCP server.
- **Only use the `gate-dex` CLI subcommands explicitly listed in this skill and its references.** Commands not documented here must NOT be run for these workflows, even if other interfaces expose them.

> One-shot DEX swap via CLI. GV checkin + sign + broadcast are all built into the `swap` command. No external `tx-checkin` binary needed. Supports EVM and Solana.

## Skill Boundaries

| This skill | Route to other skill |
|-----------|----------------|
| Swap tokens (same-chain) | Auth / login issues → `gate-dex-wallet-cli` |
| Cross-chain bridge | Balance, address, token list → `gate-dex-wallet-cli` |
| Swap quote (preview) | Token transfers (send) → `gate-dex-wallet-cli` |
| Swap / bridge history & order detail | K-line, token info, token security → `gate-dex-market-cli` |
| Swappable & bridge token discovery | — |

---

## Applicable Scenarios

- "Swap ETH for USDT", "exchange tokens", "buy SOL", "convert", "trade"
- Get a swap quote before executing
- View swap history or a specific swap order detail
- List swappable tokens or cross-chain bridge tokens

---

## CLI Commands

### Quote (preview only, no signing)

```bash
# EVM: swap native ETH → USDT on Ethereum (chain_id = 1)
gate-dex quote --from-chain 1 --to-chain 1 --from - --to 0xdAC17F958D2ee523a2206206994597C13D831ec7 --amount 0.01

# EVM: swap USDT → USDC on Arbitrum
gate-dex quote --from-chain 42161 --to-chain 42161 \
  --from 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 \
  --to 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
  --amount 100

# Solana: swap native SOL → USDC
gate-dex quote --from-chain 501 --to-chain 501 --from - \
  --to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --amount 0.1

# Cross-chain bridge: ETH on Ethereum → USDT on Arbitrum
gate-dex quote --from-chain 1 --to-chain 42161 --from - \
  --to 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 --amount 0.1 \
  --to-wallet 0xYourArbitrumAddress
```

Returns estimated output amount, price impact, route, and fee. **No signing.**

### One-Shot Swap (quote + GV checkin + sign + broadcast)

```bash
# EVM: swap native ETH → USDT
gate-dex swap --from-chain 1 --to-chain 1 --from - \
  --to 0xdAC17F958D2ee523a2206206994597C13D831ec7 --amount 0.01

# EVM: swap ERC20 with custom slippage
gate-dex swap --from-chain 42161 --to-chain 42161 \
  --from 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 \
  --to 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 \
  --amount 100 --slippage 0.005

# Solana: swap SOL → USDC
gate-dex swap --from-chain 501 --to-chain 501 --from - \
  --to EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --amount 0.05

# Cross-chain bridge: ETH on Ethereum → USDT on Arbitrum
gate-dex swap --from-chain 1 --to-chain 42161 --from - \
  --to 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 --amount 0.1 \
  --to-wallet 0xYourArbitrumAddress
```

| Option | Required | Description |
|--------|----------|-------------|
| `--from-chain <id>` | Yes | Source chain ID |
| `--to-chain <id>` | No | Destination chain ID (defaults to same as from-chain) |
| `--from <token>` | Yes | Source token contract; use `-` for native token (ETH/SOL/BNB) |
| `--to <token>` | Yes | Destination token contract |
| `--amount <n>` | Yes | Human-readable input amount |
| `--slippage <n>` | No | Slippage tolerance as decimal (default 0.03 = 3%) |
| `--native-in <0\|1>` | No | `1` if source token is native (ETH/SOL); default `0` |
| `--native-out <0\|1>` | No | `1` if destination token is native; default `0` |
| `--wallet <addr>` | No | Source wallet address (auto-detected from auth) |
| `--to-wallet <addr>` | No | Destination wallet address (required for cross-chain bridge) |

### Swap History

```bash
gate-dex swap-history
```

### Swap Order Detail

```bash
gate-dex swap-detail <order_id>
```

### List Swappable Tokens

```bash
gate-dex swap-tokens
gate-dex swap-tokens --chain eth
gate-dex swap-tokens --chain sol --search USDC
```

Use `--search` to look up a token address by symbol.

### List Cross-Chain Bridge Tokens

```bash
gate-dex bridge-tokens
gate-dex bridge-tokens --src-chain eth --dest-chain arb
```

---

## Internal Flow of `swap` Command

The agent **does not run any of these steps manually** — the CLI handles everything:

```
EVM same-chain flow:
1. Load auth; fetch wallet address
2. Get quote
3. Check if ERC20 approve is needed → auto-approve if needed (GV checkin for approve)
4. Re-quote after approve
5. Build swap transaction
6. GV security checkin (built-in) for swap tx
7. Server-side signing
8. Broadcast
9. Print tx hash + order ID

EVM cross-chain bridge flow (from-chain ≠ to-chain):
1. Load auth; fetch wallet address
2. Get cross-chain bridge quote (--from-chain / --to-chain / --to-wallet required)
3. Check if ERC20 approve is needed on source chain → auto-approve if needed
4. Build bridge transaction on source chain
5. GV security checkin (built-in)
6. Server-side signing
7. Broadcast on source chain
8. Print source tx hash + order ID (destination arrival is async, monitor via swap-detail)

Solana flow:
1. Load auth; fetch Solana address
2. Get quote
3. Build transaction (base64 → base58 conversion handled internally)
4. GV security checkin (built-in, includes priority fee)
5. Server-side signing
6. Broadcast via Solana mainnet RPC
7. Print tx hash + order ID
```

**CRITICAL**: There is no `tx-checkin` binary to run. Do NOT attempt to run a checkin binary before `swap`. The CLI has GV checkin built in.

---

## Chain IDs

| Chain | ID | Native Token |
|-------|----|-------------|
| Ethereum | 1 | ETH |
| BSC | 56 | BNB |
| Polygon | 137 | MATIC |
| Arbitrum | 42161 | ETH |
| Optimism | 10 | ETH |
| Avalanche | 43114 | AVAX |
| Base | 8453 | ETH |
| Solana | 501 | SOL |

**Native token address**: Use `-` as the token address for native tokens (ETH, SOL, BNB, etc.).

---

## Slippage Guidelines

| Token type | Recommended slippage |
|------------|----------------------|
| Stablecoins (USDT ↔ USDC) | 0.005 (0.5%) |
| Major tokens (ETH, BTC, SOL) | 0.01–0.03 (1%–3%) |
| Mid-cap tokens | 0.03 (3%) |
| Meme / low-liquidity tokens | 0.05–0.10 (5%–10%) |

---

## Common Token Addresses

| Chain | USDT | USDC |
|-------|------|------|
| Ethereum (1) | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
| Arbitrum (42161) | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9` | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` |
| BSC (56) | `0x55d398326f99059fF775485246999027B3197955` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
| Solana (501) | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |

---

## Workflow

### Step 1: Auth check

Call `gate-dex status` to verify the session.

Key data to extract:
- `is_authenticated`: boolean
- If not logged in → instruct the user to run `gate-dex login` (delegated to `gate-dex-wallet-cli`).

### Step 2: Collect parameters

Required: `from-chain`, `to-chain` (defaults to `from-chain`), `from-token`, `to-token`, `amount`. Optional: `slippage`, `to-wallet` (cross-chain only).

If a token symbol is given without an address → call `gate-dex swap-tokens --chain <chain> --search <symbol>` and confirm the resolved address with the user.

Key data to extract:
- `from_chain`, `to_chain`, `from_token`, `to_token`, `amount`, `slippage`, `to_wallet`

### Step 3: Get quote

Call `gate-dex quote --from-chain <id> --to-chain <id> --from <token> --to <token> --amount <n>`.

Key data to extract:
- `estimated_out`, `price_impact`, `route`, `fee`, `slippage_used`

### Step 4: User confirmat