Skip to content

Instantly share code, notes, and snippets.

@Klaudioz

Klaudioz/ws_birdeye.md

Created October 13, 2024 12:01
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Klaudioz/67bbc2430528615eef34447486ec36b0 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Klaudioz/67bbc2430528615eef34447486ec36b0 to your computer and use it in GitHub Desktop.
Download ZIP
Birdeye Real-Time WebSocket Documentation
Raw
ws_birdeye.md

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.

Note: Websocket is only available to users with Business Package subscription.

Code Example

Checkout this Github file for an example: websocket_example.js

WebSocket URL:

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

Header

Key Value
Origin ws://public-api.birdeye.so
Sec-WebSocket-Origin ws://public-api.birdeye.so
Sec-WebSocket-Protocol echo-protocol

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:

{
   "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.

SUBSCRIBE_PRICE

Subscribing to Real-Time Price Updates (SUBSCRIBE_PRICE)

The "SUBSCRIBE_PRICE" event allows you to receive real-time updates about price changes for tokens or token pairs. You can subscribe to price updates for individual tokens, token pairs, or a combination of both. This subscription is useful for tracking price movements and trends on the Birdeye platform.

You can use this Websocket to get real time price updates of following objects:

  • Token Price
  • Pair (Market Price)
  • Multiple Tokens/Pairs Price

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

1 - Subscribe Token Price (OHLCV)

To receive real-time updates about price changes for a specific token in the form of OHLCV (Open, High, Low, Close, Volume) data, you can use the following subscription message format:

Input

{
    "type": "SUBSCRIBE_PRICE",
    "data": {
        "queryType": "simple",
        "chartType": "1m",
        "address": "So11111111111111111111111111111111111111112",
        "currency": "usd"
    }
}

Output Example

{
  "type": "PRICE_DATA",
  "data": {
    "o": 24.586420063533236,
    "h": 24.586420063533236,
    "l": 24.586420063533236,
    "c": 24.586420063533236,
    "eventType": "ohlcv",
    "type": "1m",
    "unixTime": 1675506000,
    "v": 32.928421816,
    "symbol": "SOL",
    "address": "So11111111111111111111111111111111111111112"
  }
}

2 - Subscribe Pair Price (OHLCV)

To receive real-time updates about price changes for a specific token pair in the form of OHLCV (Open, High, Low, Close, Volume) data, you can use the following subscription message format:

Input

{
    "type": "SUBSCRIBE_PRICE",
    "data": {
        "queryType": "simple",
        "chartType": "1m",
        "address": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm",
        "currency": "pair"
    }
}

Output Example

{
  "type": "PRICE_DATA",
  "data": {
    "o": 24.552070604303985,
    "h": 24.555908821439385,
    "l": 24.552070604303985,
    "c": 24.555908821439385,
    "eventType": "ohlcv",
    "type": "1m",
    "unixTime": 1675506120,
    "v": 51.838008518,
    "symbol": "SOL-USDC",
    "address": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm"
  }
}

3 - Subscribe to Multiple Addresses Price (OHLCV) - Limit 100

You can also subscribe to price changes for multiple addresses by using the "complex" query type.

You can get updates for maximum 100 addresses at once.

The following example demonstrates how to subscribe to price changes for specific token addresses or token pair addresses:

Input

{
    "type": "SUBSCRIBE_PRICE",
    "data": {
        "queryType": "complex",
        "query": "(address = So11111111111111111111111111111111111111112 AND chartType = 1m AND currency = usd) OR (address = 7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm AND chartType = 3m AND currency = pair)"
    }
}

Output Example (First Subscription)

{
  "type": "PRICE_DATA",
  "data": {
    "o": 24.567048925168383,
    "h": 24.56815678411483,
    "l": 24.460703007175056,
    "c": 24.460884,
    "eventType": "ohlcv",
    "type": "1m",
    "unixTime": 1675506240,
    "v": 69.46933086099999,
    "symbol": "SOL",
    "address": "So11111111111111111111111111111111111111112"
  }
}

Output Example (Second Subscription)

{
  "type": "PRICE_DATA",
  "data": {
    "o": 24.544784561403507,
    "h": 24.544784561403507,
    "l": 24.543643515795363,
    "c": 24.543643515795363,
    "eventType": "ohlcv",
    "type": "3m",
    "unixTime": 1675506240,
    "v": 18.760775588,
    "symbol": "SOL-USDC",
    "address": "7qbRF6YsyGuLUVs6Y1q64bdVrfe4ZcUUz1JRdoVNUJnm"
  }
}

Please note that the provided examples in the output sections are truncated for brevity. The actual output may contain additional fields and information. Adapt the subscription messages according to your requirements and process the received real-time data accordingly.

SUBSCRIBE_TXS

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, transfers, and other relevant transactions on the Birdeye platform.

You can use this Websocket to get real time transaction updates of following objects:

  • Transactions (trades) of a token
  • Transactions (trades) of a pair/market
  • Transactions (trades) of multiple Tokens/Pairs

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

1 - Subscribe Token Transactions

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": "So11111111111111111111111111111111111111112"
    }
}

Output Example

{
  "blockUnixTime": 1675620000,
  "owner": "MeowujaCA1FGaA7hna2ezUXLbrj36qZi4hGx94xNQLo",
  "source": "raydium",
  "txHash": "5zXXgqYaXe6Dn6xkVSzui5rTTz1f8dWmFkxNXTLYVu8H3FDgf2xAxtWQz7XYpcZV21mhncrkkfgGBXrSP9KKHpCK",
  "side": "buy",
  "tokenAddress": "So11111111111111111111111111111111111111112",
  "alias": null,
  "isTradeOnBe": false,
  "platform": "slowprotocol",
  "volumeUSD": 0.05237464631298352,
  "from": {
    "symbol": "SLOW",
    "decimals": 5,
    ...
  },
  "to": {
    "symbol": "SOL",
    "decimals": 9,
    ...
  },
  "tokenPrice": null
}

2 - Subscribe Pair Transactions

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"
    }
}

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
    }
  }
}

3 - Subscribe to Multiple Addresses (Limit 100)

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.

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"
    }
}

Output

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

SUBSCRIBE_TOKEN_NEW_LISTING

Subscribing to Real-Time token new listing (SUBSCRIBE_TOKEN_NEW_LISTING)

The "SUBSCRIBE_TOKEN_NEW_LISTING" event allows you to receive real-time updates about new token listings. This subscription is useful for tracking new tokens being added on a requested blockchain.

The instructions for each type of objects are described below.

WebSocket URL:

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

Header

Key Value
Origin ws://public-api.birdeye.so
Sec-WebSocket-Origin ws://public-api.birdeye.so
Sec-WebSocket-Protocol echo-protocol

Message

{
    "type": "SUBSCRIBE_TOKEN_NEW_LISTING"
}

Output Example

{
    "type": "TOKEN_NEW_LISTING_DATA",
    "data": {
        "address": "BkQfwVktcbWmxePJN5weHWJZgReWbiz8gzTdFa2w7Uds",
        "decimals": 6,
        "name": "Worker Cat",
        "symbol": "$MCDCAT",
        "liquidity": "12120.155172280874",
        "liquidityAddedAt": 1720155863
    }
}

Response Parameters:

Key Data Type Details Example
address string The token address. "BkQfwVktcbWmxePJN5weHWJZgReWbiz8gzTdFa2w7Uds"
decimals integer The number of decimal places for the token. 6
name string The name of the token. "Worker Cat"
symbol string The symbol of the token. "$MCDCAT"
liquidity string The current liquidity of the token. "12120.155172280874"
liquidityAddedAt integer The Unix timestamp when liquidity was added. 1720155863

SUBSCRIBE_NEW_PAIR

Subscribing to Real-Time New Pairs (SUBSCRIBE_SUBSCRIBE_NEW_PAIR)

The "SUBSCRIBE_NEW_PAIR" event allows you to receive real-time updates about new pairs. This subscription is useful for tracking new tokens being added on a requested blockchain. However, please note that the DEX Openbook pairs are not supported. Currently, this feature supports the Solana and EVM chains.

The instructions for each type of objects are described below.

WebSocket URL:

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

Header

Key Value
Origin ws://public-api.birdeye.so
Sec-WebSocket-Origin ws://public-api.birdeye.so
Sec-WebSocket-Protocol echo-protocol

Message

{
    "type": "SUBSCRIBE_NEW_PAIR"
}

Output Example

{
    "type": "NEW_PAIR_DATA",
    "data": {
        "address": "CXV4S8CxSppJeGzMFv8YQjsGZJif8d1Fqz9EtJRovmJY",
        "name": "$JESUSPUMP-SOL",
        "source": "pump_dot_fun",
        "base": {
            "address": "AoMBAxc82xinKTnEBGvuJaFb7occsyyBD6GmELrypump",
            "name": "JESUS PUMP",
            "symbol": "$JESUSPUMP",
            "decimals": 6
        },
        "quote": {
            "address": "So11111111111111111111111111111111111111112",
            "name": "Wrapped SOL",
            "symbol": "SOL",
            "decimals": 9
        },
        "txHash": "3CzXpuUJV9KryVDMN5nFAqH87TfueWG6sUiksbf3Akh9eqGNJW1CJtYbrELJixXC77Dyutz8CfT3eP1uJ3LP3iy5",
        "blockTime": 1720156781
    }
}

Response Parameters:

Key Data Type Details Example
type string The type of the response data. "NEW_PAIR_DATA"
data object The main data object containing details of the new trading pair.
data.address string The address of the new trading pair. "CXV4S8CxSppJeGzMFv8YQjsGZJif8d1Fqz9EtJRovmJY"
data.name string The name of the trading pair. "$JESUSPUMP-SOL"
data.source string The source or platform where the trading pair is listed. "pump_dot_fun"
data.base object The base token object containing details of the base token.
data.base.address string The address of the base token. "AoMBAxc82xinKTnEBGvuJaFb7occsyyBD6GmELrypump"
data.base.name string The name of the base token. "JESUS PUMP"
data.base.symbol string The symbol of the base token. "$JESUSPUMP"
data.base.decimals integer The number of decimal places for the base token. 6
data.quote object The quote token object containing details of the quote token.
data.quote.address string The address of the quote token. "So11111111111111111111111111111111111111112"
data.quote.name string The name of the quote token. "Wrapped SOL"
data.quote.symbol string The symbol of the quote token. "SOL"
data.quote.decimals integer The number of decimal places for the quote token. 9
data.txHash string The transaction hash for the creation of the trading pair. "3CzXpuUJV9KryVDMN5nFAqH87TfueWG6sUiksbf3Akh9eqGNJW1CJtYbrELJixXC77Dyutz8CfT3eP1uJ3LP3iy5"
data.blockTime integer The Unix timestamp when the trading pair was created. 1720156781

WebSocket metrics

Metric Description
Data Types Over Time The number of subscriptions for each WebSocket type used over time, representing the data types at the moment the WebSocket connection is initiated, which is also when the user subscribes to that data type.
Data Size (byte) The number of bytes received, helping you track the data volume handled by each subscription type.
CU Usage (CU) The metric shows your current compute usage, calculated by multiplying the Compute Unit Per Byte (CUPB) by the number of bytes received. With this metric, you can better understand your compute usage and optimize resource allocation.
Active Connections The line chart shows the number of total unique connections at any given time, providing a clearer understanding of the connection load on your system.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment