> 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/token-transactions.md). # Token Transactions Live buys and sells from tracked smart money, KOL and whale wallets across Solana, BNB Chain and Base. One stream; pick the chain and wallet type with the `blockchain` and `type` fields. ## Token Transactions — Live Smart Money / KOL / Whale Trades (WebSocket) > Subscribe to the live transactions stream and receive a \`position\_update\` message for every matching trade. Select the data with the subscribe fields:\ > \ > \- \`blockchain\` (required) — \`solana\`, \`bnb\`, \`base\`. \*\*Change this to switch chain.\*\*\ > \- \`type\` (required) — \`kol\`, \`smart\`, \`whale\` (whale is Solana-only)\ > \- \`token\` (optional, default \`\*\`) — a mint/contract to follow one token, or \`\*\` for all\ > \ > Subscribe message: \`{ "op": "subscribe", "stream": "tx", "blockchain": "solana", "type": "kol", "token": "\*" }\`. Each subscription corresponds to the channel \`tx.\.\\`, returned in the \`channel\` field of every message.
```json {"openapi":"3.0.3","info":{"title":"CabalSpy API — Token Transactions Stream (Live Smart Money, KOL & Whale Trades)","version":"2.0.0"},"tags":[{"name":"Token Transactions","description":"Live buys and sells from tracked smart money, KOL and whale wallets across Solana, BNB Chain and Base. One stream; pick the chain and wallet type with the `blockchain` and `type` fields.\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":{"SubscribeMessage":{"type":"object","description":"Client → server. Start receiving the transactions stream for a chain + wallet type.","properties":{"op":{"type":"string","enum":["subscribe"]},"stream":{"type":"string","enum":["tx"]},"blockchain":{"type":"string","enum":["solana","bnb","base"],"description":"Change this to switch chain."},"type":{"type":"string","enum":["kol","smart","whale"],"description":"whale is Solana-only."},"token":{"type":"string","description":"A mint/contract, or \"*\" for all tokens."},"channel":{"type":"string","description":"Compact alternative to the fields above, e.g. tx.solana.kol.*"}},"required":["op"]},"TransactionEnvelope":{"type":"object","description":"One trade (buy or sell) as a full position update.","properties":{"success":{"type":"boolean"},"channel":{"type":"string","description":"Channel that produced this message — tx..."},"event":{"type":"string","enum":["position_update"]},"data":{"type":"object","properties":{"wallet":{"type":"string","description":"The trading wallet address."},"profile":{"type":"object","description":"Identity and classification of the wallet.","properties":{"name":{"type":"string","description":"Display name of the tracked wallet."},"image_url":{"type":"string","description":"Avatar / logo URL (absolute)."},"twitter":{"type":"string","description":"Twitter / X link (may be empty)."},"telegram":{"type":"string","description":"Telegram link (may be empty)."},"blockchain":{"type":"string","enum":["solana","bnb","base"],"description":"Chain the wallet trades on."},"currency":{"type":"string","enum":["SOL","BNB","ETH"],"description":"Native currency of that chain."},"type":{"type":"string","enum":["kol","smart","whale"],"description":"Wallet classification."},"active_hours":{"type":"string","nullable":true,"description":"Typical active hours in UTC","if known.":null}}},"transaction":{"type":"object","description":"The on-chain trade.","properties":{"signature":{"type":"string","description":"Transaction signature (Solana) or hash (EVM)."},"slot":{"type":"integer","nullable":true,"description":"Slot / block number."},"action":{"type":"string","enum":["buy","sell","other"]},"transaction_type":{"type":"string","enum":["buy","sell","other"],"description":"Same value as action."},"created_at":{"description":"Trade time — unix seconds (Solana) or ISO timestamp (EVM), as delivered by the source."},"fee":{"type":"number","description":"Raw network fee (lamports on Solana","wei on EVM).":null},"fee_native":{"type":"number","nullable":true,"description":"Fee converted to native currency (SOL/BNB/ETH)."},"fee_payer":{"type":"string","description":"Address that paid the fee."}}},"token":{"type":"object","description":"The traded token.","properties":{"mint":{"type":"string","description":"Mint (Solana) or contract address (EVM)."},"symbol":{"type":"string"},"name":{"type":"string"},"decimals":{"type":"integer","nullable":true},"supply":{"type":"number","description":"Total token supply (decimal-adjusted)."},"logo":{"type":"string","nullable":true}}},"value":{"type":"object","description":"Trade size and the wallet's tracked native value in this token.","properties":{"currency":{"type":"string","enum":["SOL","BNB","ETH"],"description":"Unit of the amount fields."},"amount":{"type":"number","description":"Trade size in native currency."},"amount_usd":{"type":"number","description":"Trade size in USD at the time."},"price_usd":{"type":"number","description":"Native currency price in USD."},"peak":{"type":"number","description":"Highest cumulative native value the wallet put into this token."},"current":{"type":"number","description":"Current tracked native value in this token."}}},"position":{"type":"object","description":"The wallet's running position in this token after the trade.","properties":{"token_amount":{"type":"number","description":"Tokens moved in this trade."},"held":{"type":"number","description":"Tokens currently held."},"peak":{"type":"number","description":"Peak tokens ever held."},"supply_pct":{"type":"number","description":"Held as % of total supply."},"bag_pct":{"type":"number","description":"Held as % of peak holding — 100 = still holding all, 0 = fully sold."},"prev_supply_pct":{"type":"number","description":"supply_pct before this trade."},"prev_bag_pct":{"type":"number","description":"bag_pct before this trade."},"delta_supply_pct":{"type":"number","description":"Change in supply_pct from this trade."},"delta_bag_pct":{"type":"number","description":"Change in bag_pct from this trade."},"delta_held":{"type":"integer","description":"Change in held tokens from this trade."},"used_fallback":{"type":"boolean","description":"True if bag_pct was estimated from native value (on-chain balance not yet settled)."}}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"retry":{"type":"boolean","description":"Present on a follow-up update after the on-chain balance settled (EVM sells)."}}}}}}},"paths":{"/tx":{"get":{"tags":["Token Transactions"],"summary":"Token Transactions — Live Smart Money / KOL / Whale Trades (WebSocket)","operationId":"streamTransactions","description":"Subscribe to the live transactions stream and receive a `position_update` message for every matching trade. Select the data with the subscribe fields:\n\n- `blockchain` (required) — `solana`, `bnb`, `base`. **Change this to switch chain.**\n- `type` (required) — `kol`, `smart`, `whale` (whale is Solana-only)\n- `token` (optional, default `*`) — a mint/contract to follow one token, or `*` for all\n\nSubscribe message: `{ \"op\": \"subscribe\", \"stream\": \"tx\", \"blockchain\": \"solana\", \"type\": \"kol\", \"token\": \"*\" }`. Each subscription corresponds to the channel `tx..`, returned in the `channel` field of every message.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeMessage"}}}},"responses":{"200":{"description":"A `position_update` message pushed for each matching trade on the subscribed channel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionEnvelope"}}}}}}}}} ```