Skip to main content
This endpoint is only available to Growth and Enterprise plans.
Not suitable for real-time chart animation.token-details is an enriched but slow stream — it delivers aggregated token data (volumes, holder stats, price changes, 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 token-details for dashboards, token screeners, or any UI that needs enriched stats (volume, buys/sells counts, holder percentages) but does not require tick-level speed.

Endpoint Details

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

Subscription Formats

The token-details endpoint supports subscribing to multiple token addresses for real-time token data. Subscribe to multiple tokens using the tokens array format:

Parameters

  • tokens (required): Array of token subscription items, each containing:
    • blockchain (required): Blockchain identifier (e.g., "evm:1", "solana")
    • address (required): Token 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 token. See Update Rate Throttling below
  • filterOutliers (optional, default: false): When true, drops dust trades and price outliers that would otherwise overwrite tokenData.priceUSD in the broadcast payload. See Outlier Filtering below
Token Addresses Only: This endpoint is for subscribing to token addresses. For pool-specific subscriptions, use the market-details endpoint instead.

Real-Time Updates

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

Real-Time Trade Updates for Token Subscriptions

When trades happen involving subscribed tokens, you’ll receive updates with trade information:

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 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:

Security Object Fields

All fields in tokenData.security are optional — only present when data is available for the token. A missing field means the check was not performed, not that the token is safe.
EVM vs Solana availability: Most fields apply to EVM chains. noMintAuthority is Solana-specific. isHoneypot, isNotOpenSource, renounced, locked, isWhitelisted, isMintable, modifyableTax, and selfDestruct are EVM-only.

Liquidity Burn

Unsubscribing from the Stream

Unsubscribe from All Token-Details Streams

Unsubscribe from Specific Subscription

Unsubscribe from Specific Subscription with Type

Unsubscribe from Specific Tokens (Partial Unsubscription)

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

Unsubscribe from Multiple Specific Tokens

Unsubscribe from Specific Tokens in a Specific Subscription

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 tokens, leaving other tokens in those subscriptions active.

Update Rate Throttling

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

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 token:
For example, maxUpdatesPerMinute: 100 → minimum interval of 600ms between two delivered updates for the same token.
  • Interval-based, not budget-based: The server enforces a cooldown between updates. Once an update is delivered, all subsequent updates for that token are dropped until the interval elapses. There is no counter that depletes — after each delivered update, the cooldown simply restarts.
  • Per-token throttle: Each token is throttled independently. Subscribing to 5 tokens with maxUpdatesPerMinute: 60 means each token 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 token receives a burst of 50 updates in 1 second: 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

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

Outlier Filtering

When filterOutliers is set to true, the server applies the same outlier detection used by the fast-trade and OHLCV streams. This is important for token-details specifically: each broadcast trade overrides tokenData.priceUSD in the payload with that trade’s computed price — so a single dust or low-liquidity swap can otherwise pollute your UI price.

What Gets Filtered

When filterOutliers is false (default), every trade is delivered — including dust and edge-case prints. Existing clients keep the same behavior as before this flag was introduced.
If every trade in a batch gets filtered out, the stream falls back to a compact snapshot message { token, subscriptionId, updated: true, timestamp } (no hash/token_price fields). Your UI still gets a refreshed server-side aggregate price instead of a polluted per-trade print.

Implementation Example

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:
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.

Support

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

Support

Telegram

Support

Slack

Need help?

Email