> For the complete documentation index, see [llms.txt](https://cabalspy.gitbook.io/cabalspy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cabalspy.gitbook.io/cabalspy-docs/signals/signals.md).

# Signals

Real-time cluster, entry and exit signals from tracked KOL, smart-money and whale wallets on Solana, BNB Chain, Base and Ethereum.

## Live Signals — Cluster, Entry & Exit (per-type gate)

> Returns live signals for one chain within a time window.\
> \
> \*\*Gated parameters\*\* (presence of any one switches to gated mode):\
> \- \`kol\`, \`smart\` — entry tiers as a CSV of up to 3 ascending ints\
>   (\`kol=5\` or \`kol=5,10,20\`). The smallest is the gate.\
> \
> \- \`kol\_min\_buy\`, \`kol\_max\_buy\`, \`smart\_min\_buy\`, \`smart\_max\_buy\` — per-type\
>   cumulative-buy bounds (native units).\
> \
> \- \`kol\_exit\`, \`smart\_exit\` — exit tiers as a CSV of up to 2 "still holding"\
>   counts (\`kol\_exit=3,1\`).\
> \
> \- \`include\_wallets\`, \`exclude\_wallets\` — comma-separated wallet lists.\
> \- \`min\_win\_rate\` (0–100), \`min\_token\_age\`, \`max\_token\_age\` (hours).\
> \
> \*\*Legacy parameters\*\* (when no gated parameter is present):\
> \- \`type\` (\`kol\`/\`smart\`/\`whale\`), \`mode\` (\`cluster\`/\`entry\`/\`exit\`),\
>   \`min\_wallets\`, \`min\_value\`.\
> \
> \
> \*\*Common:\*\* \`blockchain\` (required), \`hours\`, \`limit\`, \`api\_key\`.\
> \
> Unknown parameters are ignored and reported in \`data.warnings\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Live Signals (Cluster, Entry & Exit)","version":"2.0.0"},"tags":[{"name":"Signals","description":"Real-time cluster, entry and exit signals from tracked KOL, smart-money and whale wallets on Solana, BNB Chain, Base and Ethereum.\n"}],"servers":[{"url":"https://api.cabalspy.xyz"}],"paths":{"/v1/signals":{"get":{"tags":["Signals"],"summary":"Live Signals — Cluster, Entry & Exit (per-type gate)","operationId":"getSignals","description":"Returns live signals for one chain within a time window.\n\n**Gated parameters** (presence of any one switches to gated mode):\n- `kol`, `smart` — entry tiers as a CSV of up to 3 ascending ints\n  (`kol=5` or `kol=5,10,20`). The smallest is the gate.\n\n- `kol_min_buy`, `kol_max_buy`, `smart_min_buy`, `smart_max_buy` — per-type\n  cumulative-buy bounds (native units).\n\n- `kol_exit`, `smart_exit` — exit tiers as a CSV of up to 2 \"still holding\"\n  counts (`kol_exit=3,1`).\n\n- `include_wallets`, `exclude_wallets` — comma-separated wallet lists.\n- `min_win_rate` (0–100), `min_token_age`, `max_token_age` (hours).\n\n**Legacy parameters** (when no gated parameter is present):\n- `type` (`kol`/`smart`/`whale`), `mode` (`cluster`/`entry`/`exit`),\n  `min_wallets`, `min_value`.\n\n\n**Common:** `blockchain` (required), `hours`, `limit`, `api_key`.\n\nUnknown parameters are ignored and reported in `data.warnings`.\n","parameters":[{"name":"blockchain","in":"query","required":true,"description":"solana | bnb | base | eth","schema":{"type":"string","enum":["solana","bnb","base","eth"]}},{"name":"kol","in":"query","required":false,"description":"Gated: KOL entry tiers, CSV up to 3 ascending ints (e.g. 5 or 5,10,20).","schema":{"type":"string"}},{"name":"smart","in":"query","required":false,"description":"Gated: smart-money entry tiers, CSV up to 3 ints.","schema":{"type":"string"}},{"name":"kol_min_buy","in":"query","required":false,"description":"Gated: min cumulative KOL buy (native).","schema":{"type":"number","minimum":0}},{"name":"kol_max_buy","in":"query","required":false,"description":"Gated: max cumulative KOL buy (native).","schema":{"type":"number","minimum":0}},{"name":"kol_exit","in":"query","required":false,"description":"Gated: KOL exit tiers, CSV up to 2 \"still holding\" counts (e.g. 3,1).","schema":{"type":"string"}},{"name":"smart_min_buy","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"smart_max_buy","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"smart_exit","in":"query","required":false,"description":"Gated: smart-money exit tiers, CSV up to 2.","schema":{"type":"string"}},{"name":"include_wallets","in":"query","required":false,"description":"Gated: comma-separated wallets that alone count.","schema":{"type":"string"}},{"name":"exclude_wallets","in":"query","required":false,"description":"Gated: comma-separated wallets to drop.","schema":{"type":"string"}},{"name":"min_win_rate","in":"query","required":false,"description":"Gated: drop wallets below this lifetime win-rate (0–100).","schema":{"type":"number","minimum":0,"maximum":100}},{"name":"min_token_age","in":"query","required":false,"description":"Gated: min token age (hours).","schema":{"type":"number","minimum":0}},{"name":"max_token_age","in":"query","required":false,"description":"Gated: max token age (hours).","schema":{"type":"number","minimum":0}},{"name":"type","in":"query","required":false,"description":"Legacy: wallet type.","schema":{"type":"string","enum":["kol","smart","whale"]}},{"name":"mode","in":"query","required":false,"description":"Legacy: cluster | entry | exit.","schema":{"type":"string","enum":["cluster","entry","exit"]}},{"name":"min_wallets","in":"query","required":false,"description":"Legacy: min wallets for a cluster.","schema":{"type":"integer","minimum":1,"default":3}},{"name":"min_value","in":"query","required":false,"description":"Legacy: ignore trades below this (native).","schema":{"type":"number","minimum":0,"default":0}},{"name":"hours","in":"query","required":false,"description":"Window size in hours.","schema":{"type":"number","minimum":0,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Signals payload. In gated mode, `data.gated` is true and `data.signals[]` use the cluster model below.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatedSignalsEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"schemas":{"GatedSignalsEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"blockchain":{"type":"string","enum":["solana","bnb","base","eth"]},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart"]}},"currency":{"type":"string","enum":["SOL","BNB","ETH"]},"gated":{"type":"boolean"},"filters":{"type":"object","properties":{"min_win_rate":{"type":"number","nullable":true},"include_wallets":{"type":"array","items":{"type":"string"},"nullable":true},"exclude_wallets":{"type":"array","items":{"type":"string"},"nullable":true},"min_token_age_hours":{"type":"number","nullable":true},"max_token_age_hours":{"type":"number","nullable":true}}},"_total":{"type":"integer"},"signals":{"type":"array","items":{"$ref":"#/components/schemas/GatedSignal"}},"warnings":{"type":"array","items":{"type":"string"},"description":"Optional","English. Unknown/deprecated params.":null}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"cached":{"type":"boolean"},"pagination":{"type":"object","nullable":true,"properties":{"limit":{"type":"integer"},"total":{"type":"integer"},"returned":{"type":"integer"}}}}}}},"GatedSignal":{"type":"object","properties":{"token":{"$ref":"#/components/schemas/GatedTokenBlock"},"signal_type":{"type":"string","enum":["cluster"]},"signal_strength":{"type":"string","enum":["strong","medium"],"description":"strong when total qualifying >= 5."},"currency":{"type":"string","enum":["SOL","BNB","ETH"]},"gate":{"type":"object","properties":{"met":{"type":"boolean"},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart"]}},"thresholds":{"type":"object","properties":{"kol":{"allOf":[{"$ref":"#/components/schemas/GatedThreshold"}],"nullable":true},"smart":{"allOf":[{"$ref":"#/components/schemas/GatedThreshold"}],"nullable":true}}}}},"window":{"type":"object","properties":{"hours":{"type":"number"},"wallet_count":{"type":"integer","description":"Total qualifying wallets across types."},"by_type":{"type":"object","additionalProperties":{"type":"object","properties":{"wallet_count":{"type":"integer"},"sold":{"type":"integer"},"holding":{"type":"integer"},"invested":{"type":"number"},"invested_usd":{"type":"number"},"tier_reached":{"type":"integer","nullable":true}}}},"total_invested":{"type":"number"},"total_invested_usd":{"type":"number","nullable":true},"first_buy_at":{"type":"string","nullable":true},"latest_buy_at":{"type":"string","nullable":true},"time_span_minutes":{"type":"number"}}},"token_stats":{"type":"object","nullable":true,"properties":{"total_buyers":{"type":"integer"},"still_holding_count":{"type":"integer"},"active_count":{"type":"integer","nullable":true},"total_volume":{"type":"number"},"total_volume_usd":{"type":"number"},"net_flow":{"type":"number"},"holders_by_type":{"type":"object","properties":{"kol_count":{"type":"integer"},"smart_count":{"type":"integer"},"whale_count":{"type":"integer"}}},"first_entry_time":{"type":"string","nullable":true}}},"wallets":{"type":"array","items":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/Profile"},"wallet_type":{"type":"string","enum":["kol","smart"]},"win_rate":{"type":"number","nullable":true,"description":"null unless min_win_rate was requested."},"window_invested":{"type":"number"},"window_invested_usd":{"type":"number","nullable":true},"window_buy_txn":{"type":"integer"},"window_sell_txn":{"type":"integer"},"sold_in_window":{"type":"boolean"},"bought_at":{"type":"string","nullable":true},"realized_pnl":{"type":"number","description":"Lifetime realized PnL (native)."},"realized_pnl_usd":{"type":"number"},"realized_pnl_percentage":{"type":"number"},"bag_pct":{"type":"number","description":"% of peak holding still held."},"supply_pct":{"type":"number","description":"% of total supply held."},"still_holding":{"type":"boolean"},"is_active":{"type":"boolean","description":"bag_pct > 1%."}}}}}},"GatedTokenBlock":{"type":"object","description":"Token identity + live market-cap / bonding-curve state (gated mode).","properties":{"mint":{"type":"string"},"token_name":{"type":"string","nullable":true},"blockchain":{"type":"string","enum":["solana","bnb","base","eth"]},"currency":{"type":"string","enum":["SOL","BNB","ETH"]},"token_supply":{"type":"number","nullable":true},"token_decimals":{"type":"integer","nullable":true},"market_cap":{"type":"number","nullable":true,"description":"Market cap in native units (price x supply; pump.fun: price x 1e9)."},"market_cap_usd":{"type":"number","nullable":true},"market_cap_currency":{"type":"string","enum":["SOL","BNB","ETH"],"nullable":true},"pool":{"type":"string","nullable":true,"description":"pump, pump-amm, raydium-launchpad, raydium, …"},"on_curve":{"type":"boolean","nullable":true},"bonding_curve_progress":{"type":"number","nullable":true,"description":"0–100; 100 at migration."},"market_cap_updated_at":{"type":"string","nullable":true,"description":"ISO timestamp of the market-cap snapshot."}}},"GatedThreshold":{"type":"object","properties":{"min_buy":{"type":"number"},"entry_at":{"type":"array","items":{"type":"integer"}},"gate":{"type":"integer","description":"Smallest entry tier (the gate)."},"tier_reached":{"type":"integer","nullable":true,"description":"Highest entry tier actually reached."},"max_wallet_buy":{"type":"number","nullable":true},"exit_at":{"type":"array","items":{"type":"integer"}},"exit_at_met":{"type":"array","items":{"type":"integer"},"description":"Exit tiers already satisfied (holding <= tier)."}}},"Profile":{"type":"object","properties":{"name":{"type":"string"},"image_url":{"type":"string"},"twitter":{"type":"string"},"telegram":{"type":"string"},"blockchain":{"type":"string","enum":["solana","bnb","base","eth"]},"currency":{"type":"string","enum":["SOL","BNB","ETH"]},"type":{"type":"string","enum":["kol","smart","whale"]},"active_hours":{"type":"string","nullable":true}}},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"}}}}}}
```