gate-exchange-vipfee

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 VIP & Fee Query Assistant

## 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 use the `gate-cli` commands explicitly listed in this skill.** Commands not documented here must NOT be run for these workflows, even if other interfaces expose them.

## Skill Dependencies


### gate-cli commands used

**Query Operations (Read-only)**

- `gate-cli cex account detail`
- `gate-cli cex wallet market trade-fee`

### 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:** Account:Read, Wallet:Read
- **Portal:** create or rotate keys outside the chat: https://www.gate.com/myaccount/profile/api-key/manage

### Installation Check
- **Required:** `gate-cli` (run `sh ./setup.sh` from this skill directory if missing; optional `GATE_CLI_SETUP_MODE=release`).
- Add `$HOME/.openclaw/skills/bin` to **`PATH`** if you invoke `gate-cli` by name (or the directory where [`setup.sh`](./setup.sh) installs it).
- **Credentials:** When **`GATE_API_KEY`** and **`GATE_API_SECRET`** are both set (non-empty) for the host, **do not** require **`gate-cli config init`** — that is equivalent valid config for `gate-cli`. 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:** Do not proceed with authenticated calls until the CLI behaves as expected (e.g. **`gate-cli --version`** or a read-only **`gate-cli cex ...`** command from this skill); confirm credentials resolve before mutating operations.

## Execution mode

**Read and strictly follow** [`references/gate-cli.md`](./references/gate-cli.md), then execute this skill's VIP/fee query workflow.

- `SKILL.md` keeps intent routing and rendering rules.
- `references/gate-cli.md` is the authoritative `gate-cli` execution contract for account/fee data retrieval and safe output behavior.

## Quick Start

Below are the most common prompts to get started quickly:

1. **Query VIP tier**
 > What is my VIP level?

2. **Query trading fees**
 > Show me the spot and futures trading fees.

3. **Query VIP tier and fees together**
 > Check my VIP level and trading fees.

## Domain Knowledge

### Tool Mapping by Domain

| Group | Tool Calls |
|-------|------------|
| Account / VIP tier | `gate-cli cex account detail` |
| Trading fee rates | `gate-cli cex wallet market trade-fee` |

### Key Concepts

- **VIP Tier**: Gate assigns VIP levels (VIP 0 – VIP 16) based on trading volume and asset holdings. Higher VIP tiers unlock lower fee rates.
- **Spot Fee**: The maker/taker fee rate applied to spot trading pairs.
- **Futures Fee**: The maker/taker fee rate applied to futures/contract trading, differentiated by settlement currency (BTC, USDT, USD).
- The `gate-cli cex wallet market trade-fee` tool returns fee rates for both spot and futures in a single response. Use the `settle` parameter to query futures-specific fees.

### API Behavior Notes

- **Account-level pricing**: Gate fee rates are determined by the user's VIP tier. The `currency_pair` parameter does not change the returned fee values — all trading pairs share the same account-level rate.
- **`settle` parameter scope**: The `settle` parameter only affects futures fee fields (`futuresMakerFee` / `futuresTakerFee`). Spot fees (`makerFee` / `takerFee`) remain unchanged regardless of `settle`.
- **Invalid `currency_pair` handling**: The API does not return an error for non-existent trading pairs. It silently returns the default account-level fees. Do not treat a successful response as confirmation that the trading pair exists.

## Workflow

When the user asks about VIP tier or trading fees, follow this sequence.

### Step 1: Identify Query Type

Classify the request into one of these categories:

1. **VIP tier query** — user wants to know their current VIP level
2. **Fee rate query** — user wants to know spot and/or futures trading fee rates
3. **Combined query** — user wants both VIP tier and fee information

Key data to extract:
- `query_type`: "vip", "fee", or "combined"
- `currency_pair` (optional): specific trading pair for fee lookup
- `settle` (optional): futures settlement currency (BTC / USDT / USD)

### Step 2: Query VIP Tier (if needed)

If `query_type` is "vip" or "combined":

Call `gate-cli cex account detail` with:
- No parameters required

Key data to extract:
- `vip_level`: the user's current VIP tier (e.g., VIP 0, VIP 1, etc.)

### Step 3: Query Trading Fee Rates (if needed)

If `query_type` is "fee" or "combined":

Call `gate-cli cex wallet market trade-fee` with:
- `currency_pair` (optional): specify trading pair context (note: fee rates are account-level and do not vary by pair)
- `settle` (optional): futures settlement currency — affects futures fee fields only

Key data to extract:
- `maker_fee_rate`: spot maker fee rate
- `taker_fee_rate`: spot taker fee rate
- `futures_maker_fee_rate`: futures maker fee rate
- `futures_taker_fee_rate`: futures taker fee rate

### Step 4: Return Result

Format the response according to the Report Template. The API (`gate-cli cex wallet market trade-fee`) always returns the full fee structure (spot + futures + delivery). Filter the output based on the user's original intent:

- If user asked about **spot fees only** → show only `makerFee` / `takerFee`
- If user asked about **futures/contract fees only** → show only `futuresMakerFee` / `futuresTakerFee`
- If user asked about **trading fees** (general) → show both spot and futures
- If user asked about **VIP only** → show only VIP level, no fee data
- If user specified a `currency_pair` → append a note in the response: "Note: The API returns account-level fee rates. The fee shown applies to all trading pairs; if the pair you specified does not exist, the result still reflects your default account fee rate."

Key data to extract:
- VIP level (if queried)
- Spot maker/taker fee rates (if queried)
- Futures maker/taker fee rates (if queried)

## Judgment Logic Summary

| Condition | Action |
|-----------|--------|
| User asks about VIP tier/level only | Call `gate-cli cex account detail`, return VIP level |
| User asks about trading fees only | Call `gate-cli cex wallet market trade-fee`, return spot and futures fee rates |
| User asks about both VIP and fees | Call both tools, return combined result |
| User specifies a trading pair | Pass `currency_pair` parameter to `gate-cli cex wallet market trade-fee` |
| User specifies futures settlement currency | Pass `settle` parameter to `gate-cli cex wallet market trade-fee` |
| User asks about spot fees only | Call `gate-cli cex wallet market tr