# Base Smart Money Position Updates

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.


---

# 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/smart-wallet-data/base/websocket/base-smart-money-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.