> 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/signal-history.md).

# Signal History

Historical entry/exit cluster signals for backtesting.

## Signals History — Backtest Cluster Signals

> Replays cluster detection over history. Provide gated parameters for the full cluster model, or use the legacy \`type\` + \`days\` form for a compact summary.<br>

```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Signals History (Backtest)","version":"2.0.0"},"tags":[{"name":"Signal History","description":"Historical entry/exit cluster signals for backtesting."}],"servers":[{"url":"https://api.cabalspy.xyz"}],"paths":{"/v1/signals/history":{"get":{"tags":["Signal History"],"summary":"Signals History — Backtest Cluster Signals","operationId":"getSignalsHistory","description":"Replays cluster detection over history. Provide gated parameters for the full cluster model, or use the legacy `type` + `days` form for a compact summary.\n","parameters":[{"name":"blockchain","in":"query","required":true,"schema":{"type":"string","enum":["solana","bnb","base","eth"]}},{"name":"kol","in":"query","required":false,"description":"Gated: KOL entry tiers, CSV up to 3 (e.g. 5,10,20).","schema":{"type":"string"}},{"name":"smart","in":"query","required":false,"description":"Gated: smart-money entry tiers, CSV up to 3.","schema":{"type":"string"}},{"name":"kol_min_buy","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"kol_max_buy","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"kol_exit","in":"query","required":false,"description":"Gated: KOL exit tiers, CSV up to 2 (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,"schema":{"type":"string"}},{"name":"include_wallets","in":"query","required":false,"schema":{"type":"string"}},{"name":"exclude_wallets","in":"query","required":false,"schema":{"type":"string"}},{"name":"min_win_rate","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"min_token_age","in":"query","required":false,"description":"hours","schema":{"type":"number","minimum":0}},{"name":"max_token_age","in":"query","required":false,"description":"hours","schema":{"type":"number","minimum":0}},{"name":"type","in":"query","required":false,"description":"Legacy: wallet type.","schema":{"type":"string","enum":["kol","smart","whale"]}},{"name":"days","in":"query","required":false,"description":"Legacy: lookback window.","schema":{"type":"string","enum":["7","30","90","all"],"default":"30"}},{"name":"mode","in":"query","required":false,"description":"Legacy: filter by signal_type.","schema":{"type":"string","enum":["cluster","entry","exit"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":200}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Gated mode → `data.gated:true` with `data.signals[]` in the full cluster model (same shape as `/v1/signals` gated, each carrying token market cap / on_curve / bonding_curve_progress). Legacy mode → compact per-day summary.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GatedHistoryEnvelope"},{"$ref":"#/components/schemas/LegacyHistoryEnvelope"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"schemas":{"GatedHistoryEnvelope":{"type":"object","description":"Gated history. `data.signals[]` use the same cluster model as `/v1/signals` gated (token block + gate + window.by_type + token_stats + wallets), replayed over the requested days.\n","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":{"type":"object","description":"Cluster signal — see /v1/signals GatedSignal."}},"warnings":{"type":"array","items":{"type":"string"}}}},"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"}}}}}}},"LegacyHistoryEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"blockchain":{"type":"string","enum":["solana","bnb","base","eth"]},"type":{"type":"string","enum":["kol","smart","whale"]},"days":{"type":"string","enum":["7","30","90","all"]},"_total":{"type":"integer"},"signals":{"type":"array","items":{"type":"object","properties":{"token":{"$ref":"#/components/schemas/HistoryTokenBlock"},"signal_type":{"type":"string","enum":["cluster","entry","exit"]},"signal_strength":{"type":"string","enum":["strong","medium"]},"wallet_count":{"type":"integer"},"total_invested":{"type":"number"},"total_invested_usd":{"type":"number"},"currency":{"type":"string","enum":["SOL","BNB","ETH"]},"triggered_at":{"type":"string"},"day":{"type":"string"},"window":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"cached":{"type":"boolean"},"cache_age":{"type":"number","nullable":true},"pagination":{"type":"object","nullable":true,"properties":{"limit":{"type":"integer"},"total":{"type":"integer"},"returned":{"type":"integer"}}}}}}},"HistoryTokenBlock":{"type":"object","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},"market_cap_usd":{"type":"number","nullable":true},"market_cap_currency":{"type":"string","enum":["SOL","BNB","ETH"],"nullable":true},"pool":{"type":"string","nullable":true},"on_curve":{"type":"boolean","nullable":true},"bonding_curve_progress":{"type":"number","nullable":true},"market_cap_updated_at":{"type":"string","nullable":true}}},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"}}}}}}
```