Birdeye Real-Time WebSocket Documentation

Introduction

The Birdeye Real-Time WebSocket provides real-time updates for cryptocurrency-related events, including price changes, transactions, OHLCV data, and wallet activity. This documentation outlines how to connect, subscribe to events, and receive live data updates.

Connection Limits

Each WebSocket connection supports:

• Price, Transactions, and OHLCV: Up to 100 tokens per connection
• Wallet Tracking: 1 address per connection

WebSocket access is available for Business Package subscribers, which includes 500 concurrent connections by default. For higher limits, consider upgrading to the Enterprise Package for more concurrent connections.

Code Example

Checkout this Github file for an example: https://github.com/birdeye-so/tradingview-example-js-api/blob/main/websocket_example.js#L62-L65

Sample for new-pair on javascript https://github.com/TheNang2710/bds-public/blob/main/new-pair-simple.js

Sample code for ohlcv on Go https://github.com/TheNang2710/bds-public/blob/main/go/ws_price.go

WebSocket URL:

wss://public-api.birdeye.so/socket/solana?x-api-key=YOUR-API-KEY

Header

Note:

• Replace <chain> with the desired blockchain identifier (e.g., solana for the Solana blockchain, ethereum for the Ethereum blockchain) and <api_key> with your Birdeye API key.
• Add echo-protocol to your request header.

Subscription and Unsubscription

To receive real-time updates, you need to subscribe to specific events using subscription messages. The example code above demonstrates how to send a subscription message to receive price updates for a specific currency pair.

Supported WebSocket Events

Birdeye Real-Time WebSocket supports the following subscription types:

Subscription Events

• SUBSCRIBE_PRICE: Subscribe to receive real-time price updates for tokens or token pairs.
• SUBSCRIBE_TXS: Subscribe to receive real-time transaction updates for tokens or token pairs.
• SUBSCRIBE_TOKEN_NEW_LISTING: Subscribe to real-time updates about new token listings.
• SUBSCRIBE_NEW_PAIR: Subscribe to receive real-time updates about new pairs.
• SUBSCRIBE_LARGE_TRADE_TXS: Subscribe to large trade transactions filtered by specified volume thresholds in USD.
• SUBSCRIBE_WALLET_TXS: Subscribe to real-time updates for transactions involving a specific wallet address, useful for tracking all token transactions related to a provided address.

Unsubscription Events

The WebSocket also supports unsubscription with the following message values:

• UNSUBSCRIBE_NEW_PAIR
• UNSUBSCRIBE_PRICE
• UNSUBSCRIBE_TOKEN_NEW_LISTING
• UNSUBSCRIBE_TXS
• UNSUBSCRIBE_WALLET_TXS

For example:

msg = {
   type: "UNSUBSCRIBE_TXS"
}

Connection Instructions

To establish a WebSocket connection to the Birdeye Real-Time API, you can use various WebSocket client libraries available for different programming languages.

Here's an example using Node.js:

const WebSocketClient = require('websocket').client;
const util = require("util");

const client = new WebSocketClient();

client.on('connectFailed', function (error) {
    console.log('Connect Error: ' + error.toString());
});

client.on('connect', function (connection) {
    console.log('WebSocket Client Connected');

    connection.on('error', function (error) {
        console.log("Connection Error: " + error.toString());
    });

    connection.on('close', function () {
        console.log('WebSocket Connection Closed');
    });

    connection.on('message', function (message) {
        if (message.type === 'utf8') {
            console.log("Received: '" + message.utf8Data + "'");
            // Process received data here
        }
    });

    // Send subscription message here
    const subscriptionMsg = {
        type: "SUBSCRIBE_PRICE",
        data: {
            chartType: "1m",
            currency: "pair",
            address: "FmKAfMMnxRMaqG1c4emgA4AhaThi4LQ4m2A12hwoTibb"
        }
    };

    connection.send(JSON.stringify(subscriptionMsg));
});

// Connect to Birdeye WebSocket
client.connect(util.format('wss://public-api.birdeye.so/socket/<chain>?x-api-key=<api_key>'), 'echo-protocol', "https://birdeye.so");

Message Format

WebSocket messages are exchanged in JSON format, consisting of:

• type: Specifies the subscription type (e.g., "SUBSCRIBE_PRICE").
• data: Contains the relevant subscription details.

Real-Time Data

Once subscribed, real-time updates are received in JSON format, containing relevant information based on the subscribed event. The structure of the response varies depending on the event type.

Error Handling

WebSocket connections may encounter errors due to network instability, API limits, or invalid requests. To ensure smooth operation:

• Monitor error events and handle them gracefully.
• Implement automatic reconnection in case of connection failures.

Closing & Reconnecting

To properly close a WebSocket connection, ensure a graceful shutdown. If the connection is lost unexpectedly, implement a reconnection mechanism to restore subscriptions automatically.

Recommended reconnection strategy:

• Use exponential backoff to manage reconnection attempts.
• Verify network connectivity before retrying.
• Re-subscribe to previous events upon reconnection.

Security Considerations

• Keep API keys secure and avoid exposing them in public repositories or front-end code.
• Use environment variables to store sensitive credentials.
• Monitor WebSocket usage to detect unauthorized access.