insider_buy_clusters
Identify stocks where three or more insiders made open-market purchases within 24-48 hours, signaling potential bullish activity. Excludes awards and gifts.
Instructions
Form 4 insider buy clusters (3+ insiders bought same ticker in 24-48h). Bullish signal. Filtered to open-market purchases (P code), excluding awards/gifts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| window_hours | No | ||
| min_insiders | No |
Implementation Reference
- falsifylab_alpha_mcp.py:195-196 (handler)Tool dispatch for insider_buy_clusters: calls _api_get('/api/form4/clusters', args) — the actual handler is a simple HTTP GET to the backend API endpoint /api/form4/clusters.
if name == "insider_buy_clusters": return _api_get("/api/form4/clusters", args) - falsifylab_alpha_mcp.py:108-120 (schema)Tool schema definition for insider_buy_clusters with inputSchema accepting window_hours (int, default 24) and min_insiders (int, default 3).
{ "name": "insider_buy_clusters", "description": "Form 4 insider buy clusters (3+ insiders bought same " "ticker in 24-48h). Bullish signal. Filtered to " "open-market purchases (P code), excluding awards/gifts.", "inputSchema": { "type": "object", "properties": { "window_hours": {"type": "integer", "default": 24}, "min_insiders": {"type": "integer", "default": 3}, }, }, }, - falsifylab_alpha_mcp.py:75-185 (registration)TOOLS list (array of tool definitions) registered as the MCP tools/list response at line 231.
TOOLS = [ { "name": "top_yield_farms", "description": "Latest 24h top DeFi yield farm picks with realistic " "APY (emissions stripped), risk notes, TVL, protocol. " "Sourced from FalsifyLab daily aggregator.", "inputSchema": { "type": "object", "properties": { "limit": {"type": "integer", "default": 10, "description": "max results (1-50)"}, "min_apy": {"type": "number", "default": 0, "description": "filter floor in pct"}, "asset": {"type": "string", "description": "filter by asset symbol (BTC, ETH, SOL, etc.)"}, }, }, }, { "name": "hl_vault_leaderboard", "description": "Hyperliquid vault leaderboard with NAV, 30d return, " "max drawdown, follower count, composite score. " "Real-time scrape of HL info API.", "inputSchema": { "type": "object", "properties": { "limit": {"type": "integer", "default": 10}, "sort_by": {"type": "string", "enum": ["score", "tvl", "return_30d", "followers"], "default": "score"}, }, }, }, { "name": "insider_buy_clusters", "description": "Form 4 insider buy clusters (3+ insiders bought same " "ticker in 24-48h). Bullish signal. Filtered to " "open-market purchases (P code), excluding awards/gifts.", "inputSchema": { "type": "object", "properties": { "window_hours": {"type": "integer", "default": 24}, "min_insiders": {"type": "integer", "default": 3}, }, }, }, { "name": "sec8k_material_today", "description": "Material SEC 8-K filings today filtered by item code: " "2.02 (earnings), 5.02 (officer change), 2.01 (M&A), " "3.02 (dilution), 4.02 (restatement), 3.01 (delisting).", "inputSchema": { "type": "object", "properties": { "items": {"type": "array", "items": {"type": "string"}, "description": "item codes (e.g. ['2.02','5.02'])"}, "ticker": {"type": "string", "description": "filter by ticker symbol"}, }, }, }, { "name": "macro_tape", "description": "Live US macro snapshot: SPX, NDX, RUT, VIX, UST 2y/10y, " "DXY, GOLD, WTI, BTC, ETH. Last price + 1d/5d % change.", "inputSchema": { "type": "object", "properties": { "symbols": {"type": "array", "items": {"type": "string"}}, }, }, }, { "name": "etf_flow_today", "description": "US-listed spot crypto ETF aggregate flows today. " "BTC + ETH net flow, 5d streak, cumulative AUM. " "Source: SoSoValue.", "inputSchema": {"type": "object", "properties": {}}, }, { "name": "active_airdrop_farms", "description": "Active airdrop / points-farming opportunities. " "Detected from DefiLlama yield gaps (where reported " "APY exceeds base+rewards = likely points program). " "Includes realistic APY, TVL, capital required, " "confidence score. Sourced from Suki defi_scanner.", "inputSchema": { "type": "object", "properties": { "limit": {"type": "integer", "default": 10}, "min_apy": {"type": "number", "default": 0, "description": "filter floor pct (realistic APY)"}, "min_tvl_usd": {"type": "number", "default": 0, "description": "filter pools <X TVL"}, "chain": {"type": "string", "description": "filter (ethereum, base, arbitrum, etc.)"}, }, }, }, { "name": "polymarket_whale_positions", "description": "Top Polymarket whale wallets and their current " "active positions sized >$10k. Copy-trade reference.", "inputSchema": { "type": "object", "properties": { "min_position_usd": {"type": "integer", "default": 10000}, }, }, }, ] - falsifylab_alpha_mcp.py:51-70 (helper)_api_get helper function that performs the actual HTTP GET request to the backend API with auth and error handling.
def _api_get(path: str, params: dict | None = None) -> dict: if params: from urllib.parse import urlencode path = f"{path}?{urlencode(params)}" req = urllib.request.Request( f"{API_BASE}{path}", headers={ "User-Agent": USER_AGENT, "Accept": "application/json", **({"Authorization": f"Bearer {API_KEY}"} if API_KEY else {}), }, ) try: with urllib.request.urlopen(req, timeout=20) as r: return json.loads(r.read()) except urllib.error.HTTPError as e: body = e.read().decode(errors="ignore")[:400] return {"error": f"HTTP {e.code}: {body}"} except Exception as e: return {"error": str(e)[:200]}