gate-exchange-smallbalance

What this skill does

### 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`](https://github.com/gate/gate-skills/blob/master/skills/exchange-runtime-rules.md) §4 (or [`gate-runtime-rules.md`](https://github.com/gate/gate-skills/blob/master/skills/gate-runtime-rules.md) §4).


# Gate Exchange Small Balance (Dust to GT)

## General Rules

Read and follow the shared runtime rules before proceeding:
→ `exchange-runtime-rules.md` (in parent directory `skills/`)

## Skill Dependencies

### 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](https://github.com/gate/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:** Wallet read and small-balance convert as required for dust-to-GT flows (least privilege).
- **Portal:** create or rotate keys outside the chat: https://www.gate.com/myaccount/profile/api-key/manage

### Installation Check
- **Required:** `gate-cli` (install from [gate-cli releases](https://github.com/gate/gate-cli/releases) or via your environment’s Gate MCP / skills installer).
- Add the directory containing **`gate-cli`** to **`PATH`** when invoking by name.
- **Credentials:** When **`GATE_API_KEY`** and **`GATE_API_SECRET`** are both set (non-empty) for the host, **do not** require **`gate-cli config init`**. 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:** Before convert operations, confirm the CLI works (e.g. **`gate-cli cex wallet balance small`** or **`gate-cli --version`**).

---

This Skill covers **small balance conversion**: listing spot holdings that qualify under the platform dust threshold, executing conversion to **GT**, and querying conversion history. Under the hood this maps to wallet routes `GET/POST /wallet/small_balance` and `GET /wallet/small_balance_history`; **agents should drive the flow via MCP tools** `cex_wallet_*` below, not by hand-crafting HTTP.

## Domain Knowledge

**Small balance conversion** batches spot (or unified account spot-side) holdings whose value is below the platform **small-balance threshold** (typically up to **100 USDT** equivalent per policy; exact limits follow API responses).

| Term | Meaning |
|------|---------|
| **Dust** | Very small leftover balances that are hard to trade as standalone orders |
| **Small balance** | Eligible currencies under the threshold that can be converted to GT in one operation |

**Characteristics**:
- Consolidates low-value assets into **GT**
- Suited for wallet cleanup; not a substitute for normal spot sells of large positions

**Account scope**: Primarily **spot** or **unified** account spot balances (per product scope).

**Payload note**: `gate-cli cex wallet balance small` and `gate-cli cex wallet balance small-history` responses may wrap rows in an **outer array** whose first element is the **list of objects** to render; if so, use that inner list. Typical row fields: list — `currency`, `available_balance`, `estimated_as_btc`, `convertible_to_gt`; history — `id`, `create_time`, `currency`, `amount`, `gt_amount` (`create_time` often Unix seconds).

**MCP Tool Inventory**:

| Tool | Type | Description |
|------|------|-------------|
| `gate-cli cex wallet balance small` | Query | List currencies eligible for small-balance conversion and estimated GT |
| `gate-cli cex wallet balance convert-small` | Write | Convert selected currencies or all eligible dust to GT |
| `gate-cli cex wallet balance small-history` | Query | Paginated history of small-balance conversions |

## Workflow

### Step 1: Classify User Intent

Determine whether the user wants to **list** eligible assets, **convert** to GT, **review history**, or should be **excluded** from this Skill.

**Intent routing**:

| Intent | Typical user goal | Next step |
|--------|-------------------|-----------|
| `list` | Explore what can be converted, estimated GT | Step 2 |
| `convert_selected` | Convert specific tickers to GT | Step 2 → Step 3 (interactive) |
| `convert_all` | Convert every eligible dust balance | Step 2 → Step 3 (interactive) |
| `convert_unspecified` | Wants to convert but hasn't specified which coins | Step 2 → Step 3 (interactive) |
| `history` | Past small-balance conversions | Step 4 |
| `exclude` | Sell large holdings on spot, or keep specific coins | Do not call convert; redirect or stop |

**Exclusion rules**:
- User wants to **sell high-value** spot assets at a limit/market price → guide to **spot trading**, not this Skill
- User **explicitly keeps** certain coins → do **not** include those in `currencies` and do not set `is_all: true` without clear consent

Call **no tool** in this step.

Key data to extract:
- `intent`: `list` | `convert_selected` | `convert_all` | `convert_unspecified` | `history` | `exclude`
- `currencies`: optional list of symbols (e.g. `FLOKI`, `MBLK`) for selected convert
- `is_all`: boolean when user asks to convert everything eligible
- `history_filters`: optional `currency`, `page`, `limit` for history

### Step 2: Query Eligible Small Balances

**When to call**: Always call this step when:
1. Intent is `list`
2. Intent is `convert_selected`, `convert_all`, or `convert_unspecified` (before any conversion)

Call `gate-cli cex wallet balance small` with:
- No required parameters (empty call is valid)

Key data to extract:
- Row list: if the tool returns a nested array, use the **inner** array of objects (**Payload note** above)
- Each item: `currency`, `available_balance`, `estimated_as_btc`, `convertible_to_gt`
- Whether the list is **empty**

**Presentation**:
- If non-empty: summarize count, show a table with `currency`, `available_balance`, `convertible_to_gt`
- If empty: inform the user there are **no** eligible small-balance assets at this time

**For convert intents**: Store the eligible list in context for use in Step 3 validation.

### Step 3: Interactive Conversion Flow (if intent = convert_selected / convert_all / convert_unspecified)

This step enforces an **interactive flow** to ensure users make informed decisions.

#### 3.1: Validate User-Specified Currencies (if user specified tickers)

If the user specified `currencies` (e.g., "Convert FLOKI and MBLK to GT"):

1. **Check each currency against the eligible list** from Step 2:
   - If a currency **exists** in the eligible list → mark as `available`
   - If a currency **does NOT exist** in the eligible list → mark as `not_eligible`

2. **Inform the user of the validation result**:
   - For available currencies: "✅ {CURRENCY} is eligible for conversion (available: {available_balance}, estimated GT: {convertible_to_gt})"
   - For non-eligible currencies: "❌ {CURRENCY} is not in the eligible small-balance list. It may be above the threshold or not supported."

3. **If some currencies are not eligible**, ask the user:
   - "The following currencies are not eligible: {list}. Would you like to proceed with converting only the eligible ones ({eligible_list}), or would you like to review the full eligible list first?"

#### 3.2: Guide User Selection (if intent = convert_unspecified or user wants to review)

If the user has not specified which currencies to convert, or wants to review options:

1. **