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

# Bundle Snapshot

> Detect coordinated KOL bundles on a Solana token, the side wallets that buy alongside a KOL in the same block, with proof and live positions.

Detect coordinated bundles on a Solana token. A bundle is a KOL wallet plus the side wallets that bought alongside it in the same block, a common pattern for insiders riding a KOL call. For each detected bundle you get the KOL, the side wallets, a confidence score, on chain proof and a live position for every wallet.

Use it to flag tokens where a KOL is buying together with hidden wallets, or to show a bundle breakdown on a token page. Positions (unrealized PnL, remaining value, entry market cap) are computed live at request time.

<Tip>
  Bundle detection is Solana only. If no bundles are detected for the token you get a normal 200 with an empty bundles array and the token block, so you can poll. Within each bundle the KOL wallet is marked with is\_kol true, and side wallets carry extra proof fields like adjacent\_to\_kol and same\_fee.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Must be solana. Bundle detection is only available on Solana.
</ParamField>

<ParamField query="mint" type="string" required>
  The token mint address to inspect for bundles.
</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/bundle?blockchain=solana&mint=3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump&api_key=YOUR_KEY"
  ```

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

  params = {
      "blockchain": "solana",
      "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
      "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/bundle", params=params)
  d = r.json()["data"]

  for b in d["bundles"]:
      print("KOL", b["kol_wallet"], "confidence", b["confidence"], "wallets", b["wallet_count"])
      for w in b["bundle_wallets"]:
          pos = w["position"]
          print("  ", w["address"], "kol" if w["is_kol"] else "side", "uPNL", pos["unrealized_pnl_sol"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    mint: "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
    api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/bundle?${p}`);
  const { data } = await res.json();
  data.bundles.forEach(b => console.log(b.kol_wallet, b.confidence, b.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">
      Always solana for this endpoint.
    </ResponseField>

    <ResponseField name="token" type="object">
      <Expandable title="token">
        <ResponseField name="mint" type="string">
          Token mint address.
        </ResponseField>

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

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

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

        <ResponseField name="market_cap" type="number">
          Current market cap in SOL.
        </ResponseField>

        <ResponseField name="market_cap_usd" type="number">
          Current market cap in USD.
        </ResponseField>

        <ResponseField name="market_cap_currency" type="string">
          Currency of the market cap value (SOL).
        </ResponseField>

        <ResponseField name="price" type="number">
          Current token price in SOL.
        </ResponseField>

        <ResponseField name="price_usd" type="number">
          Current token price in USD.
        </ResponseField>

        <ResponseField name="sol_price_usd" type="number">
          SOL price in USD used for USD conversions.
        </ResponseField>

        <ResponseField name="pool" type="string">
          Liquidity pool identifier.
        </ResponseField>

        <ResponseField name="on_curve" type="boolean">
          Whether the token is still on the bonding curve.
        </ResponseField>

        <ResponseField name="bonding_curve_progress" type="number">
          Bonding curve progress if on curve.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bundles" type="array">
      <Expandable title="bundle">
        <ResponseField name="bundle_id" type="string">
          Unique bundle identifier.
        </ResponseField>

        <ResponseField name="kol_wallet" type="string">
          Address of the KOL at the center of the bundle.
        </ResponseField>

        <ResponseField name="kol_profile" type="object">
          Profile of the KOL wallet (name, image\_url, twitter, telegram, blockchain, currency, type).
        </ResponseField>

        <ResponseField name="confidence" type="number">
          Confidence score that this is a real coordinated bundle.
        </ResponseField>

        <ResponseField name="jito_confirmed" type="boolean">
          Whether the bundle was confirmed as a Jito bundle on chain.
        </ResponseField>

        <ResponseField name="proof_type" type="string">
          The kind of proof used for detection.
        </ResponseField>

        <ResponseField name="slot" type="integer">
          Solana slot of the bundle.
        </ResponseField>

        <ResponseField name="wallet_count" type="integer">
          Number of wallets in the bundle.
        </ResponseField>

        <ResponseField name="proof" type="string">
          On chain proof reference.
        </ResponseField>

        <ResponseField name="verify_hint" type="string">
          Hint for independently verifying the bundle on chain.
        </ResponseField>

        <ResponseField name="detected_at" type="string">
          When the bundle was detected.
        </ResponseField>

        <ResponseField name="bundle_wallets" type="array">
          <Expandable title="bundle wallet, KOL first then by invested">
            <ResponseField name="address" type="string">
              Wallet address.
            </ResponseField>

            <ResponseField name="is_kol" type="boolean">
              True for the KOL wallet, false for side wallets.
            </ResponseField>

            <ResponseField name="transaction_type" type="string">
              Last transaction type buy or sell.
            </ResponseField>

            <ResponseField name="signature" type="string">
              Last transaction signature.
            </ResponseField>

            <ResponseField name="entry_source" type="string">
              How the entry was detected, for example at\_discovery.
            </ResponseField>

            <ResponseField name="position_source" type="string">
              Source of the position data, live.
            </ResponseField>

            <ResponseField name="profile" type="object">
              Wallet profile. For side wallets this may be empty.
            </ResponseField>

            <ResponseField name="fee_lamports" type="integer">
              Side wallets only. Fee paid in lamports.
            </ResponseField>

            <ResponseField name="block_index" type="integer">
              Side wallets only. Index within the block.
            </ResponseField>

            <ResponseField name="adjacent_to_kol" type="boolean">
              Side wallets only. Whether the wallet traded directly next to the KOL.
            </ResponseField>

            <ResponseField name="same_fee" type="boolean">
              Side wallets only. Whether the wallet paid the same fee as the KOL.
            </ResponseField>

            <ResponseField name="occurrences" type="integer">
              Side wallets only. How often this wallet bundled with the KOL.
            </ResponseField>

            <ResponseField name="position" type="object">
              <Expandable title="position">
                <ResponseField name="held" type="number">
                  Tokens currently held.
                </ResponseField>

                <ResponseField name="peak" type="number">
                  Peak tokens held.
                </ResponseField>

                <ResponseField name="bought_tokens" type="number">
                  Total tokens bought.
                </ResponseField>

                <ResponseField name="sold_tokens" type="number">
                  Total tokens sold.
                </ResponseField>

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

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

                <ResponseField name="invested" type="number">
                  Total invested (SOL).
                </ResponseField>

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

                <ResponseField name="max_single_buy" type="number">
                  Largest single buy (SOL).
                </ResponseField>

                <ResponseField name="buy_txn" type="integer">
                  Number of buys.
                </ResponseField>

                <ResponseField name="sell_txn" type="integer">
                  Number of sells.
                </ResponseField>

                <ResponseField name="sold_value" type="number">
                  Total sold value (SOL).
                </ResponseField>

                <ResponseField name="sold_value_usd" type="number">
                  Total sold value in USD.
                </ResponseField>

                <ResponseField name="realized_pnl_sol" type="number">
                  Realized PnL (SOL).
                </ResponseField>

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

                <ResponseField name="entry_market_cap" type="number">
                  Market cap in SOL when the wallet first bought, frozen.
                </ResponseField>

                <ResponseField name="entry_market_cap_usd" type="number">
                  Entry market cap in USD, frozen at buy time.
                </ResponseField>

                <ResponseField name="unrealized_pnl_sol" type="number">
                  Unrealized PnL on the remaining bag (SOL). Null if market cap is missing.
                </ResponseField>

                <ResponseField name="unrealized_pnl_usd" type="number">
                  Unrealized PnL in USD.
                </ResponseField>

                <ResponseField name="unrealized_pnl_pct" type="number">
                  Unrealized PnL percentage.
                </ResponseField>

                <ResponseField name="remaining_sol" type="number">
                  Current value of the remaining bag (SOL).
                </ResponseField>

                <ResponseField name="remaining_usd" type="number">
                  Current value of the remaining bag in USD.
                </ResponseField>

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

                <ResponseField name="last_activity_at" type="string">
                  ISO timestamp of the last activity.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "blockchain": "solana",
      "token": {
        "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
        "symbol": "invisibull",
        "name": "invisibull",
        "supply": 1000000000,
        "market_cap": 40.08,
        "market_cap_usd": 3301.2,
        "market_cap_currency": "SOL",
        "price": 4.008e-8,
        "price_usd": 3.3e-6,
        "sol_price_usd": 82.36,
        "pool": "pump",
        "on_curve": true,
        "bonding_curve_progress": 42.5
      },
      "bundles": [
        {
          "bundle_id": "bnd_7f3a2c",
          "kol_wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
          "kol_profile": {
            "name": "Maze",
            "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
            "twitter": "https://x.com/MazeCCC",
            "telegram": "",
            "blockchain": "solana",
            "currency": "SOL",
            "type": "kol"
          },
          "confidence": 0.92,
          "jito_confirmed": true,
          "proof_type": "same_block",
          "slot": 301948220,
          "wallet_count": 3,
          "proof": "slot:301948220",
          "verify_hint": "check same slot buys on solscan",
          "detected_at": "2026-07-04T16:25:34Z",
          "bundle_wallets": [
            {
              "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
              "is_kol": true,
              "transaction_type": "buy",
              "signature": "5xr8abc...",
              "entry_source": "at_discovery",
              "position_source": "live",
              "profile": {
                "name": "Maze",
                "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
                "twitter": "https://x.com/MazeCCC",
                "telegram": "",
                "blockchain": "solana",
                "currency": "SOL",
                "type": "kol"
              },
              "position": {
                "held": 22113972.03,
                "peak": 22113972.03,
                "bought_tokens": 22113972.03,
                "sold_tokens": 0.0,
                "bag_pct": 100.0,
                "supply_pct": 2.21,
                "invested": 1.66,
                "invested_usd": 137.44,
                "max_single_buy": 1.66,
                "buy_txn": 1,
                "sell_txn": 0,
                "sold_value": 0.0,
                "sold_value_usd": 0.0,
                "realized_pnl_sol": 0.0,
                "realized_pnl_usd": 0.0,
                "entry_market_cap": 44.6,
                "entry_market_cap_usd": 3673.2,
                "unrealized_pnl_sol": -0.099817,
                "unrealized_pnl_usd": -8.22,
                "unrealized_pnl_pct": -10.12,
                "remaining_sol": 0.886537,
                "remaining_usd": 73.02,
                "first_buy_at": "2026-07-04T16:25:34Z",
                "last_activity_at": "2026-07-04T16:40:10Z"
              }
            },
            {
              "address": "SideWa11etAbc123...",
              "is_kol": false,
              "transaction_type": "buy",
              "signature": "9kp2def...",
              "entry_source": "at_discovery",
              "position_source": "live",
              "profile": {
                "name": "",
                "image_url": "",
                "twitter": "",
                "telegram": "",
                "blockchain": "solana",
                "currency": "SOL",
                "type": null
              },
              "fee_lamports": 5000,
              "block_index": 4,
              "adjacent_to_kol": true,
              "same_fee": true,
              "occurrences": 7,
              "position": {
                "held": 8000000.0,
                "peak": 8000000.0,
                "bought_tokens": 8000000.0,
                "sold_tokens": 0.0,
                "bag_pct": 100.0,
                "supply_pct": 0.8,
                "invested": 0.6,
                "invested_usd": 49.4,
                "max_single_buy": 0.6,
                "buy_txn": 1,
                "sell_txn": 0,
                "sold_value": 0.0,
                "sold_value_usd": 0.0,
                "realized_pnl_sol": 0.0,
                "realized_pnl_usd": 0.0,
                "entry_market_cap": 44.6,
                "entry_market_cap_usd": 3673.2,
                "unrealized_pnl_sol": -0.036,
                "unrealized_pnl_usd": -2.97,
                "unrealized_pnl_pct": -10.12,
                "remaining_sol": 0.320,
                "remaining_usd": 26.4,
                "first_buy_at": "2026-07-04T16:25:34Z",
                "last_activity_at": "2026-07-04T16:25:34Z"
              }
            }
          ]
        }
      ]
    },
    "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    | missing\_parameter | mint is missing.                                           |
| 400    | invalid\_parameter | blockchain is not solana. Bundle detection is Solana only. |
| 401    | unauthorized       | API key missing.                                           |
| 403    | forbidden          | API key invalid or credits exhausted.                      |
| 429    | rate\_limited      | Rate limit exceeded.                                       |