WebSocket JSON 2.0 RPC API
Access paths and compatibility
The RPC WebSocket API can be accessed by the ws://localhost:9901/rpc-v2
.
Access paths and compatibility
The WebSocket API can be accessed by the wss://service.lisk.com/rpc-v2
.
The testnet network can also be accessed by wss://testnet-service.lisk.com/rpc-v2
.
The Lisk Service WebSocket API uses the socket.io
library and is compatible with the JSON-RPC 2.0 standard.
The specification below contains numerous examples how to use the API in practice.
Endpoint logic
The logic of the endpoints is derived as follows: the method naming is always based on the following pattern: <action>.<entity>
, where the action is equivalent to HTTP standard (GET, POST, PUT, etc.) and entity
is a part of the application logic, ex. accounts
, transactions and so on.
Requests
import io from 'socket.io-client';
const request = async (endpoint, method, params) => new Promise(resolve => {
const socket = io(endpoint, { forceNew: true, transports: ['websocket'] });
socket.emit('request', { jsonrpc: '2.0', method, params }, answer => {
socket.close();
resolve(answer);
});
});
const wsRequest = async () => {
return await request('ws://localhost:9901/rpc', 'get.accounts', { "address": "lskzkfw7ofgp3uusknbetemrey4aeatgf2ntbhcds" });
};
wsRequest().then(response => {
console.log(response);
});
Responses
All responses are returned in the JSON format - application/json.
Each API response has the following structure:
{
"jsonrpc": "2.0", // standard JSON-RPC envelope
"result": {
"data": {}, // Contains the requested data
"meta": {}, // Contains additional metadata, e.g. the values of `limit` and `offset`
},
"id": 1 // Number of response in chain
}
Date Format
In the contrary to the original Lisk Core API, all timestamps used by the Lisk Service are in the UNIX timestamp format. The blockchain dates are always expressed as integers and the epoch date is equal to the number of seconds since 1970-01-01 00:00:00.
Multi-Requests
A request can consist of an array of multiple responses.
[
{ "jsonrpc": "2.0", "id": 1, "method": "get.blocks", "params": {} },
{ "jsonrpc": "2.0", "id": 2, "method": "get.transactions", "params": { "height": "123" } },
{ "jsonrpc": "2.0", "id": 3, "method": "get.accounts", "params": { "address": "lskzkfw7ofgp3uusknbetemrey4aeatgf2ntbhcds"} }
]
Response
[
{
"jsonrpc": "2.0",
"result": {
"data": [
... // List of blocks
],
"meta": {},
},
"id": 1
},
{
"jsonrpc": "2.0",
"result": {
"data": [
... // List of transactions
],
"meta": {},
},
"id": 2
},
{
"jsonrpc": "2.0",
"data": [
... // List of accounts
],
"meta": {},
},
"id": 3
}
]
Lisk Blockchain-related Endpoints
Accounts
get.accounts
Retrieves account details based on criteria defined by params.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
Resolves new and old address system. |
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
Boolean |
|
(empty) |
|
|
String |
|
(empty) |
Multiple choice possible i.e. |
|
String |
(empty) |
||
|
Number |
|
10 |
|
|
Number |
|
0 |
|
|
Array of strings |
|
|
Rank is dedicated to delegate accounts |
{
"data": {
"summary": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"legacyAddress": "2841524825665420181L",
"balance": "151146419900",
"username": "liberspirita",
"publicKey": "968ba2fa993ea9dc27ed740da0daf49eddd740dbd7cb1cb4fc5db3a20baf341b",
"isMigrated": true,
"isDelegate": true,
"isMultisignature": true,
},
"knowledge": {
"owner": "Genesis Account",
"description": ""
},
"token": {
"balance": "151146419900"
},
"sequence": {
"nonce": "11"
},
"keys": {
"numberOfSignatures": 0,
"mandatoryKeys": [],
"optionalKeys": [],
"members": [
{
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"publicKey": "968ba2fa993ea9dc27ed740da0daf49eddd740dbd7cb1cb4fc5db3a20baf341b",
"isMandatory": true,
}
],
"memberships": [
{
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"publicKey": "968ba2fa993ea9dc27ed740da0daf49eddd740dbd7cb1cb4fc5db3a20baf341b",
"username": "genesis_51",
}
],
},
"dpos": {
"delegate": {
"username": "liberspirita",
"pomHeights": [
{ "start": 123, "end": 456 },
{ "start": 789, "end": 1050 }
],
"consecutiveMissedBlocks": 0,
"lastForgedHeight": 68115,
"isBanned": false,
"totalVotesReceived": "201000000000",
},
"sentVotes": [
{
"delegateAddress": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"amount": "102000000000"
},
{
"delegateAddress": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"amount": "95000000000"
}
],
"unlocking": [
{
"delegateAddress": "lskdwsyfmcko6mcd357446yatromr9vzgu7eb8y99",
"amount": "150000000",
"height": {
"start": "10",
"end": "2010"
}
}
],
"legacy": {
"address": "2841524825665420181L", // legacyAddress
"balance": "234500000" // Reclaimable balance
}
}
},
"meta": {
"count": 1,
"offset": 0
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.accounts",
"params": {
"address": "lskzkfw7ofgp3uusknbetemrey4aeatgf2ntbhcds"
}
}
get.votes_sent
Retrieves votes of a single account based on address, public key or delegate name.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
Resolves only new address system |
|
String |
|
(empty) |
|
|
String |
|
(empty) |
{
"data": {
"account": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"username": "genesis_56",
"votesUsed": 10
},
"votes": [
{
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"amount": 1081560729258, // = voteWeight
"username": "liskhq"
}
]
},
"meta": {
"count": 10,
"offset": 0,
"total": 10 // = votesUsed
},
"links": {}
}
{
"method": "get.votes_sent",
"params": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu"
}
}
get.votes_received
Retrieves voters for a delegate account based on address, public key or delegate name.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
Resolves only new address system |
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
Number |
|
10 |
|
|
Number |
|
0 |
{
"data": {
"account": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"username": "genesis_56",
"votesUsed": 10
},
"votes": [
{
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"amount": 1081560729258, // = voteWeight
"username": "liskhq"
}
]
},
"meta": {
"count": 10,
"offset": 0,
"total": 10 // = votesUsed
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.votes_received",
"params": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu"
}
}
Blocks
get.blocks
Retrieves blocks from the blockchain based on ID, height or account.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
Can be expressed as an interval ie. |
|
String |
|
(empty) |
Resolves new and old address system. |
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
Number |
|
10 |
|
|
Number |
|
0 |
|
|
Array of strings |
|
|
Rank is dedicated to delegate accounts |
{
"data": [
{
"id": "1963e291eaa694fb41af320d7af4e92e38be26ddd88f61b150c74347f119de2e",
"height": 8344448,
"version": 0,
"timestamp": 85944650,
"generatorAddress": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"generatorPublicKey": "6e904b2f678eb3b6c3042acb188a607d903d441d61508d047fe36b3c982995c8",
"generatorUsername": "genesis_13",
"transactionRoot": "4e4d91be041e09a2e54bb7dd38f1f2a02ee7432ec9f169ba63cd1f193a733dd2",
"signature": "a3733254aad600fa787d6223002278c3400be5e8ed4763ae27f9a15b80e20c22ac9259dc926f4f4cabdf0e4f8cec49308fa8296d71c288f56b9d1e11dfe81e07",
"previousBlockId": "15918760246746894806",
"numberOfTransactions": 15,
"totalFee": "15000000",
"reward": "50000000",
"totalForged": "65000000",
"totalBurnt": "10000000",
"isFinal": true,
"maxHeightPreviouslyForged": 68636,
"maxHeightPrevoted": 68707,
"seedReveal": "4021e5048af4c9f64ff2e12780af21f4"
}
],
"meta": {
"count": 100,
"offset": 25,
"total": 43749
},
"links": {}
}
Forgers
get.forgers
Retrieves next forgers with details in the current round.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
Number |
|
10 |
|
|
Number |
|
0 |
{
"data": [
{
"username": "genesis_51",
"totalVotesReceived": "1006000000000",
"address": "c6d076ed541ca20869a1398a9d28c645ac8a8719",
"minActiveHeight": 27605,
"isConsensusParticipant": true,
"nextForgingTime": 1607521557
},
],
"meta": {
"count": 10,
"offset": 20,
"total": 103
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.forgers",
"params": {
"limit": "20",
"offset": "50"
}
}
Transactions
get.transactions
Retrieves network transactions by criteria defined by params.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
Transfer transaction: moduleID = 2,assetID = 0 |
|
String |
|
(empty) |
Transfer transaction: moduleName = token, assetName = transfer |
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
String |
(empty) |
Can be expressed as interval ie. |
|
|
String |
(empty) |
Can be expressed as interval ie. |
|
|
String |
|
(empty) |
Block ID |
|
String |
(empty) |
Block height |
|
|
String |
(empty) |
Wildcard search |
|
|
String |
(empty) |
Wildcard search |
|
|
Boolean |
false |
||
|
String |
|
(empty) |
In conjunction with senderAddress |
|
Number |
|
10 |
|
|
Number |
|
0 |
|
|
Array of strings |
|
|
{
"data": [
{
"id": "222675625422353767",
"operationId": "2:0",
"operationName": "token:transfer",
"fee": "1000000",
"nonce": "0",
"block": { // optional
"id": "6258354802676165798",
"height": 8350681,
"timestamp": 28227090,
},
"sender": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"publicKey": "2ca9a7...c23079",
"username": "genesis_51",
},
"signatures": [ "72c9b2...36c60a" ],
"confirmations": 0,
"asset": { // Depends on operation
"amount": "150000000",
"recipient": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"publicKey": "2ca9a7...c23079",
"username": "genesis_49",
},
"data": "message"
},
"relays": 0,
"isPending": false
}
],
"meta": {
"count": 100,
"offset": 25,
"total": 43749
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.transactions",
"params": {
"transactionId": "222675625422353767"
}
}
{
"jsonrpc": "2.0",
"method": "get.transactions",
"params": {
"address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
"limit": "25"
}
}
post.transactions
Posts transactions to the network.
No parameters.
{
"message": "Transaction payload was successfully passed to the network node"
"transactionId": "123456789"
}
{
"jsonrpc": "2.0",
"method": "post.transactions",
"payload": {"transaction":"08021000180d2080c2d72f2a200fe9a3f1a21b5530f27f87a414b549e79a940bf24fdf2b2f05e7f22aeeecc86a32270880c2d72f12144fd8cc4e27a3489b57ed986efe3d327d3de40d921a0a73656e6420746f6b656e3a4069242925e0e377906364fe6c2eed67f419dfc1a757f73e848ff2f1ff97477f90263487d20aedf538edffe2ce5b3e7601a8528e5cd63845272e9d79c294a6590a"}
}
get.transactions.statistics
Retrieves daily network transactions statistics for time spans defined by params.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
Required field. |
|
Number |
|
10 |
|
|
Number |
|
0 |
{
"data": {
"timeline": [
{
"timestamp": 1556100060,
"date": "2019-11-27",
"transactionCount": "14447177193385",
"volume": "14447177193385"
}
],
"distributionByOperation": {},
"distributionByAmount": {}
},
"meta": {
"count": 100,
"offset": 25,
"total": 43749
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.transactions.statistics",
"params": {
"interval": "day",
"limit": 7
}
}
get.transactions.schemas
Retrieves transaction schema for certain transaction payloads.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
Transfer transaction: moduleID = 2,assetID = 0 |
|
String |
|
(empty) |
Transfer transaction: moduleName = token, assetName = transfer |
{
"data": [
{
"moduleAssetId": "2:0",
"moduleAssetName": "token:transfer",
"schema": {
...
}
},
],
"meta": {
"count": 10,
"offset": 0,
"total": 10
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.transactions.schemas",
"params": {
"moduleAssetName": "token:transfer"
}
}
Fees
get.fees
Requests transaction fee estimates per byte.
No parameters.
{
"data": {
"feeEstimatePerByte": {
"low": 0,
"medium": 1000,
"high": 2000
},
"baseFeeById": {
"2:0": "1000000000"
},
"baseFeeByName": {
"token:transfer": "1000000000"
},
"minFeePerByte": 1000,
},
"meta": {
"lastUpdate": 123456789,
"lastBlockHeight": 25,
"lastBlockId": 1354568
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.fees",
}
Peers
get.peers
Retrieves network peers with details based on criteria.
Supports pagination.
Parameter | Type | Validation | Default | Comment |
---|---|---|---|---|
|
String |
|
(empty) |
|
|
String |
|
(empty) |
|
|
Array of strings |
|
|
|
|
Number |
|
(empty) |
|
|
Number |
|
10 |
|
|
Number |
|
0 |
|
|
Array of strings |
|
|
{
"data": [
{
"ip": "127.0.0.1",
"port": 4000,
"networkVersion": "2.0",
"state": "connected",
"height": 8350681,
"networkIdentifier": "258974416d58533227c6a3da1b6333f0541b06c65b41e45cf31926847a3db1ea",
"location": {
"countryCode": "DE",
"countryName": "Germany",
"hostname": "host.210.239.23.62.rev.coltfrance.com",
"ip": "210.239.23.62",
}
}
],
"meta": {
"count": 100,
"offset": 25,
"total": 43749
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.peers",
"params": {
"ip": "210.239.23.62"
}
}
Network
get.network.status
Retrieves network details and constants such as network height, broadhash, fees, reward amount, etc.
No parameters.
{
"data": {
"height": 27256,
"finalizedHeight": 27112,
"milestone": "0",
"networkVersion": "2.0",
"networkIdentifier": "08ec0e01794b57e5ceaf5203be8c1bda51bcdd39bb6fc516adbe93223f85d630",
"reward": "500000000",
"supply": "10094237000000000",
"registeredModules": ["token", "sequence", "keys", "dpos", "legacyAccount"],
"operations": [
{ "id": "2:0", "name": "token:transfer" }
...
],
"blockTime": 10,
"communityIdentifier": "Lisk",
"maxPayloadLength": 15360,
},
"meta": {
"lastUpdate": 123456789,
"lastBlockHeight": 25,
"lastBlockId": 1354568
},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.network.status"
}
get.network.statistics
Retrieves network statistics such as the number of peers, node versions, heights, etc.
No parameters.
{
"data": {
"basic": {
"connectedPeers": 134,
"disconnectedPeers": 48,
"totalPeers": 181
},
"height": {
"7982598": 24
},
"networkVersion": {
"2.0": 12,
"2.1": 41
}
},
"meta": {},
"links": {}
}
{
"jsonrpc": "2.0",
"method": "get.network.statistics"
}
Off-chain Features
News Feed Aggregator
Retrieves recent blogposts from Lisk Blog and Twitter.
Supports pagination.
Request parameters
Parameter | Type | Validation |
---|---|---|
source |
String |
Retrieves all sources by default. |
limit |
Number |
|
offset |
Number |
|
Response example
{
"data": [
{
"author": "Lisk",
"content": "On Wednesday, March 3rd, Max Kordek, CEO and Co-founder at Lisk, hosted a live\nmonthly AMA (Ask Max Anything) on Lisk.chat. He answered questions regarding the\nupcoming milestones for Lisk, Lisk.js 2021, marketing plans for this year, and\nmuch more.\n\nThis blog post includes a recap of the live AMA session and features the\nquestions asked by community members, as well as Max’s answers.",
"image_url": "https://lisk.com/sites/default/files/styles/blog_main_image_xl_retina/public/images/2021-04/montly-ama-ask-max-anything-recap-MAIN-V1%402x_0.png?itok=_0lipXxp",
"imageUrl": "https://lisk.com/sites/default/files/styles/blog_main_image_xl_retina/public/images/2021-04/montly-ama-ask-max-anything-recap-MAIN-V1%402x_0.png?itok=_0lipXxp",
"source": "drupal_lisk_general",
"sourceId": "1001",
"timestamp": 1614854580,
"createdAt": 1614854580,
"modifiedAt": 1614854580,
"title": "AMA Recap: Ask Max Anything in March 2021",
"url": "https://lisk.com/blog/events/ama-recap-ask-max-anything-march-2021"
}
],
"meta": {
"count": 1,
"limit": 1,
"offset": 0
}
}
400 Bad Request
```
{
"error": true,
"message": "Unknown input parameter(s): <param_name>"
}
{
"error": true,
"message": "Invalid input: The 'source' field fails to match the required pattern."
}
{
"error": true,
"message": "Service is not ready yet"
}