> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Tags

> Tag your WebSocket subscriptions to track and break down usage by category in the dashboard

<Tip> This feature is available on all plans with WebSocket access. </Tip>

## Overview

Subscription tags let you categorize your WebSocket subscriptions by purpose (e.g., "majors", "long tail", "defi") and see a breakdown of usage and credits consumption by tag in the [dashboard](https://admin.mobula.io/usage).

Without tags, usage is only broken down by endpoint or by individual API key. Tags give you a third dimension — grouping subscriptions into logical categories across any WebSocket endpoint.

## How It Works

Add an optional `tag` field (max 50 characters) to the `payload` of any WebSocket subscription message. The tag is tracked per event and aggregated in the usage dashboard under the **"By Tag"** breakdown view.

## Supported Endpoints

Tags work on **every** WebSocket endpoint:

| Endpoint                                                                     | Event Type        |
| ---------------------------------------------------------------------------- | ----------------- |
| [Fast Trades](/indexing-stream/stream/websocket/wss-fast-trades)             | `fast-trade`      |
| [Market Details](/indexing-stream/stream/websocket/wss-market-details)       | `market-details`  |
| [Token Details](/indexing-stream/stream/websocket/wss-token-details)         | `token-details`   |
| [OHLCV](/indexing-stream/stream/websocket/ohlcv-stream)                      | `ohlcv`           |
| [Balance](/indexing-stream/stream/websocket/wss-balance-stream)              | `balance`         |
| [Positions](/indexing-stream/stream/websocket/wss-position-stream)           | `position`        |
| [Holders](/indexing-stream/stream/websocket/holders-stream)                  | `holders`         |
| [Funding](/indexing-stream/stream/websocket/wss-funding)                     | `funding`         |
| [Pulse Streams](/indexing-stream/stream/websocket/pulse-stream-v2)           | `market` / `pair` |
| [Multi-Events Stream](/indexing-stream/stream/websocket/multi-events-stream) | `stream`          |

## Usage Examples

### Fast Trades with Tag

```json theme={null}
{
  "type": "fast-trade",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "assetMode": true,
    "items": [
      { "blockchain": "evm:1", "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" },
      { "blockchain": "evm:1", "address": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599" }
    ],
    "tag": "majors",
    "subscriptionTracking": true
  }
}
```

### Market Details with Tag

```json theme={null}
{
  "type": "market-details",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "pools": [
      { "blockchain": "evm:1", "address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640" }
    ],
    "tag": "defi",
    "subscriptionTracking": true
  }
}
```

### OHLCV with Tag

```json theme={null}
{
  "type": "ohlcv",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "asset": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "chainId": "evm:1",
    "period": "1h",
    "tag": "charts"
  }
}
```

### Multi-Events Stream with Tag

```json theme={null}
{
  "type": "stream",
  "payload": {
    "authorization": "YOUR-API-KEY",
    "chainIds": ["evm:1", "evm:56"],
    "events": ["swap"],
    "tag": "long tail",
    "subscriptionId": "my-swap-tracker",
    "subscriptionTracking": "true"
  }
}
```

## Viewing Tag Usage in the Dashboard

1. Go to [admin.mobula.io/usage](https://admin.mobula.io/usage)
2. Select **WebSocket** as the data source
3. Use the **"By Event" / "By Tag"** selector to switch to the tag breakdown view
4. You'll see credits and event counts aggregated per tag

Subscriptions without a `tag` are grouped under **"Untagged"**.

## Tag Guidelines

* Tags are **optional** — omit the field or pass `null` to leave a subscription untagged
* Maximum length: **50 characters**
* Tags are **case-sensitive** — `"Majors"` and `"majors"` are tracked separately
* Use consistent naming across your subscriptions for clean aggregation
* You can use different tags on different subscriptions with the same API key

### Recommended Tag Patterns

| Use Case         | Example Tags                                      |
| ---------------- | ------------------------------------------------- |
| Asset categories | `majors`, `long tail`, `stablecoins`, `memecoins` |
| Product features | `charts`, `alerts`, `portfolio`, `screener`       |
| Environments     | `staging`, `production`, `dev`                    |
| Clients/tenants  | `client-acme`, `client-globex`                    |

## Implementation Example

```typescript theme={null}
const socket = new WebSocket("wss://api.mobula.io");

socket.addEventListener("open", () => {
  // Subscribe to majors
  socket.send(JSON.stringify({
    type: "fast-trade",
    authorization: "YOUR_API_KEY",
    payload: {
      assetMode: true,
      items: [
        { blockchain: "evm:1", address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" }
      ],
      tag: "majors"
    }
  }));

  // Subscribe to memecoins with a different tag
  socket.send(JSON.stringify({
    type: "fast-trade",
    authorization: "YOUR_API_KEY",
    payload: {
      assetMode: true,
      items: [
        { blockchain: "solana", address: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" }
      ],
      tag: "memecoins"
    }
  }));
});

socket.addEventListener("message", (event) => {
  const data = JSON.parse(event.data);
  console.log(`Trade on ${data.token}:`, data);
});
```

## Support

Can't find what you're looking for? Reach out to us, response times \< 1h.

<CardGroup>
  <Card title="Support" icon="Telegram" href="https://t.me/mobuladevelopers?start=Mobula_API_Support_Key">
    Telegram
  </Card>

  <Card title="Support" icon="Slack" href="https://join.slack.com/t/mobulaapi/shared_invite/zt-29zrrpjnl-I0tyD73sy7zKy8q~KLL3Ug">
    Slack
  </Card>

  <Card title="Need help?" icon="envelope" href="mailto:contact@mobulalabs.org">
    Email
  </Card>
</CardGroup>