# BNB KOL Position Updates

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 KOL wallets on BNB Chain only. For other feeds see:

* SOL KOL: `wss://kolstream.cabalspy.xyz`
* Base KOL: `wss://kolstreambase.cabalspy.xyz`
* BNB Smart Money: `wss://smartstreambnb.cabalspy.xyz`

***

### Connection

javascript

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

Alternative — Authorization header:

javascript

```javascript
const ws = new WebSocket("wss://kolstreambnb.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

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

**Subscribe to all tokens**

javascript

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

**Unsubscribe**

javascript

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

**List active subscriptions**

javascript

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

***

### Connection Flow

javascript

```javascript
const ws = new WebSocket("wss://kolstreambnb.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

```json
{
  "type": "position_update",
  "feed": "bnb_kol",
  "blockchain": "bnb",
  "signature": "0x7a4a39da...f02a72",
  "slot": 47812345,
  "timestamp": "2025-01-15T12:34:56.789Z",
  "action": "buy",
  "transaction_type": "buy",

  "wallet": "0x503828976d22510aad0201ac7ec88293211d23da",
  "wallet_name": "BNB Whale #7",
  "wallet_image": "https://cabalspy.xyz/...",
  "telegram": null,
  "twitter": "https://x.com/bnbwhale7",
  "wallet_data": {
    "name": "BNB Whale #7",
    "wallet_address": "0x503828976d22510aad0201ac7ec88293211d23da",
    "twitter": "https://x.com/bnbwhale7",
    "image_url": "https://cabalspy.xyz/..."
  },

  "bnb_value": 1.50,
  "bnb_value_usd": 900.00,
  "bnb_price_usd": 600.00,
  "bnb_value_peak": 1.50,
  "bnb_value_current": 1.50,

  "sol_value": 1.50,
  "sol_value_usd": 900.00,
  "sol_price_usd": 600.00,

  "fee": 210000000000000,
  "fee_bnb": 0.00021,
  "fee_payer": "0x503828976d22510aad0201ac7ec88293211d23da",

  "mint": "0x2170Ed0880ac9A755fd29B2688956BD959F933F8",
  "token_symbol": "ETH",
  "symbol": "ETH",
  "token_name": "Ethereum Token",
  "token_decimals": 18,
  "token_supply": 1000000000,
  "token_amount": 0.5,

  "held": 0.500000,
  "peak": 0.500000,
  "supply_pct": 0.0000,
  "bag_pct": 100.00,
  "prev_supply_pct": 0.0000,
  "prev_bag_pct": 0.00,
  "delta_supply_pct": 0.0000,
  "delta_bag_pct": 100.00,
  "delta_held": 0,
  "used_fallback": false
}
```

***

### Field Reference

#### Transaction

| Field              | Type   | Description                             |
| ------------------ | ------ | --------------------------------------- |
| `type`             | string | Always `"position_update"`              |
| `feed`             | string | Always `"bnb_kol"`                      |
| `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                     |
| `twitter`      | string? | Twitter/X profile URL if available             |
| `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   |
| `fee_bnb`   | number | Transaction fee in BNB   |
| `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

```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.
* Token balance (`held`) is fetched live from BNB Chain via `balanceOf()` on each transaction.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cabalspy.gitbook.io/cabalspy-docs/kol-data/bnb/websocket/bnb-kol-position-updates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.