> 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/data-stream/holder.md).
# Holder
Live positions of tracked KOL, smart-money and whale wallets in a single Solana token — bought, sold, held, unrealized PnL and remaining value — seeded from history on subscribe and updated live.
## Holder — Live Tracked-Wallet Positions per Token (WebSocket)
> Subscribe to one Solana token and receive an \`init\` snapshot of all tracked holders, then live \`holder\_update\` (a wallet traded) and \`position\_update\` (market cap moved) messages.\
> \
> \- \`blockchain\` (required) — must be \`solana\`.\
> \- \`token\` (required) — a mint to watch one token, or \`\*\` for all tokens\
> live (no snapshot).\
> \
> \- \`wallet\_types\` (optional) — any subset of \`kol\`, \`smart\`, \`whale\`;\
> defaults to all three.
```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Holder Stream (Live Tracked-Wallet Positions per Token)","version":"2.0.0"},"tags":[{"name":"Holder","description":"Live positions of tracked KOL, smart-money and whale wallets in a single Solana token — bought, sold, held, unrealized PnL and remaining value — seeded from history on subscribe and updated live.\n"}],"servers":[{"url":"wss://stream.cabalspy.xyz","description":"Production WebSocket gateway"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"apiKey"}},"schemas":{"SubscribeHolderMessage":{"type":"object","description":"Client -> server. Subscribe to a token's tracked holders; filters persist until unsubscribe.","properties":{"op":{"type":"string","enum":["subscribe"]},"stream":{"type":"string","enum":["holder"]},"blockchain":{"type":"string","enum":["solana"],"description":"Must be solana."},"token":{"type":"string","description":"A mint to watch one token, or \"*\" for all tokens (live only, no snapshot)."},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart","whale"]},"description":"Any subset; defaults to all three if omitted."},"channel":{"type":"string","description":"Alternative to blockchain+token: holder.solana. or holder.solana for all.","nullable":true}},"required":["op","stream","token"]},"HolderEnvelope":{"type":"object","description":"One holder message — init snapshot, holder_update, or position_update.","properties":{"success":{"type":"boolean"},"channel":{"type":"string"},"event":{"type":"string","enum":["init","holder_update","position_update"]},"data":{"type":"object","properties":{"trigger":{"type":"string","enum":["transaction","marketcap"],"nullable":true,"description":"transaction (holder_update) or marketcap (position_update)."},"blockchain":{"type":"string","enum":["solana"]},"mint":{"type":"string","nullable":true},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart","whale"]},"nullable":true,"description":"Present on init."},"holder_count":{"type":"integer","nullable":true,"description":"Present on init and position_update."},"token":{"allOf":[{"$ref":"#/components/schemas/HolderToken"}],"nullable":true},"transaction":{"type":"object","nullable":true,"description":"Present on holder_update — the trade that triggered it.","properties":{"signature":{"type":"string","nullable":true},"slot":{"type":"integer","nullable":true},"action":{"type":"string","enum":["buy","sell"]},"transaction_type":{"type":"string","enum":["buy","sell"]},"created_at":{"type":"string","nullable":true},"token_amount":{"type":"number"},"value":{"type":"object","properties":{"currency":{"type":"string","enum":["SOL"]},"amount":{"type":"number"},"amount_usd":{"type":"number","nullable":true}}}}},"holder":{"allOf":[{"$ref":"#/components/schemas/Holder"}],"nullable":true,"description":"Present on holder_update (single wallet)."},"holders":{"type":"array","nullable":true,"description":"Present on init (full Holder objects) and position_update (HolderLite objects).","items":{"oneOf":[{"$ref":"#/components/schemas/Holder"},{"$ref":"#/components/schemas/HolderLite"}]}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"HolderToken":{"type":"object","description":"Token identity plus live market-cap / price state.","properties":{"mint":{"type":"string"},"symbol":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"supply":{"type":"number","nullable":true},"decimals":{"type":"integer","nullable":true},"market_cap":{"type":"number","nullable":true,"description":"Market cap in SOL (price x supply)."},"market_cap_usd":{"type":"number","nullable":true},"market_cap_currency":{"type":"string","enum":["SOL"],"nullable":true},"price":{"type":"number","nullable":true,"description":"Current token price in SOL."},"price_usd":{"type":"number","nullable":true},"sol_price_usd":{"type":"number","nullable":true,"description":"Current SOL/USD","so clients never need to derive it.":null},"pool":{"type":"string","nullable":true,"description":"pump, pump-amm, raydium-launchpad, …"},"on_curve":{"type":"boolean","nullable":true},"bonding_curve_progress":{"type":"number","nullable":true,"description":"0–100; 100 at migration."}}},"Holder":{"type":"object","description":"A tracked wallet with profile and position (init / holder_update).","properties":{"wallet":{"type":"string"},"wallet_type":{"type":"string","enum":["kol","smart","whale"]},"win_rate":{"type":"number","nullable":true,"description":"Lifetime win-rate (0–100); null until warm."},"profile":{"$ref":"#/components/schemas/Profile"},"position":{"$ref":"#/components/schemas/Position"}}},"Profile":{"type":"object","description":"Identity and classification of a tracked wallet.","properties":{"name":{"type":"string"},"image_url":{"type":"string"},"twitter":{"type":"string"},"telegram":{"type":"string"},"blockchain":{"type":"string","enum":["solana"]},"currency":{"type":"string","enum":["SOL"]},"type":{"type":"string","enum":["kol","smart","whale"]},"active_hours":{"type":"string","nullable":true}}},"Position":{"type":"object","description":"A tracked wallet's full position in the token.","properties":{"held":{"type":"number","description":"Tokens currently held."},"peak":{"type":"number","description":"Highest token balance ever held."},"bought_tokens":{"type":"number","description":"Cumulative tokens bought."},"sold_tokens":{"type":"number","description":"Cumulative tokens sold."},"bag_pct":{"type":"number","nullable":true,"description":"% of peak holding still held (100 = full bag, 0 = out)."},"supply_pct":{"type":"number","nullable":true,"description":"% of total token supply currently held."},"invested":{"type":"number","description":"Cumulative buy in SOL."},"invested_usd":{"type":"number","nullable":true},"max_single_buy":{"type":"number","description":"Largest single buy (SOL)."},"buy_txn":{"type":"integer"},"sell_txn":{"type":"integer"},"sold_value":{"type":"number","description":"Cumulative sold amount (SOL)."},"sold_value_usd":{"type":"number","nullable":true},"sold":{"type":"boolean","description":"True if the wallet has at least one sell."},"realized_pnl_sol":{"type":"number","description":"sold_value − invested (SOL)."},"realized_pnl_usd":{"type":"number","nullable":true},"entry_market_cap":{"type":"number","nullable":true,"description":"Market cap (SOL) at first buy. Display only; not used for uPNL."},"entry_market_cap_usd":{"type":"number","nullable":true},"unrealized_pnl_sol":{"type":"number","nullable":true,"description":"held value − cost basis at average buy price (SOL). Null while no live price."},"unrealized_pnl_usd":{"type":"number","nullable":true},"unrealized_pnl_pct":{"type":"number","nullable":true,"description":"current price / average buy price − 1, in %."},"remaining_sol":{"type":"number","nullable":true,"description":"Current value of the held bag (SOL). Never negative."},"remaining_usd":{"type":"number","nullable":true},"first_buy_at":{"type":"string","nullable":true,"description":"ISO timestamp of the wallet's first buy."},"last_activity_at":{"type":"string","nullable":true,"description":"ISO timestamp of the wallet's last trade."}}},"HolderLite":{"type":"object","description":"A tracked wallet in a position_update (no profile; client already has it).","properties":{"wallet":{"type":"string"},"wallet_type":{"type":"string","enum":["kol","smart","whale"]},"win_rate":{"type":"number","nullable":true},"position":{"$ref":"#/components/schemas/Position"}}}}},"paths":{"/holder":{"get":{"tags":["Holder"],"summary":"Holder — Live Tracked-Wallet Positions per Token (WebSocket)","operationId":"streamHolder","description":"Subscribe to one Solana token and receive an `init` snapshot of all tracked holders, then live `holder_update` (a wallet traded) and `position_update` (market cap moved) messages.\n\n- `blockchain` (required) — must be `solana`.\n- `token` (required) — a mint to watch one token, or `*` for all tokens\n live (no snapshot).\n\n- `wallet_types` (optional) — any subset of `kol`, `smart`, `whale`;\n defaults to all three.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeHolderMessage"}}}},"responses":{"200":{"description":"`init`, `holder_update` and `position_update` messages. (The connection also delivers a `connected` welcome, a `subscribed` ack per subscribe, and `error` messages — see schemas.)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderEnvelope"}}}}}}}}}
```