The Lisk Service is a web application that interacts with the entire Lisk ecosystem in various aspects. For example, one key aspect is an update about blockchain events.
The Subscribe API is sometimes called publish/subscribe or Event-Driven API. The biggest difference between Event-Driven and regular REST API is not only technical. In practice, a two-way streaming connection is used, which means that not only can the client request the server for a data update, (and also potential updates) but also the server can notify the client about new data instantly as it arrives.
Lisk Service leverages the two-way communication approach by utilizing the WebSocket library responsible for updating users about changes in the blockchain network and markets.
The blockchain update API can be accessed by the following path https://service.lisk.com/blockchain.
You might also be interested in accessing the testnet network by using the https://testnet-service.lisk.com/blockchain endpoint.
Important: The Lisk Service WebSocket API uses the socket.io library. This implementation is compatible with version 2.0 of the socket.io library. Using the wrong major version might result in a broken connection and events not being passed.
The specification below contains numerous examples of how to use the API in practice.
The logic of the endpoints comes as follows: the method naming is always based on the following pattern: <action>.<entity>, where the action is equivalent to the method type performed on the server (ie. update) and entity is a part of the application logic, eg. blocks, transactions.
All the event payloads are returned in the JSON format - application/json and adhere to the following structure:
{
"data": {}, // Contains the update information
"meta": {
"count": <integer>, // number of items
"timestamp": <timestamp>, // timestamp in seconds
... // other metadata
},
}const io = require('socket.io-client');
const connection = io.connect('https://service.lisk.com/blockchain', { transports: ['websocket'] });
connection.on('update.block', (block) => { (...) });Updates about a newly generated block.
{
"data": [
{
"id": "01967dba384998026fe028119bd099ecf073c05c045381500a93d1a7c7307e5b",
"version": 0,
"height": 8344448,
"timestamp": 85944650,
"previousBlockId": "827080df7829cd2757501a85f80a0767fcb40615304b701c2890dbbaf214bb89",
"generator": {
"address": "lskdwsyfmcko6mcd357446yatromr9vzgu7eb8y99",
"name": "genesis_3",
"publicKey": "32ddb97e8d7e607a14fef8449c2a2180cd74a51f67b04a50a4b1917d3ca8a52e"
},
"transactionRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"assetsRoot": "6e904b2f678eb3b6c3042acb188a607d903d441d61508d047fe36b3c982995c8",
"stateRoot": "95d9b1773b78034b8df9ac741c903b881da761d8ba002a939de28a4b86982c04",
"maxHeightGenerated": 559421,
"maxHeightPrevoted": 559434,
"validatorsHash": "ad0076aa444f6cda608bb163c3bd77d9bf172f1d2803d53095bc0f277db6bcb3",
"aggregateCommit": {
"height": 166,
"aggregationBits": "ffffffffffffffffffffffff1f",
"certificateSignature": "a7db952f87db29718c40afca9a9fb2f6b605f8588c1c99e41e92f26ec005e6d14327c33051fa383fe903b7040d16c7441570167a73d9468aa16a6720c765b3f22aeca42102c45b4616fd7543d7a0649e0fa934e0de1973486eede9d56f014f9f"
},
"numberOfTransactions": 10,
"numberOfAssets": 10,
"numberOfEvents": 10,
"totalBurnt": "0",
"networkFee": "15000000",
"totalForged": "65000000",
"reward": "50000000",
"signature": "a3733254aad600fa787d6223002278c3400be5e8ed4763ae27f9a15b80e20c22ac9259dc926f4f4cabdf0e4f8cec49308fa8296d71c288f56b9d1e11dfe81e07",
"isFinal": true
}
],
"meta": {
"count": 1,
"offset": 0,
"total": 1
}
}Updates about a deleted block. This usually happens when the chain switches forks.
{
"data": [
{
"id": "01967dba384998026fe028119bd099ecf073c05c045381500a93d1a7c7307e5b",
"version": 0,
"height": 8344448,
"timestamp": 85944650,
"previousBlockId": "827080df7829cd2757501a85f80a0767fcb40615304b701c2890dbbaf214bb89",
"generator": {
"address": "lskdwsyfmcko6mcd357446yatromr9vzgu7eb8y99",
"name": "genesis_3",
"publicKey": "32ddb97e8d7e607a14fef8449c2a2180cd74a51f67b04a50a4b1917d3ca8a52e"
},
"transactionRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"assetsRoot": "6e904b2f678eb3b6c3042acb188a607d903d441d61508d047fe36b3c982995c8",
"stateRoot": "95d9b1773b78034b8df9ac741c903b881da761d8ba002a939de28a4b86982c04",
"maxHeightGenerated": 559421,
"maxHeightPrevoted": 559434,
"validatorsHash": "ad0076aa444f6cda608bb163c3bd77d9bf172f1d2803d53095bc0f277db6bcb3",
"aggregateCommit": {
"height": 166,
"aggregationBits": "ffffffffffffffffffffffff1f",
"certificateSignature": "a7db952f87db29718c40afca9a9fb2f6b605f8588c1c99e41e92f26ec005e6d14327c33051fa383fe903b7040d16c7441570167a73d9468aa16a6720c765b3f22aeca42102c45b4616fd7543d7a0649e0fa934e0de1973486eede9d56f014f9f"
},
"numberOfTransactions": 10,
"numberOfAssets": 10,
"numberOfEvents": 10,
"totalBurnt": "0",
"networkFee": "15000000",
"totalForged": "65000000",
"reward": "50000000",
"signature": "a3733254aad600fa787d6223002278c3400be5e8ed4763ae27f9a15b80e20c22ac9259dc926f4f4cabdf0e4f8cec49308fa8296d71c288f56b9d1e11dfe81e07",
"isFinal": true
}
],
"meta": {
"count": 1,
"offset": 0,
"total": 1
}
}Updates about included transactions within a newly generated block.
{
"data": [
{
"id": "65c28137c130c6609a67fccfcd9d0f7c3df3577324f8d33134326d653ded613f",
"moduleCommand": "token:transfer",
"nonce": "1",
"fee": "5166000",
"minFee": "165000",
"size": 166,
"sender": {
"address": "lskyvvam5rxyvbvofxbdfcupxetzmqxu22phm4yuo",
"publicKey": "475697e34ae02b394721020d38677a072dbd5c03d61c1c8fdd6563eb66160fa3",
"name": "genesis_0"
},
"params": {
"tokenID": "0400000100000000",
"amount": "10000000000",
"recipientAddress": "lskezo8pcrbsoceuuu64rpc8w2qkont2ec3n772yu",
"data": ""
},
"block": {
"id": "ebb1ba587a1e8385a2aac1317edcb872c05b2b07df6560fabd0f0d23d7d6a0df",
"height": 122721,
"timestamp": 1678989430,
"isFinal": true
},
"meta": {
"recipient": {
"address": "lskezo8pcrbsoceuuu64rpc8w2qkont2ec3n772yu",
"publicKey": null,
"name": null
}
},
"executionStatus": "success",
"index": 0
},
],
"meta": {
"count": 1,
"offset": 0,
"total": 1
}
}Updates about deleted transactions within a deleted block. This usually happens when the chain switches forks.
{
"data": [
{
"id": "65c28137c130c6609a67fccfcd9d0f7c3df3577324f8d33134326d653ded613f",
"moduleCommand": "token:transfer",
"nonce": "1",
"fee": "5166000",
"minFee": "165000",
"size": 166,
"sender": {
"address": "lskyvvam5rxyvbvofxbdfcupxetzmqxu22phm4yuo",
"publicKey": "475697e34ae02b394721020d38677a072dbd5c03d61c1c8fdd6563eb66160fa3",
"name": "genesis_0"
},
"params": {
"tokenID": "0400000100000000",
"amount": "10000000000",
"recipientAddress": "lskezo8pcrbsoceuuu64rpc8w2qkont2ec3n772yu",
"data": ""
},
"block": {
"id": "ebb1ba587a1e8385a2aac1317edcb872c05b2b07df6560fabd0f0d23d7d6a0df",
"height": 122721,
"timestamp": 1678989430,
"isFinal": true
},
"meta": {
"recipient": {
"address": "lskezo8pcrbsoceuuu64rpc8w2qkont2ec3n772yu",
"publicKey": null,
"name": null
}
},
"executionStatus": "success",
"index": 0
},
],
"meta": {
"count": 1,
"offset": 0,
"total": 1
}
}Updates about the generators for the next round.
{
"data": [
{
"address": "lskjta9erat6qqpa32hqbssttc6p5da3k7tydvhmv",
"name": "panzer",
"publicKey": "2ca9a7...c23079",
"nextAllocatedTime": 1659863166,
"status": "active"
},
...
],
"meta": {
"count": 10,
"offset": 0,
"total": 103,
},
}Updates the current generators list, so the current generator is in the first position.
{
"data": [
{
"address": "lskjta9erat6qqpa32hqbssttc6p5da3k7tydvhmv",
"name": "panzer",
"publicKey": "2ca9a7...c23079",
"nextAllocatedTime": 1659863166
},
...
],
"meta": {
"count": 10,
"offset": 0,
"total": 103,
},
}Updates about recent fee estimates.
{
"data": {
"feeEstimatePerByte": {
"low": 0,
"medium": 0,
"high": 0
},
"minFeePerByte": 1000,
"feeTokenID": "0000000000000000",
},
"meta": {
"lastUpdate": 1659974881,
"lastBlockHeight": 19264798,
"lastBlockID": "fbcb48456086d11dc797321a672cd964cebee85296ec8c7bd6ed036f88f27fb1"
}
}Updates about recent metadata changes.
{
"mainnet": ["Lisk", "Colecti"],
"testnet": ["Lisk", "Enevti"],
"betanet": ["Lisk"],
}