BNB Smart Money Position Updates

Get position updates for tracked Smart Money wallets across any BNB Chain token.

The POSITION_UPDATE feed broadcasts every buy/sell transaction enriched with position data: current holdings, bag percentage, supply percentage and BNB tracking.

This feed covers Smart Money wallets on BNB Chain only. For other feeds see:

• SOL Smart Money: wss://smartstream.cabalspy.xyz

• Base Smart Money: wss://smartstreambase.cabalspy.xyz

• BNB KOL: wss://kolstreambnb.cabalspy.xyz

---

Connection

javascript

const ws = new WebSocket("wss://smartstreambnb.cabalspy.xyz?apiKey=YOUR_API_KEY");

Alternative — Authorization header:

javascript

const ws = new WebSocket("wss://smartstreambnb.cabalspy.xyz");
// Authorization: Bearer YOUR_API_KEY

Without a valid API key the connection is rejected immediately.

---

Subscriptions

You must subscribe before receiving any events.

Subscribe to a specific token

javascript

ws.send(JSON.stringify({
  type:  "subscribe",
  token: "0x2170Ed0880ac9A755fd29B2688956BD959F933F8"
}));

Subscribe to all tokens

javascript

ws.send(JSON.stringify({
  type:  "subscribe",
  token: "*"
}));

Unsubscribe

javascript

ws.send(JSON.stringify({
  type:  "unsubscribe",
  token: "0x2170Ed0880ac9A755fd29B2688956BD959F933F8"
}));

List active subscriptions

javascript

ws.send(JSON.stringify({ type: "subscriptions" }));

---

Connection Flow

javascript

const ws = new WebSocket("wss://smartstreambnb.cabalspy.xyz?apiKey=YOUR_API_KEY");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "subscribe", token: "*" }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case "connected":
      console.log("Connected:", message.message);
      break;
    case "subscribed":
      console.log("Subscribed to:", message.token);
      break;
    case "unsubscribed":
      console.log("Unsubscribed from:", message.token);
      break;
    case "position_update":
      console.log("New trade:", message);
      break;
    case "error":
      console.error("Error:", message.message);
      break;
  }
};

---

System Messages

type	When	Fields
connected	On successful connect	message, docs
subscribed	After subscribe	token, subscriptions, message
unsubscribed	After unsubscribe	token, subscriptions, message
subscriptions	After requesting list	subscriptions, count
error	On invalid message or auth	message

---

Example Message — position_update

json

{
  "type": "position_update",
  "feed": "bnb_smart",
  "blockchain": "bnb",
  "signature": "0x9c1a45ef...b3d28a",
  "slot": 47813001,
  "timestamp": "2025-01-15T14:22:10.123Z",
  "action": "buy",
  "transaction_type": "buy",

  "wallet": "0xbe3f4b43db5eb49d1f48f53443b9abce45da3b79",
  "wallet_name": "BNB Smart #5",
  "wallet_image": "https://cabalspy.xyz/...",
  "telegram": null,
  "twitter": null,
  "wallet_data": {
    "name": "BNB Smart #5",
    "wallet_address": "0xbe3f4b43db5eb49d1f48f53443b9abce45da3b79",
    "image_url": "https://cabalspy.xyz/..."
  },

  "bnb_value": 0.80,
  "bnb_value_usd": 480.00,
  "bnb_price_usd": 600.00,
  "bnb_value_peak": 0.80,
  "bnb_value_current": 0.80,

  "sol_value": 0.80,
  "sol_value_usd": 480.00,
  "sol_price_usd": 600.00,

  "fee": 0,
  "fee_bnb": 0,
  "fee_payer": "0xbe3f4b43db5eb49d1f48f53443b9abce45da3b79",

  "mint": "0xcc42724c6683b7e57334c4e856f4c9965ed682bd",
  "token_symbol": "MATIC",
  "symbol": "MATIC",
  "token_name": "Matic Token",
  "token_decimals": 18,
  "token_supply": 1000000000,
  "token_amount": 850.5,

  "held": 850.500000,
  "peak": 850.500000,
  "supply_pct": 0.0001,
  "bag_pct": 100.00,
  "prev_supply_pct": 0.0000,
  "prev_bag_pct": 0.00,
  "delta_supply_pct": 0.0001,
  "delta_bag_pct": 100.00,
  "delta_held": 851,
  "used_fallback": false
}

---

Field Reference

Transaction

Field	Type	Description
type	string	Always "position_update"
feed	string	Always "bnb_smart"
blockchain	string	Always "bnb"
signature	string	BNB Chain transaction hash
slot	number	BNB Chain block number
timestamp	string	ISO 8601 timestamp
action	string	"buy" or "sell"
transaction_type	string	Same as action — kept for compatibility

Wallet

Field	Type	Description
wallet	string	EVM address of the trading wallet
wallet_name	string?	Internal label for this wallet
wallet_image	string?	Profile picture URL if available
telegram	string?	Telegram link if available (often null for Smart Money)
twitter	string?	Twitter/X profile URL if available (often null for Smart Money)
wallet_data	object	Full wallet object containing all fields above

BNB Value

Field	Type	Description
bnb_value	number	BNB amount of this transaction
bnb_value_usd	number	USD value of this transaction
bnb_price_usd	number	BNB price in USD at time of broadcast
bnb_value_peak	number	Total BNB ever spent buying this token by this wallet
bnb_value_current	number	Remaining unrealized BNB value in this position
sol_value	number	Alias for bnb_value — for cross-chain compatibility
sol_value_usd	number	Alias for bnb_value_usd — for cross-chain compatibility
sol_price_usd	number	Alias for bnb_price_usd — for cross-chain compatibility

Fees

Field	Type	Description
fee	number	Transaction fee in Wei (may be 0 if not available)
fee_bnb	number	Transaction fee in BNB (may be 0 if not available)
fee_payer	string	Wallet that paid the fee

Token

Field	Type	Description
mint	string	Token contract address
token_symbol	string	Token ticker e.g. "PEPE"
symbol	string	Alias for token_symbol — for cross-chain compatibility
token_name	string?	Full token name
token_decimals	number	Token decimal places
token_supply	number	Total on-chain token supply
token_amount	number	Amount of tokens traded in this specific transaction

Position

Field	Type	Description
held	number	Current token balance of this wallet for this token
peak	number	All-time highest token balance this wallet held
bag_pct	number	How much of the peak position is still held (0–100%)
supply_pct	number	Percentage of total supply currently held
prev_supply_pct	number	Supply % before this transaction
prev_bag_pct	number	Bag % before this transaction
delta_supply_pct	number	Change in supply % from this transaction
delta_bag_pct	number	Change in bag % from this transaction
delta_held	number	Change in token amount from this transaction
used_fallback	boolean	true if supply was estimated (1B fallback) instead of on-chain value

---

Errors

json

{ "type": "error", "message": "Invalid or missing API key" }
{ "type": "error", "message": "Unknown type: xyz. Valid: subscribe, unsubscribe, subscriptions" }
{ "type": "error", "message": "Invalid JSON message" }

---

Notes

• You must subscribe before receiving any events. Without a subscription nothing is received.

• Use "token": "*" to receive all events across all tracked tokens.

• Multiple tokens can be subscribed simultaneously — send one subscribe message per token.

• token_supply falls back to 1,000,000,000 if the on-chain value is unavailable. Check used_fallback: true to detect this.

• bag_pct is calculated as held / peak * 100. A value of 0% means the position was fully closed.

• token_amount is the amount traded in this specific transaction. held is the cumulative position.

• bnb_value_current tracks unrealized BNB based on buys minus sells — does not reflect real-time price.

• sol_value, sol_value_usd, sol_price_usd and symbol are aliases provided for cross-chain compatibility. Code written for the SOL feed works here without changes.

• Smart Money wallets may have limited social data — telegram and twitter are often null.

• Token balance (held) is fetched live from BNB Chain via balanceOf() on each transaction.

• Fee data may be 0 for Smart Money transactions depending on the source feed.