Bundle

KOL bundle / side-wallet detection on Solana, grouped per token.

Bundle Stream — KOL Bundle / Side-Wallet Detection (WebSocket)

get

Real-time WebSocket stream of KOL bundles. CabalSpy detects wallets that a KOL controls or coordinates with — "side wallets" that buy the same token in the same Jito bundle or the same block as the KOL — and delivers them grouped per token, each with a full live position (bought, sold, held, unrealized PnL, remaining value).

Solana only. A bundle only exists because a KOL bought the token, so the token is always tracked and its market cap is always available — which is why positions and unrealized PnL can be computed for the bundle wallets too.

Whole-token delivery

You always receive the whole token, not a single bundle. Every message carries the complete current picture for one token: the bundles list holds all bundles detected in that token (a token can have several, each with a different KOL), and each bundle holds all of its wallets. When anything changes, the entire token is re-sent, so you simply replace your view of that token with the latest message — no need to merge partial updates.

Each bundle carries its own KOL

A token can contain bundles from several different KOLs. Every entry in bundles therefore has its own kol_wallet and kol_profile, and the KOL is also included inside that bundle's bundle_wallets list with is_kol: true and the same position fields as the side wallets. Take the KOL identity from each bundle's own kol_wallet / kol_profile — there is no token-level KOL, because a token can have many.

Confidence, not two event types

Confirmed side wallets and structural leads are merged into one shape, distinguished by confidence: low | medium | high | verified. verified means Jito-confirmed (jito_confirmed: true, with a bundle_id); lower tiers are on-chain footprint leads (adjacent in block, matching fee, recurrence) that are not Jito-confirmed. Each bundle also carries a human-readable proof and a verify_hint. A wallet's transaction_type is buy or sell; there is no separate sell event.

Two subscription modes — this controls how much you receive (and pay)

Every delivered message counts as one credit. The mode you subscribe with decides how many messages you get:

mode: "full" (default) — you receive the token again on every relevant change, INCLUDING marketcap ticks, so unrealized_pnl_* and remaining_* stay live to the second. Ideal for a live holder/positions table, but chatty: an active token can produce thousands of updates (and thus thousands of credits) per hour.
mode: "events" — you receive the token only on real events: a new bundle is detected, or a bundle wallet buys or sells. Marketcap-driven updates are NOT sent. Positions are still included, computed at the moment of the event. This is the economical choice when you only need to know that a bundle exists and when wallets trade. Example: 3 bundles and 10 sells on a token cost 13 credits instead of thousands.

Combine mode with the token selector freely: one token + full (live table), one token + events (cheap event feed), * + full (everything live — very high volume), * + events (every new bundle network-wide, events only).

Message events

init — one-time snapshot of all known bundles for the token at subscribe time, rebuilt from CabalSpy's store (survives restarts; positions recomputed with the current market cap). Sent in both modes.
kol_bundle — an update. In full mode this fires on new detections, trades, AND marketcap moves. In events mode it fires ONLY on new detections and trades.

Connect

Open a WebSocket to wss://stream.cabalspy.xyz with your API key as a query parameter (?apiKey=YOUR_KEY) or a Bearer header (Authorization: Bearer YOUR_KEY). You receive a {"type":"connected"} welcome.

{ "op":"subscribe", "stream":"bundle", "blockchain":"solana", "token":"<mint>", "mode":"events" }. Bundles are always token-scoped. Use "*" to receive bundles across all tokens. A concrete mint returns an init snapshot first. Omit mode (or set "full") for live marketcap-driven updates. The server replies with a subscribed ack echoing the filters (including the resolved mode).

Unsubscribe

{ "op":"unsubscribe", "stream":"bundle", "token":"<mint>" } — stops all updates for that token.

List / Ping

{ "op":"subscriptions" } lists active subscriptions; { "op":"ping" } returns a pong.

Envelope

Every message: { "success":true, "channel":"bundle.solana", "event":"init|kol_bundle", "data":{ ... }, "meta":{ ... } }.

Authorizations

AuthorizationstringRequired

Authorization: Bearer YOUR_KEY

Body

Client -> server. Subscribe to a token's bundles; token-scoped. Filters persist until unsubscribe.

opstring · enumRequiredExample: subscribePossible values:

streamstring · enumRequiredExample: bundlePossible values:

blockchainstring · enumOptional

Must be solana.

Possible values:

tokenstringRequired

A mint to watch one token, or "*" for all tokens.

Example: 2yeMv8fRYmLTmCDJJsdF7sNBFuPP2BunRkKRpUQbpump

modestring · enumOptional

'events' = only real events (new bundle, buy, sell); no marketcap updates; cheapest. 'full' = adds live marketcap-driven position updates (uPNL/remaining stay live); higher credit usage.

Default: fullPossible values:

channelstring · nullableOptional

Alternative to blockchain+token: bundle.solana. or bundle.solana for all. (Pass mode as a separate field.)

Responses

200

init and kol_bundle messages. (The connection also delivers a connected welcome, a subscribed ack per subscribe, and error messages — see schemas.)

application/json

One bundle message — init snapshot or live kol_bundle update. ALWAYS the whole token: bundles contains every bundle detected in the token, each with its own KOL and wallets. Replace your view of the token with each message.

successbooleanOptionalExample: true

channelstringOptionalExample: bundle.solana

eventstring · enumOptionalPossible values:

get/bundle

GET /bundle HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 129

{
  "op": "subscribe",
  "stream": "bundle",
  "blockchain": "solana",
  "token": "2yeMv8fRYmLTmCDJJsdF7sNBFuPP2BunRkKRpUQbpump",
  "mode": "events"
}

200

init and kol_bundle messages. (The connection also delivers a connected welcome, a subscribed ack per subscribe, and error messages — see schemas.)

{
  "success": true,
  "channel": "bundle.solana",
  "event": "kol_bundle",
  "data": {
    "blockchain": "solana",
    "token": {
      "mint": "2yeMv8fRYmLTmCDJJsdF7sNBFuPP2BunRkKRpUQbpump",
      "symbol": "EXMPL",
      "name": "Example",
      "supply": 1000000000,
      "market_cap": 2744,
      "market_cap_usd": 221500,
      "market_cap_currency": "SOL",
      "price": 0.000002744,
      "price_usd": 0.0002215,
      "sol_price_usd": 80.73,
      "pool": "pump-amm",
      "on_curve": false,
      "bonding_curve_progress": 100
    },
    "bundles": [
      {
        "bundle_id": "a1b2c3d4e5f6",
        "kol_wallet": "53BnMonkiExampleKolWalletYnsh",
        "kol_profile": {
          "name": "Monki",
          "image_url": "https://cabalspy.xyz/images/53Bn.png",
          "twitter": "https://x.com/monki",
          "telegram": "",
          "blockchain": "solana",
          "currency": "SOL",
          "type": "kol"
        },
        "confidence": "verified",
        "jito_confirmed": true,
        "proof_type": "jito_bundle",
        "slot": 372837123,
        "wallet_count": 2,
        "proof": "Bundle wallet was submitted in the SAME atomic Jito bundle as the KOL (bundle a1b2…) in slot 372837123.",
        "verify_hint": "Query Jito getBundleStatuses for bundle_id a1b2…; both signatures are listed.",
        "detected_at": "2026-07-04T09:09:00.000Z",
        "bundle_wallets": [
          {
            "address": "53BnMonkiExampleKolWalletYnsh",
            "is_kol": true,
            "transaction_type": "buy",
            "signature": "3kD9xR2...",
            "entry_source": "at_bundle",
            "position_source": "live",
            "profile": {
              "name": "Monki",
              "image_url": "https://cabalspy.xyz/images/53Bn.png",
              "twitter": "https://x.com/monki",
              "telegram": "",
              "blockchain": "solana",
              "currency": "SOL",
              "type": "kol"
            },
            "position": {
              "held": 5000000,
              "peak": 5000000,
              "bought_tokens": 5000000,
              "sold_tokens": 0,
              "bag_pct": 100,
              "supply_pct": 0.5,
              "invested": 0.98,
              "invested_usd": 79.35,
              "buy_txn": 1,
              "sell_txn": 0,
              "sold_value": 0,
              "sold_value_usd": 0,
              "sold": false,
              "realized_pnl_sol": -0.98,
              "realized_pnl_usd": -79.35,
              "entry_market_cap": 2404,
              "entry_market_cap_usd": 194100,
              "unrealized_pnl_sol": 0.13,
              "unrealized_pnl_usd": 10.48,
              "unrealized_pnl_pct": 13.2,
              "remaining_sol": 1.11,
              "remaining_usd": 89.83,
              "first_buy_at": "2026-07-04T09:05:00.000Z",
              "last_activity_at": "2026-07-04T09:09:00.000Z"
            }
          },
          {
            "address": "6RupExampleSideWalletUjRz",
            "is_kol": false,
            "transaction_type": "buy",
            "signature": "8wQ1zK5...",
            "fee_lamports": 105000,
            "block_index": 412,
            "adjacent_to_kol": true,
            "same_fee": true,
            "occurrences": 4,
            "entry_source": "at_bundle",
            "position_source": "live",
            "profile": null,
            "position": {
              "held": 5600000,
              "peak": 5600000,
              "bought_tokens": 5600000,
              "sold_tokens": 0,
              "bag_pct": 100,
              "supply_pct": 0.56,
              "invested": 1.13,
              "invested_usd": 91.37,
              "buy_txn": 1,
              "sell_txn": 0,
              "sold_value": 0,
              "sold_value_usd": 0,
              "sold": false,
              "realized_pnl_sol": -1.13,
              "realized_pnl_usd": -91.37,
              "entry_market_cap": 2404,
              "entry_market_cap_usd": 194100,
              "unrealized_pnl_sol": 0.15,
              "unrealized_pnl_usd": 12.06,
              "unrealized_pnl_pct": 13.2,
              "remaining_sol": 1.28,
              "remaining_usd": 103.43,
              "first_buy_at": "2026-07-04T09:05:00.000Z",
              "last_activity_at": "2026-07-04T09:09:00.000Z"
            }
          }
        ]
      },
      {
        "bundle_id": null,
        "kol_wallet": "ECa6DifferentKolWalletpqM8",
        "kol_profile": {
          "name": "Vero",
          "image_url": "https://cabalspy.xyz/images/ECa6.png",
          "twitter": "",
          "telegram": "",
          "blockchain": "solana",
          "currency": "SOL",
          "type": "kol"
        },
        "confidence": "high",
        "jito_confirmed": false,
        "proof_type": "on_chain_footprint",
        "slot": 372837980,
        "wallet_count": 2,
        "proof": "Same-token co-buyer within a few block positions of the KOL, sharing the KOL's fee and similar size. Footprint lead, not Jito-confirmed.",
        "verify_hint": "Open the slot on a Solana explorer; the buys sit close together with the same fee.",
        "detected_at": "2026-07-04T09:08:40.000Z",
        "bundle_wallets": [
          {
            "address": "ECa6DifferentKolWalletpqM8",
            "is_kol": true,
            "transaction_type": "buy",
            "signature": "7mF2aB1...",
            "entry_source": "at_discovery",
            "position_source": "live",
            "profile": {
              "name": "Vero",
              "image_url": "https://cabalspy.xyz/images/ECa6.png",
              "twitter": "",
              "telegram": "",
              "blockchain": "solana",
              "currency": "SOL",
              "type": "kol"
            },
            "position": {
              "held": 4200000,
              "peak": 4200000,
              "bought_tokens": 4200000,
              "sold_tokens": 0,
              "bag_pct": 100,
              "supply_pct": 0.42,
              "invested": 1.03,
              "invested_usd": 83.56,
              "buy_txn": 1,
              "sell_txn": 0,
              "sold_value": 0,
              "sold_value_usd": 0,
              "sold": false,
              "realized_pnl_sol": -1.03,
              "realized_pnl_usd": -83.56,
              "entry_market_cap": 2380,
              "entry_market_cap_usd": 192200,
              "unrealized_pnl_sol": 0.13,
              "unrealized_pnl_usd": 10.48,
              "unrealized_pnl_pct": 12.54,
              "remaining_sol": 1.16,
              "remaining_usd": 94.04,
              "first_buy_at": "2026-07-04T09:08:40.000Z",
              "last_activity_at": "2026-07-04T09:08:40.000Z"
            }
          },
          {
            "address": "5U9dExampleSideWallethh9p",
            "is_kol": false,
            "transaction_type": "buy",
            "signature": "9xQrT...",
            "fee_lamports": 100000,
            "block_index": 588,
            "adjacent_to_kol": true,
            "same_fee": true,
            "occurrences": 2,
            "entry_source": "at_discovery",
            "position_source": "live",
            "profile": null,
            "position": {
              "held": 4180000,
              "peak": 4180000,
              "bought_tokens": 4180000,
              "sold_tokens": 0,
              "bag_pct": 100,
              "supply_pct": 0.418,
              "invested": 1.03,
              "invested_usd": 83.62,
              "buy_txn": 1,
              "sell_txn": 0,
              "sold_value": 0,
              "sold_value_usd": 0,
              "sold": false,
              "realized_pnl_sol": -1.03,
              "realized_pnl_usd": -83.62,
              "entry_market_cap": 2380,
              "entry_market_cap_usd": 192200,
              "unrealized_pnl_sol": 0,
              "unrealized_pnl_usd": -0.04,
              "unrealized_pnl_pct": -0.05,
              "remaining_sol": 1.03,
              "remaining_usd": 83.59,
              "first_buy_at": "2026-07-04T09:08:40.000Z",
              "last_activity_at": "2026-07-04T09:08:40.000Z"
            }
          }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_ab12cd34",
    "version": "2.1.0",
    "timestamp": "2026-07-04T09:09:24.696Z"
  }
}

PreviousSignals NextHolder

Last updated 9 days ago