gate-exchange-autoinvest

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-autoinvest

The fast auto-invest (DCA) function of Gate Exchange Earn, supporting create, update, stop plans, and query related information.

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

### 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 (auto-invest) access as required by your API key and deployment.
- **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:** Confirm the CLI works (e.g. **`gate-cli --version`** or a read-only earn/auto-invest query from this skill) before plan mutations.

## Risk Disclaimer

**Digital Asset Trading Risk Statement**:
Digital asset trading carries significant risks. Prices are subject to high volatility and market manipulation. Past performance is not indicative of future results. This skill provides informational tools only and does not constitute investment advice. Users are solely responsible for their investment decisions. Only invest what you can afford to lose. For full risk disclosure, please visit Gate's official website.

## AI Interaction Data Flow

**Data Handling Notice**:
When you use this skill, your queries and account data are processed through AI systems to provide trading assistance. This includes:
- Your trading instructions and preferences
- Account balance and position information (read-only access)
- Historical trading records for context

**Important**:
- All data transmission is encrypted and follows Gate's privacy policy
- AI processes data in real-time; no long-term storage of your trading data by the AI
- You retain full control; AI only executes trades after your explicit confirmation
- For privacy details, see Gate's Privacy Policy

## Feature Modules

| Module | Description | Trigger Keywords |
|--------|-------------|------------------|
| **Plan Management** | Create, update, stop, and add position to auto-invest plans | `create DCA`, `auto-invest`, `stop plan`, `add to my DCA`, `dollar cost averaging` |
| **Information Query** | Query supported coins, minimum amounts, execution records, order details, and plan details | `min amount`, `execution history`, `records`, `plan detail` |

## Business Rules

### Investment Currency Restrictions

- **Only USDT or BTC supported** as investment currency (the currency deducted each period)
- Target coins can be other assets

### Create Plan Constraints

**Required Parameters**:
- Target coins to invest (asset list)
- Investment amount per period

**Optional Parameters** (with defaults):
- Investment time: Defaults to daily at 10:00 (can be customized)
- Fund source: Defaults to `spot` (spot account)
- Fund flow: Defaults to `auto_invest` (purchased assets remain in Spot account)

**Execution Time Restriction**:
- **Auto-invest only supports execution on the hour** (0-23 o'clock)
- `plan_period_hour` must be an integer from 0 to 23
- Minutes and seconds are not supported; all executions occur at :00
- ⚠️ **CRITICAL - Time Zone**: `plan_period_hour` uses **UTC time zone**
  - When user specifies local time (e.g., "10:00 AM Beijing time"), **convert to UTC** before passing to API
  - Example: Beijing 10:00 (UTC+8) → UTC 02:00 → set `plan_period_hour: 2`
  - **Fallback**: If system time zone cannot be detected, use user's specified hour directly
  - Always show both UTC and local time in confirmation (or note if time zone detection failed)
  - See `references/autoinvest-plans.md` → Time Zone Handling section for detailed conversion rules

**`plan_period_day` (create plans only)**:
- Required on create; value **must not be `0`**. Full workflow: `references/autoinvest-plans.md` → Workflow step 6.
- By **`plan_period_type`**:
  - **`monthly`**: Day of month **1–30**
  - **`weekly`** or **`biweekly`**: Weekday **1–7** (**1 = Monday**, **7 = Sunday**)
  - **`daily`**, **`hourly`**, or **`4-hourly`**: Use **`1`**

**Investment Amount Limits**:
- **Minimum amount**: Must be ≥ the value returned by `gate-cli cex earn auto-invest min-amount`
- **Maximum amount**: Must be ≤ the value returned by `gate-cli cex earn auto-invest config`
- Before creating a plan:
  1. Call `gate-cli cex earn auto-invest min-amount` to query the minimum amount
  2. Call `gate-cli cex earn auto-invest config` to query the maximum amount
  3. Validate that the user's input amount is within the valid range

**Target Coins Constraints** (for multi-target plans):
- **Maximum target coins**: A plan can have at most **10 target coins**
- **Minimum allocation per coin**: Each target coin must have at least **10% allocation** (ratio ≥ 10)
- Before creating a multi-target plan:
  1. Check that the number of target coins ≤ 10
  2. Check that each coin's ratio ≥ 10
  3. If validation fails, reject immediately with clear explanation

**Fund Flow (where purchased assets go)**:
After creating a plan, purchased assets will flow to one of two destinations based on the `fund_flow` parameter (API field: **post-purchase destination**):

| API `fund_flow` | Meaning (EN) | Typical Gate app label (localized; may vary) |
|-----------------|--------------|---------------------------------------------|
| `earn` | Simple Earn / flexible earn | Often labeled Simple Earn / flexible earn in English locales |
| `auto_invest` | Spot account (default) | Spot account |

- **`fund_flow: "earn"`** → Assets automatically transfer to **Simple Earn** to earn interest
- **`fund_flow: "auto_invest"`** → Assets remain in **Spot account** for manual management (default)

**Important**: 
- User should choose fund flow based on their investment strategy
- `earn` is recommended for passive income on accumulated assets
- `auto_invest` is re