gate-exchange-staking

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 Staking Query Suite

## 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 earn staking assets`
- `gate-cli cex earn staking awards`
- `gate-cli cex earn staking find`
- `gate-cli cex earn staking orders`

**Execution Operations (Write)**

- `gate-cli cex earn staking swap`

### 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:** Earn:Write
- **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 staking workflow.

- `SKILL.md` keeps staking intent routing and scenario boundaries.
- `references/gate-cli.md` is the authoritative `gate-cli` execution contract for query/action separation, confirmation gates, and result verification.

## Module overview

| Module | Description | Trigger keywords |
|--------|-------------|------------------|
| **Positions** | Query staking positions, balances, available vs locked | `position`, `balance`, `staked`, `staking assets`, `holdings`, `redeemable` |
| **Rewards** | Query reward history, yesterday/monthly earnings | `reward`, `earning`, `profit`, `income`, `yesterday earnings`, `monthly earnings` |
| **Products** | Discover available staking products, APY, min amount | `products`, `available`, `APY`, `stakeable coins`, `high yield`, `flexible` |
| **Order history** | Query stake/redeem order list and pagination | `history`, `orders`, `transactions`, `staking records`, `redemption records` |
| **Stake / Redeem** | Execute stake or redeem via swap (pid required) | `stake`, `redeem`, `unstake`, `stake 100 USDT`, `redeem my ETH`, `swap staking` |

**Mint**: Treated as **immediate stake**. Route to the same Stake workflow: read `references/staking-swap.md`, resolve product (pid) and amount, then call `gate-cli cex earn staking swap` with **side=0**. For GUSD products, require the user to choose USDT or USDC and pass `coin`.

**Cancel redeem (not supported)**: When the user intends to **cancel** or **revoke** a redeem (e.g. cancel a redemption order already submitted), do not call any tool. Reply **in English** that this operation is not supported.

## Domain Knowledge

### Product types

| productType | Label | Description |
|-------------|-------|-------------|
| 0 | Certificate | Flexible staking with instant redemption (redeemPeriod = 0) |
| 1 | Lock-up | Fixed-term staking with a defined lock period (redeemPeriod > 0) |
| 2 | US Treasury Bond | Products backed by US Treasury bonds (e.g. GUSD). Users stake crypto and receive yield derived from US Treasury interest rates. Typically has a fixed or semi-fixed APR with low risk. |

### Redeemable amount calculation

The redeemable amount for a position is **not** `mortgage_amount − freeze_amount`. The correct formula is:

```
redeemable = mortgage_amount × exchangeRate
```

Where `exchangeRate` comes from `gate-cli cex earn staking find` for the same `pid` and matching `currency`. Some products have exchangeRate = 1 (e.g. USDT flexible), while others vary (e.g. liquid staking tokens).
### Dynamic exchange rate (exchangeRate ≠ 1)

When a product’s **exchange rate is not equal to 1**, it is a **dynamic-rate** product. In stake/redeem **response** data (swap result or order list): **amount** = staked/redeemed base coin quantity; **exchangeAmount** (or **exchange_amount**) = received quote/reward coin quantity.

**Display rule (English only):**
- **Stake**: Show **exchangeAmount** (what the user receives).
- **Redeem**: Show **amount** (what the user receives).
When exchangeRate = 1, either field may be omitted or shown as equal; prefer showing the single amount.

### Reward distribution

- `reward_delay_days = -1` means the reward is paid **on redeem**, not periodically.
- `interest_delay_days` indicates the delay after staking before rewards start accruing (typically 1 day / T+1).
- Multi-coin rewards: a single position can generate rewards in multiple coins (e.g. stake USDT in Compound V3, receive USDT + COMP).
### GUSD / multi-currency products (USDT or USDC)

When **staking**, **redeeming**, or **minting** GUSD (or any product whose `currency` or `mortgage_coin` is `"USDT,USDC"`):

- **Require the user to choose a coin.** Only **USDT** and **USDC** are supported.
- Prompt: e.g. "This product accepts USDT or USDC. Which do you want to use: USDT or USDC?"
- **Pass the user’s choice as the `coin` parameter** to the swap (or mint) tool. Do not call the tool until the user has selected one of the two.


### Positions: status field

When **viewing staking positions** (position/balance/holdings queries), **ignore and do not display** the `status` field. Omit it from all user-facing position output.

### Timestamps in results

**Do not display or format timestamp-related fields in any result.** Omit from user-facing output all timestamp fields (e.g. `createStamp`, `redeem_stamp`, `updateStamp`, `should_bonus_stamp`). Do not convert timestamps to dates, times, or relative time (e.g. no "YYYY-MM-DD", "HH:mm", "2 hours ago"). If a field is purely timestamp-based, do not show it.

### Number formatting

| Category | Precision | Trailing zeros | Examples |
|----------|-----------|----------------|----------|
| General amounts (mortgage_amount, freeze_amount, income_total, fee, etc.) | 8 decimals | Removed | `1.23` not `1.23000000`; `100` not `100.00000000` |
| R