Our goal at Relay is to make multichain payments feel instant. Even when transactions confirm quickly onchain, API polling latency can degrade user experience. Connecting your app to Relay Websockets means your users get streamed updates of the status of their Relays for a speedier experience.

​
Relay Status Websockets

Relay Status Websockets specifically stream transaction statuses for both cross and same-chain status, though the stages differ slightly.
statusindication
waitingwaiting for origin chain deposit
pendingorigin chain deposit confirmed, fill pending submission
submittedfill submitted on destination chain
successfill succeeded
delayedfill delayed, still processing
failurefill failed
refundrefunded

​
Integrating Relay Websockets

Today Relay Websockets are in Beta, and we are rolling them out to priority customers on an as-needed basis. Please reach out if you are interested in integrating them into your product.

​
Events

EventTagsEvent Description
request.status.updatedidTriggered status of the request changes.

​
Authentication

The Websocket Service is available for anyone with strict rate limits. For customers with an API key it can be used for authentication for higher rate limits, the service is available at the following URL wss://ws.relay.link To connect using an API key, provide your API key as a query param in the connection url: 
const wss = new ws(`wss://ws.reservoir.tools?apiKey=${YOUR_API_KEY}`);

​
Interacting with the Websocket

Before sending any messages over the Websocket, wait for a ready message back from the server. The message looks like: JSON 
{
  // The type of operation
	"type": "connection",
  // The status of the operation
	"status": "ready",
	"data": {
    // Your socket id for debugging purposes
		"id": "9nqpzwmwh86"
	}
}

​
Subscribing with Filters

Below is an example on how to subscribe to a websocket using filters. JSON 
{
	"type": "subscribe",
	"event": "request.status.updated",
    "filters": {
        "id": "0xae0827617d4ae75b406969971c2d4df9a8e8d819ff0f09581fb45ca123fcc7a0"
    }
}

​
Subscription Response

JSON 
{
	"type": "subscribe",
	"status": "success",
	"data": {
		"event": "equest.status.updated",
		"filters": {
			"id": "0xae0827617d4ae75b406969971c2d4df9a8e8d819ff0f09581fb45ca123fcc7a0"
		}
	}
}

​
Unsubscribing

JSON 
{
	"type": "unsubscribe",
	"event": "request.status.updated",
  "filters": {
      "id": "0xae0827617d4ae75b406969971c2d4df9a8e8d819ff0f09581fb45ca123fcc7a0"
  }
}

​
Unsubscribe Response

JSON 
{
	"type": "unsubscribe",
	"status": "success",
	"data": {
		"event": "request.status.updated"
	}
}

​
Connecting Examples

​
Javascript

npm install ws
JavaScript 
const ws = require("ws");

const YOUR_API_KEY = "";

const wss = new ws(`wss://ws.relay.link?apiKey=${YOUR_API_KEY}`);

wss.on("open", function open() {
  console.log("Connected to Relay");

  wss.on("message", function incoming(data) {
    console.log("Message received: ", JSON.stringify(JSON.parse(data)));

    // When the connection is ready, subscribe to the top-bids event
    if (JSON.parse(data).status === "ready") {
      console.log("Subscribing");
      wss.send(
        JSON.stringify({
          type: "subscribe",
          event: "request.status.updated",
          filters: {
            id: "0xae0827617d4ae75b406969971c2d4df9a8e8d819ff0f09581fb45ca123fcc7a0",
          },
        })
      );

      // To unsubscribe, send the following message
      // wss.send(
      //     JSON.stringify({
      //         type: 'unsubscribe',
      //         event: 'request.status.updated',
      //     }),
      // );
    }
  });
});
¸