Caduceus WebSocket Endpoints

8 min

WebSocket is a bidirectional communication protocol based on TCP that standardises communication between a client and a server, allowing for both parties to request data from one another. In contrast, a unidirectional protocol like HTTP only allows for the client to request data from the server. The JSON RPC endpoint that you would use to connect to caduceus is an example of a unidirectional protocol using HTTP.

A WebSocket connection between a client and a server can stay open as long as the parties wish it to maintain the connection, allowing for continuous communication. With HTTP, each connection begins when the client makes a request and ends the connection when the request is fulfilled.

WebSockets may be superior for Web3 dApp notifications because they enable real-time notifications for critical events continuously compared to requiring individual requests. So if your D'App needs to monitor the chain and react to certain events then this is the right place to look for.

Caduceus WebSocket Endpoint

For Mainnet the websocket endpoint URL is wss://mainnet.ws.caduceus.foundation

wss://mainnet.ws.caduceus.foundation

Currently we do not support websockets for the galaxy testnet

You can either embed this in your Web3 provider like ethers.js or use a cli tool like wscat and call it directly from your terminal. Let us show you how you do this:

Using WSCAT on the Terminal

on Mac

First you will need to install wscat. You can do so using npm.

npm i -g wscat

Then you need to you can call

> wscat -c "wss://mainnet.ws.caduceus.foundation"
# This will open up a connection and it will show the following message if
# successfully connected
Connected (press CTRL+C to quit)
>

Now enter the json payload to indicate the event that you want to listen to a specific event:

> wscat -c "wss://mainnet.ws.caduceus.foundation"
# This will open up a connection and it will show the following message if
# successfully connected
Connected (press CTRL+C to quit)
> { "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }
# this will return a json payload, where the result 0x6daff287831915b5c075500ca0ba5ce5 is the subscription id. 
< {"jsonrpc":"2.0","result":"0x6daff287831915b5c075500ca0ba5ce5","id":1}
# you will now start to receive block data for every new block that is mined.

For more information about the eth specification then check out our eth_subscribe documentation

eth_subscribe

Ethers.js

Ethers provides a websocket provider so that you can listen to your scripts in your javascript or your nodejs application.

import { ethers } from 'ethers';
// the caduceus mainnet websocket url
const url = 'wss://mainnet.ws.caduceus.foundation';
// Currently there is no galaxy testnet websocket url

// this is a typescript script that can be run by doing `ts-node <insert-file-path-here>`
const init = function () {
  const customWsProvider = new ethers.providers.WebSocketProvider(url);
  console.log('loading');

  // listens to the latest blocks and prints the number of transactions for each block
  customWsProvider.on('block', (res: any, err: any) => {
    console.log('block', res);
    customWsProvider.getBlock(res).then(function (fullBlock) {
      console.log(`${fullBlock.transactions.length} transactions in block ${res}`);
    });
  });

  // listens to the Wrap CMP contract events
  const eventFilter = {
    address: '0x1fcba3cb797465f38839f48ca7c9cda9d9aac28b',
  };
  customWsProvider.on(eventFilter, (res: any, err: any) => {
    console.log('logs of wrap cmp', res);
  });

  // logs any potential errors
  customWsProvider._websocket.on('error', async () => {
    console.log(`Unable to connect retrying in 3s...`);
    setTimeout(init, 3000);
  });

  // reopens connection if the connection closes
  customWsProvider._websocket.on('close', async (code: any) => {
    console.log(`Connection lost with code ${code}! Attempting reconnect in 3s...`);
    customWsProvider._websocket.terminate();
    setTimeout(init, 3000);
  });
};

init();

You can run this script by doing:

ts-node ./caduceus-websockets.ts

You need to have ts-node installed and point to the name of the file. In our case we named our file caduceus-websockets.ts.

Remeber to check the full documentation for eth_subscribe here: eth_subscribe