# 🦬 Robinhood Memescan **English** Β· [δΈ­ζ–‡](README.zh-CN.md) A real-time **meme-coin monitor & AI scoring dashboard**, built entirely on the **[Clawby](https://www.openclawby.com/) API**. Seven monitor windows + a custom-report window + an admin panel. It watches Robinhood launches, ranks the hottest memes, and runs **automated AI scoring on Robinhood, BSC and Base**, plus one-click **illustrated PDF research reports** β€” all powered by your local **Claude Code / Codex**, with optional Telegram alerts. > All data comes from Clawby (`dex_trending` / `dex_token_info` / `dex_token_holders` / `dex_token_kline` / `dex_token_traders` / `dexscreener_*` / `x_search` + on-chain RPC). No Blockscout needed. --- ## Features | Window | What it does | |---|---| | **β‘  New Launches** | Polls each launchpad's factory events (Clawby RPC `eth_getLogs`) for brand-new tokens: platform / name / CA / creation time / creator / is-creator-a-KOL + the creator's tx counts across **5 chains** (robinhood Β· ETH Β· BSC Β· Base Β· HyperEVM) | | **β‘‘ Top100** | Top 100 memes by 24h volume: platform / price / mcap / 24h vol / holders / **txns (24h swaps)** / liquidity / ETH-in-pool / X buzz | | **β‘’ Watchlist** | Favorite any CA, per-CA refresh interval; adds **KOL / smart-money counts** (sampled top holders) and a one-click **πŸ”¬ deep analysis β†’ PDF** | | **β‘£ New ≀3 days** | Only coins whose **real on-chain creation time ≀ 3 days**, top 100 by volume (creation time is calibrated on-chain, so "old coins that just graduated" are excluded) | | **β‘€ AI Β· Robinhood** | Every 10 min scans memes in a **configurable market-cap band** (default $100k–$5M, optional "created ≀ N days" filter), stores each one's on-chain / holder / trading / social data as an LLM wiki, then uses **Claude Code / Codex to score it 1–100** (100 = best early buy) with a **1–5 sentence rationale** + its **24h txn count**. Optional **Telegram alert** when a score clears a threshold | | **β‘₯ AI Β· BSC** | The same automated AI scoring for **BSC** memecoins (own mcap band / age filter) | | **⑦ AI Β· Base** | The same automated AI scoring for **Base** memecoins (own mcap band / age filter) | | **⑧ Custom Report** | Pick a chain (Robinhood / BSC / Base) + paste a contract β†’ Clawby gathers **all RPC / holder / trade / holder-relationship / X data** β†’ generates a full **illustrated PDF** with a price line chart, volume bars, a holder-distribution doughnut, a timeline and the total tx count | | **βš™οΈ Admin** | Every setting: concurrency, report dir, report language, **analysis engine**, per-window interval + pause, **per-scorer mcap band + age filter**, launchpad toggles, **scan-field customization**, Telegram alerts, runtime status & recent errors | **Also:** - **Bilingual UI (English / δΈ­ζ–‡)** β€” a language picker on first open; the whole interface switches instantly. - **Copy buttons** on every contract / address (`⧉` β†’ βœ“ + toast). - **Live feedback** β€” per-window status pills (scanning / idle / paused / scoring), an AI-score progress bar, the coin being scored right now, and a header activity indicator. - **Local persistence** β€” favorites and every setting live in `state.json` and are restored on restart. - **Startup safety** β€” windows boot **paused** (no request spike) and **at most 2 can monitor at once**. --- ## Requirements - **Python 3.9+** (a venv with `fastapi` / `uvicorn` / `httpx` is created automatically) - **Clawby API key** β€” sign up (free) at (starts with `pk_`) - **For deep analysis / AI scoring (optional):** - **Google Chrome** (macOS) to render report HTML β†’ PDF - **Claude Code CLI** (`claude`, logged in) **or** **Codex CLI** (`codex login` / `OPENAI_API_KEY`) - **For Telegram alerts (optional):** a Telegram bot token (from [@BotFather](https://t.me/BotFather)) > Monitoring only needs Python + a Clawby key. The AI/PDF and Telegram pieces are opt-in. --- ## Install & run ```bash cd Robinhood_Memescan # 1. configure your key cp .env.example .env # edit .env β†’ set CLAWBY_API_KEY=pk_xxx # 2. run (first run creates the venv + installs deps) bash run.sh ``` Then open **** and pick a language. `.env`: ```ini CLAWBY_API_KEY=pk_your_key_here # required, from openclawby.com PORT=8799 # optional, default 8799 ``` Everything else is configured in the **Admin** window (and persisted): | Setting | Notes | |---|---| | Concurrency | 1–100, default 10 (paired with a built-in ~6 req/s limiter) | | Report output dir | where analysis PDFs are saved, default `./reports` | | Report language | δΈ­ζ–‡ / English | | **Analysis engine** | **Claude Code** or **Codex** | | Per-window scan interval | β‘  5s Β· β‘‘ / β‘£ 300s Β· β‘€β‘₯⑦ 600s | | **Per-scorer mcap band + age** | β‘€β‘₯⑦ each get their own market-cap min/max and "created ≀ N days" filter | | Launchpad factory toggles | enable/disable the platforms window β‘  listens to | | Scan-field customization | turn individual fields off to skip their fetch (saves quota) | | Telegram alerts | token / chat_id / threshold / on-off | --- ## AI scoring (β‘€ Robinhood Β· β‘₯ BSC Β· ⑦ Base) Three automated "early-stage opportunity" scorers, one per chain: 1. Every **10 min**, `dex_trending` selects that chain's memes in the configured **market-cap band** (default $100k–$5M; you can also require "created ≀ N days"). 2. A **sequential background worker** processes them **one at a time**: gather data β†’ store as an LLM wiki (`scores/_/wiki/`) β†’ call the **fast Claude/Codex model** to read the wiki and score. 3. Output = **1–100** (100 = strongest early buy; 1 = highest risk) + a **1–5 sentence rationale** + the coin's **24h txn count**. 4. Scores **persist** and update live; new / oldest-scored coins go first, then it keeps rolling. > Dozens of coins can't all be re-scored within each 10-min tick (each is a separate LLM call), so it's "refresh data every 10 min + keep rolling through scoring". The engine follows the Admin Claude/Codex setting. Only 2 windows monitor at once, so opening β‘€ + β‘₯ (say) runs Robinhood and BSC scoring in parallel. ## Custom deep report (⑧) Pick a chain + paste a contract address β†’ the app gathers **everything** for that token and asks the AI to write a full illustrated report: - On-chain: total tx (RPC-counted from the deploy block), 24h tx, unique senders/receivers, deploy block - Holders: full top-holder table + a **distribution doughnut**, plus **relationship signals** (top-10 concentration, sniper / bundler / fresh-wallet / dev-hold rates) - Trading: top traders by realized PnL; a **price line chart** + **volume bars** from the OHLC series; an event **timeline** - Social: recent X posts The charts are pre-built server-side (Chart.js, bundled `vendor/chart.min.js` β€” no CDN), then Chrome renders it to a **multi-page PDF** (~5–7 min for a full report; the window shows live progress). ## Telegram alerts Push an alert whenever a coin scores **β‰₯ a threshold**. In Admin β†’ **πŸ“² Telegram**: 1. Message your bot once in Telegram (so it can see your chat id). 2. Paste the **Bot Token** β†’ click **Refresh chat_id** to auto-detect your chat β†’ select it. 3. Set the **threshold** (default 80), enable it, click **Send test**. 4. Afterwards every β‰₯-threshold score is pushed (once per coin; re-armed if it drops below then climbs back). > The token can be replaced anytime (shown masked). Telegram usually needs a proxy β€” the app reuses the proxy `run.sh` saved and retries transient drops. ## Scan-field customization Admin β†’ **Scan-field customization** toggles fields per window. **Turning a field off skips its fetch (saves Clawby quota, runs faster) and hides its column.** E.g. turn off "X buzz" and no window calls `x_search` anymore. ## Deep analysis (πŸ”¬) From the Watchlist, click a coin's **πŸ”¬ Analyze**: gather its on-chain + X data β†’ local wiki β†’ local **Claude Code / Codex** reads it and writes an HTML report β†’ Chrome renders it to a **PDF** in the report folder. --- ## Data sources (all via Clawby) **`/api/relay`:** `dex_trending` (ranking, any of robinhood/bsc/base) Β· `dex_token_info` (per-CA snapshot: holders / price / vol / creation time / launchpad / creator / relationship stats) Β· `dex_token_holders` Β· `dex_token_kline` (OHLC for charts) Β· `dex_token_traders` (top traders) Β· `dexscreener_token_pools` (pool liquidity / ETH) Β· `dex_wallet_stats` (wallet KOL / smart-money tags) Β· `x_search` (X sentiment) **`/api/rpc` (`chain` = robinhood / bsc / base):** `eth_blockNumber` Β· `eth_getLogs` (factory events / transfer counts) Β· `eth_call` Β· `eth_getCode` (binary-search the deploy block) Β· `eth_getBlockByNumber` Β· `eth_getTransactionByHash` Β· `eth_getTransactionCount` **Only non-Clawby call:** HyperEVM public RPC (`eth_getTransactionCount`, since Clawby has no hyperevm chain). Providers behind Clawby: **GMGN** (`dex_*`, covers robinhood/bsc/base), **DexScreener** (`dexscreener_*`), **X** (`x_search`) β€” each has its own upstream rate limits. --- ## Project structure ``` Robinhood_Memescan/ β”œβ”€β”€ app.py FastAPI app: REST endpoints + state persistence + lifespan β”œβ”€β”€ monitors.py window logic (discover / rank / watch / multi-chain AI scorers) + loops + controls β”œβ”€β”€ sources.py Clawby data wrappers (rh_trending / rh_token / rh_holders / rh_by_mcap / rh_kline / rh_traders), chain-aware β”œβ”€β”€ clawby.py Clawby client: relay + rpc + concurrency + rate limiter + ban backoff β”œβ”€β”€ analyze.py AI scoring + deep/custom reports (gather β†’ wiki β†’ charts β†’ claude/codex β†’ PDF) β”œβ”€β”€ tg.py Telegram alerts β”œβ”€β”€ wallets.py wallet KOL / smart-money tagging + cache β”œβ”€β”€ factories.py launchpad factory addresses + event decode rules β”œβ”€β”€ util.py shared helpers + caches + rate limiter + state I/O β”œβ”€β”€ dashboard.html frontend (vanilla JS single page, 7 windows + report + admin, i18n) β”œβ”€β”€ vendor/chart.min.js bundled Chart.js for the report charts (no CDN at render time) β”œβ”€β”€ run.sh venv / deps / proxy handling / uvicorn β”œβ”€β”€ .env.example config template └── .env your real config (git-ignored) ``` --- ## Notes & limits - **Robinhood chain** = Arbitrum Orbit L2, chain id 4663. - **Proxy:** `run.sh` clears http(s)/all proxy at startup (the app's httpx must connect directly) but saves it to `SAVED_*_PROXY` for the `claude` / `codex` subprocesses and Telegram. - **First load:** β‘‘ / β‘£ take ~1–2 min to enrich on cold start (bounded by the rate limiter); the window shows progress, it isn't stuck. - **Upstream rate limits:** heavy bursts (many restarts, aggressive polling) can get a provider (usually GMGN) to temporarily rate-limit-ban the IP. The client detects it (by response body, any HTTP status), backs off with an escalating cooldown, shows a "rate-limited, resets in Xs" banner, and auto-recovers. Normal 2-window use (~1 req/s) stays well under the limits. - **KOL / smart-money** relies on GMGN wallet tags; a coin's top holders are often pools / whales, so counts are frequently 0. - Reports / analysis / score dirs are pruned to the newest entries. *This tool is for research only β€” not investment advice.*