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

​
Subscribe to Holders Stream

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"
}

​
Support

Need help? Our response times are < 1h.

Support

Telegram

Support

Slack

Need help?

Email