Holders Stream

This endpoint is only available to Growth and Enterprise plans.

Real-time vs HTTP

🔗 GET Method

Available in HTTP queriesUse the same filtering system in HTTP GET requests for simple queries.

📝 POST Method

Available in HTTP queriesUse the same filtering system in HTTP POST requests for advanced configurations.

Overview

Holders Stream provides real-time monitoring of token holder analytics and distribution data. This WebSocket API allows you to track holder statistics, wallet labels, trading behavior, and concentration metrics for specific tokens across multiple blockchains.

Key Features

Real-time Holder Analytics: Monitor holder distribution and concentration metrics
Wallet Labeling: Track insider, bundler, sniper, and professional trader activity
Trading Behavior Analysis: Monitor buy/sell patterns and PnL tracking
Multi-chain Support: Support for Solana, Ethereum, Base, and other supported blockchains
Live Updates: Real-time updates when holder positions change
Comprehensive Metrics: Detailed analytics including top holder percentages and trader classifications

Endpoint Details

URL: wss://api.mobula.io
Message format: JSON string
Architecture: Real-time holder data streaming
Mode: Token holder analytics

Basic Usage

The simplest way to get started is subscribing to holder data for specific tokens:

{
  "type": "holders",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "tokens": [
      {
        "address": "BCghRAYsRq3wByYWLwicnRieZP2LocEMosbhU595QLnz",
        "blockchain": "solana:solana"
      }
    ]
  }
}

Multiple Tokens Subscription

You can subscribe to multiple tokens simultaneously:

{
  "type": "holders",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "tokens": [
      {
        "address": "BCghRAYsRq3wByYWLwicnRieZP2LocEMosbhU595QLnz",
        "blockchain": "solana:solana"
      },
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "blockchain": "evm:8453"
      }
    ]
  }
}

Data Model

HoldersStreamData Structure

The Holders Stream provides comprehensive holder analytics following this structure:

interface HoldersStreamData {
  // Holder Distribution Metrics
  top10HoldingsPercentage: number;
  top50HoldingsPercentage: number;
  top100HoldingsPercentage: number;
  top200HoldingsPercentage: number;
  
  // Wallet Classification Percentages
  devHoldingsPercentage: number;
  insidersHoldingsPercentage: number;
  snipersHoldingsPercentage: number;
  bundlersHoldingsPercentage: number;
  
  // Trader Counts
  snipersCount: number;
  insidersCount: number;
  bundlersCount: number;
  proTradersCount: number;
  smartTradersCount: number;
  freshTradersCount: number;
  
  // Trading Activity Counts
  proTradersBuys: number;
  smartTradersBuys: number;
  freshTradersBuys: number;
  
  // Total Holder Count
  holdersCount: number;
  
  // Detailed Holder List
  holders: HolderData[];
}

interface HolderData {
  // Basic Information
  address: string;
  updatedAt: string;
  createdAt: string;
  
  // Balance Information (Raw Values)
  balanceRaw: string;
  nativeBalanceRaw: string;
  boughtAmountRaw: string;
  soldAmountRaw: string;
  
  // Balance Information (Formatted Values)
  balance: number;
  nativeBalance: number;
  boughtAmount: number;
  soldAmount: number;
  
  // USD Values
  boughtAmountUSD: number;
  soldAmountUSD: number;
  balanceUSD: number;
  realizedPnlUSD: number;
  unrealizedPnlUSD: number;
  
  // Wallet Labels/Tags
  tags: string[];
}

Available Holder Statistics

The Holders Stream provides access to comprehensive holder analytics:

Distribution Metrics

top10HoldingsPercentage: Percentage of tokens held by top 10 holders
top50HoldingsPercentage: Percentage of tokens held by top 50 holders
top100HoldingsPercentage: Percentage of tokens held by top 100 holders
top200HoldingsPercentage: Percentage of tokens held by top 200 holders

Wallet Classification

devHoldingsPercentage: Percentage held by developer wallets
insidersHoldingsPercentage: Percentage held by insider wallets
snipersHoldingsPercentage: Percentage held by sniper wallets
bundlersHoldingsPercentage: Percentage held by bundler wallets

Trader Analytics

snipersCount: Number of sniper wallets
insidersCount: Number of insider wallets
bundlersCount: Number of bundler wallets
proTradersCount: Number of professional trader wallets
smartTradersCount: Number of smart trader wallets
freshTradersCount: Number of fresh trader wallets

Trading Activity

proTradersBuys: Number of buy transactions by professional traders
smartTradersBuys: Number of buy transactions by smart traders
freshTradersBuys: Number of buy transactions by fresh traders

Individual Holder Data

Each holder in the holders array contains:

address: Wallet address
balance: Current token balance
balanceUSD: Current balance value in USD
boughtAmount: Total amount bought
soldAmount: Total amount sold
realizedPnlUSD: Realized profit/loss in USD
unrealizedPnlUSD: Unrealized profit/loss in USD
tags: Array of wallet labels (e.g., “insider”, “bundler”, “sniper”)

Message Types

Initial Data Message

Sent when first subscribing to a token’s holder data:

{
  "data": {
    "top10HoldingsPercentage": 3.6179797268414,
    "devHoldingsPercentage": -3.6180838471429,
    "top50HoldingsPercentage": -1.2512e-9,
    "top100HoldingsPercentage": -1.2512e-9,
    "top200HoldingsPercentage": -1.2512e-9,
    "snipersHoldingsPercentage": 0,
    "snipersCount": 0,
    "insidersHoldingsPercentage": 2.4385038857834,
    "insidersCount": 1,
    "bundlersHoldingsPercentage": 2.4385038857834,
    "bundlersCount": 1,
    "proTradersCount": 0,
    "smartTradersCount": 0,
    "freshTradersCount": 0,
    "proTradersBuys": 0,
    "smartTradersBuys": 0,
    "freshTradersBuys": 0,
    "holdersCount": 20,
    "holders": [
      {
        "address": "11111111111111111111111111111113",
        "updatedAt": "2025-09-24T23:23:15.955Z",
        "createdAt": "2025-09-24T23:22:31.618Z",
        "balanceRaw": "24385038857834",
        "nativeBalanceRaw": "0",
        "boughtAmountRaw": "24385038857834",
        "soldAmountRaw": "0",
        "tags": ["insider", "bundler"],
        "boughtAmountUSD": 0,
        "soldAmountUSD": 0,
        "balanceUSD": 412.6731108691701,
        "balance": 24385038.857834,
        "nativeBalance": 0,
        "boughtAmount": 24385038.857834,
        "soldAmount": 0,
        "realizedPnlUSD": 0,
        "unrealizedPnlUSD": 412.6731108691701
      }
    ]
  },
  "subscriptionId": "9841a684920b832a"
}

Update Messages

Sent when holder data changes (new holders, balance updates, etc.):

{
  "data": {
    "top10HoldingsPercentage": 3.8,
    "devHoldingsPercentage": -3.5,
    "top50HoldingsPercentage": 0.1,
    "top100HoldingsPercentage": 0.1,
    "top200HoldingsPercentage": 0.1,
    "snipersHoldingsPercentage": 0,
    "snipersCount": 0,
    "insidersHoldingsPercentage": 2.6,
    "insidersCount": 1,
    "bundlersHoldingsPercentage": 2.6,
    "bundlersCount": 1,
    "proTradersCount": 0,
    "smartTradersCount": 0,
    "freshTradersCount": 0,
    "proTradersBuys": 0,
    "smartTradersBuys": 0,
    "freshTradersBuys": 0,
    "holdersCount": 22,
    "holders": [
      {
        "address": "NewHolderAddress123456789",
        "updatedAt": "2025-09-24T23:25:00.000Z",
        "createdAt": "2025-09-24T23:25:00.000Z",
        "balanceRaw": "1000000000000",
        "nativeBalanceRaw": "0",
        "boughtAmountRaw": "1000000000000",
        "soldAmountRaw": "0",
        "tags": [],
        "boughtAmountUSD": 0,
        "soldAmountUSD": 0,
        "balanceUSD": 16.93,
        "balance": 1000000,
        "nativeBalance": 0,
        "boughtAmount": 1000000,
        "soldAmount": 0,
        "realizedPnlUSD": 0,
        "unrealizedPnlUSD": 16.93
      }
    ]
  },
  "subscriptionId": "9841a684920b832a"
}

Use Cases

Token Distribution Analysis

Monitor the distribution of tokens among holders to identify concentration risks:

{
  "type": "holders",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "tokens": [
      {
        "address": "TOKEN_ADDRESS",
        "blockchain": "solana:solana"
      }
    ]
  }
}

Insider Activity Monitoring

Track insider and developer wallet activity:

{
  "type": "holders",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "tokens": [
      {
        "address": "TOKEN_ADDRESS",
        "blockchain": "evm:8453"
      }
    ]
  }
}

Professional Trader Tracking

Monitor professional trader activity and their impact on token distribution:

{
  "type": "holders",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "tokens": [
      {
        "address": "TOKEN_ADDRESS",
        "blockchain": "solana:solana"
      }
    ]
  }
}

Unsubscribe

To unsubscribe from holder data:

{
  "type": "unsubscribe",
  "payload": {
    "subscriptionId": "9841a684920b832a"
  }
}

Performance Considerations

Subscription Limits

Maximum 10 tokens per connection
Real-time updates for all subscribed tokens
Efficient data streaming with minimal bandwidth usage

Data Update Frequency

Updates sent when holder positions change
Real-time balance updates
New holder additions and removals

Supported Blockchains

The Holders Stream supports all blockchains available in the Mobula API:

Solana: solana:solana
Ethereum: evm:1
Base: evm:8453
BSC: evm:56
Polygon: evm:137
Arbitrum: evm:42161
Optimism: evm:10
And many more…

Error Handling

Common Error Responses

{
  "error": "Invalid token address",
  "message": "The provided token address is not valid for the specified blockchain"
}

{
  "error": "Unsupported blockchain",
  "message": "The specified blockchain is not supported for holder analytics"
}

{
  "error": "Rate limit exceeded",
  "message": "Too many subscription requests. Please wait before making new requests"
}

Stream

Guides

Real-time vs HTTP

🔗 GET Method

📝 POST Method

Overview

Key Features

Endpoint Details

Basic Usage

Multiple Tokens Subscription

Data Model

HoldersStreamData Structure

Available Holder Statistics

Distribution Metrics

Wallet Classification

Trader Analytics

Trading Activity

Individual Holder Data

Message Types

Initial Data Message

Update Messages

Use Cases

Token Distribution Analysis

Insider Activity Monitoring

Professional Trader Tracking

Unsubscribe

Performance Considerations

Subscription Limits

Data Update Frequency

Supported Blockchains

Error Handling

Common Error Responses

Support

Support

Support

Need help?

Stream

Guides

​Real-time vs HTTP

🔗 GET Method

📝 POST Method

​Overview

​Key Features

​Endpoint Details

​Basic Usage

​Subscribe to Holders Stream

​Multiple Tokens Subscription

​Data Model

​HoldersStreamData Structure

​Available Holder Statistics

​Distribution Metrics

​Wallet Classification

​Trader Analytics

​Trading Activity

​Individual Holder Data

​Message Types

​Initial Data Message

​Update Messages

​Use Cases

​Token Distribution Analysis

​Insider Activity Monitoring

​Professional Trader Tracking

​Unsubscribe

​Performance Considerations

​Subscription Limits

​Data Update Frequency

​Supported Blockchains

​Error Handling

​Common Error Responses

​Support

Support

Support

Need help?

Real-time vs HTTP

Overview

Key Features

Endpoint Details

Basic Usage

Subscribe to Holders Stream

Multiple Tokens Subscription

Data Model

HoldersStreamData Structure

Available Holder Statistics

Distribution Metrics

Wallet Classification

Trader Analytics

Trading Activity

Individual Holder Data

Message Types

Initial Data Message

Update Messages

Use Cases

Token Distribution Analysis

Insider Activity Monitoring

Professional Trader Tracking

Unsubscribe

Performance Considerations

Subscription Limits

Data Update Frequency

Supported Blockchains

Error Handling

Common Error Responses

Support