Birdeye Real-Time WebSocket Documentation

Introduction

The Birdeye Real-Time WebSocket API provides a way to receive real-time updates for various cryptocurrency-related events and data, such as price changes, transaction updates, and more. This documentation outlines how to connect to the Birdeye WebSocket API, subscribe to specific events, and receive real-time data updates.

Websocket is only available to users with Business Package subscription.

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: https://github.com/TheNang2710/bds-public/blob/main/new-pair-simple.js

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:

• 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.

The WebSocket also supports unsubscription with the following message values:

• UNSUBSCRIBE_NEW_PAIR
• UNSUBSCRIBE_PRICE
• UNSUBSCRIBE_TOKEN_NEW_LISTING
• UNSUBSCRIBE_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 typically sent and received in JSON format. Birdeye WebSocket messages consist of a type field specifying the type of subscription (e.g., "SUBSCRIBE_PRICE") and a data field containing relevant subscription details.

Real-Time Data

Once subscribed, you will start receiving real-time data updates based on your subscriptions. The received data will be in JSON format and will contain the relevant information for the subscribed event.

Error Handling

The WebSocket connection may encounter errors or issues. You should handle error events and connection closure events appropriately to ensure smooth operation.

Close Connection

When you're done receiving updates or want to close the WebSocket connection, you can gracefully close the connection.

Security Considerations

Ensure that you keep your API key secure and do not expose it publicly in your code or any public repositories.

Supported Events/Topics

The Birdeye WebSocket API supports various event types such as "SUBSCRIBE_PRICE" and "SUBSCRIBE_TXS." Refer to the Birdeye API documentation for a complete list of supported events and their details.