> 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/smart-wallet-data-legacy/base/websocket/base-smart-money-position-updates.md).

# Base Smart Money Position Updates

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

The POSITION\_UPDATE feed broadcasts every buy/sell transaction enriched with position data: current holdings, bag percentage, supply percentage and ETH tracking.

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

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

***

### Connection

javascript

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

Alternative — Authorization header:

javascript

```javascript
const ws = new WebSocket("wss://smartstreambase.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: "0x4200000000000000000000000000000000000006"
}));
```

**Subscribe to all tokens**

javascript

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

**Unsubscribe**

javascript

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

**List active subscriptions**

javascript

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

***

### Connection Flow

javascript

```javascript
const ws = new WebSocket("wss://smartstreambase.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": "base_smart",
  "blockchain": "base",
  "signature": "0x2f5d93a9...6dc2f5",
  "slot": 23460001,
  "timestamp": "2025-01-15T15:10:42.456Z",
  "action": "sell",
  "transaction_type": "sell",

  "wallet": "0x7853b3736edba9d7ce681f2a90264307694f97f2",
  "wallet_name": "Base Smart #9",
  "wallet_image": "https://cabalspy.xyz/...",
  "telegram": null,
  "twitter": null,
  "wallet_data": {
    "name": "Base Smart #9",
    "wallet_address": "0x7853b3736edba9d7ce681f2a90264307694f97f2",
    "image_url": "https://cabalspy.xyz/..."
  },

  "eth_value": 0.10,
  "eth_value_usd": 250.00,
  "eth_price_usd": 2500.00,
  "eth_value_peak": 0.40,
  "eth_value_current": 0.30,

  "sol_value": 0.10,
  "sol_value_usd": 250.00,
  "sol_price_usd": 2500.00,

  "fee": 0,
  "fee_eth": 0,
  "fee_payer": "0x7853b3736edba9d7ce681f2a90264307694f97f2",

  "mint": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "token_symbol": "USDC",
  "symbol": "USDC",
  "token_name": "USD Coin",
  "token_decimals": 6,
  "token_supply": 1000000000,
  "token_amount": 250.00,

  "held": 750.000000,
  "peak": 1000.000000,
  "supply_pct": 0.0001,
  "bag_pct": 75.00,
  "prev_supply_pct": 0.0001,
  "prev_bag_pct": 100.00,
  "delta_supply_pct": 0.0000,
  "delta_bag_pct": -25.00,
  "delta_held": -250,
  "used_fallback": false
}
```

***

### Field Reference

#### Transaction

| Field              | Type   | Description                             |
| ------------------ | ------ | --------------------------------------- |
| `type`             | string | Always `"position_update"`              |
| `feed`             | string | Always `"base_smart"`                   |
| `blockchain`       | string | Always `"base"`                         |
| `signature`        | string | Base Chain transaction hash             |
| `slot`             | number | Base 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                  |

#### ETH Value

| Field               | Type   | Description                                               |
| ------------------- | ------ | --------------------------------------------------------- |
| `eth_value`         | number | ETH amount of this transaction                            |
| `eth_value_usd`     | number | USD value of this transaction                             |
| `eth_price_usd`     | number | ETH price in USD at time of broadcast                     |
| `eth_value_peak`    | number | Total ETH ever spent buying this token by this wallet     |
| `eth_value_current` | number | Remaining unrealized ETH value in this position           |
| `sol_value`         | number | Alias for `eth_value` — for cross-chain compatibility     |
| `sol_value_usd`     | number | Alias for `eth_value_usd` — for cross-chain compatibility |
| `sol_price_usd`     | number | Alias for `eth_price_usd` — for cross-chain compatibility |

#### Fees

| Field       | Type   | Description                                        |
| ----------- | ------ | -------------------------------------------------- |
| `fee`       | number | Transaction fee in Wei (may be 0 if not available) |
| `fee_eth`   | number | Transaction fee in ETH (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. `"BRETT"`                              |
| `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.
* `eth_value_current` tracks unrealized ETH 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 Base Chain via `balanceOf()` on each transaction.
* Fee data may be `0` for Smart Money transactions depending on the source feed.