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
    }
]

Accounts

get.accounts

Retrieves account details based on criteria defined by params.

Supports pagination.

Table 1. Parameters
Parameter Type Validation Default Comment

address

String

/lsk[a-hjkm-z2-9]{38}$//[1-9]\d{0,19}[L|l]$/

(empty)

Resolves new and old address system.

publickey

String

/^([A-Fa-f0-9]{2}){32}$/

(empty)

username

String

/^[a-z0-9!@$&_.]{1,20}$/

(empty)

isDelegate

Boolean

true or false

(empty)

status

String

active, standby, banned, punished, non-eligible

(empty)

Multiple choice possible i.e. active,banned

search

String

(empty)

limit

Number

<1;100>

10

offset

Number

<0;+Inf>

0

sort

Array of strings

["balance:asc", "balance:desc", "rank:asc", "rank:desc"]

balance:desc

Rank is dedicated to delegate accounts
Response example
{
  "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": {}
}
Example: Get account with a specific Lisk account ID
{
    "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.

Table 2. Parameters
Parameter Type Validation Default Comment

address

String

/lsk[a-hjkm-z2-9]{38}$//[1-9]\d{0,19}[L|l]$/

(empty)

Resolves only new address system

publickey

String

/^([A-Fa-f0-9]{2}){32}$/

(empty)

username

String

/^[a-z0-9!@$&_.]{1,20}$/

(empty)
Response
{
  "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": {}
}
Example
{
    "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.

Table 3. Parameters
Parameter Type Validation Default Comment

address

String

/lsk[a-hjkm-z2-9]{38}$//[1-9]\d{0,19}[L|l]$/

(empty)

Resolves only new address system

publickey

String

/^([A-Fa-f0-9]{2}){32}$/

(empty)

username

String

/^[a-z0-9!@$&_.]{1,20}$/

(empty)

limit

Number

<1;100>

10

offset

Number

<0;+Inf>

0
Response
{
  "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": {}
}
Example
{
    "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.

Table 4. Parameters
Parameter Type Validation Default Comment

blockId

String

/^([1-9]|[A-Fa-f0-9]){1,64}$/

(empty)

height

String

/[0-9]+/ and /[0-9]+:[0-9]+/

(empty)

Can be expressed as an interval ie. 1:20.

generatorAddress

String

/^lsk[a-hjkm-z2-9]{38}$/ and /^[1-9]\d{0,19}[L|l]$/

(empty)

Resolves new and old address system.

generatorPublicKey

String

/^([A-Fa-f0-9]{2}){32}$/

(empty)

generatorUsername

String

/^[a-z0-9!@$&_.]{1,20}$/

(empty)

limit

Number

<1;100>

10

offset

Number

<0;+Inf>

0

sort

Array of strings

["height:asc", "height:desc","timestamp:asc", "timestamp:desc"]

height:desc

Rank is dedicated to delegate accounts
Response
{
  "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.

Table 5. Parameters
Parameter Type Validation Default Comment

limit

Number

<1;103>

10

offset

Number

<0;+Inf>

0
Response
{
  "data": [
    {
      "username": "genesis_51",
      "totalVotesReceived": "1006000000000",
      "address": "c6d076ed541ca20869a1398a9d28c645ac8a8719",
      "minActiveHeight": 27605,
      "isConsensusParticipant": true,
      "nextForgingTime": 1607521557
    },
  ],
  "meta": {
    "count": 10,
    "offset": 20,
    "total": 103
  },
  "links": {}
}
Example: Get 20 items, skip 50 first
{
    "jsonrpc": "2.0",
    "method": "get.forgers",
    "params": {
        "limit": "20",
        "offset": "50"
    }
}

Transactions

get.transactions

Retrieves network transactions by criteria defined by params.

Supports pagination.

Table 6. Parameters
Parameter Type Validation Default Comment

transactionId

String

/^([1-9]|[A-Fa-f0-9]){1,64}$/

(empty)

moduleAssetId

String

ModuleId:AssetId/[0-9]+:[0-9]+/

(empty)

Transfer transaction: moduleID = 2,assetID = 0

moduleAssetName

String

ModuleName:AssetName/[a-z]+:[a-z]+/

(empty)

Transfer transaction: moduleName = token, assetName = transfer

senderAddress

String

/lsk[a-hjkm-z2-9]{38}$//[1-9]\d{0,19}[L|l]$/

(empty)

senderPublicKey

String

/^([A-Fa-f0-9]{2}){32}$/

(empty)

senderUsername

String

/^[a-z0-9!@$&_.]{1,20}$/

(empty)

recipientAddress

String

/lsk[a-hjkm-z2-9]{38}$//[1-9]\d{0,19}[L|l]$/

(empty)

recipientPublicKey

String

/^([A-Fa-f0-9]{2}){32}$/

(empty)

recipientUsername

String

/^[a-z0-9!@$&_.]{1,20}$/

(empty)

amount

String

(empty)

Can be expressed as interval ie. 100000:200000.

timestamp

String

(empty)

Can be expressed as interval ie. 100000:200000

blockId

String

/^([1-9]|[A-Fa-f0-9]){1,64}$/

(empty)

Block ID

height

String

(empty)

Block height

search

String

(empty)

Wildcard search

data

String

(empty)

Wildcard search

includePending

Boolean

false

nonce

String

/^\d+$/

(empty)

In conjunction with senderAddress

limit

Number

<1;100>

10

offset

Number

<0;+Inf>

0

sort

Array of strings

["amount:asc", "amount:desc", "timestamp:asc", "timestamp:desc"]

timestamp:desc
Response
{
  "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": {}
}
Example: Getting a transaction by transaction ID
{
    "jsonrpc": "2.0",
    "method": "get.transactions",
    "params": {
        "transactionId": "222675625422353767"
    }
}
Example: Getting the last 25 transactions for account 14935562234363081651L
{
    "jsonrpc": "2.0",
    "method": "get.transactions",
    "params": {
        "address": "lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu",
        "limit": "25"
    }
}

post.transactions

Posts transactions to the network.

No parameters.

Example Response
{
  "message": "Transaction payload was successfully passed to the network node"
  "transactionId": "123456789"
}
Example: Posting a transaction
{
    "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.

Table 7. Parameters
Parameter Type Validation Default Comment

interval

String

["day", "month"]

(empty)

Required field.

limit

Number

<1;103>

10

offset

Number

<0;+Inf>

0
Response
{
    "data": {
      "timeline": [
        {
          "timestamp": 1556100060,
          "date": "2019-11-27",
          "transactionCount": "14447177193385",
          "volume": "14447177193385"
        }
      ],
      "distributionByOperation": {},
      "distributionByAmount": {}
    },
    "meta": {
      "count": 100,
      "offset": 25,
      "total": 43749
    },
    "links": {}
}
Example: Get transaction statistics for past 7 days
{
    "jsonrpc": "2.0",
    "method": "get.transactions.statistics",
    "params": {
        "interval": "day",
        "limit": 7
    }
}

get.transactions.schemas

Retrieves transaction schema for certain transaction payloads.

Table 8. Parameters
Parameter Type Validation Default Comment

moduleAssetId

String

ModuleId:AssetId /[0-9]+:[0-9]+/

(empty)

Transfer transaction: moduleID = 2,assetID = 0

moduleAssetName

String

ModuleName:AssetName /[a-z]+:[a-z]+/

(empty)

Transfer transaction: moduleName = token, assetName = transfer
Response
{
  "data": [
    {
      "moduleAssetId": "2:0",
      "moduleAssetName": "token:transfer",
      "schema": {
        ...
      }
    },
  ],
  "meta": {
    "count": 10,
    "offset": 0,
    "total": 10
  },
  "links": {}
}
Example: Get transaction schema for token transfer
{
    "jsonrpc": "2.0",
    "method": "get.transactions.schemas",
    "params": {
        "moduleAssetName": "token:transfer"
    }
}

Fees

get.fees

Requests transaction fee estimates per byte.

No parameters.

Response
{
  "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": {}
}
Example: Get fees
{
    "jsonrpc": "2.0",
    "method": "get.fees",
}

Peers

get.peers

Retrieves network peers with details based on criteria.

Supports pagination.

Table 9. Parameters
Parameter Type Validation Default Comment

ip

String

/^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/

(empty)

networkVersion

String

/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-(0|[1-9]\d*|\d*[a-zA-Z-])(\.(0|[1-9]\d|\d*[a-zA-Z-])))?(\+[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$/

(empty)

state

Array of strings

["connected", "disconnected", "any"]

connected

height

Number

<1;+Inf>

(empty)

limit

Number

<1;100>

10

offset

Number

<0;+Inf>

0

sort

Array of strings

["height:asc", "height:desc", "networkVersion:asc", "networkVersion:desc"]

height:desc
Response
{
    "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": {}
}
Example: Get hosts with a specific IP address
{
    "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.

Response
{
  "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": {}
}
Example
{
    "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.

Response
{
    "data": {
      "basic": {
        "connectedPeers": 134,
        "disconnectedPeers": 48,
        "totalPeers": 181
      },
      "height": {
        "7982598": 24
      },
      "networkVersion": {
        "2.0": 12,
        "2.1": 41
      }
    },
    "meta": {},
    "links": {}
  }
Example
{
    "jsonrpc": "2.0",
    "method": "get.network.statistics"
}

Off-chain Features

Market Prices

Retrieves current market prices.

Endpoints

  • HTTP /api/v2/market/prices

  • RPC get.market.prices

Request parameters

(no params)

Response example

200 OK
{
  "data": [
    {
      "code": "BTC_EUR",
      "from": "BTC",
      "rate": "53623.7800",
      "sources": [
          "binance"
      ],
      "to": "EUR",
      "updateTimestamp": 1634649300
    },
  ],
  "meta": {
      "count": 7
  }
}
503 Service Unavailable
{
  "error": true,
  "message": "Service is not ready yet"
}

News Feed Aggregator

Retrieves recent blogposts from Lisk Blog and Twitter.

Supports pagination.

Endpoints

  • HTTP: /api/v2/newsfeed

  • RPC: get.newsfeed

Request parameters

Table 10. The Lisk Service microservices
Parameter Type Validation

source

String

/[A-z]+/ | *

Retrieves all sources by default.

limit

Number

<1;100>

offset

Number

<0;+Inf>

Response example

200 OK
{
  "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

Invalid parameter
```
{
  "error": true,
  "message": "Unknown input parameter(s): <param_name>"
}
Invalid source name
{
    "error": true,
    "message": "Invalid input: The 'source' field fails to match the required pattern."
}
503 Service Unavailable
{
  "error": true,
  "message": "Service is not ready yet"
}