gate-exchange-affiliate

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 Affiliate Program Assistant

Query and manage Gate Exchange affiliate/partner program data, including commission tracking, team performance analysis, and application guidance.

## 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 `./references/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 rebate partner application`
- `gate-cli cex rebate partner eligibility`
- `gate-cli cex rebate partner commissions`
- `gate-cli cex rebate partner sub-list`
- `gate-cli cex rebate partner transactions`

### 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.
- API Key Required: Yes
- **Permissions:** Rebate: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 affiliate workflow.

- `SKILL.md` keeps routing and reporting policy.
- `references/gate-cli.md` is the authoritative `gate-cli` execution contract for eligibility/application/commission query flow and degraded handling.

## Important Notice

- **Role**: This skill uses Partner APIs only. The term "affiliate" in user queries refers to Partner role.
- **Time Limit**: API supports maximum 30 days per request. For queries >30 days (up to 180 days), agent must split into multiple 30-day segments.
- **Authentication**: Partner APIs still run through the local Gate MCP session. Any required partner headers (including `X-Gate-User-Id`) are supplied by that session, not pasted by the user.
- **CRITICAL - user_id Parameter**: In both `commission_history` and `transaction_history` APIs, the `user_id` parameter filters by "trader/trading user" NOT "commission receiver". Only use this parameter when explicitly querying a specific trader's contribution. For general commission queries, DO NOT use user_id parameter.
- **Data Aggregation**: When calculating totals from API response lists, use custom aggregation logic based on business rules. DO NOT simply sum all values as this may lead to incorrect results due to data structure and business logic considerations.

### Query time and timezone (UTC+8)

All query windows use the user's **current calendar date** in **UTC+8**. For relative phrases ("last 7 days", "last 30 days", "this week", "last month"): compute the start date by subtracting the requested span from today, convert start and end to UTC+8 00:00:00 and 23:59:59 respectively, then to Unix timestamps. **NEVER** use future timestamps as query bounds. The `to` parameter must always be ≤ current Unix time. If the user specifies a future date, reject the query and explain that only historical data is available.

## Available APIs (Partner Only)

| API Endpoint | Description | Time Limit |
|--------------|-------------|------------|
| `GET /rebate/partner/transaction_history` | Get referred users' trading records | ≤30 days per request |
| `GET /rebate/partner/commission_history` | Get referred users' commission records | ≤30 days per request |
| `GET /rebate/partner/sub_list` | Get subordinate list (for customer count) | No time parameter |
| `GET /rebate/partner/eligibility` | Check if user is eligible to apply for partner | No time parameter |
| `GET /rebate/partner/applications/recent` | Get user's recent partner application record (last 30 days) | No time parameter |

**Note**: Agency APIs (`/rebate/agency/*`) are deprecated and not used in this skill.

## ⚠️ CRITICAL API USAGE WARNINGS

### user_id Parameter Clarification
- **NEVER use `user_id` parameter for general commission queries**
- The `user_id` parameter in both `commission_history` and `transaction_history` APIs filters by **TRADER/TRADING USER**, not commission receiver
- Only use `user_id` when explicitly querying a specific trader's contribution (e.g., "UID 123456's trading volume")
- For queries like "my commission", "my earnings", "my rebate" - **DO NOT use user_id parameter**

### Data Aggregation Rules
- **DO NOT simply sum all values from API response lists**
- Use custom aggregation logic that considers:
 - Business rules and data relationships
 - Asset type grouping
 - Proper filtering and deduplication
 - Time period boundaries
- Raw summation may lead to incorrect results due to data structure complexities

## Safety Rules

- **Query times (UTC+8)**: Follow **Important Notice → Query time and timezone (UTC+8)** for relative ranges, day boundaries, and Unix conversion. Never use future timestamps; `to` must be ≤ current Unix time; reject user-specified future dates.
- **user_id usage**: Use the `user_id` parameter only when the user explicitly asks about a specific trader's contribution (e.g. "UID 123456's volume"). Do not use `user_id` for "my commission" or "my earnings"—those are the partner's own totals across all referred users.
- **Data scope**: Query only data for the authenticated partner. Do not attempt to access other partners' data or to infer data outside the API responses.
- **Aggregation**: Do not sum list fields blindly. Use documented aggregation rules and respect asset types, deduplication, and period boundaries to avoid incorrect totals.
- **Sub-accounts**: If the API indicates the account is a sub-account or returns a sub_account eligibility block, direct the user to use the main account for partner data or application.

## Core Metrics

1. **Commission Amount**: Total rebate earnings from `commission_history`
2. **Trading Volume**: Total trading amount from `transaction_history`
3. **Net Fees**: Total fees collected from `transac