Fast Trades Stream - Mobula API

This endpoint is only available to Growth and Enterprise plans.

Endpoint Details

URL: wss://api.mobula.io
Event Type: fast-trade

Subscription Formats

The fast-trade endpoint supports subscribing to trades for multiple pools and tokens with real-time updates.

Multiple Items Subscription (Recommended)

Subscribe to multiple pools and tokens using the items array format with assetMode:

{
  "type": "fast-trade",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "assetMode": false,
    "items": [
      {
        "blockchain": "evm:1",
        "address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      },
      {
        "blockchain": "evm:1",
        "address": "0xA0b86a33E6441e88C5F2712C3E9b74B6F3B5C8b6"
      }
    ],
    "subscriptionTracking": true,
    "maxUpdatesPerMinute": 60
  }
}

Token Mode Subscription

For token-specific trades (when assetMode is true):

{
  "type": "fast-trade",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "assetMode": true,
    "items": [
      {
        "blockchain": "solana",
        "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      },
      {
        "blockchain": "evm:1",
        "address": "0xA0b86a33E6441e88C5F2712C3E9b74B6F3B5C8b6"
      }
    ],
    "subscriptionTracking": true
  }
}

Parameters

assetMode (required): Boolean indicating subscription mode
- false: Subscribe to pools (default)
- true: Subscribe to tokens
items (required): Array of subscription items, each containing:
- blockchain (required): Blockchain identifier (e.g., "evm:1", "solana")
- address (required): Pool or 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 pool/token. See Update Rate Throttling below
filterOutliers (optional, default: false): When true, filters out dust trades and price outliers. See Outlier Filtering below

Trade Data Only: This endpoint provides trade events without enriched market data. For complete market statistics with each trade, use market-details or token-details streams instead.Asset Mode: The assetMode parameter determines address interpretation:

false (default): Addresses are pool addresses
true: Addresses are token addresses

Real-Time Updates

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

Real-Time Trade Updates

When trades happen involving subscribed items, you’ll receive updates with trade information. The response format depends on the assetMode used in your subscription:

Pool Mode Response (`assetMode: false`)

{
  "pair": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",
  "date": 1704067800000,
  "tokenPrice": 0.0234,
  "tokenPriceVs": 2500.75,
  "tokenAmount": 1000.0,
  "tokenAmountVs": 0.4,
  "tokenAmountUsd": 23.40,
  "tokenNativePrice": 0.00000936,
  "tokenMarketCapUSD": 234000.00,
  "type": "sell",
  "operation": "regular",
  "blockchain": "Ethereum",
  "hash": "0xdef789abc012...",
  "sender": "0x1234567890abcdef...",
  "tokenAmountRaw": "1000000000000000000000",
  "tokenAmountRawVs": "400000000000000000",
  "preBalanceBaseToken": "5000000000000000000000",
  "preBalanceQuoteToken": "2000000000000000000",
  "postBalanceBaseToken": "4000000000000000000000",
  "postBalanceQuoteToken": "2400000000000000000",
  "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
  },
  "platform": "axiom",
  "platformMetadata": {
    "id": "axiom",
    "name": "Axiom",
    "logo": "https://example.com/axiom.png"
  },
  "totalFeesUSD": 0.27,
  "gasFeesUSD": 0.02,
  "platformFeesUSD": 0.23,
  "mevFeesUSD": 0.02,
  "subscriptionId": "sub_abc123",
  "timestamp": 1704067800000
}

Token Mode Response (`assetMode: true`)

{
  "token": "0xA0b86a33E6441e88C5F2712C3E9b74B6F3B5C8b6",
  "pair": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",
  "date": 1704067800000,
  "tokenPrice": 0.0234,
  "tokenPriceVs": 2500.75,
  "tokenAmount": 1000.0,
  "tokenAmountVs": 0.4,
  "tokenAmountUsd": 23.40,
  "tokenNativePrice": 0.00000936,
  "tokenMarketCapUSD": 234000.00,
  "type": "sell",
  "operation": "regular",
  "blockchain": "Ethereum",
  "hash": "0xdef789abc012...",
  "sender": "0x1234567890abcdef...",
  "tokenAmountRaw": "1000000000000000000000",
  "tokenAmountRawVs": "400000000000000000",
  "preBalanceBaseToken": "5000000000000000000000",
  "preBalanceQuoteToken": "2000000000000000000",
  "postBalanceBaseToken": "4000000000000000000000",
  "postBalanceQuoteToken": "2400000000000000000",
  "labels": ["sniper", "freshTrader"],
  "walletMetadata": null,
  "platform": null,
  "platformMetadata": null,
  "totalFeesUSD": 0.27,
  "gasFeesUSD": 0.02,
  "platformFeesUSD": 0.23,
  "mevFeesUSD": 0.02,
  "subscriptionId": "sub_abc123",
  "timestamp": 1704067800000
}

Response Fields

pair: Pool address where the trade occurred (present in pool mode and token mode)
token: Base token address involved in the trade (only in token mode: assetMode = true)
date: Timestamp of the trade (Unix milliseconds)
tokenPrice: Price of the traded token in USD
tokenPriceVs: Price of the quote token in USD
tokenAmount: Amount of tokens traded (base token)
tokenAmountVs: Amount of quote tokens traded
tokenAmountUsd: USD value of the trade
tokenNativePrice: Price of the traded token in the blockchain’s native currency (e.g., ETH for Ethereum, SOL for Solana)
tokenMarketCapUSD: Market capitalization of the traded token in USD (based on circulating supply)
type: Trade type (“buy” or “sell”)
operation: Operation type (“regular”, “arbitrage”, etc.)
blockchain: Blockchain name
hash: Transaction hash
sender: Transaction sender address
tokenAmountRaw: Raw token amount (base token)
tokenAmountRawVs: Raw token amount (quote token)
preBalanceBaseToken: Sender’s balance of the base token before the swap (bigint or null)
preBalanceQuoteToken: Sender’s balance of the quote token before the swap (bigint or null)
postBalanceBaseToken: Sender’s balance of the base token after the swap (bigint or null)
postBalanceQuoteToken: Sender’s balance of the quote token after the swap (bigint or null)
labels: Array of labels associated with the sender wallet for the base token/pool (see Label Values below)
walletMetadata: Entity metadata for the sender wallet (see Wallet Metadata below), or null if not available
platform: Trading platform/aggregator identifier (e.g., “axiom”, “gmgn”, “padre”, “trojan”, “universalX”) or null if not available
platformMetadata: Object with id, name, and logo for the trading platform, or null if not available
subscriptionId: Your subscription identifier
timestamp: Server timestamp when the update was sent

Fee Breakdown

Complete fee transparency: Unlike other platforms that only show gas + total, Mobula provides the full breakdown in real-time.

totalFeesUSD: Total fees in USD (gas + platform + MEV combined)
gasFeesUSD: Network gas fees in USD
platformFeesUSD: Platform/aggregator fees in USD (Axiom, GMGN, Trojan, etc.)
mevFeesUSD: MEV-related fees in USD (priority fees, Jito bundles, etc.)

Label Values

The labels array can contain any combination of the following values, providing insight into the trader’s behavior and classification:

Label	Value	Description
Sniper	`sniper`	Wallet that bought the token very early (typically in the first few blocks after launch)
Insider	`insider`	Wallet with suspected insider/privileged information (e.g., pre-launch access)
Bundler	`bundler`	Wallet that bundles multiple transactions together (often associated with MEV strategies)
Pro Trader	`proTrader`	Uses a known professional trading platform (Axiom, GMGN, Trojan, Padre, UniversalX, etc.)
Smart Trader	`smartTrader`	Wallet identified as a profitable/smart trader within the last 7 days
Fresh Trader	`freshTrader`	Newly funded wallet (received initial funding within the last 24 hours)
Dev	`dev`	Token deployer/developer wallet
Liquidity Pool	`liquidityPool`	Address is a liquidity pool

Label Context: Labels are scoped to the specific token being traded. For example, a wallet may be labeled as sniper for Token A but not for Token B.

Example with Labels

{
  "token": "0xA0b86a33E6441e88C5F2712C3E9b74B6F3B5C8b6",
  "type": "buy",
  "tokenAmountUsd": 5000.00,
  "sender": "0x1234567890abcdef...",
  "labels": ["sniper", "proTrader", "smartTrader"],
  "platform": "axiom",
  "hash": "0xdef789abc012..."
}

In this example, the trader:

Sniped the token early (sniper)
Uses a professional trading platform (proTrader)
Has been identified as a smart/profitable trader (smartTrader)

Wallet Metadata

When the sender wallet is a known entity (e.g., Wintermute, Binance, Jump Trading), the walletMetadata field provides additional context:

Field	Type	Description
entityName	string \| null	Entity name (e.g., “Wintermute”)
entityLogo	string \| null	URL to the entity’s logo
entityLabels	string[]	Array of entity classification labels (e.g., “market-maker”)
entityType	string \| null	Entity type classification
entityDescription	string \| null	Short description of the entity
entityTwitter	string \| null	Twitter/X URL
entityWebsite	string \| null	Website URL
entityGithub	string \| null	GitHub URL
entityDiscord	string \| null	Discord invite URL
entityTelegram	string \| null	Telegram URL

Optional Fields Behavior

Some fields may be entirely absent, not null: In streams that use the buildSwapMessage format (token-details, market-details, pair), the labels and walletMetadata fields 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 array.In fast-trade streams, labels and walletMetadata are always present (as [] and null respectively when empty).Always use optional chaining or check for field existence:

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

Unsubscribing from the Stream

Unsubscribe from All Trade Streams

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "fast-trade"
  }
}

Unsubscribe from Specific Subscription

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

Unsubscribe from Specific Subscription with Type

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "fast-trade",
    "subscriptionId": "sub_abc123"
  }
}

Unsubscribe from Specific Items (Partial Unsubscription)

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

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "fast-trade",
    "items": [
      {
        "blockchain": "evm:1",
        "address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      }
    ]
  }
}

Unsubscribe from Multiple Specific Items

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "fast-trade",
    "items": [
      {
        "blockchain": "evm:1",
        "address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      },
      {
        "blockchain": "evm:1",
        "address": "0xA0b86a33E6441e88C5F2712C3E9b74B6F3B5C8b6"
      }
    ]
  }
}

Unsubscribe from Specific Items in a Specific Subscription

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "type": "fast-trade",
    "subscriptionId": "sub_abc123",
    "items": [
      {
        "blockchain": "evm:1",
        "address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      }
    ]
  }
}

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

Update Rate Throttling

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

{
  "type": "fast-trade",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "assetMode": false,
    "items": [
      {
        "blockchain": "evm:1",
        "address": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
      }
    ],
    "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/token:

interval = 60 000ms / maxUpdatesPerMinute

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

Interval-based, not budget-based: The server enforces a cooldown between updates. Once an update is delivered, all subsequent updates for that pool/token are dropped until the interval elapses. There is no counter that depletes — after each delivered update, the cooldown simply restarts.
Per-pool/per-token throttle: Each subscribed item is throttled independently. Subscribing to 5 items with maxUpdatesPerMinute: 60 means each item 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 item)
60	1s	One update per second per item
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.

Outlier Filtering

When filterOutliers is set to true, the server applies the same outlier detection used by the OHLCV WebSocket stream. This prevents dust trades and price manipulation from polluting your data.

{
  "type": "fast-trade",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "assetMode": true,
    "filterOutliers": true,
    "items": [
      {
        "blockchain": "solana",
        "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    ]
  }
}

What Gets Filtered

Filter	Condition	Purpose
Dust trades	`amountUSD <= $0.10`	Removes near-zero trades that can print false prices
Non-regular swaps	`swapType != REGULAR`	Removes LP deposits/withdrawals
Extreme prices	Price > 3.4e30 or < 1e-16	Removes UniV3/CLMM edge-case prices
Low-volume multi-pool	`amountUSD <= $100` on tokens with multiple pools	Removes small trades on low-liquidity pools that deviate from the market price

When filterOutliers is false (default), all trades are delivered without any filtering — the same behavior as before this feature was introduced.

Implementation Example

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

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    type: "fast-trade",
    authorization: "YOUR_API_KEY",
    payload: {
      assetMode: false,
      items: [
        {
          blockchain: "evm:1",
          address: "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
        }
      ],
      subscriptionTracking: true
    }
  }));
});

socket.addEventListener("message", (event) => {
  const data = JSON.parse(event.data);
  
  // Process trade update
  console.log(`${data.type} trade:`, data);
  console.log(`Amount: $${data.tokenAmountUsd}`);
});

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.

​Endpoint Details

​Subscription Formats

​Multiple Items Subscription (Recommended)

​Token Mode Subscription

​Parameters

​Real-Time Updates

​Real-Time Trade Updates

​Pool Mode Response (assetMode: false)

​Token Mode Response (assetMode: true)

​Response Fields

​Fee Breakdown

​Label Values

​Example with Labels

​Wallet Metadata

​Optional Fields Behavior

​Unsubscribing from the Stream

​Unsubscribe from All Trade Streams

​Unsubscribe from Specific Subscription

​Unsubscribe from Specific Subscription with Type

​Unsubscribe from Specific Items (Partial Unsubscription)

​Unsubscribe from Multiple Specific Items

​Unsubscribe from Specific Items in a Specific Subscription

​Update Rate Throttling

​How It Works

​Burst Behavior Example

​Reference Values

​Outlier Filtering

​What Gets Filtered

​Implementation Example

​Connection Keepalive (Ping/Pong)

​Support

Support

Support

Need help?

Endpoint Details

Subscription Formats

Multiple Items Subscription (Recommended)

Token Mode Subscription

Parameters

Real-Time Updates

Real-Time Trade Updates

Pool Mode Response (`assetMode: false`)

Token Mode Response (`assetMode: true`)

Response Fields

Fee Breakdown

Label Values

Example with Labels

Wallet Metadata

Optional Fields Behavior

Unsubscribing from the Stream

Unsubscribe from All Trade Streams

Unsubscribe from Specific Subscription

Unsubscribe from Specific Subscription with Type

Unsubscribe from Specific Items (Partial Unsubscription)

Unsubscribe from Multiple Specific Items

Unsubscribe from Specific Items in a Specific Subscription

Update Rate Throttling

How It Works

Burst Behavior Example

Reference Values

Outlier Filtering

What Gets Filtered

Implementation Example

Connection Keepalive (Ping/Pong)

Support