Market Details Stream

This endpoint is only available to Growth and Enterprise plans.

Not suitable for real-time chart animation.market-details is an enriched but slow stream — it delivers aggregated pool data (volumes, trade counts, holder percentages, fee stats, etc.) recomputed on each trade, which introduces significant processing latency. Updates may arrive up to 1 second after a trade**.If you want to animate a live price chart, use fast-trade instead:

Trades arrive in near real-time (sub-second latency)
Minimal payload — price, amount, type, hash
Designed for high-frequency rendering

Use market-details for dashboards, pool explorers, or any UI that needs enriched stats (volume breakdowns, buyer/seller counts, liquidity) but does not require tick-level speed.

Endpoint Details

URL: wss://api.mobula.io
Event Type: market-details

Subscription Formats

The market-details endpoint supports subscribing to multiple pool addresses for real-time market data.

Multiple Pools Subscription (Recommended)

Subscribe to multiple pools using the pools array format:

{
  "type": "market-details",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "pools": [
      {
        "blockchain": "evm:1",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      },
      {
        "blockchain": "evm:56",
        "address": "0xabcdef1234567890abcdef1234567890abcdef12"
      }
    ],
    "subscriptionTracking": true
  }
}

Parameters

pools (required): Array of pool subscription items, each containing:
- blockchain (required): Blockchain identifier (e.g., "evm:1", "solana")
- address (required): Pool address
subscriptionId (optional): Unique identifier for your WebSocket connection. Auto-generated if not provided
subscriptionTracking (optional, default: false): Include subscription details in response logs for debugging
maxUpdatesPerMinute (optional): Limit how often the server sends updates for each pool. See Update Rate Throttling below

Pool Addresses Only: This endpoint is for subscribing to pool addresses. For token-specific subscriptions, use the token-details endpoint instead.

Real-Time Updates

After subscribing, you’ll receive real-time updates whenever new trades occur on the subscribed pools.

Real-Time Trade Updates for Pool Subscriptions

When trades happen on subscribed pool addresses, you’ll receive updates with trade information:

{
  "pair": "0x1234567890abcdef1234567890abcdef12345678",
  "date": 1704067800000,
  "token_price": 2500.75,
  "token_price_vs": 1.0,
  "token_amount": 1.5,
  "token_amount_vs": 3751.125,
  "token_amount_usd": 3751.125,
  "type": "buy",
  "operation": "regular",
  "blockchain": "Ethereum",
  "hash": "0xabc123def456...",
  "sender": "0x9876543210fedcba...",
  "token_amount_raw": "1500000000000000000",
  "token_amount_raw_vs": "3751125000",
  "labels": ["proTrader"],
  "walletMetadata": {
    "entityName": "Wintermute",
    "entityLogo": "https://example.com/wintermute.png",
    "entityLabels": ["market-maker"],
    "entityType": "market_maker",
    "entityDescription": "Wintermute is a leading global algorithmic trading firm",
    "entityTwitter": "https://twitter.com/wintermute_t",
    "entityWebsite": "https://wintermute.com",
    "entityGithub": null,
    "entityDiscord": null,
    "entityTelegram": null
  },
  "preBalanceBaseToken": "5000000000000000000000",
  "preBalanceQuoteToken": "2000000000000000000",
  "postBalanceBaseToken": "4000000000000000000000",
  "postBalanceQuoteToken": "2400000000000000000",
  "swapRecipient": null,
  "platform": "axiom",
  "platformMetadata": {
    "id": "axiom",
    "name": "Axiom",
    "logo": "https://example.com/axiom.png"
  },
  "pairData": {
    // Complete EnrichedPoolData structure with all fields from MarketDetailsOutput.ts
    "baseToken": {
      "address": "0xA0b86a33E6441e98f0bE9F9f7D5D2b5c3D8F4e7c",
      "chainId": "evm:1",
      "symbol": "WETH",
      "name": "Wrapped Ether",
      "decimals": 18,
      "id": 12345,
      "priceUSD": 2500.50,
      "priceToken": 1.0,
      "priceTokenString": "1.000000000000000000000000000000",
      "approximateReserveUSD": 90000000.0,
      "approximateReserveTokenRaw": "36000000000000000000",
      "approximateReserveToken": 36000.0,
      "totalSupply": 1000000000000000000000000,
      "circulatingSupply": 900000000000000000000000,
      "marketCapUSD": 2250450000000,
      "marketCapDilutedUSD": 2500500000000,
      "logo": "https://example.com/weth-logo.png",
      "exchange": {
        "name": "Uniswap V3",
        "logo": "https://example.com/uniswap-logo.png"
      },
      "factory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
      "source": "uniswap",
      "sourceFactory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
      "liquidityUSD": 100000000.0,
      "liquidityMaxUSD": 120000000.0,
      "bonded": false,
      "bondingPercentage": 0,
      "bondingCurveAddress": null,
      "preBondingFactory": null,
      "poolAddress": null,
      "blockchain": "ethereum",
      "type": "token",
      "deployer": "0x1234567890abcdef...",
      "createdAt": "2020-01-01T00:00:00.000Z",
      "bondedAt": null,
      "athUSD": 4878.26,
      "atlUSD": 88.01,
      "athDate": "2021-11-10T14:00:00.000Z",
      "atlDate": "2019-02-08T00:00:00.000Z"
    },
    "quoteToken": {
      "address": "0xB0c87a44F6c95d6E5C4e8g7F9E3D7c2b1A9e8f6d",
      "chainId": "evm:1",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "id": 67890,
      "priceUSD": 1.0,
      "priceToken": 0.0004,
      "priceTokenString": "0.000400000000000000000000000000",
      "approximateReserveUSD": 90000000.0,
      "approximateReserveTokenRaw": "90000000000",
      "approximateReserveToken": 90000000.0,
      "totalSupply": 1000000000000000000000000000,
      "circulatingSupply": 900000000000000000000000000,
      "marketCapUSD": 1000000000000,
      "marketCapDilutedUSD": 1000000000000,
      "logo": "https://example.com/usdc-logo.png",
      "exchange": {
        "name": "Circle",
        "logo": "https://example.com/circle-logo.png"
      },
      "factory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
      "source": "uniswap",
      "sourceFactory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
      "liquidityUSD": 100000000.0,
      "liquidityMaxUSD": 120000000.0,
      "bonded": false,
      "bondingPercentage": 0,
      "bondingCurveAddress": null,
      "preBondingFactory": null,
      "poolAddress": null,
      "blockchain": "ethereum",
      "type": "token",
      "deployer": "0x1234567890abcdef...",
      "createdAt": "2018-01-01T00:00:00.000Z",
      "bondedAt": null,
      "athUSD": 1.17,
      "atlUSD": 0.88,
      "athDate": "2021-05-19T14:00:00.000Z",
      "atlDate": "2020-03-13T00:00:00.000Z"
    },
    "liquidityUSD": 5000000.25,
    "blockchain": "Ethereum",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "type": "uniswap-v3",
    "exchange": {
      "name": "Uniswap V3",
      "logo": "https://example.com/uniswap-logo.png"
    },
    "factory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
    "priceUSD": 2500.50,
    "priceToken": 0.0004,
    "priceTokenString": "0.000400000000000000000000000000",
    "bonded": false,
    "bondingPercentage": 0,
    "preBondingPoolAddress": null,
    "sourceFactory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
    "top10HoldingsPercentage": 35.2,
    "top50HoldingsPercentage": 58.7,
    "top100HoldingsPercentage": 68.9,
    "top200HoldingsPercentage": 78.3,
    "devHoldingsPercentage": 12.5,
    "insidersHoldingsPercentage": 6.8,
    "bundlersHoldingsPercentage": 1.9,
    "snipersHoldingsPercentage": 2.1,
    "proTradersHoldingsPercentage": 5.0,
    "totalFeesPaidUSD": 150000.0,
    "priceChange1minPercentage": 0.1,
    "priceChange5minPercentage": -0.5,
    "priceChange1hPercentage": 2.3,
    "priceChange4hPercentage": 1.2,
    "priceChange6hPercentage": 0.8,
    "priceChange12hPercentage": -0.3,
    "priceChange24hPercentage": -3.8,
    "volume1minUSD": 15000.50,
    "volume5minUSD": 85000.75,
    "volume15minUSD": 425000.25,
    "volume1hUSD": 450000.25,
    "volume4hUSD": 1800000.0,
    "volume6hUSD": 2700000.0,
    "volume12hUSD": 5400000.0,
    "volume24hUSD": 1500000.75,
    "volumeBuy1minUSD": 8000.25,
    "volumeBuy5minUSD": 45000.50,
    "volumeBuy15minUSD": 225000.15,
    "volumeBuy1hUSD": 240000.15,
    "volumeBuy4hUSD": 960000.0,
    "volumeBuy6hUSD": 1440000.0,
    "volumeBuy12hUSD": 2880000.0,
    "volumeBuy24hUSD": 800000.40,
    "volumeSell1minUSD": 7000.25,
    "volumeSell5minUSD": 40000.25,
    "volumeSell15minUSD": 200000.10,
    "volumeSell1hUSD": 210000.10,
    "volumeSell4hUSD": 840000.0,
    "volumeSell6hUSD": 1260000.0,
    "volumeSell12hUSD": 2520000.0,
    "volumeSell24hUSD": 700000.35,
    "trades1min": 25,
    "trades5min": 125,
    "trades15min": 625,
    "trades1h": 650,
    "trades4h": 2600,
    "trades6h": 3900,
    "trades12h": 7800,
    "trades24h": 12000,
    "buys1min": 13,
    "buys5min": 68,
    "buys15min": 340,
    "buys1h": 340,
    "buys4h": 1360,
    "buys6h": 2040,
    "buys12h": 4080,
    "buys24h": 6500,
    "sells1min": 12,
    "sells5min": 57,
    "sells15min": 285,
    "sells1h": 310,
    "sells4h": 1240,
    "sells6h": 1860,
    "sells12h": 3720,
    "sells24h": 5500,
    "buyers1min": 13,
    "buyers5min": 65,
    "buyers15min": 325,
    "buyers1h": 325,
    "buyers4h": 1300,
    "buyers6h": 1950,
    "buyers12h": 3900,
    "buyers24h": 6200,
    "sellers1min": 12,
    "sellers5min": 55,
    "sellers15min": 275,
    "sellers1h": 295,
    "sellers4h": 1180,
    "sellers6h": 1770,
    "sellers12h": 3540,
    "sellers24h": 5200,
    "traders1min": 24,
    "traders5min": 115,
    "traders15min": 575,
    "traders1h": 595,
    "traders4h": 2380,
    "traders6h": 3570,
    "traders12h": 7140,
    "traders24h": 10400,
    "feesPaid1minUSD": 75.0,
    "feesPaid5minUSD": 425.0,
    "feesPaid15minUSD": 2125.0,
    "feesPaid1hUSD": 2250.0,
    "feesPaid4hUSD": 9000.0,
    "feesPaid6hUSD": 13500.0,
    "feesPaid12hUSD": 27000.0,
    "feesPaid24hUSD": 75000.0,
    "extraData": {
      "customField1": "value1",
      "customField2": 123,
      "customField3": true
    }
  },
  "subscriptionId": "sub_def456",
  "updated": true,
  "timestamp": 1704067800000
}

Optional Fields Behavior

Fields may be entirely absent, not null: Several fields in trade update messages are conditionally included — when there is no data, the field is completely omitted from the JSON payload rather than being set to null or an empty value.This applies to:

labels: Only present when the sender wallet has known labels for this pool’s base token. If absent, the sender has no labels.
walletMetadata: Only present when the sender wallet has entity metadata (e.g., known entity like Wintermute, Binance). If absent, no entity info is available.

Always use optional chaining or check for field existence:

// Correct
const labels = data.labels ?? [];
const entityName = data.walletMetadata?.entityName ?? null;

// Incorrect — will throw if field is missing
const labels = data.labels; // undefined, not []

Unsubscribing from the Stream

Unsubscribe from All Market-Details Streams

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "market-details"
  }
}

Unsubscribe from Specific Subscription

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "subscriptionId": "sub_def456"
  }
}

Unsubscribe from Specific Subscription with Type

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "market-details",
    "subscriptionId": "sub_def456"
  }
}

Unsubscribe from Specific Pools (Partial Unsubscription)

You can unsubscribe from specific pools while keeping others active in the same subscription:

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "market-details",
    "pools": [
      {
        "blockchain": "evm:1",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ]
  }
}

Unsubscribe from Multiple Specific Pools

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "market-details",
    "pools": [
      {
        "blockchain": "evm:1",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      },
      {
        "blockchain": "evm:56",
        "address": "0xabcdef1234567890abcdef1234567890abcdef12"
      }
    ]
  }
}

Unsubscribe from Specific Pools in a Specific Subscription

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "market-details",
    "subscriptionId": "sub_def456",
    "pools": [
      {
        "blockchain": "evm:1",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ]
  }
}

If you didn’t provide a subscriptionId when subscribing, one is auto-generated. To retrieve it, set "subscriptionTracking": true in the subscription payload.For partial unsubscriptions without subscriptionId, the system will automatically find and modify subscriptions that contain the specified pools, leaving other pools in those subscriptions active.

Update Rate Throttling

You can control how frequently the server sends update messages per pool using the maxUpdatesPerMinute field. This is useful for reducing bandwidth on dashboards that don’t need every single trade update.

{
  "type": "market-details",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "pools": [
      {
        "blockchain": "evm:1",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "maxUpdatesPerMinute": 60
  }
}

How It Works

Despite the name, maxUpdatesPerMinute does not set a budget that gets consumed over a minute. Instead, it sets a minimum interval between delivered updates per pool:

interval = 60 000ms / maxUpdatesPerMinute

For example, maxUpdatesPerMinute: 100 → minimum interval of 600ms between two delivered updates for the same pool.

Interval-based, not budget-based: The server enforces a cooldown between updates. Once an update is delivered, all subsequent updates for that pool are dropped until the interval elapses. There is no counter that depletes — after each delivered update, the cooldown simply restarts.
Per-pool throttle: Each pool is throttled independently. Subscribing to 5 pools with maxUpdatesPerMinute: 60 means each pool sends at most 1 update/second.
Dropped, not buffered: When an update arrives during the cooldown, it is silently dropped — not queued or aggregated. The next update arriving after the interval has elapsed will be delivered normally.

Burst Behavior Example

With maxUpdatesPerMinute: 100 (interval = 600ms), if a pool receives a burst of 50 updates in 1 second:

Time	Event	Result
t=0ms	Update 1 arrives	Delivered (cooldown starts)
t=50ms	Updates 2–10 arrive	Dropped (still within 600ms cooldown)
t=600ms	Update ~20 arrives	Delivered (cooldown elapsed, restarts)
t=800ms	Updates ~25–50 arrive	Dropped (still within new 600ms cooldown)
t=2s	Next update arrives	Delivered normally

You receive ~2 updates from the burst, and updates resume normally afterwards. There is no debt or penalty — the throttle does not “remember” dropped updates or block future delivery.

Reference Values

`maxUpdatesPerMinute`	Effective interval	Description
600	100ms	Maximum rate (~10 updates/sec per pool)
60	1s	One update per second per pool
6	10s	One update every 10 seconds
1	60s	One update per minute (minimum rate)

When maxUpdatesPerMinute is not provided, no throttle is applied and updates are delivered as fast as they arrive.

Implementation Example

const socket = new WebSocket("wss://api.mobula.io");

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    type: "market-details",
    authorization: "YOUR_API_KEY",
    payload: {
      pools: [
        {
          blockchain: "evm:1",
          address: "0x1234567890abcdef1234567890abcdef12345678"
        }
      ],
      subscriptionTracking: true
    }
  }));
});

socket.addEventListener("message", (event) => {
  const data = JSON.parse(event.data);
  
  // Process market update
  if (data.pairData) {
    console.log("Market update:", data.pairData);
    console.log(`Liquidity: $${data.pairData.liquidityUSD}`);
  }
});

socket.addEventListener("error", (error) => {
  console.error("WebSocket error:", error);
});

socket.addEventListener("close", () => {
  console.log("WebSocket connection closed");
});

You can use the Network tab in your browser to see the WebSocket requests and responses in real-time.

Connection Keepalive (Ping/Pong)

To maintain active WebSocket connections and prevent timeouts, you can use the ping/pong mechanism: Send ping:

{"event":"ping"}

Receive pong: The server will respond with a pong message to confirm the connection is active.

Use ping messages periodically (every 30-60 seconds) to keep long-lived connections alive.

Introduction

Market Data

Price History & OHLCV

Trades

Holders

Pulse

Wallet

Swap Execution

Streams

Market Details Stream

Endpoint Details

Subscription Formats

Multiple Pools Subscription (Recommended)

Parameters

Real-Time Updates

Real-Time Trade Updates for Pool Subscriptions

Optional Fields Behavior

Unsubscribing from the Stream

Unsubscribe from All Market-Details Streams

Unsubscribe from Specific Subscription

Unsubscribe from Specific Subscription with Type

Unsubscribe from Specific Pools (Partial Unsubscription)

Unsubscribe from Multiple Specific Pools

Unsubscribe from Specific Pools in a Specific Subscription

Update Rate Throttling

How It Works

Burst Behavior Example

Reference Values

Implementation Example

Connection Keepalive (Ping/Pong)

Support

Support

Support

Need help?

Introduction

Market Data

Price History & OHLCV

Trades

Holders

Pulse

Wallet

Swap Execution

Streams

​Endpoint Details

​Subscription Formats

​Multiple Pools Subscription (Recommended)

​Parameters

​Real-Time Updates

​Real-Time Trade Updates for Pool Subscriptions

​Optional Fields Behavior

​Unsubscribing from the Stream

​Unsubscribe from All Market-Details Streams

​Unsubscribe from Specific Subscription

​Unsubscribe from Specific Subscription with Type

​Unsubscribe from Specific Pools (Partial Unsubscription)

​Unsubscribe from Multiple Specific Pools

​Unsubscribe from Specific Pools in a Specific Subscription

​Update Rate Throttling

​How It Works

​Burst Behavior Example

​Reference Values

​Implementation Example

​Connection Keepalive (Ping/Pong)

​Support

Support

Support

Need help?

Endpoint Details

Subscription Formats

Multiple Pools Subscription (Recommended)

Parameters

Real-Time Updates

Real-Time Trade Updates for Pool Subscriptions

Optional Fields Behavior

Unsubscribing from the Stream

Unsubscribe from All Market-Details Streams

Unsubscribe from Specific Subscription

Unsubscribe from Specific Subscription with Type

Unsubscribe from Specific Pools (Partial Unsubscription)

Unsubscribe from Multiple Specific Pools

Unsubscribe from Specific Pools in a Specific Subscription

Update Rate Throttling

How It Works

Burst Behavior Example

Reference Values

Implementation Example

Connection Keepalive (Ping/Pong)

Support