WebSockets (Beta)

We recommend the centrifuge websocket client side libraries below:

centrifuge-js – for a browser, NodeJS and React Native
centrifuge-go - for Go language
centrifuge-mobile - for iOS/Android with centrifuge-go as basis and gomobile
centrifuge-dart - for Dart and Flutter
centrifuge-swift – for native iOS development
centrifuge-java – for native Android development and general Java

Non-centrifuge clients connect to separate endpoints specified in each section.

The supported networks are:

Mainnet
Testnet

Simple js example using centrifuge client:

    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script type="text/javascript" src="https://cdn.jsdelivr.net/gh/centrifugal/centrifuge-js@latest/dist/centrifuge.min.js"></script>
    <script type="text/javascript">
    $(function () {
        const centrifuge = new Centrifuge('wss://socket.whatsonchain.com/blockheaders');

        centrifuge.on('publish', function(message) {
              console.log('Data: '+   JSON.stringify(message.data, null, 2))
        });

        centrifuge.on('disconnect', function(ctx){
            console.log('Disconnected: ' + ctx.reason + (ctx.reconnect?", will try to reconnect":", won't try to reconnect"));
        });

        centrifuge.on('connect', function(ctx){
            console.log('Connected with client ID ' + ctx.client + ' over ' + ctx.transport );
        });

        centrifuge.connect();
    });
    </script>

Simple js example using websocket API client

    <script type="text/javascript">
        window.addEventListener('load', function() {
            let clientID;
            let reconnect = true;
            let numFailures = 0;

            function connect() {
                // Subscribe to multiple channels
                const ws = new WebSocket('wss://socket.whatsonchain.com/websocket?channels=woc:chainStats');
                ws.onopen = function(e) {
                    numFailures = 0;
                    console.log("websocket: connection open",e);
                    // This is required to trigger connect on server side.
                 ws.send(JSON.stringify({}));
                };

                ws.onerror = function(e) {
                    numFailures++;
                    console.log("websocket: connection error: ", e);
                };

                ws.onclose = function (e) {
                    if (!reconnect) {
                        return;
                    }
                    setTimeout(function () {
                        console.log("websocket: connection reconnecting");
                        connect();
                    }, Math.min(numFailures * 1000, 20000));
                }

                ws.onmessage = function(e) {
                    console.log("websocket: new message");
                    processData(e.data);
                };
            }

            connect();

            function processData(rawData) {
                if (rawData.length === 0) {
                    console.log("--> ping");
                    return
                }
                console.log("--> " + rawData);
                const data = JSON.parse(rawData);
                const pushType = data.type || 0;
                switch (pushType) {
                    case 0:
                        console.log("new data from a channel " + data.channel + ": " + JSON.stringify(data.data));
                        break;
                    case 6:
                        clientID = data.data.client;
                        let subscriptions = [];
                        const subs = data.data.subs;
                        if (subs) {
                            for (const m in subs) {
                                if (subs.hasOwnProperty(m)) {
                                    subscriptions.push(m);
                                }
                            }
                        }
                        console.log("connected with client ID " + clientID + " and subscriptions: " + JSON.stringify(subscriptions));
                        break;
                    case 7:
                        clientID = null;
                        if (!data.data.reconnect) {
                            reconnect = false;
                            ws.close();
                            console.log("disconnected from a server, won't reconnect");
                        } else {
                            console.log("disconnected from a server, will reconnect");
                        }
                        break;
                    case 3:
                    console.log("unsubscribed from a channel " + data.channel);
                        break;
                    case 5:
                    console.log("subscribed to a channel " + data.channel);
                        break;
                    default:
                    console.log("unsupported push type " + data.type);
                }
            }

        });
    </script>

New Block Header Event

Receive new block header events in real time.

URL

Mainnet: wss://socket.whatsonchain.com/websocket?channels=woc:blockHeader
Testnet: wss://socket-testnet.whatsonchain.com/websocket?channels=woc:blockHeader

URL - for centrifuge clients

Mainnet: wss://socket.whatsonchain.com/blockheaders
Testnet: wss://socket-testnet.whatsonchain.com/blockheaders

Data JSON structure

{
  "hash": "0000000000000000010cb155a44577ff3541940ec4355c026dc2706fb7e261d6",
  "confirmations": 4,
  "size": 1229956,
  "height": 676421,
  "version": 541065216,
  "versionHex": "20400000",
  "merkleroot": "e2f64e87c0362314b65dc28b4367c41d904c22b891b652951779336ef735386b",
  "txcount": 654,
  "time": 1614534798,
  "mediantime": 1614527058,
  "nonce": 610133701,
  "bits": "180d359d",
  "difficulty": 83235621087.7299,
  "chainwork": "00000000000000000000000000000000000000000127d3854a414d8ec8f53190",
  "previousblockhash": "00000000000000000428ca33597675bd85f5a2ef464ba25e4db7b4a74d898d33",
  "nextblockhash": "00000000000000000cb40c1d850dece5cd3747e08a1e4066ef887251388c4ae6",
  "coinbaseTx": {
    "hex": "01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff410345520a2f7461616c2e636f6d2f506c656173652070617920302e3520736174732f627974652c20696e666f407461616c2e636f6d6eead6b0ad91f2ce86be0400ffffffff0176674325000000001976a9148e9170be3f733a9773c907517fb9b786f1c884c688ac00000000",
    "txid": "13686a10870d23b4c94642bf0b78d6630e2640fc0de83bc30af835d96bb17482",
    "hash": "13686a10870d23b4c94642bf0b78d6630e2640fc0de83bc30af835d96bb17482",
    "size": 150,
    "version": 1,
    "locktime": 0,
    "vin": [
      {
        "coinbase": "0345520a2f7461616c2e636f6d2f506c656173652070617920302e3520736174732f627974652c20696e666f407461616c2e636f6d6eead6b0ad91f2ce86be0400",
        "sequence": 4294967295
      }
    ],
    "vout": [
      {
        "value": 6.2517439,
        "n": 0,
        "scriptPubKey": {
          "asm": "OP_DUP OP_HASH160 8e9170be3f733a9773c907517fb9b786f1c884c6 OP_EQUALVERIFY OP_CHECKSIG",
          "hex": "76a9148e9170be3f733a9773c907517fb9b786f1c884c688ac",
          "reqSigs": 1,
          "type": "pubkeyhash",
          "addresses": [
            "1DzqBck9oyCBzxJbbje2s15deZis6BeATi"
          ],
          "isTruncated": false
        }
      }
    ],
    "blockhash": "0000000000000000010cb155a44577ff3541940ec4355c026dc2706fb7e261d6",
    "confirmations": 4,
    "time": 1614534798,
    "blocktime": 1614534798
  }
}

Block Headers History

Stream block headers starting at a pre-specified block height.

URL

Mainnet: wss://socket.whatsonchain.com/websocket/history?from=<blockHeight>
Testnet: wss://socket-testnet.whatsonchain.com/websocket/history?from=<blockHeight>

URL - for centrifuge clients

Mainnet: wss://socket.whatsonchain.com/blockheaders/history?from=<blockHeight>
Testnet: wss://socket-testnet.whatsonchain.com/blockheaders/history?from=<blockHeight>

Data JSON structure

{
  "hash": "000000000000000007dde2992ff13fdaba5473341af1c45d0c19c86deb4c732a",
  "confirmations": 1,
  "size": 3449218,
  "height": 676417,
  "version": 536870912,
  "versionHex": "20000000",
  "merkleroot": "df1fe3b56cacd2f4063fbe41d15b51071c72d5748d265f4e61793db79ce0d8ff",
  "txcount": 8859,
  "time": 1614529458,
  "mediantime": 1614524118,
  "nonce": 347880361,
  "bits": "180d6633",
  "difficulty": 82056657294.07133,
  "chainwork": "00000000000000000000000000000000000000000127d3376e97bb73257c98c5",
  "previousblockhash": "00000000000000000b04692ac2bf62654e2ea577476e20ea74eb9e5b53f0ed48",
  "nextblockhash": ""
}

Block Transactions

Stream transactions from a block height and transaction index.

hex, vin and vout values are not published for message sizes greater than 10MB. Recommended to fetch details for such transactions using these REST endpoints using the published txid value.

URL

Mainnet: wss://socket.whatsonchain.com/websocket/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}
Testnet: wss://socket-testnet.whatsonchain.com/websocket/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}

URL - for centrifuge clients

Mainnet: wss://socket.whatsonchain.com/block/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}
Testnet: wss://socket-testnet.whatsonchain.com/block/transactions?from=<blockHeight>&txIndex={txIndex}&to=<blockHeight>&format={hex|json}

Data JSON structure

{
  "txid": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
  "hash": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
  "size": 219,
  "version": 2,
  "locktime": 0,
  "vin": [
    {
      "txid": "15b416adf871f9285788ebf36b67714d9e49f413f3a3f083d80e01535bd40433",
      "vout": 1,
      "scriptSig": {
        "asm": "304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb641 02a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff",
        "hex": "47304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb6412102a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff"
      },
      "sequence": 4294967295
    }
  ],
  "vout": [
    {
      "value": 0,
      "n": 0,
      "scriptPubKey": {
        "asm": "OP_FALSE OP_RETURN 39366665313633626131303138386636",
        "hex": "006a1039366665313633626131303138386636",
        "type": "nulldata",
        "isTruncated": false
      }
    },
    {
      "value": 0.00007511,
      "n": 1,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 966a0c69734d51307ba0bcfcd9092b51addfaf78 OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a914966a0c69734d51307ba0bcfcd9092b51addfaf7888ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "1EiKQ9qiAkjDn86JvUt6aJpZvETq8uim2D"
        ],
        "isTruncated": false
      }
    }
  ]
}

URL Parameters

Parameter	Description
blockHeight	The height of the block.
txIndex	Index of a transaction as a starting point in the first block to deliver. Default value 0.
format	Hex or json. If hex, the response will include transaction hex and metadata. If json, hex is excluded. Default value is json.

Parameter

Description

blockHeight

The height of the block.

txIndex

Index of a transaction as a starting point in the first block to deliver. Default value 0.

format

Hex or json. If hex, the response will include transaction hex and metadata. If json, hex is excluded. Default value is json.

Mempool Transactions

Receive mempool transactions in real time.

Mempool transactions are collected from multiple nodes.
Client side should be idempotent because duplicate transaction events are not guaranteed to have been removed.
hex, vin and vout values are not published for message sizes greater than 10MB. Recommended to fetch details for such transactions using these REST endpoints using the published txid value.

URL

Mainnet: wss://socket.whatsonchain.com/websocket?channels=woc:mempoolTx?filter=<filter1,filter2,...>
Testnet: wss://socket-testnet.whatsonchain.com/websocket?channels=woc:mempoolTx?filter=<filter1,filter2,...>

URL - for centrifuge clients

Mainnet: wss://socket.whatsonchain.com/mempool?filter=<filter1,filter2,...>
Testnet: wss://socket-testnet.whatsonchain.com/mempool?filter=<filter1,filter2,...>

Data JSON structure

{
  "hex": "02 ...",
  "txid": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
  "hash": "20ac30f5aa6aebc0f9e532f32a9691bf7faa332c755d6aea1fd3f6ba36d195e8",
  "size": 219,
  "version": 2,
  "locktime": 0,
  "vin": [
    {
      "txid": "15b416adf871f9285788ebf36b67714d9e49f413f3a3f083d80e01535bd40433",
      "vout": 1,
      "scriptSig": {
        "asm": "304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb641 02a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff",
        "hex": "47304402204ac1d9f22f09044f66aa6055835b19d5617c19ef180422683b9d168da272e40d022078d3e876f7134eb29cd9e26081feae70f393a1aa3e9926307233f1c419bd1eb6412102a3089907380f086e9d5616ef6e62876a2777ea0c5abca785b15ef92d173afdff"
      },
      "sequence": 4294967295
    }
  ],
  "vout": [
    {
      "value": 0,
      "n": 0,
      "scriptPubKey": {
        "asm": "OP_FALSE OP_RETURN 39366665313633626131303138386636",
        "hex": "006a1039366665313633626131303138386636",
        "type": "nulldata",
        "isTruncated": false
      }
    },
    {
      "value": 0.00007511,
      "n": 1,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 966a0c69734d51307ba0bcfcd9092b51addfaf78 OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a914966a0c69734d51307ba0bcfcd9092b51addfaf7888ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "1EiKQ9qiAkjDn86JvUt6aJpZvETq8uim2D"
        ],
        "isTruncated": false
      }
    }
  ]
}

URL Parameters

Parameter	Description
filter	The filter transactions based on the output (vout) types. The available filters are: nulldata, multisig, pubkey, pubkeyhash, scripthash, and nonstandard.

Parameter

Description

filter

The filter transactions based on the output (vout) types. The available filters are: nulldata, multisig, pubkey, pubkeyhash, scripthash, and nonstandard.

Confirmed Transactions (Unavailable)

This feature is currently unavailable as we are working on a v2. Please let us know in our Telegram channel if you are interested in streaming and what features you would like to see in the next version.

Receive confirmed transactions in real time.

Confirmed transactions are collected from multiple nodes.
Client side should be idempotent because duplicate transaction events are not guaranteed to have been removed.
hex, vin and vout values are not published for transaction sizes greater than 1 MB. Recommended to fetch details for such transactions using these REST endpoints using the published txid value.

URL

Mainnet: wss://socket.whatsonchain.com/websocket?channels=woc:confirmedTx?filter=<filter1,filter2,...>
Testnet: wss://socket-testnet.whatsonchain.com/websocket?channels=woc:confirmedTx?filter=<filter1,filter2,...>

URL - for centrifuge clients

Mainnet: wss://socket.whatsonchain.com/confirmed?filter=<filter1,filter2,...>
Testnet: wss://socket-testnet.whatsonchain.com/confirmed?filter=<filter1,filter2,...>

Data JSON structure

{
  "hex": "01 ...",
  "txid": "651dd0bc40520dfc5927b8b9a6fbb0d3d7ff7314fae28d6c5ddad66e1f75ffff",
  "hash": "651dd0bc40520dfc5927b8b9a6fbb0d3d7ff7314fae28d6c5ddad66e1f75ffff",
  "size": 442,
  "version": 1,
  "locktime": 0,
  "vin": [
    {
      "txid": "719f1f2e79c29f30d60b106518f29abcab0e3d17fc79731c7bc37504130eb91d",
      "vout": 2,
      "scriptSig": {
        "asm": "30450221008117adcf9c88330b85efa6772ba6b8cecccc473ecea8160494885cec46abefe302202fa8f1469dd070ecc2713f1e55117bb245e14e4f9f4a6f1f54ecdde2cfad875941 02569ec180c4917405a9f285260804e5d34c696218edc7fa818e9c7f414e2cbcc4",
        "hex": "4830450221008117adcf9c88330b85efa6772ba6b8cecccc473ecea8160494885cec46abefe302202fa8f1469dd070ecc2713f1e55117bb245e14e4f9f4a6f1f54ecdde2cfad8759412102569ec180c4917405a9f285260804e5d34c696218edc7fa818e9c7f414e2cbcc4"
      },
      "sequence": 4294967295
    }
  ],
  "vout": [
    {
      "value": 0.00003822,
      "n": 0,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 09cc4559bdcb84cb35c107743f0dbb10d66679cc OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a91409cc4559bdcb84cb35c107743f0dbb10d66679cc88ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "1tonicZQwN2BNKhVwPXqh8ez3q56y1EYw"
        ],
        "isTruncated": false
      }
    },
    {
      "value": 0.00038224,
      "n": 1,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 b8cba27cbf0357e1e74ede6b4ac17f49aa297991 OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a914b8cba27cbf0357e1e74ede6b4ac17f49aa29799188ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "1Hr7H5vdaxordBEu9CJxnfD2NNWEnwEfih"
        ],
        "isTruncated": false
      }
    },

    ...

  ],
  "blockhash": "00000000000000000045876574d74d4006b8b821525135720a0a12343986a14a",
  "confirmations": 1,
  "time": 1616419527,
  "blocktime": 1616419527,
  "blockheight": 679542
}

URL Parameters

Parameter	Description
filter	The filter transactions based on the output (vout) types. The available filters are: nulldata, multisig, pubkey, pubkeyhash, scripthash, and nonstandard.

Parameter

Description

filter

The filter transactions based on the output (vout) types. The available filters are: nulldata, multisig, pubkey, pubkeyhash, scripthash, and nonstandard.

Chain Stats

Receive common chain stats every 10 seconds.

URL

Mainnet: wss://socket.whatsonchain.com/websocket?channels=woc:chainStats
Testnet: wss://socket-testnet.whatsonchain.com/websocket?channels=woc:chainStats

URL - for centrifuge clients

Mainnet: wss://socket.whatsonchain.com/stats
Testnet: wss://socket-testnet.whatsonchain.com/stats

Data JSON structure

{
   "chainSummary":{
      "blocks":691040,
      "bestblockhash":"000000000000000006f693315876096d472a8313780df342905e1003a6cf0b70",
      "difficulty":102522924402.0986,
      "chainwork":"0000000000000000000000000000000000000000012cfa97321f921dab48da26",
      "networkhashps":650555175336335400,
      "circulatingSupply":18756500,
      "mempoolSize":6554,
      "mempoolBytes":16540861,
      "mempoolUsage":26650576,
      "exchangeRate":{
         "currency":"USD",
         "rate":"170.70749999999998"
      }
   },
   "latestBlocks":[
      {
         "hash":"000000000000000006f693315876096d472a8313780df342905e1003a6cf0b70",
         "confirmations":1,
         "size":208141,
         "height":691040,
         "version":538968064,
         "versionHex":"20200000",
         "merkleroot":"e3454f52b6715dcf4db5d8c8f237344ef6bd6d415d6e754a3b4b1083cd3ab48c",
         "txcount":102,
         "time":1623330613,
         "mediantime":1623328816,
         "nonce":3022302528,
         "bits":"180ab971",
         "difficulty":102522924402.0986,
         "chainwork":"0000000000000000000000000000000000000000012cfa97321f921dab48da26",
         "previousblockhash":"0000000000000000013ab5705e150967a057f807f396628231a7ceaa11a0bac1",
         "nextblockhash":"",
         "coinbaseTx":{...},
         "totalFees":0.0009790499999997593
      },
      {...},
      ...
   ]
}

Examples

Customized Events

If your application needs customized/filtered events via WebSockets, please let us know in the WoC devs telegram channel.

PreviousStats NextChange Log

Last updated 1 month ago