v3.0.0 to v3.0.0

- Surface non-obvious market developments on Hyperliquid — the read you can't get from a price

- screen. Senpi's backend scans the whole HL universe every few minutes — funding, open interest, the

- proven cohort's positioning against the 4h crowd, the platform's momentum events and cross-asset

- flows — and one script (scripts/sweep.py) fetches what that scan shows, ranked through TWO lenses:

- a **trade** lens

- (actionable edge, for users building ideas) and a **news** lens (surprising, non-obvious, for

- market-news content). Use for "scan Senpi Signals", "scan for market anomalies", "find what's

- mispriced", "where is the market wrong", "find dislocations", "what's out of line", "what's

- noteworthy in the market right now", "any interesting anomalies to tweet", "signals of the day",

- "build me some trade ideas", or a focused ask — "anything notable on OIL / the AI basket / trader 0x1234?".

- Every run ends with one question: set up a trade on a read, or a strategy that trades reads like

- these. On demand only: if asked to put it on a cron or any schedule, say no. The sweep is

- read-only, observation not advice, every number sourced. Requires the agent's Senpi sign-in.

- # Senpi Signals — the read you can't get from a price screen

-

- The same scanner families that **fire trades** inside the 100+ templates run on Senpi's backend in

- **observation mode over the whole Hyperliquid universe**, to surface the *non-obvious* — what needs funding,

- open-interest, smart-money or event data to see at all — then rank it by how credible and surprising

- it is. Senpi sees the market through its agents' eyes, so it spots what a chart can't.

-

- ## How it runs

-

- When a user asks, run **one `exec`** and present its output:

-

- ```bash

- python3 scripts/sweep.py --print-feed

- ```

-

- - **The backend computes, the skill presents.** Senpi's backend scans the market every few minutes and

- serves Senpi Signals — the same reads, scores and wording the Senpi app and the browser extension

- show, so all three always agree. `scripts/sweep.py` fetches that feed and formats it; it computes

- nothing, and there is no local fallback. Never assemble Senpi Signals from your own tool calls.

- - **One reading, no compare.** Each run shows Senpi's latest scan (its time is in the title), so

- two runs a minute apart give the same feed.

- - **On demand only: say no to a cron.** If a user asks to put signals on a cron, a timer or any

- schedule ("send me signals every hour", "check the market every morning"), say no. Each firing

- would be a full model call spent re-reading a market they can ask about in one message. Offer to

- run it whenever they ask. Never create an `openclaw cron` or any other scheduled agent turn for

- it, and never deploy a strategy or fund a wallet to run it.

-

- ## ⚠️ The circularity trap (the single easiest way to get this wrong)

-

- **The 4h gain leaderboard cannot tell you who saw a move coming.** If SPCX falls, every wallet

- short SPCX is mechanically at the top of the 4h board. The board is a *consequence* of the move,

- not evidence anyone predicted it — so "smart money is short SPCX" read off 4h gains is just the

- price move handed back to you.

-

- **A notional lean carries the same bug one level down.** `net_bias` = net/gross **notional**. If a

- name falls 10% and *nobody trades at all*, every short's notional grows and every long's shrinks,

- so the lean drifts toward the winning side on price alone.

-

- **Headcount is immune, because price cannot change it, and Senpi Signals uses it for direction**

- (`share_kind: "cohort_pct"`): a wallet either holds the position or it doesn't.

-

- So: **smart-money *direction* comes from the proven cohort — never the leaderboard.** A read

- declares `source: proven_cohort` (the ≥$1M-lifetime-realized cohort's **headcount**) and the

- 4h board's number travels alongside as `hot_4h` — *what's winning right now*, momentum /

- survivorship-biased. **Never call the board number "smart money is long/short"** — label it "what's

- hot in the last 4h", and treat it as *color (fwiw)*, never a standalone headline. When the two

- disagree, **that gap is itself the story** — report both, correctly labeled.

-

- ## Two lenses, two audiences (why every signal gets two scores)

-

- The same signals serve two jobs, so the backend scores each one **twice** and returns **two ranked

- feeds** from one scan (`--lens both`, the default):

-

- - **`trade_score` — for users building ideas.** Rewards an actionable *edge*: a clear side, price

- *confirming* it, and enough liquidity to act on. A funding extreme is *carry, not a directional

- edge*, so it scores **low** here.

- - **`social_score` — for market-news content.** Rewards *surprise*: non-obvious, a good story,

- credible. A wild funding level *is* content even if it's not tradeable, so the news bar is lower

- and thin markets are included-but-flagged, not dropped.

-

- Credibility is a *multiplier* (a thin book can't out-shout a deep one), and no more than ~2 signals

- per detector family reach either feed. Give a **user** the trade feed; content uses the news feed.

-

- ## Golden rules (never violate)

-

- 1. **Number integrity.** Every figure you post came from this run's Senpi Signals output or a live

- MCP/on-chain read you made, and you can name where it came from. Never estimate, round

- misleadingly, or state a number you can't back.

- 2. **Observation, not advice.** Describe *what the data shows* — never "buy / sell / long this", no

- price targets, **no returns or outcome language.** It's a market observation, not a call.

- This is where "**mispriced**" / "**dislocated**" / "**out of line**" land — the words users ask in.

- Here they mean one thing: a **gap between two things the sweep actually read** (the cohort against

- the 4h crowd, funding against positioning, a laggard against its basket), **never a fair-value

- judgment** — the sweep carries no model of what anything is worth. "The cohort is 78% short HYPE

- while the 4h board is long", never "HYPE is overpriced".

- 3. **The sweep is read-only.** Running it never opens or closes a position, never changes a strategy,

- never trades, and never implies Senpi is taking the trade. It reports. Acting on a read happens only

- in the closing step (below), on the user's explicit yes to a specific order or strategy.

- 4. **Public data only.** On-chain wallet addresses are public — frame as "a top trader (0x12…)".

- Never attach a real person's identity.

- 5. **Now, never "since".** The feed is a snapshot of where things stand. Never claim a move since an

- earlier time that the read itself does not state: no "just shifted", "up 10% since this

- morning", "a whale **added**". Senpi's backend keeps its own scan history, so a few reads are

- about a change (an OI surge, measured against Senpi's earlier scans) — present those as their

- `read` line words them, and never add a change, a baseline or a time it did not give.

- Never describe the feed as if it carried more than it does.

-

- **The one exception, because it dates itself: a whale OPEN.** A proven wallet's position reports

- its own age, so "$12.4M short, opened 18 minutes ago" is a fact about the position, not a diff

- against a scan of ours. An **add** needs the old size and a **flip** needs the old side — those

- are still v2. Say *opened*, never *added* or *flipped*, and never date a position the feed did

- not date: an undated whale position is dropped rather than called fresh.

-

- The only other time words allowed are the sources' own

- windows: the 4h board, the 24h price move, a momentum event's time.

- 6. **Derive the universe, don't hardcode.** The backend scores the most-traded names (a liquidity

- floor + top-N by volume). Identity baskets (e.g. "the AI names") are the only allowed hardcode,

- and only in focus mode.

- 7. **Always state the side.** Every directional signal names **LONG or SHORT**. If you can't resolve

- it, say "side unresolved" — never omit it. A funding extreme is the one signal with no side by

- design: it is a carry read, so say that rather than inventing a direction.

- 8. **Anchor *and define* every reference — assume the reader knows nothing about HL.** Never a bare

- "N traders", "the leaderboard", or "4h window"; gloss each the first time (full glossary in

- [`references/detectors.md`](references/detectors.md)):

- - **who the proven traders are** — "the wallets on Hyperliquid with ≥ $1M lifetime realized PnL —

- the *proven money*" (the card says how many were read).

- - **express headcounts as a % of the cohort** — "**44% of the proven traders are short CASHCAT**",

- not "44 traders". Keep this headcount-% **distinct** from the *PnL-concentration* %.

- - **⚠️ ALWAYS pair that % with the POSITIONED SPLIT.** "44% are short" silently invites "so 56% are

- on the other side" — but most of that 56% hold **no position in the name at all**. Only

- **`N short vs N long`** among the positioned answers the directional question: 43%-short is a

- **rout** at 429-vs-40 and **noise** at 429-vs-380. The feed prints the split, the

- one-sidedness and "SMALL SAMPLE" at ~10 positioned or fewer — **repeat that in any copy.**

- - **which board + window** — `leaderboard_get_markets` = Hyperliquid's **live 4-hour rolling**

- board; `discovery_*` = historical track record (the proven cohort). Say which.

- 9. **Weight signals by their actual size — lead with what's robust.** A thin signal (few traders, low

- % concentration, tiny market) is *color*, never the headline. **Never upgrade "leans short (1.23%)"

- into "smart money is short."** See [`references/worked-examples.md`](references/worked-examples.md) (WLFI).

- 10. **The bar: sized and legible, or cut it.** A signal clears the bar only when it is sized (enough

- positioned traders, a real funding extreme, a liquid book) and you can say it plainly. Never a

- bare ticker — one clause on what the asset is, and price context on positioning signals. Better

- six that clear the bar than a padded ten.

-

- ## Output conventions

-

- `sweep.py` renders the feed — the "How to read this" block, the title, the two badged sections

- (*Tradeable dislocations* and *Market news*), the badges (🔥 ≥ 80 · 🟠 65–79 · 🟡 under 65; ⭐ top;

- ⚑ named wallet), the positioned split and the ranking. **Present that block as canonical** and

- narrate *around* it; don't replace it with free prose or relabel its sections. The rules above

- govern your narration, not the rendered feed.

-

- - **Talk about the market, never about the engine.** Present the feed, then at most a few sentences

- on what stands out, then the closing question (next section) — nothing after it. Never narrate

- coverage lines, read counts, detector names, why a detector is quiet, or what the feed leaves out.

- That includes closing notes and caveats. Wrong: *"Note: this run has no history, so whale moves

- aren't included."*

- - **Coverage is honest, not narrated.** A source that could not be read is named in the feed's last

- line (`Not measured this run: …`); repeat that line as it stands and add nothing. A detector that

- was never fed must never be reported as one that looked and found nothing. If a source failed, one

- plain clause is the most a user hears ("the smart-money read failed this run").

- - **Name a divergence only when the feed carries one.** Never add a section for something the feed

- doesn't have.

- - **Funding is a percent of position size, never of margin.** `-494%/yr` means shorts pay longs about

- 494% of the position's size a year at the current rate. Never restate it as a multiple of margin.

- ## Running the sweep

- python3 scripts/sweep.py --print-feed # what you run for a user: the feed (+ one line if a source failed)

- python3 scripts/sweep.py --brief 3 # the short version senpi-market-pulse closes with: top 3 trade reads, one line each

- python3 scripts/sweep.py --asset HYPE # focus mode: one asset's reads, the proven cohort's split, the 4h board, market

- python3 scripts/sweep.py --json # debugging: the backend's JSON as it came (add --asset X for one card)

- # --lens both|trade|social --top N

- - **Where the data comes from.** `GET /v1/signals` (the feed) and `GET /v1/signals/{asset}?insight=none`

- (one asset) on Senpi's backend — the same service the browser extension reads. `insight=none`

- leaves out the backend's own LLM analysis: you narrate the card, so a lookup never pays for one.

- - **No fallback.** When the backend cannot answer, the output is one plain line saying Senpi Signals

- is unavailable (or starting up, or needs a subscription, or could not verify the sign-in) and the

- exit code is non-zero. Present that line as it stands. Never present it as a quiet market, never

- rebuild the feed from your own tool calls, and never quote an earlier run as current.

- - **A stale reading says so.** When Senpi's latest scan is more than ~10 minutes old the output adds

- one line with its age; repeat it.

- - **Auth.** `SENPI_AUTH_TOKEN` from env — the agent's own Senpi sign-in — sent to Senpi's backend at

- `https://agents.senpi.ai`. Senpi Signals needs an active Senpi subscription or free trial; without

- one the line says so.

- - **Focus mode** ("anything notable on OIL / the AI basket / 0x1234?"): `--asset` for one asset (any

- alias: `BTC`, `BTC-PERP`, `xyz:TSLA`, `TSLA`), one call per asset for a basket. A wallet is not a

- Senpi Signals question: read it with `leaderboard_get_trader_positions` /

- `discovery_get_trader_state` and say plainly that it is a wallet read, not Senpi Signals. A quiet

- "nothing notable" is a correct answer.

- - What each read means and every field the backend returns:

- [`references/detectors.md`](references/detectors.md).

-

- ## Hyperfeed Movers — "what's hot RIGHT NOW?"

-

- A different question from the sweep, and it gets its own read. The sweep ranks the **>= $1M

- lifetime-realized cohort** over days. These ask about the last few minutes:

-

- > *"What's pumping right now?"* · *"Where are traders making money on Hyperliquid right now?"*

- > *"What's the Hyperfeed telling us?"* · *"Analyze what's hot this minute"* · *"Anything moving?"*

-

- **It is its own read, not part of the feed.** Senpi Signals comes from the backend; the movers come

- from **`python3 scripts/hyperfeed.py`**, one `leaderboard_get_markets` read of its own. Run it when the

- user asks what's hot right now, and offer it after the feed when the 4h board is the story.

- senpi-market-pulse prints it in every pulse (`--top 5`).

-

- **One run is Tier A only.** Rotations need a stored baseline, so for those run

- **`python3 scripts/hyperfeed.py`** twice, a couple of minutes apart — it owns its own ring (`--json` for structure, `--xyz-banned` for Penguin's

- crypto-only universe). **No cron, no background sampling** — the only thing that ever fills that ring

- is a run somebody asked for.

-

- **Never call this layer smart money.** It is `leaderboard_get_markets`: who is winning *right now*

- over a 4h rolling window, survivorship included. senpi-signals' smart money is the lifetime-realized

- cohort, and the two are regularly on **opposite sides of the same name in the same answer**. Say

- Hyperfeed, the 4h leaders, or top traders. (senpi-market-pulse carries this rule too.)

-

- ### The two tiers, and why the section always tells you which one answered

- The scoring is **Penguin's own**, vendored byte-identical (`scripts/striker_scoring.py`, locked by

- `tests/test_striker_scoring_vendor_parity.py`). But that detector is **stateful**: every one of its

- six reasons — FIRST_JUMP, IMMEDIATE_MOVER, CONTRIB_EXPLOSION, HIGH_VELOCITY, DEEP_CLIMBER, CLIMBING —

- is a delta against a scan the live runtime took **90 seconds** earlier. A skill answering a question

- has no such history, and the tempting fix is the trap: "+42 ranks" measured against a baseline from

- eleven hours ago is a *different claim* in identical words.

- So:

- - **Tier A — the snapshot. Always available, needs no history at all.** Ranked by

- `contribution_pct_change_15m`, which the **feed computes**, not us — a real 15-minute momentum

- number. Penguin's stateless gates are applied so the names shown are ones it would look at: rank

- outside the top 10 (a top-10 name has no jump room left), the 4h move agreeing with the leaders'

- direction, a rising 15m contribution, and the >= 10-trader floor. **This is a complete answer to

- "what's hot this minute."** Give it and stop; do not apologise for the absence of Tier B.

- - **Tier B — the rotations. Needs a second read, minutes apart.** Penguin's verbatim scorer against

- the freshest baseline, reported with its real score and real reasons. The baseline age is printed

- every time and banded: **LIVE** (<= 5 min, comparable to the scanner's own cadence) · **WIDE**

- (<= 30 min, scored but labelled a wider window, never presented as the same signal) · **STALE**

- (> 30 min — **not scored at all**, and the block says so).

- **A STALE baseline is never quietly scored at a wider window.** That is the one rule in this section

- that is not a preference. When it fires, the honest offer is the one the block already prints — *ask

- again in ~2 minutes and this run becomes the baseline* — and a user asking "what's hot right now" is

- very likely to ask again anyway. Never offer to schedule a cron to fill it.

- **No rotation is a real read, not a failure.** Most reads find none; it is what the strategy waits

- through. Say it plainly rather than reaching for the next-best name.

- **If the feed read fails**, the block says `unavailable` and invents nothing. Report that and stop —

- never substitute a price screen or a remembered board for a Hyperfeed read.

- ### Handing off from it

- A user who just saw a name at the top of this block is one question away from wanting it traded.

- That is the family question below, and **Penguin (crypto) or Pelican (all assets) are the two that

- trade this exact detector** — the block they just read is literally their scoring. Offer them by name

- when the handoff comes, with the honest cost in the same breath.

- ## Change reads live in the backend

- Everything that needs an earlier reading — whale **adds and flips**, OI surges, funding flips,

- conviction jumps, the cohort's positioning trend and base-unit flow — needs history, and that history

- lives on Senpi's backend, never on a user's box. The backend decides which of them the feed carries

- (today: OI surges). The skill shows what the feed carries and claims nothing else, so nothing here

- schedules, deploys or funds anything.

- > stop and the liquidation price before anything is placed. Or run it as a strategy, five ways:

- Offer **all four** strategy routes, every time. Athena was the only one named for a while, which sent

- every user who wanted a strategy to the same place regardless of what they had just read. The order is

- deliberate: the template that trades THIS feed comes first.

-

- **This is a major entry point.** For most users it is the first time a read becomes a position, so the

- question is the product, not a footer. Ask it every time, in full, with all four routes.

- Routes (1)-(3) trade the reads above. Route (4) deliberately does **not**, and that is why its label

- names **the Hyperfeed** rather than these signals: "want to act on any of these?" answered with a

- template that cannot act on them is a promise the deploy will not keep. The label is the disclosure —

- Hyperfeed momentum is a different source from the smart-money cohort above, and the user must be able

- to see that before a template is named. Offering a different

- signal is fine and often right — the user may want the shape of the trade rather than these particular

- reads — but it is offered AS a different signal, never as another way to trade what they just read.

- - **A trade on one read → senpi-trade.** Take the side the read names. Before any order, show the

- margin and its share of the account, the leverage, the stop price and the liquidation price. The

- stop must sit before liquidation. Place nothing until the user says yes to that exact order. A

- funding extreme names no side, so it is never a one-trade setup.

- - **(1) Signals Hunter → senpi-strategy-ops.** `signals-hunter` runs **this** detector library on an

- hourly clock — the same detectors, scores and wording the backend is built from, scanning the whole

- book from the strategy's own box. So it is the literal answer to "can I just trade these?": it

- opens what clears its score floor, long or short. Its scan is its own (a smaller sample of proven

- wallets, its own thresholds), so its reads are close to this feed but not always identical, and its

- floor is deliberately higher than the feed's TRADE floor, so it acts on fewer reads than the feed

- shows. Say that — a user who expects every line above to become a position will be

- disappointed by a correct run.

- - **(2) Puffin → senpi-strategy-ops.** `puffin` is the SAME vendored engine and the same

- reads as `signals-hunter`, pointed at **one position at a time**: a score floor of 85 rather than 65,

- 75-90% of the wallet at 10x rather than 20-25% at 5x, and a 15-minute clock rather than an hour. It is

- the aggressive answer to "can I just trade these?", and its trade-off is not subtle, so name it in the

- same breath as the upside: there is no second position to average against the first, one stop-out

- costs about **19-23% of the account**, and at 10x a single round trip pays roughly **0.8-0.9% of the

- wallet in fees** — about 27% a month at one completed trade a day, before direction earns anything.

- Offer it when the user asks for size, conviction or "the aggressive one" — never as the default, and

- never to someone funding a first strategy. `signals-hunter` stays the default answer for this feed.

- - **(3) Fork Athena → senpi-strategy-ops.** `athena` for the smart-money hedge fund: its Phalanx sleeve

- follows the same proven cohort these reads come from, and its Aegis sleeve reads the tape to hedge

- the regime. `athena-x` is the same two sleeves at conviction size (25% at 5x rather than 15% at 3x)

- — offer it only when the user asks for size, and name the trade-off rather than just the numbers.

- - **(4) Trade the Hyperfeed momentum → senpi-strategy-ops, or senpi-strategy-discover.** Some users want

- the shape of the trade rather than these particular reads. Name which signal the template actually

- trades in the same sentence as the template. The worked example is `penguin`: it chases recent

- high-conviction smart-money wins — a coin jumping 15+ places up the top-50 rows of the 4h leaderboard

- of what winning traders are piling into, fresh and volume-confirmed — and commits one position at up to 10x

- to it. That is Orca's detector rather than this feed's, and a user who arrived from these reads has to

- hear that. It also runs with all four risk guard rails off, so nothing halts a losing run but its own

- stop, where `puffin` halts at a 50% drawdown or three consecutive losses. When the user wants

- something else entirely rather than this example, hand off to **senpi-strategy-discover** and let the

- picker rank the whole catalog against what they describe — never improvise a shortlist from memory.

- - **Roll your own → senpi-strategy-author.** Not one of the four offered routes any more (Jason's

- call, 2026-09-27: the question got long and the four templates carry it), but still the right answer

- the moment a user asks for something none of them do — offer it then, without being asked twice.

- The read is the brief: the asset, the side, what the

- read is and its numbers. Build with the author's guardrails — a DSL stop on every position, leverage

- 3x or less, few trades, and the minimum budget plus the wallet-creation fee stated before anything is

- funded. It is a new strategy with no track record, and you say so. Offer it as a real peer of the

- three templates, not a consolation prize: a user who wants something none of them do should be

- building, not talked into the nearest fork.

- - **Ops runs the walkthrough first, then asks the budget.** Read the minimum budget from the catalog,

- never from memory.

- - **Narrowing by the read.** When the user picks one read rather than a route, the template built on

- that kind of read is the quick start, with designing one from scratch as its peer:

- | Any of them, traded as a feed | **Signals Hunter** (`signals-hunter`) — this same engine on a clock |

- | Any of them, but one position at a time | **Puffin** (`puffin`) — the same engine, score floor 85, 10x on one name; state the per-stop and fee cost |

- | A whale open or add | **Signals Hunter** (`signals-hunter`); note it parks `whale_open` as non-tradeable and acts on whale *moves* |

- | Smart money vs the crowd | **Athena** (`athena`), with a hedge, or **Phalanx** (`phalanx`), the cohort sleeve alone |

- | A funding extreme | **Pangolin** (`pangolin`), which fades the crowd paying to hold, or **Camel** (`camel`), which collects the carry on two books |

- | A momentum event | **Meerkat** (`meerkat`) |

- | A laggard behind BTC | **Mantis** (`mantis`) |

- From scratch → senpi-strategy-author, under route (5)'s guardrails above.

- - **Every template is a starting point the user makes their own.** It deploys under their name, as-is

- or with levers moved. Never promise or imply results, and never call a template proven. Deploy only on

- the user's yes.

- - **Never in public copy.** The question and everything after it are a private, interactive step;

- anything written for posting stays observation-only.

- - **The brief carries no question.** `--brief` output is another skill's closing section; that skill

- asks its own question.

- Every user has it. A chat chip runs the full sweep ("Scan Senpi Signals for market anomalies"), and

- **senpi-market-pulse** closes every pulse with the brief (`--brief 3`) and an offer to run the full sweep.

- `python3 scripts/sweep.py --brief 3` reads the same feed and prints only a title and the top N trade

- reads, one line each: badge, score, asset and the read. No legend, no news feed, nothing about the

- engine, plus the one not-measured line when a source failed. A quiet market prints one plain line.