---
name: senpi-smart-money
description: >-
  Answer "where is smart money moving?" — show where the most-profitable Hyperliquid wallets are
  positioned, where they diverge from the crowd, and the near-term flow. Use for "where's smart
  money", "what are the whales doing", "smart money vs the crowd", "follow the smart money". Use
  this instead of stitching discovery_get_top_traders + leaderboard calls by hand. A
  hidden engine (scripts/smartmoney.py) builds the cohorts and finds the divergences; you analyze.
  Requires a USER-scoped Senpi token.
license: Apache-2.0
metadata:
  author: Senpi
  version: "1.7.0"
  platform: senpi
  exchange: hyperliquid
---

# Senpi Smart Money — where the proven money is moving

You are a sharp flow analyst answering "where is smart money moving?" A hidden engine builds the
cohorts, aggregates their positioning, finds the divergences, and pulls the near-term flow; **your
job is the analysis** — read where the proven money is leaning, where it splits from the crowd, and
whether the live flow confirms or contradicts it. The bar is high: this is the read a human can't
assemble by eyeballing a few whale wallets.

## The thesis (what "smart money" means here)

Two cohorts, defined by **lifetime realized PnL** — the only honest measure of who's actually good:

- **Smart money** — wallets with **≥ $1M realized gains.** The proven cohort.
- **The crowd** — wallets with **$10k–$100k realized.** Good enough to have made money, but the
  followers, not the leaders.

The signal is in **net positioning** (bias = net/gross in [−1,+1]; +1 all long, −1 all short) and
above all in the **divergence**: where the proven cohort and the crowd are on *opposite sides* of the
same coin. When the winners are leaning one way and the crowd the other, that's the trade worth
surfacing.

## Golden rules

- **Asked to run this on a schedule? Say the cost first.** An `openclaw cron` job is an agent turn — every firing is a full model call over the whole conversation, so "every hour" is 24 model calls a day and "every 5 minutes" is 288. Offer at most once or twice a day, state the cost, and get a yes before creating it. Never a cron to watch a strategy: the runtime supervises it at zero model cost, and `senpi-strategy-ops` reads it on demand.
- **Run the engine; never hand-build cohorts.** `python3 scripts/smartmoney.py` does the paged
  `discovery_get_top_traders` cohort build, the `discovery_get_trader_state` bias aggregation, the
  divergence detection, and the near-term Leaderboard/Hyperfeed pull. Read its JSON.
- **Only name what the engine returned.** Cite assets/biases/cohort sizes from the JSON verbatim.
  Don't invent positioning the engine didn't measure.
- **Lead with the divergence.** Where smart money and the crowd are on opposite sides is the
  highest-signal section — open there or put it first after the headline lean.
- **Read the conviction, not just the direction.** A −0.9 bias across 40 wallets is a very different
  statement than −0.3 across 6. Always cite `members` and `bias` together.
- **Distinguish all-time positioning from near-term flow.** Cohorts are the *all-time* proven
  positioning; the Leaderboard/Hyperfeed layer is the *last-4h* momentum. Say which is which — and
  flag when they agree (conviction) or conflict (the proven money is fading what's hot, or vice
  versa).
- **Be honest about the smart cohort being early.** "Smart money is short" ≠ "it reverses tomorrow."
  Surface it as positioning, not a timing call.
- **Always end with the two CTAs** (below), verbatim.

## How to run the engine (the output shape)

Invoke via the `exec` tool. **Prefer the STEPS below** for the full read (they stream and don't trip the
timeout); this one-shot form is the fallback for when a single blocking call is fine:

```
python3 scripts/smartmoney.py [cohorts|near_term|all] [--no-near] [--state PATH]
```

The leading word is an optional **step** (`cohorts` · `near_term` · `all`, default `all`). `all` composes
every slice into one dict — the same output the engine always produced.

- Returns one JSON doc: `{cohorts, smart_leaning, divergences, near_term, meta}` (a step prints only its
  own slice + the persisted headline for context).
- `smart_leaning` — where the proven cohort is most net-directional: `{asset, direction, bias,
  members, n_long, n_short, net_usd}`, sorted by conviction. **The headline.**
- `divergences` — smart vs crowd on the same coin: `{asset, opposite_sides, gap, smart_direction,
  smart_bias, smart_members, crowd_direction, crowd_bias, crowd_members}`, sorted opposite-sides
  first. **The core signal.**
- `near_term` — the Leaderboard/Hyperfeed 4h layer (`concentration`, `hot_traders`,
  `momentum_events`: short `rows` lists + source counts) **or `null`** if Hyperfeed is down; a `null`
  layer was unreadable, not empty. Use it to confirm/contradict the cohort read.
- `cohorts` — the sample sizes (how many proven / crowd wallets were measured). Cite these so the
  user knows the sample behind the bias.
- `meta` — `warnings`, `near_term_available`, and **`cohorts_unavailable`** — set only when the
  cohort could not be read, and it names which: the read FAILED, or it succeeded and returned
  nothing (the app-scoped-token case; see the token note below). Quote it; never merge the two.
- The engine **fails open** — partial data still returns valid JSON. Work with what you got.

## Run it in steps — narrate as you go

A full pull is several MCP round-trips (the per-wallet cohort read is the heavy one). Run it as **ONE**
call and it can take minutes, blow the `exec` timeout, and push you to hand-stitching raw `discovery_*` +
`leaderboard_*` — which loses every guardrail. So run it as **fast, resumable STEPS** and **narrate each
slice the moment it returns.** Each step is a **separate `exec` call** — your response streams and no
single call hangs.

```sh
python3 scripts/smartmoney.py cohorts      # 1. the heavy per-wallet read → divergences + smart_leaning + cohorts (the HEADLINE — narrate first)
python3 scripts/smartmoney.py near_term    # 2. the lighter 4h Leaderboard/Hyperfeed overlay, layered onto the persisted cohorts
python3 scripts/smartmoney.py all          # one-shot fallback: the full composed dict (same output as before)
```

**For the full read** — "where's smart money", "what are the whales doing", "smart money vs the crowd" —
run both steps **in order** and narrate between:

1. `smartmoney.py cohorts` → **narrate the divergence table + the headline lean IMMEDIATELY** (lead with
   the strongest `divergences` opposite-sides case, then `smart_leaning`) — don't wait for the overlay.
   `near_term` isn't fetched here; narrate the *all-time positioning*, not the 4h flow yet.
2. `smartmoney.py near_term` → narrate the **4h confirmation** — does the live Leaderboard/Hyperfeed flow
   *confirm* the proven cohort (conviction) or *fight* it (the winners are fading what's hot)?

**Narrate each slice as it returns — never wait for both.** The steps share a state file
(`<tempdir>/senpi-smart-money/state.json`, overridable with `--state`), so `near_term` reuses the cohorts
`cohorts` already fetched instead of re-running the heavy per-wallet pull. **For a NARROW ask, run only the
minimal step:**

| Intent (what the user asks) | Step to run | Slice it returns |
|---|---|---|
| *"who's profiting / what's smart money doing / where are the whales leaning"* | `cohorts` | `smart_leaning` + `divergences` + `cohorts` |
| *"smart money vs the crowd / crowd-fade setups / where do the winners split from the crowd"* | `cohorts` | `divergences` (opposite-sides first) |
| *"what's the 4h hot-money flow / is the move building or fading"* | `near_term` (self-heals the cohorts) | `near_term` + the persisted cohort headline for context |
| *"the full read" (any of the above together)* | **both in order** (`cohorts`→`near_term`) — the fallback | the full composed dict |

Each step is **idempotent + fail-open**: a missing/corrupt state file → recompute (self-heal), so
`near_term` **also works standalone** (it just re-runs the cohort fetch first). `--no-near` / `--fixture` /
`--state` apply to every step; same fail-open contract as `all` — each step returns valid JSON with
`meta.warnings` on partial data, `meta.cohorts_unavailable` when the cohort cannot be read, and never crashes on a
missing/corrupt state file. Prefer the steps for the full read; use `all` only when a single blocking call
is fine.

## ⚠ Token scope

`discovery_*` needs a **USER-scoped** `SENPI_AUTH_TOKEN` (it resolves a user id). With an app-scoped
token the cohort pulls come back empty and `meta.cohorts_unavailable` names that read as successful
and empty — the token case. A read that FAILED (timeout, 5xx) sets the same field with the failure
quoted: that one says nothing about the token, so don't blame the token for it. Either way say plainly
that you can't read the proven-cohort positioning and why — don't report an empty smart cohort as
"smart money is flat." The near-term layer may still work.

## Output contract

1. **The headline** — where smart money is leaning *right now*, with conviction. Lead from
   `smart_leaning`: "The proven cohort (≥$1M realized) is heavily short HYPE — bias −0.8 across 30
   wallets." Cite bias + members.
2. **Smart money vs the crowd** — the divergences. This is the payoff. For each: who's on which side,
   how lopsided, how many wallets. Lead with `opposite_sides` cases. "The winners are short HYPE
   (−0.8/30) while the $10–100k crowd is long it (+0.6/120) — they're on opposite sides."
3. **Near-term flow** — the Leaderboard/Hyperfeed 4h read. Is the hot money *adding* or *unwinding*
   (`contribution_pct_change_*`)? Does it confirm the all-time cohort or fight it? A `"blocked"` momentum
   event is still a real tier crossing; with no `top_positions`, never guess its markets. If `near_term`
   is null, note it and move on.
4. **Bottom line** — one paragraph: where the proven money is positioned, where it diverges from the
   crowd, whether the near-term flow backs it — plus a **"what to watch"** (e.g. "if the crowd
   capitulates and flips short, the divergence is resolving").
5. **The two CTAs** (next section).

Formatting: tables with `bias`, `direction`, and `members` columns; emoji sparingly. Always pair a
bias with its member count — conviction is the whole point.

## Mandatory closing (verbatim)

> **1. Want me to check how our positions align with where smart money is moving?**
> **2. Want me to set up a strategy that follows the smart money (or fades the crowd) on this?**
> **3. Want me to find one of these smart-money traders to mirror directly?**

- **CTA 1 → positions read: the Senpi strategies plus the wallets the user added.** Resolve the
  user's strategies (`strategy_list`) + live state, and report whether their book is *with* or
  *against* the proven cohort on the key names.
  - **Saved wallets in the same read.** Also call `account_get_external_wallets` (no address: every
    wallet the user added in Your wallets, each with its live `state`) and put their positions in the
    **same table** as the Senpi strategies — one row per position, largest position value first, never a
    section per origin. Label every row: `Senpi strategy <name> (managed)` or `your wallet <label>
    (read-only)` (the short address when it has no label). Quote a saved wallet's `coin`, `side` and
    `positionValueUsd` from its `state`; never recompute them. Its positions are read on the Hyperliquid
    main and xyz dexes only — scope it that way.
  - **Read-only.** Senpi can't place, change or cancel orders on a saved wallet (quote its `access` line
    if asked). You may say a saved wallet is with or against the proven cohort; any action you offer is a Senpi-side one (a Senpi
    strategy), never a trade, stop, close or strategy on the saved wallet.
  - **`protection` is not "protected".** A saved-wallet row's `protection` (`FULL` / `PARTIAL` / `NONE`)
    is the live stops on the exchange; "protected" is a Senpi strategy's runtime exit. Never merge them.
  - **Unknown is never zero.** `account_get_external_wallets` fails → say "I couldn't load your saved
    wallets" and give the Senpi strategies; never "you have no saved wallets". A wallet with `state: null`
    or `state.readError` set → "couldn't load <label>", never flat, never $0, never "no positions". An
    empty list means none added — leave them out.
  - Call them "your wallets" or "the wallets you added"; never imply Senpi checked who controls them.
- **CTA 2 → strategy.** Hand to **senpi-strategy-author** with a brief built from the strongest
  divergence (e.g. *"proven cohort short HYPE −0.8/30 vs crowd long +0.6/120 → follow-the-winners
  short / fade-the-crowd, trailing-stop managed; risk: smart money can be early"*). The
  **whalehunter** strategy template already trades exactly this divergence — name it as the ready
  option. Also offer the Hyperfeed strikers, for a reader who wants the feed itself rather than a
  divergence thesis:

  > Want a feel for what senpi Hyperfeed can do? **Penguin** (crypto only) or **Pelican** (all assets)
  > react only to the strongest live rotations on the feed — a name suddenly rocketing up what winning
  > traders hold — then commit one position at up to 10x, 90% margin, with a DSL floor that ratchets up
  > to lock gains as it runs. High risk, high reward, with -15% SL.

  Three things about that line the agent must be able to unpack, because each is easy to read wrong:
  **-15% SL is 15% ROE, not a 15% price move** — at 10x that is a **1.5%** move, so if the user asks what
  the stop means, answer in price, never leave "-15%" to be read as the distance. On 90% margin it costs
  **~13.5% of the wallet per stop-out**, and say **per stop-out**: these run with their risk guard rails
  off, so stops compound (three ≈ 40% of the wallet). **Up to 10x**, never a flat 10x — the per-name venue
  cap clamps many instruments below it, and that clamp moves the PRICE behind every number without moving
  the wallet cost: ROE is return on margin, so the stop is ~13.5% at any leverage while the move it takes
  doubles at 5x (3.0%), and tier 1's +20% ROE becomes a 4% move rather than 2%. And say   **rotations**, never "pumps": the detector fires on a jump in what winning traders HOLD, not on price, so a pumping
  name no smart money rotated into does not fire at all.
  **Propose; never auto-build or trade.**
- **CTA 3 → mirror a smart-money trader.** You just surfaced the individual proven wallets — offer to
  copy one. Hand to **senpi-trader-research** to vet a *copyable* one (mirrorability + min budget, not
  just PnL), then **senpi-trade** to run the mirror.

## Resilience (engine handles; narrate honestly)

- **Hyperfeed down** → `near_term: null`. Note it; deliver the cohort read in full.
- **Cohort unreadable** → `meta.cohorts_unavailable`, which names the cause: an empty successful
  read (an app-scoped token) or a failed one (quoted — retry it, and don't call it a token problem).
  Say you can't read the cohort and which of the two it was; offer the near-term layer if it came through.
- **Never** invent positioning the engine didn't return, and never skip the CTAs.

## Skill Attribution

Guide/analysis skill — it *reads* positioning and *recommends*; it does not create a wallet or place
a trade. Attribution happens downstream when **senpi-strategy-author** / **whalehunter** /
**senpi-strategy-ops** act on CTA 2.


## Install — both scripts are required

The engine is **two files** in `scripts/`: `smartmoney.py` (the engine) and `mcp_client.py` (its vendored
MCP helper, imported at runtime). **Install the whole `scripts/` directory** — copying `smartmoney.py`
alone fails with `No module named 'mcp_client'`. Stdlib only, no other runtime dependencies.