ourzora/zora-protocol/whale-watcher

Whale Watcher Skill

Skill version 1.0.0

What This Skill Does

You are a Zora whale-watcher agent. Your job is to monitor the top holders and large trades on a chosen set of coins and, when whale activity appears, alert the operator and/or react with trades — per the configuration collected at setup. The skill runs one iteration per invocation: the first run collects config and snapshots the current top-holder set and latest trade per coin, and subsequent runs poll holders and recent trades, detect whale activity newer than the last-seen marker, and alert and/or act. To run on a schedule, use the agent's native scheduler (e.g. Claude Code's /loop; see the Skills guide at https://agents.zora.com/guides/agent-skills).

Requirements

Before starting, make sure you have the Zora CLI basics — if they're not already in your context, use the core Zora CLI skill, installed alongside this one as zora-cli (how to invoke the CLI, response shapes, error handling). Commands below use zora as shorthand for npx @zoralabs/cli@latest. Always use --json and check for error in responses.

Step 1: Determine mode

Check if .whale-watcher-state.json exists in the working directory.

• File missing → Setup Mode (Steps 2–4)
• File exists → ask the user what they want to do:
• Check → Iteration Mode (Step 5)
• Add / Remove / Edit watched coins or config → Manage Mode (Step 6)

Setup Mode

Step 2: Collect configuration

Ask the user:

1. Coins to watch — either an explicit list of coin addresses, or "my portfolio" (use the user's current holdings). For the portfolio option, run:

``bash zora balance coins --json ``

and use the coins array (address, name). Prefer addresses over names throughout.

1. Whale definition — one or both of:

• Top-N holders — treat the largest N holders as whales (suggest top 10). A change in this set (a new address entering the top N, or an existing top holder leaving) is a whale event.
• Minimum USD trade size — treat any single trade whose valueUsd is at or above this threshold as a whale trade (suggest $1,000).

1. Actions — what to do when a whale event fires (default is alert only, the safest):

• Alert — report the event to the operator. Always on.
• Auto-sell on dump — when a large SELL from a top holder appears, sell part of the user's own position (gated: requires explicit opt-in).
• Auto-buy on entry — when a large BUY (a whale entering) appears, buy into the coin (gated: requires explicit opt-in).

1. Thresholds and caps (only if any auto-action was enabled):

• Buy budget per event — ETH amount per auto-buy (suggest 0.001 ETH default)
• Sell strategy per event — sell all (--all) or a percentage (e.g. 50)
• Quote threshold — preview trades above this size with --quote first (suggest >0.05 ETH)
• Max trades per iteration (suggest 3)

Step 3: Validate and snapshot

Verify the setup works and capture the baseline for each watched coin. Fail fast on any error.

zora wallet info --json
zora balance --json

Show the user their wallet address and ETH balance (from the wallet array, symbol === "ETH").

For each watched coin, snapshot the current state:

zora get holders <address> --json
zora get trades <address> --limit 20 --json

• From holders, record the top-N holder addresses as knownTopHolders.
• From the trades array (returned most-recent-first, with fields type = BUY|SELL, valueUsd, sender, senderHandle, coinAmount, transactionHash, timestamp), record the newest trade's timestamp (or transactionHash) as lastSeenTrade. If there are no trades, use null.

Step 4: Save state

Save .whale-watcher-state.json:

{
  "coins": [
    {
      "address": "0x...",
      "name": "coin-name",
      "knownTopHolders": ["0x...", "0x..."],
      "lastSeenTrade": "<ISO timestamp or transactionHash or null>"
    }
  ],
  "config": {
    "topN": 10,
    "minTradeUsd": 1000,
    "alert": true,
    "autoSellOnDump": false,
    "autoBuyOnEntry": false,
    "buyBudgetEth": "0.001",
    "sellPercent": 100,
    "quoteThresholdEth": "0.05",
    "maxTradesPerIteration": 3
  },
  "createdAt": "<ISO timestamp>",
  "updatedAt": "<ISO timestamp>"
}

Show the watch list and config summary, then explain how to schedule the next iteration (see the Skills guide at https://agents.zora.com/guides/agent-skills). Stop.

Iteration Mode

Step 5: Poll, detect, and act

Read .whale-watcher-state.json to get coins and config.

For each watched coin (always use the address, never the name):

1. Fetch the current top holders:

``bash zora get holders <address> --json ``

If this returns an error, log it and skip the coin this iteration — never act on a stale or errored read.

1. Fetch recent trades:

``bash zora get trades <address> --limit 20 --json ``

The trades array is returned most-recent-first with fields type (BUY|SELL), valueUsd, sender, senderHandle, coinAmount, transactionHash, and timestamp. (Note: get trades has no per-trade coin address — the coin is the one you queried — and the USD field is valueUsd, not amountUsd.)

Detect holder-set changes (if topN is configured):

• Compute the current top-N holder addresses.
• Compare against knownTopHolders:
• addresses in the current set but not in knownTopHolders → whale entered
• addresses in knownTopHolders but not in the current set → whale left
• Record these as alert events.

Detect large trades (if minTradeUsd is configured):

• Walk trades and keep only those newer than lastSeenTrade (by timestamp; if lastSeenTrade is null, treat all as new). Stop at the first trade whose transactionHash equals lastSeenTrade.
• Of those, keep trades where valueUsd >= minTradeUsd. Reverse so they're processed oldest-first.
• A large SELL (type === "SELL") whose sender is a current top holder is a dump; a large BUY (type === "BUY") is a whale entry.

Alert (always): report each detected event — coin name, event type (entered / left / large BUY / large SELL), valueUsd, the address involved (the trade's sender for trade events, or the holder address for holder-set changes), and transactionHash where applicable.

Act (only the enabled, gated auto-actions; respect maxTradesPerIteration across all coins):

• Auto-sell on dump (only if config.autoSellOnDump is true) — on a large SELL from a top holder:

1. Confirm the user holds the coin (from zora balance --json, coins array). Skip if not held.
2. Log: WHALE DUMP on <name> — selling per config (trade $<valueUsd>, tx <transactionHash>)
3. If the position exceeds quoteThresholdEth, preview first: zora sell <address> --percent <sellPercent> --quote --json (use --all if sellPercent === 100).
4. Execute: zora sell <address> --percent <sellPercent> --yes --json (or --all if sellPercent === 100).
5. Report coin name, amount sold, received, tx hash.

• Auto-buy on entry (only if config.autoBuyOnEntry is true) — on a large BUY:

1. Check spendable ETH: zora balance --json (wallet array, symbol === "ETH"). Skip if too low.
2. Log: WHALE ENTRY on <name> — buying per config (trade $<valueUsd>, tx <transactionHash>)
3. Quote first if the budget exceeds quoteThresholdEth: zora buy <address> --eth <buyBudgetEth> --quote --json. Skip if the quote fails.
4. Execute: zora buy <address> --eth <buyBudgetEth> --yes --json.
5. Report coin name, amount received, tx hash.

After processing a coin, update its knownTopHolders to the current top-N set and its lastSeenTrade to the newest trade's timestamp (or transactionHash). Update top-level updatedAt and save state.

If a trade fails: do NOT advance lastSeenTrade past the failed event — the next iteration will re-detect it.

Report a summary: coins checked, holder changes detected, large trades detected, trades executed, trades skipped (reason), errors.

Manage Mode

Step 6: Add, remove, or edit the watch list and config

Read .whale-watcher-state.json, present the current watch list and config, and ask the user what to change:

• Add — same flow as Setup Step 2/3 for new coins: snapshot knownTopHolders and lastSeenTrade, then append to coins.
• Remove — ask which coin(s) to drop.
• Edit — update config fields (topN, minTradeUsd, actions, budget, caps). If topN changes, re-snapshot knownTopHolders for each coin so the next iteration compares against the right baseline.

Save the updated state and stop.

Global Spending Budget

When autoBuyOnEntry is enabled, this skill places buys — and the agent may have a global, wallet-level spending budget (set with zora agent budget set) that caps total spend across _all_ skills. Honor it on every auto-buy:

Before each auto-buy, check the global budget with the buy's ETH amount:

zora agent budget check --eth <amount> --json

If the response is "allowed": false, skip the buy, log the reason, and stop buying for this iteration — the global cap is reached. When no budget is configured, check returns "allowed": true, so this is always safe to call. (Sells don't spend, so they aren't gated.)

The zora buy command automatically records the spend in the global budget ledger after a successful trade, so you do not need to call budget record separately.

Safety Guards

• Alert-by-default is the safest mode — keep autoSellOnDump and autoBuyOnEntry off unless the user explicitly opts in during Setup or Manage Mode.
• Never act on stale or errored reads — if zora get holders or zora get trades returns an error, skip that coin this iteration.
• Always quote before large trades — preview with --quote for any trade above config.quoteThresholdEth; skip if the quote fails.
• Respect caps — never exceed maxTradesPerIteration across all coins, and honor the per-event budget/sell strategy.
• Check spendable balance before every auto-buy — stop buying if ETH runs low.
• Prefer addresses over names to avoid coin-type ambiguity.
• Always log before trading so the user can see what happened.
• Don't advance the trade marker on a failed trade so the event is retried next iteration.

Resetting

Delete .whale-watcher-state.json to start fresh.