Subscribing to Real-Time Token Transaction Updates (SUBSCRIBE_TXS)

The “SUBSCRIBE_TXS” event allows you to receive real-time updates about token transactions. You can subscribe to transactions for individual tokens, token pairs, or a combination of both. This subscription is useful for tracking trading activities and other relevant transactions on the Birdeye platform. You can use this Websocket to get real time transaction updates of following objects:

Transactions of a token
Transactions of a pair/market
Transactions of multiple Tokens/Pairs

You can also filter the transaction type for each object, including swap, add liquidity, and remove liquidity. The instructions for each type of objects are described below.

Code Example

Checkout this Github file for an example:

https://github.com/birdeye-so/tradingview-example-js-api/blob/main/websocket_example.js

To receive real-time updates about transactions for a specific token, you can use the following subscription message format:

Input

{
    "type": "SUBSCRIBE_TXS",
    "data": {
        "queryType": "simple",
        "address": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
				"txsType": "all"
    }
}

You can pass any of the following values to txsType: “all”, “add_remove_liquidity”, “add_liquidity”, “remove_liquidity”, “swap” to filter transaction types. If txsType is not provided, the result will default to returning all transaction types, the same as when using “all”.

Output Example

{
  "type": "TXS_DATA",
  "data": {
    "blockUnixTime": 1747307828,
    "owner": "Dc9jiLSNN8qwEciwd55HmZhroswZ4XvcvKeRXHWCnwbP",
    "source": "zerofi",
    "txHash": "3L4BWQxgpF7SyH13bbEH53ZXYFNdRcK5dtMXreeGviaWFKes3fod5cQWsQ3oRHXcdUaemoiEXLaUit1Syw5FdCP1",
    "side": "sell",
    "tokenAddress": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
    "alias": null,
    "isTradeOnBe": false,
    "platform": "Jupiter",
    "pricePair": 0.49898781541961984,
    "volumeUSD": 86.16813238056157,
    "from": {
      "address": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
      "amount": 172707630,
      "changeAmount": -172707630,
      "decimals": 6,
      "nearestPrice": 0.4989839116193116,
      "price": null,
      "symbol": "JUP",
      "type": "transfer",
      "typeSwap": "from",
      "uiAmount": 172.70763,
      "uiChangeAmount": -172.70763
    },
    "to": {
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": 86179003,
      "changeAmount": 86179003,
      "decimals": 6,
      "feeInfo": null,
      "nearestPrice": 0.99987386,
      "price": null,
      "symbol": "USDC",
      "type": "transfer",
      "typeSwap": "to",
      "uiAmount": 86.179003,
      "uiChangeAmount": 86.179003
    },
    "priceMark": true,
    "tokenPrice": 0.4989248730965828,
    "network": "solana",
    "poolId": "1amiJLvkVHjPz7t8dwBsWHknHitcpqwPPuuUCfHyzjB"
  }
}

To receive real-time updates about transactions for a specific token pair, you can use the following subscription message format:

Input

{
    "type": "SUBSCRIBE_TXS",
    "data": {
       "queryType": "simple",
     	 "pairAddress": "842NwDnKYcfMRWAYqsD3hoTWXKKMi28gVABtmaupFcnS",
			 "txsType":"all"
    }
}

Output Example

 type: 'TXS_DATA',
  data: {
    blockUnixTime: 1714107255,
    owner: 'TyrZ6SDVQGdMpnYtAgKGocvi1w1mdffhZENf1knyeqy',
    source: 'raydium',
    txHash: '3XtCydTzZPJNGr9qQ83rvkKyGQHMQcUa3QpgBZoz97i3VkRGL3e8UBhM7JUnprwbcgWXeHXST74NeaEE4vjWeEME',
    alias: null,
    isTradeOnBe: false,
    platform: 'YmirFH6wUrtUMUmfRPZE7TcnszDw689YNWYrMgyB55N',
    volumeUSD: 31.569239727896086,
    from: {
      symbol: 'SOL',
      decimals: 9,
      address: 'So11111111111111111111111111111111111111112',
      amount: 219852856,
      type: 'transfer',
      typeSwap: 'from',
      uiAmount: 0.219852856,
      price: null,
      nearestPrice: 143.5925841595439,
      changeAmount: -219852856,
      uiChangeAmount: -0.219852856,
      icon: null
    },
    to: {
      symbol: 'TOM',
      decimals: 9,
      address: '2rJSfgxoWP7h3rw3hDUF7HPToY3exb6FdH9xFBg7TeQk',
      amount: 650244687263,
      type: 'transfer',
      typeSwap: 'to',
      feeInfo: null,
      uiAmount: 650.244687263,
      price: 0.048549784944459676,
      nearestPrice: 0.048420900217275124,
      changeAmount: 650244687263,
      uiChangeAmount: 650.244687263,
      icon: null
    }
  }
}

You can also subscribe to transactions for multiple addresses by using the “complex” query type. You can get updates for maximum 100 addresses at once.
Subscribing to TXS for Multiple Tokens SUBSCRIBE_TXS replaces the existing txs subscription for that connection and message type. If you want to add more tokens to your txs subscription, you must send a new SUBSCRIBE_TXS message whose payload includes the full list of token addresses you want to receive txs updates for— including both tokens you were already subscribed to and the new ones. Example You first send: SUBSCRIBE_TXS for So11111111111111111111111111111111111111112 You will begin receiving: TXS events for So11111111111111111111111111111111111111112 Later, you want to subscribe to tx updates for an additional token: JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN To do this, you must send SUBSCRIBE_TXS again with a payload containing both addresses: SUBSCRIBE_TXS with addresses: [So11111111111111111111111111111111111111112, JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN] Result You continue receiving txs events for So11111111111111111111111111111111111111112 You start receiving txs events for JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN The previous SUBSCRIBE_TXS subscription is overwritten by the new one (now containing both tokens) The following example demonstrates how to subscribe to transactions for either a specific token address or a specific token pair address:

Input

{
    "type": "SUBSCRIBE_TXS",
    "data": {
        "queryType": "complex",
        "query": "address = So11111111111111111111111111111111111111112 OR pairAddress = FmKAfMMnxRMaqG1c4emgA4AhaThi4LQ4m2A12hwoTibb",
				"txsType":"all"
    }
}

{
    "type": "TXS_DATA",
    "data": {
        "blockUnixTime": 1692205532,
        "owner": "EkZStqj9BSwLS19uLDEsErCW6N1HHzvoGg92Ei3YYBNt",
        "source": "marinade",
        "txHash": "3GqVQTaimS2QsprgjTvpV4ArdZGUjoiacDE5Hy3baLapvAXekya7EsNjhWvMVbqdMRaJanwwAd4Bi9h8ag58vK3",
        ...
    }
}

The two WebSocket messages differ in their subscription type (complex vs simple), and as a result, there are key differences in the structure of the resulting TXS_DATA responses.

Request Type Difference

First WebSocket Request (COMPLEX Query)

{
    "type": "SUBSCRIBE_TXS",
    "data": {
        "queryType": "complex",
        "query": "address = 0x539bdE0d7Dbd336b79148AA742883198BBF60342 OR address = 0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f",
				"txsType":"all"
    }
}

Query:

Logical OR statement, tracking multiple addresses.
Returns all transactions involving these addresses, including swap, add liquidity and remove liquidity.

Second WebSocket Request (SIMPLE Query)

{
    "type": "SUBSCRIBE_TXS",
    "data": {
        "queryType": "simple",
        "address": "0x539bdE0d7Dbd336b79148AA742883198BBF60342"
				"txsType":"all"
    }
}

Query:

Tracks only this specific address.
Optimized for this token address being a main asset in the transaction.

Response Structural Differences

Field	COMPLEX Response	SIMPLE response
side	swap	buy / sell
tokenAddress	❌	✅
pricePair	❌	✅
priceMark / tokenPrice	✅	❌

Contextual Interpretation

COMPLEX query is more general and is probably used for monitoring addresses (wallets or token contracts) regardless of their transaction role. It yields raw swap data and doesn’t include enriched metadata like tokenAddress, pricePair, or network.
Example:

{  
    "type": "TXS_DATA",
    "data": {
        "blockUnixTime": 1750298427,
        "owner": "0x22e4668AB0c1eE4A249F3A8A975f2aD780b08444",
        "source": "0xd845f7D4f4DeB9Ff5bCf09D140Ef13718F6f6C71",
        "txHash": "0x5ce5c84cfd3ae78ac6bf7f89b539a9f9aa4210e9ea56a8d495509bdd4dd6dea9",
        "side": "swap",
        "alias": null,
        "isTradeOnBe": false,
        "platform": "0x409De6561Cfc8C14359BeD66cB668b4f33420E73",
        "volumeUSD": 547.9549194582437,
        "from": {
            "address": "0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f",
            "amount": 524114,
            "changeAmount": -524114,
            "decimals": 8,
            "mint": "0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f",
            "name": "Wrapped Bitcoin",
            "nearestPrice": 104533.06339411934,
            "price": 104548.80416440769,
            "symbol": "WBTC",
            "typeSwap": "from",
            "uiAmount": 0.00524114,
            "uiChangeAmount": -0.00524114
        },
        "to": {
            "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
            "amount": 217772242384751600,
            "changeAmount": 217772242384751600,
            "decimals": 18,
            "mint": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
            "name": "WETH",
            "nearestPrice": 2516.183483522836,
            "price": 2516.183483522836,
            "symbol": "WETH",
            "typeSwap": "to",
            "uiAmount": 0.21777224238475162,
            "uiChangeAmount": 0.21777224238475162
        },
        "poolId": "0xd845f7D4f4DeB9Ff5bCf09D140Ef13718F6f6C71"
    }
}

SIMPLE query is specialized for token-level tracking, likely focused on the specific token contract address as the selling/swapping asset. It gives extra fields (like tokenPrice, network, pricePair) that are useful in token-centric analytics. Example:

{
    "type": "TXS_DATA",
    "data": {
        "blockUnixTime": 1750234547,
        "owner": "0xcFbFeA9aE5EF502BB1Cb188993542638b4d26900",
        "source": "0xB7E50106A5bd3Cf21AF210A755F9C8740890A8c9",
        "txHash": "0x6dc1bfd71156e32ef8d8c03b9e9697e7a6446cc5c143c7915c7c6e8e3ccf3f63",
        "side": "sell",
        "tokenAddress": "0x539bdE0d7Dbd336b79148AA742883198BBF60342",
        "alias": null,
        "isTradeOnBe": false,
        "platform": "0xaaaaaaae92Cc1cEeF79a038017889fDd26D23D4d",
        "pricePair": 0.00006240110207123055,
        "volumeUSD": 6.747140220183636,
        "from": {
            "address": "0x539bdE0d7Dbd336b79148AA742883198BBF60342",
            "amount": 42518663000000000000,
            "changeAmount": -42518663000000000000,
            "decimals": 18,
            "mint": "0x539bdE0d7Dbd336b79148AA742883198BBF60342",
            "name": "Magic",
            "nearestPrice": 0.1595716148388752,
            "price": 0.1586865565406804,
            "symbol": "MAGIC",
            "typeSwap": "from",
            "uiAmount": 42.518663000000004,
            "uiChangeAmount": -42.518663000000004
        },
        "to": {
            "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
            "amount": 2653211429795254,
            "changeAmount": 2653211429795254,
            "decimals": 18,
            "mint": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
            "name": "WETH",
            "nearestPrice": 2543.008877624316,
            "price": 2543.008877624316,
            "symbol": "WETH",
            "typeSwap": "to",
            "uiAmount": 0.002653211429795254,
            "uiChangeAmount": 0.002653211429795254
        },
        "priceMark": false,
        "tokenPrice": 0.1586865565406804,
        "network": "arbitrum",
        "poolId": "0xB7E50106A5bd3Cf21AF210A755F9C8740890A8c9"
    }
}

WebSockets

Token/Pair Transactions

Subscribing to Real-Time Token Transaction Updates (SUBSCRIBE_TXS)

Code Example

Input

Output Example

Input

Output Example

Input

Request Type Difference

Response Structural Differences

Contextual Interpretation

​Subscribing to Real-Time Token Transaction Updates (SUBSCRIBE_TXS)

​Code Example

​1 - Subscribe Token Transactions

​Input

​Output Example

​2 - Subscribe Pair Transactions

​Input

​Output Example

​3 - Subscribe to Multiple Addresses (Limit 100)

​Input

​Request Type Difference

​Response Structural Differences

​Contextual Interpretation

Subscribing to Real-Time Token Transaction Updates (SUBSCRIBE_TXS)

Code Example

1 - Subscribe Token Transactions

Input

Output Example

2 - Subscribe Pair Transactions

Input

Output Example

3 - Subscribe to Multiple Addresses (Limit 100)

Input

Request Type Difference

Response Structural Differences

Contextual Interpretation