This endpoint is only available to Growth and Enterprise plans.

​
Endpoint Details

  • URL: wss://api.mobula.io
  • Event Type: pairs

​
Subscription Formats

The pairs endpoint supports multiple payload formats and can handle both pool addresses and token assets. Subscribe to multiple tokens or pools using the items array format: 
{
  "type": "pairs",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "items": [
      {
        "blockchain": "solana",
        "asset": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump"
      },
      {
        "blockchain": "solana",
        "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      },
      {
        "blockchain": "evm:1",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "subscriptionTracking": true
  }
}

​
Direct Items Format (Alternative)

You can also send the items array directly without nesting: 
{
  "items": [
    {
      "blockchain": "solana",
      "asset": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump"
    },
    {
      "blockchain": "evm:1",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    }
  ],
  "authorization": "YOUR-API-KEY",
  "subscriptionId": "my-subscription"
}

​
Single Item Subscription (Legacy Format)

Subscribe to a single token or pool using the legacy format: 
{
  "type": "pairs",
  "authorization": "YOUR-API-KEY",
  "payload": {
    "asset": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump",
    "blockchain": "solana"
  }
}

​
Parameters

​
Core Parameters

  • items (required for multiple items): Array of subscription items, each containing:
    • blockchain (required): Blockchain identifier (e.g., "evm:1", "solana")
    • asset (optional): Asset name, symbol, or address
    • symbol (optional): Asset symbol for better identification
    • address (optional): Direct pool or token address
  • asset (optional, legacy): Single token address or name for backward compatibility
  • address (optional, legacy): Single pool address for backward compatibility
  • blockchain (optional): Blockchain identifier for single item subscriptions
  • mode (optional): Stream mode - "asset" or "pair". Defaults to "pair"

​
Optional Parameters

  • 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
  • interval (optional, default: 30): Refresh interval in seconds
  • factory (optional): Filter by specific factory contract

​
Important Constraints

You can now subscribe to both pool addresses and token assets in the same request using the items array format. Each item in the array can specify either an asset (token) or address (pool) along with its blockchain.

​
Response Data Models

​
For Token Subscriptions (Asset Mode)

When subscribing to tokens, you’ll receive enriched token data with trade information: 
{
  "pair": "0x1234567890abcdef1234567890abcdef12345678",
  "date": 1704067800000,
  "token_price": 0.0234,
  "token_price_vs": 43.21,
  "token_amount": 1000.0,
  "token_amount_vs": 0.4,
  "token_amount_usd": 23.40,
  "type": "sell",
  "operation": "regular",
  "blockchain": "ethereum",
  "hash": "0xdef789abc012...",
  "sender": "0x1234567890abcdef...",
  "token_amount_raw": "1000000000000000000000",
  "token_amount_raw_vs": "400000000000000000",
  "tokenData": {
    "address": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump",
    "chainId": "solana",
    "symbol": "EXAMPLE",
    "name": "Example Token",
    "decimals": 9,
    "price": 0.0234,
    "priceToken": 43.21,
    "priceTokenString": "43.210000000000000000000000000000",
    "approximateReserveUSD": 125000.50,
    "approximateReserveTokenRaw": "5000000000000000000",
    "approximateReserveToken": 5000.0,
    "totalSupply": 1000000000,
    "circulatingSupply": 800000000,
    "marketCap": 18720000,
    "marketCapDiluted": 23400000,
    "logo": "https://example.com/token-logo.png",

    "latest_trade_date": "2025-01-15T10:30:00.000Z",
    "price_change_1min": 0.5,
    "price_change_5min": -1.2,
    "price_change_1h": 3.4,
    "price_change_24h": -5.8,

    "volume_1min": 1250.75,
    "volume_5min": 8500.25,
    "volume_1h": 45000.80,
    "volume_24h": 890000.50,

    "buy_volume_1min": 675.50,
    "buy_volume_5min": 4500.25,
    "buy_volume_1h": 24000.40,
    "buy_volume_24h": 480000.25,

    "sell_volume_1min": 575.25,
    "sell_volume_5min": 4000.00,
    "sell_volume_1h": 21000.40,
    "sell_volume_24h": 410000.25,

    "trades_1min": 15,
    "trades_5min": 85,
    "trades_1h": 450,
    "trades_24h": 8900,

    "buys_1min": 8,
    "buys_5min": 45,
    "buys_1h": 240,
    "buys_24h": 4800,

    "sells_1min": 7,
    "sells_5min": 40,
    "sells_1h": 210,
    "sells_24h": 4100,

    "buyers_1min": 8,
    "buyers_5min": 42,
    "buyers_1h": 235,
    "buyers_24h": 4650,

    "sellers_1min": 7,
    "sellers_5min": 38,
    "sellers_1h": 205,
    "sellers_24h": 3950,

    "traders_1min": 14,
    "traders_5min": 78,
    "traders_1h": 420,
    "traders_24h": 8200,

    "holders_count": 1250,
    "liquidity": 250000.75,

    "top10Holdings": 45.6,
    "top50Holdings": 68.9,
    "top100Holdings": 78.5,
    "top200Holdings": 85.2,
    "devHoldings": 15.5,
    "insidersHoldings": 8.2,
    "snipersHoldings": 3.1,
    "bundlersHoldings": 2.8,

    "security": {
      "honeypot": false,
      "rugPull": false,
      "scam": false,
      "verified": true
    },

    "socials": {
      "twitter": "https://twitter.com/example",
      "website": "https://example.com",
      "telegram": "https://t.me/example",
      "others": {}
    },

    "description": "Example token description",
    "created_at": "2024-12-01T00:00:00.000Z"
  },
  "subscriptionId": "sub_abc123",
  "updated": true,
  "timestamp": 1704067800000
}

​
For Pool Subscriptions (Pair Mode)

When subscribing to pool addresses, you’ll receive enriched pool data 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",
  "pairData": {
    "token0": {
      "address": "0xA0b86a33E6441e98f0bE9F9f7D5D2b5c3D8F4e7c",
      "chainId": "evm:1",
      "symbol": "WETH",
      "name": "Wrapped Ether",
      "decimals": 18,
      "price": 2500.50,
      "priceToken": 1.0,
      "logo": "https://example.com/weth-logo.png"
    },
    "token1": {
      "address": "0xB0c87a44F6c95d6E5C4e8g7F9E3D7c2b1A9e8f6d",
      "chainId": "evm:1",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "price": 1.0,
      "priceToken": 0.0004,
      "logo": "https://example.com/usdc-logo.png"
    },

    "volume24h": 1500000.75,
    "liquidity": 5000000.25,
    "blockchain": "Ethereum",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "type": "uniswap-v3",
    "baseToken": "token0",
    "exchange": {
      "name": "Uniswap V3",
      "logo": "https://example.com/uniswap-logo.png"
    },
    "factory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
    "quoteToken": "token1",
    "price": 2500.50,

    "price_change_1min": 0.1,
    "price_change_5min": -0.5,
    "price_change_1h": 2.3,
    "price_change_24h": -3.8,

    "volume_1min": 15000.50,
    "volume_5min": 85000.75,
    "volume_1h": 450000.25,
    "volume_24h": 1500000.75,

    "buy_volume_1min": 8000.25,
    "buy_volume_5min": 45000.50,
    "buy_volume_1h": 240000.15,
    "buy_volume_24h": 800000.40,

    "sell_volume_1min": 7000.25,
    "sell_volume_5min": 40000.25,
    "sell_volume_1h": 210000.10,
    "sell_volume_24h": 700000.35,

    "trades_1min": 25,
    "trades_5min": 125,
    "trades_1h": 650,
    "trades_24h": 12000,

    "buys_1min": 13,
    "buys_5min": 68,
    "buys_1h": 340,
    "buys_24h": 6500,

    "sells_1min": 12,
    "sells_5min": 57,
    "sells_1h": 310,
    "sells_24h": 5500,

    "liquidity": 5000000.25,
    "holders_count": 2500,

    "top10Holdings": 35.2,
    "top50Holdings": 58.7,
    "top100Holdings": 68.9,
    "top200Holdings": 78.3,
    "devHoldings": 12.5,
    "insidersHoldings": 6.8,
    "snipersHoldings": 2.1,
    "bundlersHoldings": 1.9,

    "security": {
      "honeypot": false,
      "rugPull": false,
      "scam": false,
      "verified": true
    },

    "socials": {
      "twitter": "https://twitter.com/example",
      "website": "https://example.com",
      "telegram": "https://t.me/example",
      "others": {}
    }
  },
  "subscriptionId": "sub_def456",
  "updated": true,
  "timestamp": 1704067800000
}

​
Real-Time Updates

After the initial subscription response, you’ll receive real-time updates whenever new trades occur. These updates include both the trade data and refreshed market data.

​
Real-Time Trade Updates for Pool Subscriptions

When trades happen on subscribed pool addresses, you’ll receive: 
{
  "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",
  
  "pairData": {
    // Full EnrichedPoolData structure with updated metrics
    "token0": { /* ... */ },
    "token1": { /* ... */ },
    "volume24h": 1500000.75,
    "liquidity": 5000000.25,
    // ... all pool statistics updated
  },
  
  "subscriptionId": "sub_def456",
  "updated": true,
  "timestamp": 1704067800000
}

​
Real-Time Trade Updates for Token Subscriptions

When trades happen involving subscribed tokens, you’ll receive: 
{
  "pair": "0x1234567890abcdef1234567890abcdef12345678",
  "date": 1704067800000,
  "token_price": 0.0234,
  "token_price_vs": 2500.75,
  "token_amount": 1000.0,
  "token_amount_vs": 0.4,
  "token_amount_usd": 23.40,
  "type": "sell",
  "operation": "regular",
  "blockchain": "Ethereum",
  "hash": "0xdef789abc012...",
  "sender": "0x1234567890abcdef...",
  "token_amount_raw": "1000000000000000000000",
  "token_amount_raw_vs": "400000000000000000",
  
  "tokenData": {
    // Full EnrichedTokenData structure with updated metrics
    "address": "3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump",
    "symbol": "EXAMPLE",
    "price": 0.0234,
    // ... all token statistics updated
  },
  
  "subscriptionId": "sub_abc123",
  "updated": true,
  "timestamp": 1704067800000
}

​
Trade Data Fields

The real-time trade updates include the following fields from CuratedSwap:
  • pair: Pool address where the trade occurred
  • date: Trade timestamp in milliseconds
  • token_price: Price of the base token in USD
  • token_price_vs: Price of the quote token in USD
  • token_amount: Amount of base token traded
  • token_amount_vs: Amount of quote token traded
  • token_amount_usd: USD value of the trade
  • type: Trade type - "buy" or "sell"
  • operation: Operation type (e.g., "regular", "limit")
  • blockchain: Human-readable blockchain name
  • hash: Transaction hash
  • sender: Address that initiated the transaction
  • token_amount_raw: Raw token amount (string to handle large numbers)
  • token_amount_raw_vs: Raw quote token amount (string)
Additionally, the response includes either:
  • pairData: Full EnrichedPoolData for pool subscriptions
  • tokenData: Full EnrichedTokenData for token subscriptions

​
Unsubscribing from the Stream

​
Unsubscribe from All Streams

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

​
Unsubscribe from Specific Subscription

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

​
Unsubscribe from All Pairs Streams

{
  "type": "unsubscribe",
  "authorization": "YOUR-API-KEY", 
  "payload": {
    "type": "pairs"
  }
}
If you didn’t provide a subscriptionId when subscribing, one is auto-generated. To retrieve it, set "subscriptionTracking": true in the subscription payload.

​
Migration from Legacy Endpoint

Legacy Single Pair EndpointThe previous single pair endpoint is still supported but consider migrating to the new pairs endpoint for better performance and flexibility. The legacy endpoint documentation can be found here.
Key advantages of the new pairs endpoint:
  • Subscribe to multiple assets/pools in a single connection
  • Better performance with batch processing
  • Consistent data format for both pools and tokens
  • Enhanced real-time updates

​
Examples

​
TypeScript Example

const ws = new WebSocket('wss://api.mobula.io');

ws.onopen = () => {
  // Subscribe to multiple assets using the items format
  ws.send(JSON.stringify({
    type: 'pairs',
    authorization: 'YOUR-API-KEY',
    payload: {
      items: [
        {
          blockchain: 'solana',
          asset: '3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump'
        },
        {
          blockchain: 'solana',
          asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
        },
        {
          blockchain: 'evm:1',
          address: '0x1234567890abcdef1234567890abcdef12345678'
        }
      ],
      subscriptionTracking: true,
      interval: 30
    }
  }));
};

// Alternative: Direct format without nested payload
ws.send(JSON.stringify({
  items: [
    {
      blockchain: 'solana',
      asset: '3vz82EWYv8xnc7Cm7qSgERcpMeqw92PcX8PBz88npump'
    }
  ],
  authorization: 'YOUR-API-KEY',
  subscriptionId: 'my-subscription'
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);

  if (data.tokens) {
    // Initial subscription response with token data
    data.tokens.forEach(token => {
      console.log(`Initial ${token.symbol}: $${token.price}`);
    });
  } else if (data.pairs) {
    // Initial subscription response with pair data
    data.pairs.forEach(pair => {
      console.log(`Initial ${pair.address}: $${pair.price}`);
    });
  } else if (data.updated && data.hash) {
    // Real-time trade update
    console.log(`🚀 New ${data.type} trade!`);
    console.log(`💰 Amount: ${data.token_amount} tokens ($${data.token_amount_usd})`);
    console.log(`💵 Price: $${data.token_price}`);
    console.log(`🔗 Hash: ${data.hash}`);
    console.log(`⛓️ Blockchain: ${data.blockchain}`);

    if (data.pairData) {
      // Pool subscription - access enriched pool data
      console.log(`📊 Pool Volume 24h: $${data.pairData.volume24h}`);
      console.log(`💧 Liquidity: $${data.pairData.liquidity}`);
    } else if (data.tokenData) {
      // Token subscription - access enriched token data
      console.log(`📊 Token Volume 24h: $${data.tokenData.volume_24h}`);
      console.log(`👥 Holders: ${data.tokenData.holders_count}`);
    }
  }
};

Support

Telegram

Support

Slack

Need help?

Email