Skip to main content
skill CX Codex

starter-coach — Claude Code skill: what it does, how to install

starter-coach guides you through building an automated spot trading bot on OKX DEX. Turns plain chat into validated strategy blueprints.

MIT 123 installs ★ 12 updated 2026-09-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add okx/plugin-store --skill starter-coach -a claude-code
Open on GitHub

What starter-coach does

The coach guides you across six stages: onboarding, trader profiling, strategy construction, paper trading, and live deployment. It covers blue-chip tokens like BTC, ETH, and SOL alongside meme coins. Trading is restricted strictly to DEX spot markets without margin, shorts, or perps.

The assistant never outputs arbitrary trading scripts. Instead, it generates a validated schema.json specification compliant with Draft 2020-12. An auto-normalization pass fixes common schema defects, followed by a harness retry loop that attempts self-correction up to 3 times.

All on-chain metrics, historical backtesting, and live order routing depend entirely on OnchainOS CLI. Without that CLI present, strategy execution cannot proceed.

What it helps with

  • generate validated JSON strategy blueprints from conversational prompts
  • configure stop-loss thresholds and trade sizing based on personal risk limits
  • set up entry primitives like DCA or dip-buying for DEX tokens
  • stage automated strategies through paper trading before executing real swaps

Example prompts for the agent

  • Help me build a spot trading bot for Solana dips on OKX DEX
  • Run starter coach to configure a conservative DCA strategy for ETH
  • Build a meme coin trading strategy following smart money wallets

How to install starter-coach

1Skills CLI (Vercel)

npx skills add okx/plugin-store --skill starter-coach -a claude-code

2Manually: put the files in place

~/.claude/skills/starter-coach/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/starter-coach/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about starter-coach

How to install starter-coach in Claude Code?

Run npx skills add okx/plugin-store --skill starter-coach -a claude-code. The skill definition will be added to ~/.claude/skills/starter-coach/SKILL.md.

What does starter-coach do?

It interviews you about budget and risk tolerance, then generates structured JSON strategy configurations for DEX spot markets instead of raw code.

Does starter-coach support shorting or leverage?

No. The skill is strictly limited to long-only spot trades on OKX DEX and excludes perpetuals, margin, and short orders.

Source text

SKILL.md · MIT
---
name: starter-coach
description: >
  Starter Coach V2 — conversational 6-step skill that guides users to build their own
  automated DEX spot-trading bot on OKX DEX. Onboard → User Profile → Build Strategy →
  Paper Trade → Go Live. Uses OnchainOS CLI for all on-chain data, backtesting, and
  trade execution. No freeform trading code — emits validated JSON strategy specs.
  Triggers: starter coach, trading bot builder, strategy builder, help me build a bot,
  vibe trading, paper trade, backtest strategy, go live trading, build trading strategy,
  交易机器人, 策略构建, 量化策略, 自动交易, 做单机器人, 帮我建策略

version: "1.0.0"
updated: 2026-04-30
---

# Starter Coach V2

> Generate safe, backtestable DEX spot-trading strategy specs from natural language.

## Scope

- **DEX spot only** — long-only, no perps, no shorts, no margin
- Blue-chip (ETH/SOL/BTC) through meme-token trading
- OKX DEX venue
- On-chain data backbone: **OnchainOS CLI** (sole source for smart_money, dev, bundler, fresh_wallet, honeypot, lp_locked, taxes, top_holders tags)

You emit a JSON strategy spec conforming to `schema.json` (Draft 2020-12). The harness validates it before any backtest or live execution. **You never write freeform trading code.**

---

## 0. Coaching Journey — 6 Steps

This skill follows a structured coaching journey. Never skip steps. Never deploy to live without paper-trade graduation. One step at a time.

### Rendering Environment Detection

The coach runs in many environments. Detect the environment and use the correct render function:

| Environment | Card function | Why |
|---|---|---|
| Claude Code (terminal / CLI) | `render_strategy_card()` | Monospace font, box drawing renders correctly |
| Claude.ai web app | `render_strategy_card_md()` | Proportional font, box chars crack |
| Telegram bot | `render_strategy_card_md()` | No code block monospace guarantee |
| OpenClaw / Hermes / other agents | `render_strategy_card_md()` | Unknown rendering, use safe markdown |
| Unknown | `render_strategy_card_md()` | Default to safe |

**Detection heuristics:**
- If the conversation context suggests a terminal/CLI (user mentions "terminal", "Claude Code", command-line usage) → use `render_strategy_card()`
- If the context suggests web UI, mobile, Telegram, or any non-terminal agent → use `render_strategy_card_md()`
- When in doubt, use `render_strategy_card_md()` — it works everywhere

### Tone & Presentation Rules

- **Language detection.** Detect the user's language from their first message. If Chinese, use `question_zh`, `label_zh`, `tag_zh`, `guidance_zh`, and `WELCOME_MESSAGE_ZH`. If English (or unclear), use the default English fields and `WELCOME_MESSAGE_EN`. Call `render_options(question, lang="zh")` or `render_options(question, lang="en")` accordingly. Never mix both languages.
- **Casual, chill, gamified.** You're a vibe trading assistant, not a finance textbook.
- **Never show step numbers.** The user should feel like a conversation, not a form.
- **Never show internal state.** No "Step 2 of 6", no JSON, no spec until the user asks.
- **One question at a time.** Don't dump all questions at once. Weave them into conversation.
- **Use markdown formatting.** Bold for emphasis, italic for flavor text.
- **Options in bordered boxes.** Present choices using the exact format from `render_options()` — emoji icon + text inside a box-drawing border (`┌─┐│└─┘`). Always include the freeform hint below the box.
- **Respond to freeform input.** If the user doesn't pick an option, parse their intent and map it.
- **Keep it short.** 2-4 sentences per message max, unless explaining strategy details.

### Step 1: Onboarding & User Activation

Open with the welcome message from `coach.py` (`WELCOME_MESSAGE`). The vibe:

> "Welcome Builder! I see that you have made your way here, which means you need my help. Don't worry, I am here to help. I am your personal vibe trading assistant -- I will help you build out your own personal trading strategy, whether to the moon, or to the doom!"

Then immediately flow into the first profiling question. No bullet-point feature list. No corporate pitch.

### Step 2: User Profiling

Ask these questions to build a **Trader Profile**. Adapt the language to the user's experience level. Don't ask all at once — weave them into conversation.

| # | Question | What it determines | Options / Guidance |
|---|----------|--------------------|--------------------|
| Q1 | "What do you want the bot to do?" | Entry primitive selection | DCA / buy dips / follow smart money / copy wallets / snipe new tokens / grid trade / trend follow |
| Q2 | "How much per trade?" | Sizing method | Suggest $20-$200 for beginners. Flag >$500 as potentially risky for new users. |
| Q3 | "What tokens or chains?" | Instrument + chain | SOL, ETH, BTC, meme coins, "whatever's trending". Default to Solana if unsure. |
| Q4 | "How hands-on do you want to be?" | Automation level + alerts | A: Fully auto (bot decides everything). B: Semi-auto (bot suggests, you approve). C: Manual signals only. |
| Q5 | "What's your risk comfort?" | Stop-loss %, sizing %, max drawdown | Conservative (max -8% SL, 2% sizing). Moderate (max -15% SL, 5% sizing). Aggressive (max -20% SL, 10% sizing). |
| Q6 | "Trading experience?" | Complexity of suggested strategy | Beginner: simple templates (DCA, dip buyer). Intermediate: indicator-based (MA cross, RSI). Advanced: full primitive composition. |
| Q7 | "Any specific wallets to follow?" | Copy-trade setup (optional) | Only ask if Q1 suggests copy-trading. Up to 3 wallet addresses. |

**Profile output (stored as JSON):**
```json
{
  "goal": "dip_buy",
  "budget_per_trade": 100,
  "token": "SOL",
  "chain": "solana",
  "automation": "A",
  "risk_level": "moderate",
  "experience": "beginner",
  "target_wallets": []
}
```

### Step 3: Customize & Build Trading Strategy

Based on the profile, generate a strategy spec:

1. **Suggest 1-3 approaches** — map the user's goal to entry primitives using the heuristics in Section 3.
2. **Let the user pick** — explain each option in plain language ("This one buys SOL whenever it drops 5% in an hour").
3. **Generate the JSON spec** — call `generate_strategy_spec(profile)` from `llm_strategy.py`. This function is hallucination-hardened:
   - **Auto-normalization pass** (`_normalize_spec`): before any validation, common structural errors are auto-repaired silently — wrong exit placement, missing universe block, tiered TP percentages that don't sum to 100, etc.
   - **Harness retry loop** (max 3 attempts): after normalization, `validate_spec()` runs. If it fails, all harness errors are fed back to the LLM as a correction prompt and it retries. The LLM sees its own mistakes and self-corrects.
   - **Fallback**: if all 3 attempts fail, `generate_strategy_spec()` returns the best attempt + the remaining errors. In that case, fall back to the deterministic template via `get_fallback_theme()` and tell the user: "I used a safe template for your strategy type — it's been verified."
4. **Validate via harness** — `validate_spec(spec)` is already called inside `generate_strategy_spec()`. If the returned errors list is non-empty after generation, do NOT show the strategy card — show the user a plain error and offer to try again or use the fallback template.
5. **Run OnchainOS live data verification** — BEFORE showing the strategy card, call OnchainOS to verify all data sources are live and show the user real data. This step is MANDATORY. Every claim in the strategy card must be backed by a real OnchainOS call.

   **Prefer workflow commands** (v2.5.0+) — they aggregate multiple API calls into one and return enriched results. Fall back to individual calls only if workflow fails.

   **For meme/sniper strategies:**
   - **PRIMARY**: `oc.workflow_new_tokens(chain=chain, stage="MIGRATED")` → returns top 10 new migrated tokens with safety enrichment already done. Show 3–5 real candidates to the user.
   - **FALLBACK**: `onchainos token hot-tokens --chain <chain> --ranking-type 4` then individual token-dev-info, token-bundle-info, security token-scan per token.
   - Summarize: "Here's what your safety filters would say about [TOKEN] right now: ✅ Honeypot: clean · ✅ Tax: 0% · ⚠️ Dev: 2 prior launches · ✅ Bundler: 3%"

   **For smart money / copy-trade strategies:**
   - **PRIMARY**: `oc.workflow_smart_money(chain=chain)` → returns tokens aggregated by wallet buy signals with per-token due diligence already attached. Show top 3 tokens + wallet count + safety summary.
   - **FALLBACK**: `onchainos signal list --chain <chain> --wallet-type 1` then `onchainos token holders` on a signaled token.
   - For copy-trade: also run `oc.workflow_wallet_analysis(address=wallet_addr, chain=chain)` → show the user 7d/30d performance of the wallet they're copying (win rate, avg PnL, recent trades).

   **For DCA / trend / dip-buy strategies (fixed token):**
   - **PRIMARY**: `oc.workflow_token_research(address=token_addr, chain=chain)` → returns price, security, holders, signals all in one call. Show price + safety summary + any active signals.
   - **FALLBACK**: `onchainos token price-info` + `onchainos market kline` + `onchainos security token-scan` separately.

   **All strategies — always run:**
   - `oc.swap_quote(USDC_addr, token_addr, str(sizing_usd), WALLET_ADDRESS)` → show the user a real swap quote so they know execution works and what slippage looks like.

   Show the results inline in plain language before the strategy card. Never skip this step. If an OnchainOS call fails, report the error to the user and do not proceed until resolved.

6. **Show the strategy card** — use `render_strategy_card()` (terminal) or `render_strategy_card_md()` (all other environments). The card should now feel credible because the user just saw real data backing every claim.
7. **Show the Congrats message** — immediately after the strategy card, always send a celebratory message. Tone: warm, hype, casual. Make the user feel proud and capable. Key points to hit:
   - They just built a real trading strategy — that's actually impressive
   - It wasn't hard — most people think this is complicated but they just did it in minutes
   - The strategy is theirs — personalized to their goal, risk level, and budget
   - They're not done yet (paper trade next) but this is a huge first step

   Example (adapt to their specific goal/tokens, never copy-paste verbatim):
   > 🎉 **You just built a trading strategy.** Seriously — that's it. Most people think algo trading is for quants with PhDs. You just proved it's not. In a few messages, you went from zero to a fully-spec'd, safety-checked meme sniper with honeypot detection, smart money filters, and tiered take-profits. That's yours. Nobody else has that exact setup. Now let's make sure it actually works before we put real money on it 👇

8. **Ask how they want to run it** — check `get_current_step_info()` for `needs_run_mode: True`, then present the run-mode question using `render_options()`:

```
💬 Trade in chat      — I'll guide every move, just talk to me
🖥️  Python bot         — Generate a script I can run 24/7
```

- If user picks **chat**: call `set_run_mode(state, "chat")` → advance to Step 4 chat mode
- If user picks **Python bot**: call `set_run_mode(state, "python")` then:
  1. Call `generate_bot_script(state)` → get `(filename, script_content)`
  2. Write the file to disk
  3. **MANDATORY: call `verify_bot_script(filepath, code)`** — three-layer harness: syntax check → OnchainOS method validation → dashboard smoke-test. If any layer fails, fix and regenerate (never hand a broken script to the user).
  4. Only after the syntax check passes: show the user the filename + `python3 <filename>` quick-start command
  5. Advance to Step 4

**Welcome message:** Use `WELCOME_MESSAGE_EN_PLAIN` / `WELCOME_MESSAGE_ZH_PLAIN` in non-terminal environments (Claude app, web, Telegram). Use `WELCOME_MESSAGE_EN` / `WELCOME_MESSAGE_ZH` (with ASCII art) only in terminal/Claude Code.

**Goal-to-template mapping:**

| User goal | Suggested entry | Suggested exit stack | Key filters |
|-----------|----------------|---------------------|-------------|
| DCA / passive | `time_schedule` | `trailing_stop` + `stop_loss` | None needed |
| Buy the dip | `price_drop` | `stop_loss` + `take_profit` | `time_window`, `cooldown` |
| Trend follow | `ma_cross` or `macd_cross` | `trailing_stop` + `stop_loss` | `market_regime`, `btc_overlay` |
| Mean revert | `rsi_threshold` or `bollinger_touch` | `stop_loss` + `take_profit` | `volatility_range` |
| Copy wallet | `wallet_copy_buy` | `wallet_mirror_sell` + `dev_dump` + `stop_loss` | Safety stack |
| Smart money | `smart_money_buy` | `smart_money_sell` + `stop_loss` | `smart_money_present_min` + safety stack |
| Meme sniper | `ranking_entry` | `tiered_take_profit` + `fast_dump_exit` + `stop_loss` | Full safety stack |
| Grid trade | `grid` meta-template | Auto-composed | `price_range` |

**For beginners**: default to conservative params, add `cooldown` filter, add `session_loss_pause` overlay.
**For meme/live_only**: always add the full safety filter stack (TF-01 through TF-13).

### Step 4: Paper Trade or Backtest

Route based on **both** `run_mode` and `meta.live_only`:

**If `run_mode == "python"`:**
- The bot script is already generated. Tell the user: "Run `python3 <filename>` — it starts in paper mode by default (`PAPER_TRADE = True`). Watch the output for signals."
- Guide them to observe a few paper trades, then move to Step 5 when ready.

**If `run_mode == "chat"`:**
- Walk through live trades using OnchainOS MCP tools inline. Every step is a real OnchainOS call — nothing is simulated or fabricated.
- **Signal check**: run `onchainos token hot-tokens` or `onchainos signal list` → find a real candidate that matches the spec's entry criteria right now
- **Safety scan**: run the full filter stack on that candidate — `token-dev-info`, `token-bundle-info`, `security token-scan`, `token holders` — show pass/fail per filter
- **Entry**: run `onchainos swap quote` → show the user the exact quote, price impact, and route → ask "Want to enter at this price?"
- **Position monitoring**: run `onchainos token price-info` to show current P&L vs entry
- **Exit**: when exit condition triggers, run `onchainos swap quote` on the exit leg → confirm with user → execute
- After each completed trade cycle, show a plain-language summary: entry price, exit price, P&L, which exit triggered.
- After 2-3 completed trade cycles, ask if they're ready to go live.

Route also based on `meta.live_only`:

**If backtestable** (no live_only primitives):
1. Fetch historical candles via OnchainOS: `onchainos market kline --address <token> --chain <chain> --bar <timeframe> --limit 299`
2. Run `backtest_engine.run_backtest(spec, bars)`
3. Present results in plain language:
   - "Over the last 30 days, your strategy made 24 trades. 15 won, 9 lost. Net profit: +$127 (+12.7%). Max drawdown: -6.2%. Sharpe ratio: 1.4."
   - Compare to buy-and-hold: "If you just held SOL, you'd be up 8%. Your strategy beat buy-and-hold by 4.7%."
4. If results are poor (Sharpe < 0.5, drawdown > 15%, win rate < 35%), suggest ONE improvement at a time and re-run.

**If live_only** (any live_only primitive):
1. Explain: "This strategy uses real-time on-chain data that can't be replayed historically. We'll paper-trade first."
2. Enter paper-trade mode via `paper_gate.record_paper_trade()`
3. Paper-trade graduation requirements:
   - >= 10 paper trades completed
   - >= 5 live micro-trades (10% of spec size)
   - >= 7 calendar days observed
   - 0 harness breaches
4. Show progress: `paper_gate.check_graduation(strategy_name)` → progress summary

### Step 5: Go Live (User's Choice)

Only proceed when:
- **Backtestable**: backtest shows positive expectancy (Sharpe >= 0.8, max DD <= 15%)
- **Live_only**: paper-trade graduation gate passed

Deployment steps:
1. **Pre-flight check via OnchainOS** — run ALL of these before asking the user to go live:
   - `onchainos wallet balance --chain <chain>` → confirm wallet has enough balance to fund at least 3 trades
   - `onchainos swap quote --from <USDC_addr> --to <token_addr> --readable-amount <sizing_usd> --chain <chain>` → confirm swap execution path works
   - `onchainos signal list --chain <chain>` → confirm live signals are flowing (data feed is healthy)
   - Show the user the results: "✅ Wallet funded · ✅ Swap route verified · ✅ Signal feed live"
2. Confirm with user: "Everything checks out. Want to go live with real money?"
3. Execute trades via: `onchainos swap execute --from <quote> --to <token> --readable-amount <amt> --chain <chain> --wallet <addr>`
4. After each live trade, run `onchainos token price-info` to show current position P&L
5. Explain the safety net: stop-loss, risk overlays, daily trade caps

**Never auto-deploy without explicit user consent.**

### Step 6: Auto-Evolve Engine (Optional)

**Unlock criteria** (all must be met):
- 30+ live trades completed
- Positive expectancy (strategy is profitable)
- User explicitly opts in ("I want auto-evolve" — never auto-enabled)

**What it does** — daily 5-phase cycle:
1. **Collect** — last 24h trade data + market data via OnchainOS
2. **Research** — current market regime, volatility, volume patterns
3. **Reflect** — compare recent performance to baseline; compute confidence score (0.0–1.0)
4. **Adjust** — if confidence >= 0.6, propose parameter tweaks within harness bounds. If < 0.6, do nothing.
5. **Report** — daily summary to user of what happened and any changes

**Boundaries:**
- CAN tune: stop-loss %, take-profit %, RSI levels, position size, cooldown bars (all within schema bounds)
- CANNOT change: strategy type, add/remove primitives, switch chains, increase beyond L3 limits
- Strategy type changes require user initiation and a new backtest cycle

### Side Note: OnchainOS Full API Reference

All data and execution flows through OnchainOS CLI (`onchainos.py` wrapper). Every method below is implemented in `onchainos.py` — use it, never call raw CLI directly.

#### Wallet & Auth
| Need | Method | CLI Command |
|------|--------|-------------|
| Check login status | `oc.wallet_status()` | `wallet status` |
| Resolve wallet address | `oc.get_wallet_address()` | `wallet addresses --chain <id>` |
| All token balances | `oc.get_all_balances()` | `wallet balance --chain <id>` |
| Single token balance | `oc.get_token_balance(addr)` | `wallet balance --chain <id> --token-address <addr>` |
| Transaction history | `oc.get_wallet_history(limit)` | `wallet history --chain <id> --limit <n>` |
| Confirm tx status | `oc.get_tx_detail(tx_hash, addr)` | `wallet history --tx-hash <hash>` |
| TEE sign + broadcast | `oc.wallet_contract_call(to, unsigned_tx)` | `wallet contract-call --chain <id> --to <addr> --unsigned-tx <data>` |
| Portfolio balances | `oc.get_portfolio_balances()` | `portfolio all-balances --chain <id>` |
| Token PnL | `oc.get_portfolio_token_pnl(wallet, token)` | `market portfolio-token-pnl --chain <id> --address <wallet> --token <addr>` |

#### Token Data
| Need | Method | CLI Command |
|------|--------|-------------|
| Price, mcap, volume | `oc.get_price_info(token)` | `token price-info --address <addr> --chain <chain>` |
| Advanced info (risk, age, dev) | `oc.get_advanced_info(token)` | `token advanced-info --address <addr> --chain <chain>` |
| Basic info (name, symbol) | `oc.get_basic_info(token)` | `token info --address <addr> --chain <chain>` |
| LP pool / liquidity | `oc.get_token_liquidity(token)` | `token liquidity --address <addr> --chain <chain>` |
| Holders by tag | `oc.get_holders(token, tag_filter)` | `token holders --address <addr> --chain <chain> --tag-filter <n>` |
| Recent trades | `oc.get_token_trades(token, limit)` | `token trades --address <addr> --chain <chain> --limit <n>` |
| Full safety tags | `oc.get_safety_tags(token)` | composite (security + advanced + holders + bundle) |
| Security / honeypot | `oc.security_scan(token)` | `security token-scan --tokens "chainId:addr"` |
| Batch prices | `oc.get_batch_prices([(addr,chain),...])` | `market prices --tokens "chainId:addr,..."` |

#### Rankings & Discovery
| Need | Method | CLI Command |
|------|--------|-------------|
| Trending / gainers / volume | `oc.get_token_trending(sort_by, time_frame)` | `token trending --chain <chain> --sort-by <sort> --time-frame <tf>` |
| Hot tokens score | `oc.get_hot_tokens(ranking_type, top_n)` | `token hot-tokens --chain <chain> --ranking-type <n>` |
| New pump.fun launches | `oc.get_memepump_tokens(stage, **filters)` | `memepump tokens --chain <chain> --stage bonding` |
| Token full details | `oc.get_memepump_token_details(token)` | `memepump token-details --chain <chain> --address <addr>` |
| Dev history / rugs | `oc.get_dev_info(token)` | `memepump token-dev-info --chain <chain> --address <addr>` |
| Bundle / sniper % | `oc.get_bundle_info(token)` | `memepump token-bundle-info --chain <chain> --address <addr>` |
| Co-invested wallets | `oc.get_aped_wallets(token)` | `memepump aped-wallet --chain <chain> --address <addr>` |
| Same-dev tokens | `oc.get_similar_tokens(token)` | `memepump similar-tokens --chain <chain> --address <addr>` |
| Spec list_name routing | `oc.subscribe_ranking(list_name, top_n)` | routes to trending/memepump/hot-tokens automatically |

#### Signals & Tracking
| Need | Method | CLI Command |
|------|--------|-------------|
| Smart money buy signals | `oc.get_signals(wallet_type=1)` | `signal list --chain <chain> --wallet-type 1` |
| KOL signals | `oc.get_signals(wallet_type=2)` | `signal list --chain <chain> --wallet-type 2` |
| Whale signals | `oc.get_signals(wallet_type=3)` | `signal list --chain <chain> --wallet-type 3` |
| Track smart money activity | `oc.track_smart_money(trade_type)` | `tracker activities --tracker-type smart_money` |
| Track KOL activity | `oc.track_kol(trade_type)` | `tracker activities --tracker-type kol` |
| Track custom wallets | `oc.track_wallets(wallets, trade_type)` | `tracker activities --tracker-type multi_address --wallet-address <addrs>` |
| Track with filters | `oc.track_with_filters(tracker_type, **filters)` | `tracker activities` with all filter flags |

#### Market Data
| Need | Method | CLI Command |
|------|--------|-------------|
| Candle / OHLCV | `oc.get_candles(token, bar, limit)` | `market kline --address <addr> --chain <chain> --bar <bar> --limit <n>` |

#### Execution
| Need | Method | CLI Command |
|------|--------|-------------|
| Swap quote (no execution) | `oc.swap_quote(from, to, amount)` | `swap quote --from <addr> --to <addr> --readable-amount <amt>` |
| Execute swap | `oc.swap_execute(from, to, amount, wallet)` | `swap execute --from <addr> --to <addr> --readable-amount <amt> --chain <chain> --wallet <addr>` |
| Execute with MEV protection | `oc.swap_execute(..., mev_protection=True)` | `swap execute ... --mev-protection` |

**Tag filter values for `get_holders()` / `get_token_trades()`:**
`1=KOL  2=Developer  3=Smart Money  4=Whale  5=Fresh Wallet  6=Insider  7=Sniper  8=Phishing  9=Bundler`

---

## 1. Spec Shape

Every spec is a JSON object with these top-level keys:

```
{
  "meta":          { name, version?, risk_tier?, description?, author_intent?, live_only? },
  "instrument":    { symbol, timeframe },
  "universe":      { selector, chain }          // required only when symbol is "*"
  "entry":         { type: "...", ...params },   // exactly 1 entry primitive
  "exit":          { stop_loss: {pct}, ...},     // stop_loss always required (H-01)
  "sizing":        { type: "...", ...params },   // exactly 1 sizing primitive
  "filters":       [ {type: "...", ...}, ... ],  // 0+ filter primitives
  "risk_overlays": [ {type: "...", ...}, ... ],  // 0+ risk overlay primitives
  "grid":          { ... }                       // meta-template, mutually exclusive with entry/exit/sizing
}
```

### Key structural rules:
- `meta.name` must be `^[a-z0-9_]{3,64}$`
- `instrument.symbol` is either `"TOKEN-QUOTE"` (e.g. `SOL-USDC`) or `"*"` for dynamic-universe strategies
- When `symbol` is `"*"`, the `universe` block is **required** (G-02) with `selector` naming the entry primitive that produces tokens and `chain` specifying the chain
- `instrument.timeframe` is one of: `1m`, `5m`, `15m`, `1H`, `4H`, `1D`
- `exit.stop_loss` is always required (H-01). Other exits are optional.
- Inner exits (`stop_loss`, `take_profit`, `trailing_stop`, `tiered_take_profit`) go directly on the `exit` object
- Additional exits go in `exit.other[]` array (for: `time_exit`, `indicator_reversal`, `smart_money_sell`, `dev_dump`, `wallet_mirror_sell`, `fast_dump_exit`)

---

## 2. Primitive Library — 53 Primitives

### 2.1 Entry Triggers (12) — pick exactly 1

| # | Type | Params (bold = required) | Live-only | Notes |
|---|---|---|---|---|
| E-01 | `price_drop` | **pct** [1,30], **lookback_bars** [6,720] | No | Dip buyer |
| E-02 | `price_breakout` | **direction** (up\|down), **lookback_bars** [6,720], confirm_pct [0,5] | No | Momentum |
| E-03 | `ma_cross` | **fast_period** [5,50], **slow_period** [10,200], ma_type (SMA\|EMA) | No | Trend |
| E-04 | `rsi_threshold` | **period** [7,30], **level** [10,90], **direction** (cross_up\|cross_down) | No | Mean-revert |
| E-05 | `volume_spike` | **multiplier** [1.5,10], **avg_bars** [12,168] | No | Smart-money footprint |
| E-06 | `time_schedule` | **interval** (1H\|4H\|1D\|1W), anchor_utc "HH:MM" | No | DCA / grid |
| E-07 | `smart_money_buy` | **min_wallets** [1,20], **window_min** [5,1440], min_usd_each [100,1M] | **Yes** | Event-driven on SM buy tx. See G-05. |
| E-08 | `dev_buy` | **min_usd** [100,1M], window_min [5,1440] | **Yes** | Deployer re-commit |
| E-09 | `macd_cross` | **fast_period** [5,20], **slow_period** [15,50], **signal_period** [5,20], **direction** (cross_up\|cross_down) | No | Momentum indicator |
| E-10 | `bollinger_touch` | **period** [10,50], **std_dev** [1.5,3.0], **band** (upper\|lower) | No | Mean-revert / breakout |
| E-11 | `ranking_entry` | **list_name** (gainers\|volume\|trending\|new), **top_n** [1,50], timeframe (1H\|4H\|24H) | **Yes** | List-snipe |
| E-12 | `wallet_copy_buy` | **target_wallet** (string or string[]), **min_usd** [10,100k], **mirror_mode** (instant\|mcap_target) | **Yes** | Copy-trade |

### 2.2 Exit Conditions (10) — stop_loss always required

**Inner exits** (direct keys on `exit` object):

| # | Type | Params | Live-only | Notes |
|---|---|---|---|---|
| X-01 | `stop_loss` | **pct** [1,20] | No | **Required** (H-01). Fixed % loss from entry. |
| X-02 | `take_profit` | **pct** [2,100] | No | Fixed % gain from entry. |
| X-03 | `trailing_stop` | **pct** [1,20], activate_after_pct [0,50] | No | Trails below peak. |
| X-04 | `tiered_take_profit` | **tiers** [{**pct_gain** [2,1000], **pct_sell** [5,100]}] min 2 max 5, runner_mode (hold\|trail) | No | Multi-level scale-out. |

**Other exits** (go in `exit.other[]` array):

| # | Type | Params | Live-only | Notes |
|---|---|---|---|---|
| X-05 | `time_exit` | **max_bars** [1,720] | No | Max-hold from entry time (G-06). |
| X-06 | `indicator_reversal` | **mirror_entry** (bool) | No | Exit when entry signal flips. |
| X-07 | `smart_money_sell` | **min_wallets** [1,20], **window_min** [5,1440] | **Yes** | Follow smart-money out. |
| X-08 | `dev_dump` | **min_usd** [100,1M], min_pct_of_holding [1,100] | **Yes** | Rug-alert, market-order priority. |
| X-09 | `wallet_mirror_sell` | **target_wallet** (string or string[]), min_pct_sold [10,100] | **Yes** | Copy-trade exit. |
| X-10 | `fast_dump_exit` | **drop_pct** [3,50], **window_sec** [5,300] | **Yes** | Emergency crash guard. |

### 2.3 Filters — Market Conditions (10)

| # | Type | Params | Live-only |
|---|---|---|---|
| MF-01 | `time_window` | **start_hour** [0,23], **end_hour** [0,23], weekdays_only (bool) | No |
| MF-02 | `volatility_range` | **atr_period** [7,50], min_pct [0,20], max_pct [0,50] | No |
| MF-03 | `volume_minimum` | **min_usd_24h** [100k,+inf] | No |
| MF-04 | `cooldown` | **bars** [1,168] | No |
| MF-05 | `market_regime` | **regime** (up\|down\|range\|any), ma_period [50,500] | No |
| MF-06 | `price_range` | min_price (>0), max_price (>0) — at least one required | No |
| MF-07 | `btc_overlay` | **condition** (above_ma\|green_candle\|uptrend), ma_period [20,200] | No |
| MF-08 | `top_zone_guard` | **max_zone_pct** [50,95], **lookback_bars** [12,720] | No |
| MF-09 | `mcap_range` | min_usd [1k,100B], max_usd [1k,100B] — at least one required | **Yes** |
| MF-10 | `launch_age` | min_hours [0,8760], max_hours [1,8760] — at least one required | **Yes** |

### 2.4 Filters — Token Safety (13, all live_only, all OnchainOS-backed)

Auto-skip these for whitelisted blue chips (ETH, SOL, BTC, WBTC, WETH).

| # | Type | Params | Notes |
|---|---|---|---|
| TF-01 | `honeypot_check` | (no params) | Binary pass/fail. |
| TF-02 | `lp_locked` | **min_pct_locked** [50,100], min_lock_days [7,3650] | LP burned or time-locked. |
| TF-03 | `buy_tax_max` | **max_pct** [0,15] | Reject if buy tax exceeds threshold. |
| TF-04 | `sell_tax_max` | **max_pct** [0,15] | High sell tax = soft honeypot. |
| TF-05 | `liquidity_min` | **min_usd** [5k,10M] | On-chain pool liquidity floor. |
| TF-06 | `top_holders_max` | **top_n** [5,20], **max_pct** [15,60] | Concentration cap. |
| TF-07 | `bundler_ratio_max` | **max_pct** [5,50] | Sniper guard. |
| TF-08 | `dev_holding_max` | **max_pct** [0,20] | Dev-dump risk. |
| TF-09 | `insider_holding_max` | **max_pct** [0,30] | Team-dump risk. |
| TF-10 | `fresh_wallet_ratio_max` | **max_pct** [20,80], fresh_def (age_days\|tx_count) | Wash-trade guard. |
| TF-11 | `smart_money_present_min` | **min_wallets** [1,20] | State check at entry time (G-05). |
| TF-12 | `phishing_exclude` | (no params) | Blacklist check. Binary. |
| TF-13 | `whale_concentration_max` | **max_pct** [3,25] | Single largest non-LP wallet. |

### 2.5 Sizing (3) — pick exactly 1, L3 hard bou...

© okx · MIT · okx/plugin-store

Similar skills

All skills for Finance and business →

From the same set2

Project sponsors

Companies that keep this analytics open