# Solwatch ☀
**Real-data Solana memecoin auditor & rug/bundle/honeypot scanner.** Sister tool to [Hoodwatch](https://github.com/aetherBytes/hoodwatch) (Robinhood Chain).
Solwatch reads live on-chain data — the Solana RPC, DexScreener, and Jupiter's tokenless lite-api — and returns a structured risk report for any token mint. **No mock data, no API keys.** On Solana the rug levers are readable straight off the mint account, so instead of simulating a sell it decodes them directly: freeze authority (the #1 Solana honeypot), mint authority, and every Token-2022 trap (transfer fees, permanent delegates, transfer hooks, non-transferable / frozen-by-default mints).
**Written in Rust** (pure `reqwest`, no solana-sdk), shipped as a single small static binary — no toolchain, no runtime deps. Drops straight into the Rokha sandbox (or any host) and starts instantly.
### Install / run
```bash
# The Rokha sandbox path — public npm wrapper ships the prebuilt binary:
npx -y @aetherbytes/solwatch audit DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
# Rust devs:
cargo install solwatch
solwatch audit <MINT> --json
# Build from source:
git clone https://github.com/aetherBytes/solwatch && cd solwatch && cargo build --release
```
Use it as a **library** too: `solwatch = "0.1"` then `solwatch::audit::audit_token(&client, mint, opts, now_ms, ts).await`.
## Commands
| Command | What it does |
|---|---|
| `solwatch audit <mint>` | Full audit of one token (human-readable). Add `--json` for machine output, `--md` for a Markdown report, `--fast` to skip the slower launch-bundle/copycat/cluster passes, `--deep` for a bigger cluster budget (more funding hops probed), `--out <dir>` to save report artifacts. |
| `solwatch tweet <mint>` | Emit the ≤280-char X post for a token. |
| `solwatch scan [--json]` | List freshly created tokens across ALL Solana launchpads (pump.fun, LetsBonk, Moonshot, Boop, Raydium LaunchLab, …). |
| `solwatch watch [--limit N] [--out <dir>]` | Audit the newest launches in a batch (JSON), saving a `.md` + `.json` report per token. |
| `solwatch serve [--port N] [--out <dir>]` | Launch the **live dashboard** (default port 7565): audit from the browser with full data-vis — score gauge, safety tiles, holder bars, launch-window sniper chart, the **interactive cluster bubblemap** (pan/zoom/drag, evidence-layer toggles, per-wallet side panel), buy/sell pressure — plus the fresh-launch feed and the saved-report archive. Newbie-friendly: every finding is plain English, with a built-in glossary. |
## What it checks (all real, all on-chain)
- **Mint authorities — the Solana honeypot levers.** Active **freeze authority** (your tokens can be frozen mid-trade — the classic sell-block), active **mint authority** (infinite supply), and owner-renounce status.
- **Token-2022 extensions.** Transfer fees (sell tax, with the exact %), **permanent delegate** (tokens can be seized out of your wallet), **transfer hooks** (programmable sell-blocking), **non-transferable** and **frozen-by-default** mints — each an explicit honeypot-class flag.
- **Launch bundle / snipers — the TrenchBot signal.** Walks the mint's history back to its very first transaction, parses the token-balance deltas of the launch window, and reports **% of supply sniped**, wallets buying **in the exact creation slot** (coordinated bundles), fresh-wallet ratio, the dev's own allocation (deterministically attributed: Jupiter's dev, else the creation transaction's fee payer), and how much the snipers **still hold right now** — probed for EVERY parsed buyer, so the sniped and still-hold numbers share one denominator. The pump.fun **bonding-curve PDA is derived offline** and always excluded, so a seconds-old token never counts the curve's ~793M allocation as a "buyer". Partial parse coverage is flagged explicitly — a floor is never presented as the full picture.
- **Wallet clusters — the anti-evasion layer (shared contract with Hoodwatch).** Merges wallets back into ENTITIES using hard evidence: shared first-funders (funding-graph walk, ≤3 hops), direct token transfers within the holder/sniper set, same-slot co-buys, and **Jito bundles** — a tip-account heuristic over the launch transactions (including CPI tips) plus the `bundles.jito.wtf` proof API: two buys sharing a `bundle_id` are **provably one actor** (`proof: "jito:<id>"`). Union-find with evidence weights (transfer 1.0 / shared direct funder 1.0 / bundle 1.0 / same-slot 0.5; union at ≥1.0 — a shared non-stop funder clusters on its own). Over-merge control: CEX hot wallets (vendored list) and hub-like funders are **stop-nodes** that never propagate membership, transfers are dust-filtered, pools/burns/lockers never union, clusters >1000 wallets are discarded as merge errors. Emits `sections.cluster` (nodes/edges/clusters/effective_concentration) and new flags: `cluster_dominance`, `deployer_funded_snipers`, `insider_holders` (holds but never bought — arrived from the creator chain), `effective_concentration` (entity-level top-10; supersedes the raw read at full coverage), `bundled_supply_held` (scored on CURRENTLY-held bundled supply), `jito_proven_bundle`.
- **Holder distribution.** Owner-resolved top-20 accounts with AMM pools, bonding curves, burn addresses, and locker/vesting escrows (Streamflow, Jupiter Lock, Bonfida) excluded — 23 pool programs + 4 locker programs labeled; Jupiter-indexed fallback when the public RPC throttles.
- **Liquidity.** Total depth, liquidity-vs-FDV (illusory-price detection), pair age, socials, buy/sell imbalance, honest handling of bonding-curve venues.
- **Deployer.** Dev wallet, wallet age, dev's current bag, and **how many other tokens the same dev has launched** (serial-rugger signal).
- **Market quality.** Solwatch's own bot-volume heuristics from data already fetched (near-uniform launch-buy sizes; volume wildly out of proportion to the holder base) plus Jupiter's organic score — a third-party signal, labeled as such.
- **Copycats.** Same-symbol impersonator mints elsewhere on Solana.
Findings fold into a **0-100 score** (deduction model with hard-fail caps: a honeypot-class extension caps the score at 5) and a verdict — `AVOID` / `HIGH_RISK` / `CAUTION` / `FAIR` / `LOW_RISK`.
## Data sources (verified live 2026-07-13, all tokenless)
| | |
|---|---|
| RPC | `https://api.mainnet-beta.solana.com` (override: `SOLWATCH_RPC_URL`; or set `HELIUS_API_KEY` and Solwatch uses Helius automatically — removes the holder-list throttle) |
| Bundle proof | `bundles.jito.wtf/api/v1/bundles/transaction/<sig>` — third-party, budget-limited, degrades to the tip heuristic when unavailable (fresh txs index after a few minutes) |
| Market data | DexScreener, chain slug `solana` |
| Token index | Jupiter lite-api (`lite-api.jup.ag/tokens/v2`) — dev wallet, holder count, organic score, launchpad, recent-launch feed |
`SOLWATCH_OUT` sets the default report directory, `SOLWATCH_PORT` the dashboard port, `SOLWATCH_RPC_CONCURRENCY` the global RPC parallelism (default 4 — all RPC traffic rides one semaphore with exponential backoff; throttle-induced data loss surfaces in `warnings` and the cluster `scope.coverage`, never silently).
## For agents
Every command supports `--json` and returns the same [`AuditResult`](src/types.rs) shape Hoodwatch uses (`score`, `verdict`, `flags[]` with machine ids + severities, per-section detail under `sections`). `rokhaUrl` appears only when you set `SOLWATCH_ROKHA_URL` (e.g. your rig's product page on Rokha) — Solwatch never fabricates a link. The local dashboard accepts `/?address=<mint>` for direct links.
**Two render-ready outputs, built for egress-only sandboxes** (a live `solwatch serve` can never be reached from outside a sandbox — so every run ships its frontend OUT):
- **`rokha_app`** — every audit JSON carries a ready-made APP-view block (`title` / `verdict` / `score` / `metrics[]` with tones / `sections[]` of markdown+tables). A rig whose final step outputs this JSON renders natively in Rokha's output rail, no adapter.
- **`audit --html`** (and every `--out` report) — a **single self-contained HTML file**: the exact dashboard card with the audit data baked in, inlined CSS/JS, fetch stubbed, zero network. Renders anywhere, including a hard-sandboxed `srcdoc` iframe.
## Known limitations (honest)
- The public RPC hard-blocks `getTokenLargestAccounts` for most callers — holder concentration then comes from Jupiter's index (labeled as such), and holder-side clustering is limited (`scope.coverage: "partial"`). Set `SOLWATCH_RPC_URL` / `HELIUS_API_KEY` for the live per-wallet list.
- Deployer "wallet age" is only populated when the dev wallet has <1000 signatures (older/busier wallets report a tx-count floor instead).
- The Jito proof API indexes bundles with a few minutes' delay — on a seconds-old launch the proof lookup may come back empty and the audit falls back to the tip heuristic (says so in `scope.note`).
- Launch-window analysis needs the mint's earliest transactions; tokens with >12k signatures skip it (their launch is ancient history anyway).
- LP-lock verification covers pump.fun/PumpSwap by protocol design; other venues get an honest "unverified" flag rather than a guess.
## Not financial advice
Solwatch surfaces on-chain risk signals. It cannot prove a token is safe. Always do your own research.
MIT © aetherBytes