WebSockets

Data Engine's live data feeds can be accessed in a language agnostic manner using the Relayer via the WebSocket Protocol.

Overview

The process to access the Data Feeds is pretty straight forward using the WebSocket Protocol. Following is the necessary information for setting up a connection.

WS_ENDPOINT = wss://feeds.yggdrasilprotocol.io
PING_INTERVAL = 30s
PING_TIMEOUT = 60s

General Information

IP Limits

• Do not frequently connect and disconnect the connection.

• Do not start more than 100 connections in 5 minutes.

Arguments

• Do not include more than 100 data feedIDs in the connection request.

• Try to spread high volume data feeds like SPOT:BTC_USDT, SPOT:ETH_USDT across different connections to optimize.

Main Endpoint

WS /v1/ws

This is the default endpoint to receive all the required updates from the Relayer.

Headers

Name	Value
Content-Type	application/json

Query Params

Key	Value	Description
feedIDs	SPOT:BTC_USDT,NASDAQ:AAPL_USD	Comma-Separated List of Data Feeds

Response

Stream

// subscription status
{
  "event": "subscribe-status",
  "success": [
    {
      "feedID": "SPOT:BTC_USDT",
      "type": "CRYPTO"
    },
    {
      "feedID": "NASDAQ:AAPL_USD",
      "type": "STOCKS"
    }
  ],
  "error": null
}

// data feed response
{"event": "price", "p":"56645.12","symbol":"SPOT:BTC_USDT","t":1719178484}
{"event": "price", "p":"201.94","symbol":"NASDAQ:AAPL_USD","t":1719182971}
{"event": "price", "p":"56670.70","symbol":"SPOT:BTC_USDT","t":1719183123}

Persisting Connection

Your connection is required to send a ping message after every PING_INTERVAL to ensure that your connection is not dropped by the relayer. This will let the relayer know if any connection has become inactive or not. You can expect the Relayer to send back a PONG Frame but do not rely your application logic on this.

Using Standard PING Frames

The recommended way to achieve this is by sending the standard PING Frame as described in the WebSoscket RFC supported by your language's popular WebSocket framework.

ws.ping()    // sent after every PING_INTERVAL seconds

Using String Message

This is not the recommended way of setting-up connection persistence. We recommend using the standard byte frames as supported in the WS RFC as they're cheap & fast.

Likewise if you're to send ping messages in through a library that lacks support for sending byte frames over the WebSocket connection as seen across the WebSocket API in the current Web Standard. You can then simply proceed by sending over PING as a string message.

ws.send("PING")    // sent after every PING_INTERVAL seconds

Response

Subscription Response

This is the first message you receive when you set-up a WebSocket connection. This contains information about the success & failure of the data feeds you're subscribing to.

You receive a message with event type subscribe-status whenever at least one of the requested data feedIDs is correct & available with the relayer.

You receive a subscribe-failed message message when all of the requested data feedIDs are invalid or the connection was dropped or couldn't be set-up due to some external reason. After this message is received, the connection is closed off.

// example-1: subscription status
{
  "event": "subscribe-status",
  "success": [
    {
      "feedID": "SPOT:BTC_USDT",
      "type": "CRYPTO"
    }
  ],
  "error": null
}

// example-2: subscription-status
{
  "event": "subscribe-status",
  "success": [
    {
      "feedID": "SPOT:BTC_USDT",
      "type": "CRYPTO"
    }
  ],
  "error": [
    {
      "feedID": "SPOT:ABC_USDT",
      "type": "INVALID"
    }
  ]
}

// example-3: subscribe-failed
{
  "event": "subscribe-failed",
  "success": null,
  "error": null
}

Price Response

For the supported data feeds you receive a price event that provides you with the live price at the current timestamp.

{
  "event": "price",
  "p": "56645.12",
  "symbol": "SPOT:BTC_USDT",
  "t": 1719178484
}

Example

To connect to the Relayer through the WS API, you need to set-up a connection to the WS URL. Once connected, you will be able to receive the requested updates.

You can install websocat to easily connect with the Relayer WS API without any overhead.

# Example-1
$ websocat wss://feeds.yggdrasilprotocol.io/v1/ws?feedIDs=SPOT:BTC_USDT --ping-interval=30

# Example-2
$ websocat wss://feeds.yggdrasilprotocol.io/v1/ws?feedIDs=NASDAQ:AAPL,ARB:WETH_USDC --ping-interval=30