> 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/data-stream/signals.md).
# Signals
Live KOL and smart-money entry/exit cluster signals across Solana, BNB Chain, Base and Ethereum. One stream; pick the chain with `blockchain` and set per-type thresholds at subscribe time.
## Signals — Live Entry & Exit Cluster Alerts (WebSocket)
> Subscribe to the live signal stream and receive a \`signal\` message each time an entry or exit tier is reached for the configured wallet types.\
> \
> \- \`blockchain\` (required) — \`solana\`, \`bnb\`, \`base\`, \`eth\`. Change this to\
> switch chain.\
> \
> \- \`token\` (optional, default \`\*\`) — a mint/contract to watch one token, or\
> \`\*\` for all.\
> \
> \- \`kol\` / \`smart\` (optional) — per-type threshold blocks (\`min\_buy\`,\
> \`entry\_at\`, \`exit\_at\`, \`max\_wallet\_buy\`).\
> \
> \- \`include\_wallets\`, \`exclude\_wallets\`, \`min\_win\_rate\`, \`min\_token\_age\`,\
> \`max\_token\_age\` (optional) — subscription-wide filters.
```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Signal Stream (Live Entry & Exit Cluster Signals)","version":"2.0.0"},"tags":[{"name":"Signals","description":"Live KOL and smart-money entry/exit cluster signals across Solana, BNB Chain, Base and Ethereum. One stream; pick the chain with `blockchain` and set per-type thresholds at subscribe time.\n"}],"servers":[{"url":"wss://stream.cabalspy.xyz","description":"Production WebSocket gateway"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"apiKey"}},"schemas":{"SubscribeSignalMessage":{"type":"object","description":"Client -> server. Start receiving entry/exit cluster signals; filters persist until unsubscribe.","properties":{"op":{"type":"string","enum":["subscribe"]},"stream":{"type":"string","enum":["signal"]},"blockchain":{"type":"string","enum":["solana","bnb","base","eth"],"description":"Change this to switch chain."},"token":{"type":"string","description":"A mint/contract, or \"*\" for all tokens."},"kol":{"allOf":[{"$ref":"#/components/schemas/ThresholdBlock"}],"description":"KOL threshold block (optional)."},"smart":{"allOf":[{"$ref":"#/components/schemas/ThresholdBlock"}],"description":"Smart-money threshold block (optional; not available on eth)."},"include_wallets":{"type":"array","items":{"type":"string"},"description":"Only these wallets count toward the cluster."},"exclude_wallets":{"type":"array","items":{"type":"string"},"description":"These wallets never count."},"min_win_rate":{"type":"number","minimum":0,"maximum":100,"description":"Drop wallets below this lifetime win-rate. Warned + skipped if win-rate data is not yet warm."},"min_token_age":{"type":"number","description":"Minimum token age in hours."},"max_token_age":{"type":"number","description":"Maximum token age in hours."}},"required":["op","stream","blockchain"]},"ThresholdBlock":{"type":"object","description":"Per-type threshold config (kol or smart), as normalized by the server.","properties":{"min_buy":{"type":"number","description":"Minimum cumulative buy (native) for a wallet to qualify. 0 = no filter. Aliases: min_sol, min_value."},"entry_at":{"type":"array","items":{"type":"integer"},"description":"Up to 3 ascending wallet counts; each fires once. Alias: buy_slots."},"exit_at":{"type":"array","items":{"type":"integer"},"description":"Up to 2 \"still holding\" counts (descending). Alias: sell_remaining."},"max_wallet_buy":{"type":"number","nullable":true,"description":"Ignore wallets whose cumulative buy exceeds this (native). Alias: max_buy."}}},"SignalEnvelope":{"type":"object","description":"One cluster signal — an entry tier reached, or an exit tier reached.","properties":{"success":{"type":"boolean"},"channel":{"type":"string","description":"Channel that produced this message — signal.."},"event":{"type":"string","enum":["signal"]},"data":{"type":"object","properties":{"signal_kind":{"type":"string","enum":["entry","exit"],"description":"entry = an entry tier was reached; exit = an exit tier was reached."},"blockchain":{"type":"string","enum":["solana","bnb","base","eth"]},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart"]},"description":"Wallet types that participated in this signal."},"mint":{"type":"string","description":"Mint (Solana) or contract address (EVM)."},"token":{"$ref":"#/components/schemas/TokenBlock"},"threshold":{"type":"object","description":"What fired plus the normalized per-type config of the subscription.","properties":{"fired_on":{"type":"string","enum":["entry","exit"]},"exit_type":{"type":"string","enum":["kol","smart"],"nullable":true,"description":"On an exit signal","which type's exit tier fired.":null},"exit_remaining":{"type":"integer","nullable":true,"description":"On an exit signal","the \"still holding\" count that was reached.":null},"currency":{"type":"string","enum":["SOL","BNB","ETH"]},"kol":{"allOf":[{"$ref":"#/components/schemas/ThresholdBlock"}],"nullable":true},"smart":{"allOf":[{"$ref":"#/components/schemas/ThresholdBlock"}],"nullable":true}}},"cluster":{"type":"object","description":"State of the cluster for this token at the moment the signal fired.","properties":{"kol":{"type":"object","nullable":true,"properties":{"qualifying":{"type":"integer","description":"Qualifying KOL wallets (cumulative buy >= min_buy","within filters).":null},"sold":{"type":"integer","description":"Of those","how many have sold at least once.":null},"holding":{"type":"integer","description":"qualifying minus sold."}}},"smart":{"type":"object","nullable":true,"properties":{"qualifying":{"type":"integer"},"sold":{"type":"integer"},"holding":{"type":"integer"}}},"qualifying_total":{"type":"integer","description":"Total qualifying wallets across configured types."},"total_invested":{"type":"number","description":"Sum of qualifying wallets' cumulative buys (native)."},"total_invested_usd":{"type":"number","nullable":true},"unrealized_pnl_sol":{"type":"number","nullable":true,"description":"Bag-weighted unrealized PnL of held capital (native). Field name uses the chain's native unit conceptually; key is unrealized_pnl_sol."},"unrealized_pnl_usd":{"type":"number","nullable":true},"unrealized_pnl_pct":{"type":"number","nullable":true,"description":"Unrealized PnL as % of held entry capital."},"currency":{"type":"string","enum":["SOL","BNB","ETH"]}}},"trigger":{"type":"object","description":"The single trade that pushed the cluster over the tier.","properties":{"wallet":{"type":"string"},"action":{"type":"string","enum":["buy","sell"]},"value":{"type":"number","description":"Trade size in native currency."},"signature":{"type":"string","nullable":true},"created_at":{"description":"Trade time — unix seconds (Solana) or ISO timestamp (EVM)."}}},"wallets":{"type":"array","description":"The qualifying wallets (largest cumulative buyer first; capped per signal).","items":{"type":"object","properties":{"wallet":{"type":"string"},"wallet_type":{"type":"string","enum":["kol","smart"]},"win_rate":{"type":"number","nullable":true,"description":"Lifetime win-rate (0–100); null until win-rate data is warm."},"profile":{"$ref":"#/components/schemas/Profile"},"invested":{"type":"number","description":"Wallet's cumulative buy in this token (native)."},"invested_usd":{"type":"number","nullable":true},"max_single_buy":{"type":"number","description":"Largest single buy by this wallet (native)."},"buy_txn":{"type":"integer"},"sell_txn":{"type":"integer"},"sold_value":{"type":"number","description":"Cumulative sold amount (native)."},"sold":{"type":"boolean","description":"True if the wallet has at least one sell in this token."},"bag_pct":{"type":"number","nullable":true,"description":"% of peak holding still held (100 = full bag, 0 = out)."},"first_buy_at":{"type":"string","nullable":true,"description":"ISO timestamp of the wallet's first buy."},"entry_market_cap":{"type":"number","nullable":true,"description":"Market cap (native) at the wallet's entry. null if not captured live."},"entry_market_cap_usd":{"type":"number","nullable":true},"unrealized_pnl_sol":{"type":"number","nullable":true,"description":"Bag-weighted unrealized PnL for this wallet (native). 0 when fully sold; null if entry market cap unknown."},"unrealized_pnl_pct":{"type":"number","nullable":true,"description":"Price return from entry to now (0 when fully sold)."}}}},"warnings":{"type":"array","items":{"type":"string"},"description":"Optional, English. e.g. deprecated/unknown parameters."}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"TokenBlock":{"type":"object","description":"Token identity plus live market-cap / bonding-curve state.","properties":{"mint":{"type":"string"},"symbol":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"supply":{"type":"number","nullable":true,"description":"Total supply (decimal-adjusted)."},"decimals":{"type":"integer","nullable":true},"market_cap":{"type":"number","nullable":true,"description":"Market cap in native units (price x supply). For pump.fun: price x 1e9."},"market_cap_usd":{"type":"number","nullable":true,"description":"market_cap converted at the current native price."},"market_cap_currency":{"type":"string","enum":["SOL","BNB","ETH"],"nullable":true},"pool":{"type":"string","nullable":true,"description":"Liquidity venue: pump, pump-amm, raydium-launchpad, raydium, …"},"on_curve":{"type":"boolean","nullable":true,"description":"True while the token is still on the pump.fun bonding curve (pre-migration)."},"bonding_curve_progress":{"type":"number","nullable":true,"description":"0–100. Reaches 100 at migration (on_curve:false)."}}},"Profile":{"type":"object","description":"Identity and classification of a tracked wallet.","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"]},"active_hours":{"type":"string","nullable":true}}}}},"paths":{"/signal":{"get":{"tags":["Signals"],"summary":"Signals — Live Entry & Exit Cluster Alerts (WebSocket)","operationId":"streamSignals","description":"Subscribe to the live signal stream and receive a `signal` message each time an entry or exit tier is reached for the configured wallet types.\n\n- `blockchain` (required) — `solana`, `bnb`, `base`, `eth`. Change this to\n switch chain.\n\n- `token` (optional, default `*`) — a mint/contract to watch one token, or\n `*` for all.\n\n- `kol` / `smart` (optional) — per-type threshold blocks (`min_buy`,\n `entry_at`, `exit_at`, `max_wallet_buy`).\n\n- `include_wallets`, `exclude_wallets`, `min_win_rate`, `min_token_age`,\n `max_token_age` (optional) — subscription-wide filters.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeSignalMessage"}}}},"responses":{"200":{"description":"A `signal` message pushed each time an entry or exit tier is reached. (The connection also delivers a `connected` welcome, a `subscribed` ack per subscribe, and `error` messages — see schemas.)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalEnvelope"}}}}}}}}}
```