gate-exchange-candydrop

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 CandyDrop

**Authoring language:** This skill’s **instructions and reference prose** are written in **English** (Gate skill standard). **End-user replies** still follow **Language adaptation** (match the user’s locale).

## 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, Public)**

- `gate-cli cex launch candy-drop activities`
- `gate-cli cex launch candy-drop rules`

**Query Operations (Read-only, Auth Required)**

- `gate-cli cex launch candy-drop progress`
- `gate-cli cex launch candy-drop participations`
- `gate-cli cex launch candy-drop airdrops`

**Execution Operations (Write)**

- `gate-cli cex launch candy-drop register`

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

### Installation Check

- **Required:** Gate (main), Gate (trading); **`gate-cli`** when using CLI-backed flows (install via [`setup.sh`](./setup.sh) from this skill when applicable).
- **Install (MCP / IDE):** Run installer skill for your environment — Cursor: `gate-mcp-cursor-installer`; Codex: `gate-mcp-codex-installer`; Claude: `gate-mcp-claude-installer`; OpenClaw: `gate-mcp-openclaw-installer`.
- **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:** Before authenticated or mutating calls, confirm the runtime works (e.g. **`gate-cli --version`** or a read-only check appropriate to this skill); resolve credentials before registration or write operations.

## Execution mode

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

- `SKILL.md` keeps routing and product semantics.
- `references/gate-cli.md` is the authoritative `gate-cli` execution contract for activity/rule queries, registration confirmation gates, progress/record queries, and result verification.

## Module overview

| Module | Description | Trigger keywords |
|--------|-------------|------------------|
| **Activity List** | Browse CandyDrop activities, filter by status/coin/task type | `candydrop`, `candydrop activities`, `activity list`, `ongoing candydrop`, `USDT candydrop` |
| **Activity Rules** | View activity rules, prize pools, and tasks | `activity rules`, `task rules`, `prize pool`, `reward rules`, `candydrop rules` |
| **Register** | Register for a CandyDrop activity | `register`, `join activity`, `candydrop register`, `participate candydrop` |
| **Task Progress** | Query task completion progress for enrolled activities | `task progress`, `completion progress`, `progress query`, `task progress` |
| **Participation Records** | Query registration/participation history | `participation records`, `registration records`, `history records`, `participation records` |
| **Airdrop Records** | Query airdrop/reward distribution records | `airdrop records`, `reward records`, `received records`, `airdrop records` |

## Domain Knowledge

### CandyDrop concepts

| Concept | Description |
|---------|-------------|
| CandyDrop | A Gate activity platform where users complete tasks (trading, depositing, etc.) to earn airdrop rewards from prize pools. |
| Activity (`currency` / `activity_id`) | A CandyDrop campaign for a specific token. Identified by `currency` (token symbol) or `activity_id` (numeric ID). |
| Activity Status | Lifecycle: `upcoming` (upcoming) → `ongoing` (ongoing) → `ended` (ended). |
| Registration Status | `registered` (already registered) or `unregistered` (not yet registered). |
| Record Status | For participation records: `ongoing` (in progress), `awaiting_draw` (awaiting draw), `won` (won), `not_win` (not won). |
| Prize Pool | Each activity has one or more prize pools, each with a total prize amount (`prize_all`), per-user cap (`prize_limit`), and a list of tasks. |
| Task | Individual challenges within a prize pool (e.g. spot trading, futures trading, deposit, invite). Each has a name (`task_name`), description (`task_desc`), and exclusive label (`exclusive_label`). |
| Task Progress | The user's current completion value for a task (e.g. trading volume, deposit amount). Only shown for registered tasks (`task_status > 0`). |

### Timestamp formatting

- API returns time fields (e.g. `start_time`, `end_time`, `register_time`, `airdrop_time`) as **pre-formatted UTC strings** in the format `YYYY-MM-DD HH:MM:SS(UTC)`.
- **Tables / lists**: Put `(UTC)` in the **column header** when the time is UTC. If the header already says `(UTC)` (ASCII or full-width punctuation variants), **do not** repeat it on every cell: strip a trailing `(UTC)` from the API value and show **`YYYY-MM-DD HH:MM:SS`** only (example: `2026-04-13 04:04:10`, not `2026-04-13 04:04:10(UTC)`). If the header does **not** mark UTC, keep the API string as-is so the zone is not lost.
- **Other surfaces** (e.g. inline sentences without a UTC-labeled header): you may keep the API form or use header + stripped cell style consistently within one reply.
- Query parameters `start_time` / `end_time` for records are **integer unix timestamps (seconds)**. See **Timestamp strategy** in `references/records.md` for correct computation.

### Number formatting

| Category | Precision | Examples |
|----------|-----------|----------|
| Amounts (rewards, progress values) | 8 decimals, trailing zeros removed | `1.23` not `1.23000000` |
| Airdrop `rewards` (display) | Same numeric formatting, **then** append ` ` + row `currency` | `4.02032 ETH` not `4.02032` |
| Percentage-like fields | 2 decimals, trailing zeros retained | `5.20%` not `5.2%` |

### Dual-parameter resolution

Activity query interfaces support locating an activity by **either** `activity_id` or `currency`:

- `currency` (e.g. "USDT"): API auto-matches the nearest active activity for that token.
- `activity_id`: Precise numeric ID lookup.
- **Priority**: `currency` is preferred. If user provides both, use both. If only `activity_id` is given, use it directly. If neither is provided for rules/progress, ask the user for `