gate-dex-wallet-cli

What this skill does

# Gate DEX CLI

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

> **Pure Routing Layer** — This SKILL.md is a lightweight router. Sub-module details live in `references/`.

## Overview

`gate-dex` is a standalone CLI tool that communicates with Gate DEX services via REST APIs. **No MCP server is required.** All signing operations (transfer, sign-msg, swap) include built-in GV security checkin — the agent does not need to run any external binary.

Auth: login via Gate/Google OAuth, token stored in `~/.gate-dex/auth.json`.

The CLI also supports an **interactive REPL** — running `gate-dex` with no arguments opens a prompt.

## Applicable Scenarios

Use this skill when the user wants to:

- Authenticate (login/logout) via Gate OAuth or Google OAuth
- Query token balances, total portfolio value, or wallet addresses
- View transaction history
- Transfer or send tokens to an on-chain address (EVM + Solana)
- Sign raw messages or raw transactions
- Use `gate-dex` CLI commands directly

---

## Capability Boundaries

| Supported | Route elsewhere |
|-----------|----------------|
| Authentication & session management | Token swap → `gate-dex-trade-cli` skill |
| Balance, address & token list queries | Market data / token info / K-line → `gate-dex-market-cli` skill |
| Transaction history | DApp interactions → `gate-dex-wallet` skill (MCP-based) |
| Token transfers (EVM + Solana) | x402 payments → `gate-dex-wallet` skill (MCP-based) |
| Sign 32-byte hex messages / raw tx | MCP tool calls → `gate-dex-wallet` skill (MCP-based) |

**Prerequisites**: A `gate-dex` binary on PATH.

- **GateClaw managed scenario** — `skill/setup.sh` runs automatically on install and drops a pre-built Linux binary into `/home/node/.openclaw/skills/bin/gate-dex`. Environment variables (`RUN_ENV`, `*_URL`) are collected via the GateClaw Web form and injected into `process.env` at runtime.
- **Personal OpenClaw scenario** — the frontmatter `install` spec downloads the binary for the host OS automatically (no Node.js required).
- **Local development** — build from source:
  ```bash
  cd cli && pnpm install
  pnpm build:binary                  # production binary (no baked env)
  pnpm build:binary -- --bake-env    # bake root .env into the binary (test env)
  ```

---

## Installation

The published binary is a single self-contained executable (no Node.js runtime required).

```bash
# GateClaw / OpenClaw: auto-installed via setup.sh or frontmatter.install
# Manual download (example):
curl -fsSL https://gate-dex-cli.gateweb3.cc/latest/gate-dex-linux-x64 \
  -o /usr/local/bin/gate-dex
chmod +x /usr/local/bin/gate-dex

# Login
gate-dex login           # Gate OAuth (default)
gate-dex login --google  # Google OAuth
```

**Storage**:
- Auth token → `~/.gate-dex/auth.json`

**Environment variables** (all optional; defaults target production):

| Variable | Purpose |
|----------|---------|
| `RUN_ENV` | `dev` / `pre` / `prod` — selects GV API environment and CDN candidates |
| `WALLET_SERVICE_URL` | `web3-wallet-service` endpoint (used by `balance`) |
| `BW_SERVICE_URL` | `web3-business-wallet` endpoint |
| `MARKET_TOKEN_URL` | `gateio_service_web3_trade_token` endpoint (market/token/swap) |
| `DATA_API_URL` | `web3-data-api` endpoint (token info, security audit, ranking) |
| `BIZ_WALLET_URL` | OAuth session management endpoint |

---

## Global Options

| Option | Description |
|--------|-------------|
| `--auth-dir <path>` | Custom auth storage directory (overrides `~/.gate-dex`; also via `GATE_DEX_HOME` env) |
| `--auth-file <path>` | Custom auth.json file path (overrides `--auth-dir`; also via `GATE_DEX_AUTH_FILE` env) |
| `-v, --version` | Print version |

---

## Sub-Modules

| Sub-module | File | Scope |
|-----------|------|-------|
| **Auth** | `references/auth.md` | OAuth login/logout, session status, web3-domain |
| **Asset Query** | `references/asset-query.md` | balance, address, tokens, tx-history, tx-detail |
| **Transfer & Sign** | `references/transfer.md` | transfer (preview), send (one-shot), sign-msg, sign-tx, sol-tx, gas |

## Routing Rules

| User Intent | Target |
|-------------|--------|
| Login, logout, re-login, session expired, OAuth, "not logged in", switch account, web3-domain | `references/auth.md` |
| Check balance, total assets, wallet address, account address, token list, tx history, "how much do I have", "show my tokens" | `references/asset-query.md` |
| Transfer, send tokens, "send ETH to 0x...", "transfer USDT", "pay someone", "move tokens", sign-msg, sign-tx, sol-tx | `references/transfer.md` |
| Swap, exchange tokens, "swap ETH for USDT", "buy SOL", quote, "convert tokens" | → `gate-dex-trade-cli` skill |
| K-line, token price, market cap, liquidity, trading stats, token security, token rankings, new tokens | → `gate-dex-market-cli` skill |

## Execution

1. **Detect intent** using the Routing Rules table; resolve to exactly one sub-module file or a peer-skill route.
2. **Read the matched sub-module** (`references/auth.md`, `references/asset-query.md`, or `references/transfer.md`) and follow its workflow as the authoritative execution contract.
3. **Apply the safety rules in this SKILL.md** (Security Rules section) before any write command (`send`, `sign-msg`, `sign-tx`).
4. **For write paths** (`send`): require explicit user confirmation in chat before invoking the CLI; preview via `transfer` first.
5. **For peer-skill routes** (`gate-dex-trade-cli`, `gate-dex-market-cli`): hand off without invoking those skills' commands from here.

---

## Full Command Reference

### Auth & Session
| Command | Description |
|---------|-------------|
| `login` | Gate OAuth Device Flow login |
| `login --google` | Google OAuth Device Flow login |
| `login --no-open` | Print auth URL instead of opening browser |
| `logout` | Logout and clear `~/.gate-dex/auth.json` |
| `status` | Show current session info |
| `web3-domain` | View / refresh dynamic web3_domain list |
| `web3-domain --refresh` | Force re-fetch domain list |

### Wallet Queries
| Command | Description |
|---------|-------------|
| `balance` | Total portfolio value (USD) across all chains |
| `address` | Show EVM + Solana wallet addresses |
| `tokens` | Token list with balances (gateway) |
| `tokens --chain ETH,SOL` | Filter by chain |
| `tokens --page N --size N` | Pagination |

### Transfer & Signing
| Command | Description |
|---------|-------------|
| `transfer` | Preview-only unsigned tx (no broadcast) |
| `send` | One-shot: preview → GV checkin → sign → broadcast |
| `send-tx` | Build → GV checkin → sign → broadcast (or broadcast pre-signed with `--hex`) |
| `sol-tx` | Build Solana unsigned tx locally (latest blockhash) |
| `gas [chain]` | Query gas price + gas limit |
| `sign-msg <hex>` | Sign 32-byte hex message (GV checkin built-in) |
| `sign-tx <raw_tx>` | Sign raw hex transaction (GV checkin built-in) |

### Swap (out of scope — route to `gate-dex-trade-cli` skill)

The `quote`, `swap`, `swap-tokens`, `bridge-tokens`, `swap-history`, and `swap-detail` commands are documented in the `gate-dex-trade-cli` skill. Do not invoke them from this skill.

### Transaction History

| Command | Description |
|---------|-------------|
| `tx-history` | Transfer transaction history |
| `tx-detail <hash>` | Transaction detail by hash |

### Market & Token Data (out of scope — route to `gate-dex-market-cli` skill)

The `t