> ## 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

> Live trade signals derived from tracked wallet activity, including token clusters where several wallets buy the same token within a time window.

Live trade signals derived from tracked wallet activity in a recent time window. The main mode, cluster, surfaces tokens where several tracked wallets are buying at once, a strong early signal. Two more modes, entry and exit, return individual buy and sell signals in the feed format.

Use it to drive alerts, for example notify me when three or more KOLs buy the same token within an hour. Signals are derived live from the feed, so they reflect the current window every time.

<Tip>
  Choose the mode with mode. cluster groups wallets buying the same token, entry and exit return single buy or sell events. Tune clusters with min\_wallets, min\_value and hours. An advanced gated mode is available by passing per type filters like kol\_min\_wallets and smart\_min\_wallets.
</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="mode" type="string" required>
  Signal mode. One of cluster, entry, exit.
</ParamField>

<ParamField query="min_wallets" default="3" type="integer">
  cluster mode. Minimum number of wallets buying the same token to form a cluster.
</ParamField>

<ParamField query="min_value" default="0" type="number">
  Minimum trade value to consider (native).
</ParamField>

<ParamField query="hours" default="1" type="number">
  Time window in hours to look back for signals.
</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?blockchain=solana&type=kol&mode=cluster&min_wallets=3&hours=1&api_key=YOUR_KEY"
  ```

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

  params = {
      "blockchain": "solana", "type": "kol", "mode": "cluster",
      "min_wallets": 3, "hours": 1, "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/signals", params=params)

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

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

## Response

The response shape depends on mode. Below is the cluster mode, the most detailed. entry and exit return individual transactions in the same shape as the transactions feed (with holdings\_after).

<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="currency" type="string">
      Native currency.
    </ResponseField>

    <ResponseField name="filters" type="object">
      The applied filters (min\_win\_rate, include\_wallets, exclude\_wallets, min\_token\_age\_hours, max\_token\_age\_hours).
    </ResponseField>

    <ResponseField name="signals" type="array">
      <Expandable title="signal (cluster)">
        <ResponseField name="token" type="object">
          Token block (mint, token\_name, blockchain, currency, token\_supply, token\_decimals).
        </ResponseField>

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

        <ResponseField name="signal_strength" type="string">
          strong or medium, based on how many wallets qualified.
        </ResponseField>

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

        <ResponseField name="gate" type="object">
          Whether the gate was met and the thresholds used.
        </ResponseField>

        <ResponseField name="window" type="object">
          <Expandable title="window">
            <ResponseField name="hours" type="number">
              The window in hours.
            </ResponseField>

            <ResponseField name="wallet_count" type="integer">
              How many wallets bought in the window.
            </ResponseField>

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

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

            <ResponseField name="total_invested_usd" type="number">
              Total invested in USD.
            </ResponseField>

            <ResponseField name="first_buy_at" type="string">
              Timestamp of the first buy in the cluster.
            </ResponseField>

            <ResponseField name="latest_buy_at" type="string">
              Timestamp of the latest buy in the cluster.
            </ResponseField>

            <ResponseField name="time_span_minutes" type="number">
              Minutes between first and latest buy.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="token_stats" type="object">
          Whole history token stats (total\_buyers, still\_holding\_count, active\_count, total\_volume, total\_volume\_usd, net\_flow, holders\_by\_type, first\_entry\_time).
        </ResponseField>

        <ResponseField name="wallets" type="array">
          <Expandable title="wallet in the cluster">
            <ResponseField name="profile" type="object">
              Wallet profile.
            </ResponseField>

            <ResponseField name="wallet_type" type="string">
              kol, smart or whale.
            </ResponseField>

            <ResponseField name="win_rate" type="number">
              Lifetime win rate, only when min\_win\_rate was requested, otherwise null.
            </ResponseField>

            <ResponseField name="window_invested" type="number">
              Invested in the window (native).
            </ResponseField>

            <ResponseField name="window_invested_usd" type="number">
              Invested in the window in USD.
            </ResponseField>

            <ResponseField name="window_buy_txn" type="integer">
              Buys in the window.
            </ResponseField>

            <ResponseField name="window_sell_txn" type="integer">
              Sells in the window.
            </ResponseField>

            <ResponseField name="sold_in_window" type="boolean">
              Whether the wallet also sold in the window.
            </ResponseField>

            <ResponseField name="bought_at" type="string">
              When the wallet bought.
            </ResponseField>

            <ResponseField name="realized_pnl" type="number">
              Lifetime realized PnL on this token (native). Present when trader data exists.
            </ResponseField>

            <ResponseField name="realized_pnl_usd" type="number">
              Realized PnL in USD.
            </ResponseField>

            <ResponseField name="realized_pnl_percentage" type="number">
              Realized PnL percentage.
            </ResponseField>

            <ResponseField name="bag_pct" type="number">
              Percent of peak holding still held.
            </ResponseField>

            <ResponseField name="supply_pct" type="number">
              Percent of supply held.
            </ResponseField>

            <ResponseField name="still_holding" type="boolean">
              Whether the wallet still holds.
            </ResponseField>

            <ResponseField name="is_active" type="boolean">
              True when bag\_pct is above 1 percent.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Standard pagination object.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response (cluster) theme={null}
  {
    "success": true,
    "data": {
      "blockchain": "solana",
      "wallet_types": ["kol"],
      "currency": "SOL",
      "filters": {
        "min_win_rate": null,
        "include_wallets": null,
        "exclude_wallets": null,
        "min_token_age_hours": null,
        "max_token_age_hours": null
      },
      "signals": [
        {
          "token": {
            "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
            "token_name": "invisibull",
            "blockchain": "solana",
            "currency": "SOL",
            "token_supply": 1000000000,
            "token_decimals": 6
          },
          "signal_type": "cluster",
          "signal_strength": "strong",
          "currency": "SOL",
          "gate": { "met": true, "wallet_types": ["kol"], "thresholds": { "kol": 3 } },
          "window": {
            "hours": 1,
            "wallet_count": 5,
            "by_type": { "kol": 5 },
            "total_invested": 12.4,
            "total_invested_usd": 1021.4,
            "first_buy_at": "2026-07-06T10:20:00Z",
            "latest_buy_at": "2026-07-06T10:52:00Z",
            "time_span_minutes": 32.0
          },
          "token_stats": {
            "total_buyers": 12,
            "still_holding_count": 8,
            "active_count": 7,
            "total_volume": 44.6,
            "total_volume_usd": 3673.2,
            "net_flow": 30.1,
            "holders_by_type": { "kol_count": 5, "smart_count": 0, "whale_count": 0 },
            "first_entry_time": "2026-07-06T09:58:00Z"
          },
          "wallets": [
            {
              "profile": {
                "name": "Maze",
                "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
                "twitter": "https://x.com/MazeCCC",
                "telegram": "",
                "blockchain": "solana",
                "currency": "SOL",
                "type": "kol"
              },
              "wallet_type": "kol",
              "win_rate": null,
              "window_invested": 3.2,
              "window_invested_usd": 263.6,
              "window_buy_txn": 1,
              "window_sell_txn": 0,
              "sold_in_window": false,
              "bought_at": "2026-07-06T10:20:00Z",
              "realized_pnl": 0.0,
              "realized_pnl_usd": 0.0,
              "realized_pnl_percentage": 0.0,
              "bag_pct": 100.0,
              "supply_pct": 0.32,
              "still_holding": true,
              "is_active": true
            }
          ]
        }
      ]
    },
    "pagination": { "limit": 50, "total": 1, "has_more": false, "next_cursor": null },
    "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, type or mode missing or invalid. |
| 401    | unauthorized       | API key missing.                             |
| 403    | forbidden          | API key invalid or credits exhausted.        |
| 429    | rate\_limited      | Rate limit exceeded.                         |