> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals History

> Historical cluster signals that would have fired on past days, useful for backtesting a KOL cluster strategy against real outcomes.

The historical counterpart to Signals. Returns cluster signals that would have fired on past days, so you can backtest a strategy. Each entry marks the token, how many wallets clustered, how much they invested, and when the signal triggered.

Use it to answer questions like how often did a three KOL cluster precede a move, or to replay signals for a given day.

<Tip>
  Look back with days. Each signal carries would\_have\_fired and the day it belongs to, along with triggered\_at, so you can line signals up against price history from your own source.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain. One of solana, bnb, base, eth.
</ParamField>

<ParamField query="type" type="string" required>
  Wallet category kol, smart or whale.
</ParamField>

<ParamField query="days" type="integer">
  How many past days to include.
</ParamField>

<ParamField query="min_wallets" default="3" type="integer">
  Minimum wallets that must have clustered for a historical signal.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of signals to return.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key. Alternatively pass it as an Authorization Bearer header.
</ParamField>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cabalspy.xyz/v1/signals/history?blockchain=solana&type=kol&days=7&api_key=YOUR_KEY"
  ```

  ```python Python theme={null}
  import requests

  params = {"blockchain": "solana", "type": "kol", "days": 7, "api_key": "YOUR_KEY"}
  r = requests.get("https://api.cabalspy.xyz/v1/signals/history", params=params)

  for s in r.json()["data"]["signals"]:
      print(s["day"], s["token_name"], "wallets", s["wallet_count"], "invested", s["total_invested"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana", type: "kol", days: "7", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/signals/history?${p}`);
  const { data } = await res.json();
  data.signals.forEach(s => console.log(s.day, s.token_name, s.wallet_count));
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="blockchain" type="string">
      Requested chain.
    </ResponseField>

    <ResponseField name="wallet_types" type="array">
      The wallet types included.
    </ResponseField>

    <ResponseField name="days" type="integer">
      The number of past days included.
    </ResponseField>

    <ResponseField name="filters" type="object">
      Applied filters (min\_win\_rate, include\_wallets, exclude\_wallets).
    </ResponseField>

    <ResponseField name="signals" type="array">
      <Expandable title="historical signal">
        <ResponseField name="mint" type="string">
          Token mint.
        </ResponseField>

        <ResponseField name="token_name" type="string">
          Token name.
        </ResponseField>

        <ResponseField name="token_supply" type="number">
          Total supply.
        </ResponseField>

        <ResponseField name="signal_type" type="string">
          cluster.
        </ResponseField>

        <ResponseField name="signal_strength" type="string">
          strong or medium.
        </ResponseField>

        <ResponseField name="wallet_count" type="integer">
          How many wallets clustered.
        </ResponseField>

        <ResponseField name="by_type" type="object">
          Wallet counts split by type.
        </ResponseField>

        <ResponseField name="total_invested" type="number">
          Total invested in the cluster (native).
        </ResponseField>

        <ResponseField name="total_invested_usd" type="number">
          Total invested in USD, or null if no price was available.
        </ResponseField>

        <ResponseField name="currency" type="string">
          Native currency.
        </ResponseField>

        <ResponseField name="triggered_at" type="string">
          When the first buy of the cluster happened.
        </ResponseField>

        <ResponseField name="day" type="string">
          The day this signal belongs to.
        </ResponseField>

        <ResponseField name="window" type="string">
          The aggregation window, 1d.
        </ResponseField>

        <ResponseField name="would_have_fired" type="boolean">
          Whether the signal would have fired under the thresholds.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "blockchain": "solana",
      "wallet_types": ["kol"],
      "days": 7,
      "filters": {
        "min_win_rate": null,
        "include_wallets": null,
        "exclude_wallets": null
      },
      "signals": [
        {
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "token_supply": 1000000000,
          "signal_type": "cluster",
          "signal_strength": "strong",
          "wallet_count": 5,
          "by_type": { "kol": 5 },
          "total_invested": 12.4,
          "total_invested_usd": 1021.4,
          "currency": "SOL",
          "triggered_at": "2026-07-04T16:25:34Z",
          "day": "2026-07-04",
          "window": "1d",
          "would_have_fired": true
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code               | Meaning                                |
| ------ | ------------------ | -------------------------------------- |
| 400    | invalid\_parameter | blockchain or type missing or invalid. |
| 401    | unauthorized       | API key missing.                       |
| 403    | forbidden          | API key invalid or credits exhausted.  |
| 429    | rate\_limited      | Rate limit exceeded.                   |