Skip to main content

Real-Time Token Event Filtering Guide

What you'll learn
  • How to filter token events in real-time
  • Implement basic and advanced filtering strategies
  • Combine multiple filters effectively

Introduction​

This guide explains all available filtering options for token events. You can use these filters across any subscription type (Deployment, Trade, or Completed events).

Access Requirements

Available Filters​

interface EventFilters {
    // Basic Filters - Currently Active
    mint?: string;          // Filter by token's mint address
    deployer?: string;      // Filter by deployer's wallet address
    name?: string;          // Filter by token name
    symbol?: string;        // Filter by token symbol

    // Advanced Filters - Coming Soon
    count?: number;         // [UPCOMING] Filter for similar tokens launched in short timeframe
    narrative?: string;     // [UPCOMING] Filter by token narrative/theme
    tweet?: string;         // [UPCOMING] Filter by tweet URL

}

Basic Filter Usage​

1. Mint Address Filter​

Track specific tokens by their mint address:

const subscribeMessage = {
    type: "Subscribe",
    payload: {
        sub_type: "Deployment",
        filter: {
            mint: "BbB3bB7bB2bB9bB4bB8bB1bBb5bB2bB6bB3bB9bB4bB"
        }
    }
};

2. Deployer Filter​

Monitor deployments from specific wallets:

const subscribeMessage = {
  type: "Subscribe",
  payload: {
    sub_type: "Deployment",
    filter: {
      deployer: "AaA2aA5aA8aA4aA7aA1aA9aAa3aA6aA2aA8aA5aA1a",
    },
  },
};

3. Name Filter​

Track tokens by name pattern:

const subscribeMessage = {
  type: "Subscribe",
  payload: {
    sub_type: "Deployment",
    filter: {
      name: "AI", // Will match tokens containing "AI"
    },
  },
};

4. Symbol Filter​

Monitor specific token symbols:

const subscribeMessage = {
  type: "Subscribe",
  payload: {
    sub_type: "Deployment",
    filter: {
      symbol: "BTC", // Will match tokens with "BTC" in symbol
    },
  },
};

Combining Filters​

You can combine multiple active filters for more precise monitoring:

const subscribeMessage = {
  type: "Subscribe",
  payload: {
    sub_type: "Deployment",
    filter: {
      name: "Bitcoin",
      symbol: "BTC",
      deployer: "AaA2aA5aA8aA4aA7aA1aA9aAa3aA6aA2aA8aA5aA1a",
    },
  },
};

Complete Example Implementation​

import WebSocket from 'ws';

class TokenMonitor {
private ws: WebSocket;

    constructor(apiKey: string) {
        this.ws = new WebSocket('wss://api.callstaticrpc.com/pumpfun/v1/streams', {
            headers: { Authorization: `Bearer ${apiKey}` }
        });

        this.setupEventHandlers();
    }

    private setupEventHandlers() {
        this.ws.on('open', () => {
            console.log('Connected! Monitoring tokens...');

            const subscribeMessage = {
                type: "Subscribe",
                payload: {
                    sub_type: "Deployment",
                    filter: {
                        name: "Bitcoin",
                        symbol: "BTC"
                    }
                }
            };

            this.ws.send(JSON.stringify(subscribeMessage));
        });

        this.ws.on('message', (data: string) => {
            try {
                const message = JSON.parse(data);
                if (message.data) {
                    console.log('\n🔔 Token Deployment Detected!');
                    console.log(`Name: ${message.data.name}`);
                    console.log(`Symbol: ${message.data.symbol}`);
                    console.log(`Deployer: ${message.data.deployer}`);
                    console.log(`Mint: ${message.data.mint}`);

                    if (message.data.twitter) {
                        console.log(`Twitter: ${message.data.twitter}`);
                    }
                    if (message.data.telegram) {
                        console.log(`Telegram: ${message.data.telegram}`);
                    }
                    if (message.data.website) {
                        console.log(`Website: ${message.data.website}`);
                    }
                }
            } catch (error) {
                console.error('Error processing message:', error);
            }
        });

        this.ws.on('error', (error) => {
            console.error('WebSocket error:', error);
        });

        this.ws.on('close', () => {
            console.log('Connection closed. Attempting to reconnect...');
            setTimeout(() => this.setupEventHandlers(), 5000);
        });
    }

}

Error Handling​

The WebSocket API returns standard error messages:

try {
    ws.send(JSON.stringify(subscribeMessage));
} catch (error) {
    if (error.message.includes('Authentication')) {
        console.error('Invalid API key');
    } else if (error.message.includes('Invalid filter')) {
        console.error('Invalid filter parameters');
    } else {
        console.error('Unknown error:', error);
    }
}

Best Practices​

  1. Filter Precision

    • Use specific filters to reduce noise
    • Combine filters for better accuracy
    • Regularly review and update filters

  2. Connection Management

    • Implement reconnection logic
    • Handle connection errors gracefully
    • Monitor connection health

  3. Data Processing

    • Validate incoming messages
    • Handle missing fields gracefully
    • Log relevant information

Upcoming Features​

Future Enhancements

The following filters are coming soon:

  1. Count Filter

    • Track similar token launches in short timeframes
    • Useful for detecting trending token patterns

  2. Narrative Filter

    • Filter tokens by theme or category
    • Match token metadata against specific narratives

  3. Tweet Filter

    • Monitor tokens related to specific tweets
    • Filter by tweet URL instead of content

Next Steps​

Now that you understand token event filtering, you can:

  1. 🔍 Set up basic token monitoring
  2. 📊 Track specific deployer activity
  3. 🎯 Monitor tokens by name or symbol
  4. ⚡ Implement real-time alerts
Need Help?

For additional support: