/earn-hunter

name: earn-hunter
description: "Automatically monitors OKX Flash Earn, Fixed Earn and Flexible Earn opportunities, sends push notifications, and guides subscription. 自动监控 OKX 闪赚、定期和活期赚币机会，推送通知并引导申购。Use when user says: 有闪赚通知我, 监控赚币, monitor earn, notify me about earn, 定时检查理财, 执行 earn-hunter 扫描, earn-hunter scan, 活期年化高了通知我, 监控活期."
license: MIT
metadata:
  author: okx
  version: "1.4.1"
  homepage: "https://www.okx.com"
  agent:
    requires:
      bins: ["okx"]
    install:
      - id: okx-cli
        kind: node
        package: "@okx_ai/okx-trade-cli@1.4.1"
        bins: ["okx"]
        label: "Install okx CLI (npm)"

Earn Hunter

Automated monitor for OKX Flash Earn, Fixed Earn, and Flexible Earn (Simple Earn) opportunities.

**`{baseDir}`** = the directory containing this SKILL.md file. All relative paths (references/, templates/, config/) are resolved from here.

Preflight

1. Verify `okx` CLI installed: `which okx`. If missing, install via `npm install -g @okx_ai/okx-trade-cli`. On OpenClaw, also verify the in-session `cron` tool is available in the agent tool list (used for scheduling — not the `openclaw` CLI). 2. Check optional dependent skills:

   okx skill list --json

Optional skills (not required for scanning/notifications):

• `okx-cex-earn` — needed for purchase guide (subscription execution)
• `okx-cex-auth` — needed for authentication recovery

If either is missing, attempt to install but **do not block** if installation fails:

   okx skill add okx-cex-earn
   okx skill add okx-cex-auth

• Install succeeds → continue
• Install fails (network error, marketplace unavailable, etc.) → **warn and continue**:

"⚠ `{skill_name}` 安装失败，扫描和通知功能不受影响。申购引导和认证恢复需要该 skill，后续可手动安装。"

• Preflight continues regardless of skill installation result

4. Auth mode detection — run **both**, first match wins:

• `okx config show --json` → has non-empty `api_key` field → **API Key mode**. Add `--profile live` to all commands.
• No API key + `okx auth status --json` → `"status":"logged_in"` → **OAuth mode**. No `--profile` flag needed.
• Neither → **stop**. Load `okx-cex-auth` skill and follow login steps.

5. Init config and state:

• If `~/.okx/earn-hunter/` directory does not exist → `mkdir -p ~/.okx/earn-hunter`
• If `~/.okx/earn-hunter/config.json` does not exist → copy `{baseDir}/config/default.json` to it
• If `~/.okx/earn-hunter/state.json` does not exist → write `{"flash":{},"fixed":{},"flexible":{},"consecutive_failures":0,"last_error":""}`
• If `~/.okx/earn-hunter/platform.json` does not exist → run [Platform Detection](#platform-detection-active-probe--user-confirmation)
• Always (re)install the scan script: `cp {baseDir}/scripts/scan.sh ~/.okx/earn-hunter/scan.sh && chmod +x ~/.okx/earn-hunter/scan.sh`. This is the script cron and interactive scans both call.
• Write `~/.okx/earn-hunter/env.snapshot` with resolved tool paths (cron cannot rely on the user's login PATH):

     cat > ~/.okx/earn-hunter/env.snapshot << SNAP
     # auto-generated by earn-hunter activation — $(date -Iseconds)
     OKX_BIN=$(command -v okx)
     NODE_BIN=$(command -v node)
     JQ_BIN=$(command -v jq)
     ACTIVATION_PATH=$PATH
     SNAP

The scan script sources this file to resolve tool paths even under cron's minimal `PATH=/usr/bin:/bin`.

Config/state/platform JSON read-write done by the agent is only for activation/config management. The recurring **scan itself is performed entirely by `scripts/scan.sh`** (shell + jq) — `jq` is required for scanning. Verify with `which jq`; if missing, install (`brew install jq` / `apt-get install jq`).

Platform & Channel Detection

Three independent dimensions: **platform** (where the agent runs), **scheduler** (what triggers scans), **notification channel** (where alerts go).

Platform Detection (active probe + user confirmation)

**First run (no `platform.json` exists):**

1. Probe environment clues:

• `OPENCLAW_HOME` env var exists? → hint: OpenClaw
• Agent tool list contains `cron` / `delivery` tools? → hint: OpenClaw
• `HERMES_HOME` env var exists or `which hermes` succeeds? → hint: Hermes Agent
• Running inside Claude Code session? → hint: Claude Code
• None of the above matched → hint: Generic

2. Present detection result and **ask user to confirm**:

• "检测到你正在使用 **{detected_platform}**，是否正确？"
• User confirms → proceed
• User says no → ask: "你使用的是哪个平台？1) OpenClaw 2) Claude Code 3) Hermes Agent 4) 其他"

3. Initialize platform config:

• OpenClaw / Claude Code → copy `{baseDir}/config/<confirmed_platform>.default.json` to `~/.okx/earn-hunter/platform.json`
• Hermes Agent → copy `{baseDir}/config/claude-code.default.json` as base, set `.platform` to `"hermes"`, `.scheduler.type` to `"cron"`
• Generic → copy `{baseDir}/config/claude-code.default.json` as base, set `.platform` to `"generic"`, `.scheduler.type` to `"manual"`

4. Result written to `~/.okx/earn-hunter/platform.json`, subsequent runs skip detection.

**Subsequent runs (platform.json exists):** Read `~/.okx/earn-hunter/platform.json` and extract the `.platform` field (returns `"openclaw"`, `"claude-code"`, `"hermes"`, or `"generic"`).

**No scheduler available on detected platform** (only applies to platforms that should have one but don't) → error: "当前客户端不支持定时任务，请升级到最新版本。" **Generic platform** → no automatic scheduler. Inform: "当前平台不支持自动调度，你可以手动说'执行 earn-hunter 扫描'来触发。"

Configuration Files

| File | Scope | Content | |---|---|---| | `config.json` | Shared | Scan scope (flash/fixed/flexible), currencies, APY thresholds, terms, language, verboseLog | | `platform.json` | Platform-specific | Scheduler type/interval, notification channel, TG/Lark credentials | | `state.json` | Shared | Dedup state |

Core config (`config.json`) is identical across platforms. Platform config (`platform.json`) differs — the `scheduler.type` field determines how scans