HTTP API plugin

Registering the plugin

How to register the HTTP API plugin with the blockchain application.

const { Application, HTTPAPIPlugin, genesisBlockDevnet, configDevnet } = require('lisk-sdk');

const app = Application.defaultApplication(genesisBlockDevnet, configDevnet);

app.registerPlugin(HTTPAPIPlugin);

app
  .run()
  .then(() => app.logger.info('App started...'))
  .catch(error => {
    console.error('Faced error in application', error);
    process.exit(1);
  });

Default configuration

The HTTP API plugin can be configured in the configuration of the blockchain application under plugins.httpApi.

The application will use the default values, in case no plugin configuration is provided.
API access options in the configuration
const { Application, HTTPAPIPlugin, genesisBlockDevnet, configDevnet } = require('lisk-sdk');

const appConfig = utils.objects.mergeDeep({}, configDevnet, {
  plugins: {
    httpApi: { (1)
		port: 4000, (2)
		whiteList: ['127.0.0.1'], (3)
		cors: { (4)
			origin: '*', (5)
			methods: ['GET', 'POST', 'PUT'], (6)
		},
		limits: { (7)
			max: 0, (8)
			delayMs: 0, (9)
			delayAfter: 0, (10)
			windowMs: 60000, (11)
			headersTimeout: 5000, (12)
			serverSetTimeout: 20000, (13)
		},
	},
  }
});

const app = Application.defaultApplication(genesisBlockDevnet, appConfig);

app.registerPlugin(HTTPAPIPlugin);

app
  .run()
  .then(() => app.logger.info('App started...'))
  .catch(error => {
    console.error('Faced error in application', error);
    process.exit(1);
  });
1 httpApi: Contains options for the HTTP API plugin.
2 port: HTTP port which the HTTP API plugin listens on.
3 whiteList: This parameter allows connections to the HTTP API only by IPs mentioned here. Defaults to only allow local host.
4 cors: Contain options for CORS, (Cross-Origin Resource Sharing).
5 origin: Defines the domains that can access the resource in a cross-site manner. Defaults to all domains.
6 methods(optional): Defines the allowed methods for CORS.
7 limits: Contains options about time limits.
8 max: Maximum number of API connections.
9 delayMs: Minimum delay between API calls in ms.
10 delayAfter: Minimum delay after an API call in ms
11 windowMs: Minimum delay between API calls from the same window.
12 headersTimeout: Maximum time an idle connection will be kept open, (in seconds).
13 serverSetTimeout: Maximum time to wait for response from the server before timing out.

If the options are not present in the config, you can manually add them under the plugins property of your configuration object.

The recommended setup is to configure a whitelist only for trusted IP addresses, such as your home connection.

Use IPV4 (Internet Protocol Version 4), addresses only as the whitelist does not support IPV6 (Internet Protocol Version 6).

API specification

Access restrictions

The API endpoints are by default restricted to a whitelist of IPs that can be found under plugins.httpApi.whiteList in the config. If it is required for your API to be accessible by the public, this can be achieved by changing plugins.httpApi.whiteList to []. This will allow anyone to make requests to your application.

Requests

Chained filter parameters are logically connected with AND. HTTP is the supported URL schema by default.

Responses

The general response format is JSON (application/json). The responses for each API request have a common basic structure as shown below:

{
    "data": {}, //Contains the requested data.
    "meta": {}, //Contains additional metadata, e.g. the values of `limit` and `offset`.
}

List of endpoints

All possible API endpoints for Lisk Core are listed below. Click on an endpoint to view the descriptions, details and examples.

Version information

Version : 1.0.32

Contact information

Contact Email : admin@lisk.com

License information

License : Apache 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
Terms of service : null

URI scheme

BasePath : /api
Schemes : HTTP

Tags

  • Accounts : Account related API endpoints.

  • Blocks : Block related API endpoints.

  • Delegates : Delegates related API endpoints.

  • Node : Node related API endpoints.

  • Peers : Peers related API endpoints.

  • Transactions : Transactions related API endpoints.

Paths

Requests account data.

GET /accounts/{address}
Description

Search for matching account in the system.

Parameters
Type Name Description Schema

Path

address
required

The binary address in hex format as defined in LIP-0018.

string

Responses
HTTP Code Description Schema

200

Account requested.

400

Malformed query or parameters.

404

Data not found.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Accounts

Requests block data

GET /blocks
Description

Search for block in the system by height.

Parameters
Type Name Description Schema

Query

height
required

height of the searching block.

integer

Responses
HTTP Code Description Schema

200

Block requested.

400

Malformed query or parameters.

404

Data not found.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Blocks

Requests block data

GET /blocks/{id}
Description

Search for block in the system by ID.

Parameters
Type Name Description Schema

Path

id
required

id of the searching block in hex format

string

Responses
HTTP Code Description Schema

200

Block requested.

400

Malformed query or parameters.

404

Data not found.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Blocks

Requests delegates data.

GET /delegates
Description

Search for a specified delegate in the system.

Parameters
Type Name Description Schema Default

Query

limit
optional

Limit applied to results.

integer (int32)

10

Query

offset
optional

Offset value for results.

integer (int32)

0

Responses
HTTP Code Description Schema

200

Registered delegate accounts.

400

Malformed query or parameters.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Delegates

Requests next forgers data.

GET /forgers
Description

Returns a list of the next forgers in this delegate round.

Responses
HTTP Code Description Schema

200

A list of the next forgers.

400

Malformed query or parameters.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Delegates

Toggles the forging status of a delegate.

PATCH /forging
Description

Upon passing the correct password and address, forging will be enabled or disabled for the delegate of this particular node. The password can be generated locally by encrypting your passphrase, either by using Lisk Commander or with Lisk Elements.

Parameters
Type Name Description Schema

Body

data
required

Password for decrypting passphrase of delegate for its corresponding address.

data

Name Description Schema

address
required

Address of the delegate.
Example : "0903f4c5cb599a7928aef27e294e98293d1e3888"

string (hex)

forging
required

Forging status of the delegate.
Example : true

boolean

height
optional

Last forged block height.
Example : 100.0

number

maxHeightPreviouslyForged
required

Delegates largest previously forged height.
Example : 100.0

number

maxHeightPrevoted
required

Delegates largest prevoted height for a block.
Example : 10.0

number

overwrite
required

Boolean flag to overwrite forger info.
Example : true

boolean

password
required

Password for decrypting passphrase of delegate.
Minimum length : 5
Example : "happy tree friends elephant tree"

string

Responses
HTTP Code Description Schema

200

Delegate forging toggled on or off.

400

Malformed query or parameters.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Consumes
  • application/json

Produces
  • application/json

Tags
  • Node

Request forging status of forgers.

GET /forging/info
Description

Gives a list of all forgers and their info.

Responses
HTTP Code Description Schema

200

List of forgers.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Forging

Requests node information

GET /node/info
Description

Returns information of the running node, e.g. height.

Responses
HTTP Code Description Schema

200

Node info response.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Node

Requests unprocessed transactions data.

GET /node/transactions
Description

Search for specific transactions by providing the appropriate parameters.

Parameters
Type Name Description Schema Default

Query

limit
optional

Limit applied to results.

integer (int32)

10

Query

offset
optional

Offset value for results.

integer (int32)

0

Responses

HTTP Code Description Schema

200

Transactions list.

400

Malformed query or parameters.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Node

  • Transactions

Requests peers data.

GET /peers
Description

Search for specified peers.

Parameters
Type Name Description Schema Default

Query

limit
optional

Limit applied to results.

integer (int32)

10

Query

offset
optional

Offset value for results.

integer (int32)

0

Query

state
optional

Current state of the network.

enum (connected, disconnected)

Responses
HTTP Code Description Schema

200

List of peers.

400

Malformed query or parameters.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Peers

Submits signed transaction for processing.

POST /transactions
Description

Submits signed transaction object for processing by the transaction pool.

Parameters
Type Name Description Schema

Body

transaction
required

Transaction object for processing by the transaction pool.

Responses
HTTP Code Description Schema

200

Transaction requested.

400

Malformed query or parameters.

409

Some error related to processing of request.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Consumes
  • application/json

Produces
  • application/json

Tags
  • Transactions

Requests transaction data

GET /transactions/{id}
Description

Search for transaction in the system by ID.

Parameters
Type Name Description Schema

Path

id
required

id of the searching transaction in hex format.

string

Responses
HTTP Code Description Schema

200

Transaction requested.

400

Malformed query or parameters.

404

Data not found.

429

Too many requests, exceeded rate limit.

500

Unexpected error.

Produces
  • application/json

Tags
  • Transactions

Definitions

Account

Name Description Schema

address
required

The binary address in hex format as defined in LIP-0018.
Example : "9d0149b0962d44bfc08a9f64d5afceb6281d7fb5"

string

dpos
required

keys
required

sequence
required

token
required

dpos

Name Schema

delegate
required

sentVotes
required

< sentVotes > array

unlocking
required

< unlocking > array

delegate

Name Schema

consecutiveMissedBlocks
required

number

isBanned
required

boolean

lastForgedHeight
required

number

pomHeights
required

< number > array

totalVotesReceived
required

string

username
required

string

sentVotes

Name Schema

amount
required

string

delegateAddress
required

string

unlocking

Name Schema

amount
required

string

delegateAddress
required

string

unvoteHeight
required

number

keys

Name Description Schema

mandatoryKeys
required

Hex encoded value of mandatory multi-signature account members public keys.

< string > array

numberOfSignatures
required

Number of required signatures.

number

optionalKeys
required

Hex encoded value of optional multi-signature account members public keys.

< string > array

sequence

Name Description Schema

nonce
required

The current nonce associated to account for transaction processing.
Example : "154"

string

token

Name Description Schema

balance
required

The current balance of the account in Beddows.
Example : "1081560729258"

string

AccountResponse

Name Schema

data
required

meta
optional

object

BlockAsset

Name Description Schema

maxHeightPreviouslyForged
required

The largest height of any block previously forged by the forging delegate.

number

maxHeightPrevoted
required

The largest height of any block previously prevoted by the forging delegate.

number

seedReveal
required

Hex encoded value that contains the new seed value revealed after each round by the forging delegate.

string

BlockHeader

Name Description Schema

asset
required

Object stored in the block header as defined by the application.

generatorPublicKey
required

Hex encoded value of public key of the delegate who forged the block.

string

height
required

Height of the network, when the block was forged. The height of the network represents the number of blocks that have been forged on the network since the genesis block.

number

id
required

Hex encoded value of the unique identifier of the block.

string

previousBlockID
required

Hex encoded value of the ID of the previous block of the chain.

string

reward
required

The reward for the delegate.

string

signature
optional

Hex encoded value of the signature for the block.

string

timestamp
required

Unix timestamp of block created in seconds.

number

transactionRoot
required

Hex encoded value of Merkle tree root of the transaction IDs.

string

version
required

Versioning for future upgrades of the Lisk protocol.

number

BlockResponse

Name Schema

data
required

meta
optional

object

data

Name Schema

header
required

payload
required

< Transaction > array

BlocksResponse

Name Schema

data
required

< data > array

meta
optional

object

data

Name Schema

header
required

payload
required

< Transaction > array

DelegateResponse

Name Schema

data
required

< Account > array

meta
optional

ErrorResponse

Name Schema

errors
required

< errors > array

errors

Name Description Schema

message
optional

Error message containing details of the error.
Minimum length : 1
Example : "Reason of the error"

string

Forger

Name Description Schema

address
required

The binary address in hex format as defined in LIP-0018.
Example : "9d0149b0962d44bfc08a9f64d5afceb6281d7fb5"

string

nextForgingTime
required

Returns the unix timestamp in seconds in which the forger will be able to forge the next block. Each slot has a timespan of 10 seconds.
Example : 4368793.0

number

totalVotesReceived
optional

The total votes received by the delegate. Represents the total amount of tokens that the delegates voters casted votes for this delegate.
Example : "1081560729258"

string

username
required

The delegates username. A delegate chooses the username by registering a delegate on the network. It is unique and cannot be changed later.
Example : "genesis_01"

string

ForgersResponse

Name Description Schema

data
required

List of forgers.

< Forger > array

meta
optional

object

ForgingStatus

Name Description Schema

address
required

Address of the delegate.
Example : "0903f4c5cb599a7928aef27e294e98293d1e3888"

string (hex)

forging
required

True if the delegate enabled forging.
Example : true

boolean

height
required

Height of the forger.
Example : 234577.0

number

maxHeightPreviouslyForged
required

The largest height of any block previously forged by the forging delegate.
Example : 234534.0

number

maxHeightPrevoted
required

The largest height of any block previously prevoted by the forging delegate.
Example : 10.0

number

ForgingStatusResponse

Name Schema

data
required

< ForgingStatus > array

meta
required

meta

Name Description Schema

count
optional

Number of records returned in response.
Minimum value : 0

integer

GenesisBlockAsset

Name Description Schema

accounts
required

Array of initial forging delegate accounts.

< Account > array

initDelegates
required

Array of public keys of initial forging delegates.

< string > array

initRounds
required

Number of rounds for bootstrapping period.

number

Meta

Name Description Schema

limit
required

Limit applied to results.
Minimum value : 1

integer

offset
required

Offset value for results.
Default : 0
Minimum value : 0

integer (int32)

NodeInfo

Name Description Schema

finalizedHeight
required

The largest height with precommits by at least 68 delegates. See https://github.com/LiskHQ/lips/blob/master/proposals/lip-0014.md
Example : 123

integer

genesisConfig
required

height
required

Current block height of the node. Represents the current number of blocks in the chain on the node.
Minimum value : 1
Example : 123

integer

lastBlockID
required

ID of the last processed block.
Example : "vPFBr0ZTsyP9hUwKaQD8dW2lKBpgMWkRdgrTUUmBBCE="

string

networkIdentifier
required

Hex encoded value of the network identifier as per LIP-0009.
Example : "93d00fe5be70d90e7ae247936a2e7d83b50809c79b73fa14285f02c842348b3e"

string

networkVersion
required

The protocol version of Lisk Core that the peer node runs on.
Example : "1.1"

string

syncing
required

True if the node is syncing with other peers.
Example : false

boolean

unconfirmedTransactions
required

Number of unprocessed transactions in the pool.
Minimum value : 0
Example : 1

integer

version
required

The application version that the node is running on.
Example : "v0.8.0"

string (version)

genesisConfig

Name Description Schema

activeDelegates
required

Number of active delegates per round.
Example : 101

integer

blockTime
required

Block time interval in seconds.
Minimum value : 2
Example : 10

integer

communityIdentifier
optional

The unique name of the relevant community as a string encoded in UTF-8 format.
Example : "Lisk"

string

delegateListRoundOffset
required

Number of previous rounds in which the list of delegates will be used for the current round.
Example : 2

integer

maxPayloadLength
required

Maximum size of transactions allowed per block.
Example : 15360

integer

rewards
required

standbyDelegates
required

Number of standby delegates per round.
Example : 2

integer

totalAmount
optional

Total amount of LSK available in the network before the rewards milestone started.
Example : "10000000000000000"

string

rewards

Name Description Schema

distance
required

Distance in height between each milestone.
Example : 3000000

integer

milestones
required

Array of rewards.

< string > array

offset
required

Height in which the reward distribution starts.
Minimum value : 1
Example : 2160

integer

NodeInfoResponse

Name Schema

data
required

meta
optional

object

Peer

Name Description Schema

ipAddress
required

IPv4 address of the peer node.
Example : "127.0.0.1"

string

networkIdentifier
required

Hex encoded value of the network identifier as per LIP-0009.
Example : "93d00fe5be70d90e7ae247936a2e7d83b50809c79b73fa14285f02c842348b3e"

string

networkVersion
required

The protocol version of Lisk Core that the peer node runs on.
Example : "1.1"

string

options
required

Optional field defined by the application.

object

port
required

The port the peer node uses for P2P communication.
Minimum value : 1
Maximum value : 65535
Example : 8001

integer

state
required

The state of the peer.
Example : "connected"

enum (connected, disconnected)

PeersResponse

Name Schema

data
required

< Peer > array

meta
optional

Transaction

Name Description Schema

asset
required

Object stored per transaction type.

object

assetID
optional

Asset Id for the transaction asset.

number

fee
required

Transaction fee associated with this transaction.

string

id
required

Hex encoded value of the unique identifier of the transaction.

string

moduleID
optional

Module Id for the transaction asset.

number

nonce
required

Unique sequence of number per account.
Example : "1"

string

senderPublicKey
required

Hex encoded value of the public key of the Senders account.

string

signatures
required

< string > array

TransactionCreateResponse

Name Schema

data
required

meta
optional

object

data

Name Schema

transactionId
required

string

TransactionRequest

Name Description Schema

asset
required

Object stored per transaction type.

object

assetID
required

Asset Id for the transaction asset.

number

fee
required

Transaction fee associated with this transaction.

string

moduleID
required

Module Id for the transaction asset.

number

nonce
required

Unique sequence of number per account.
Example : "1"

string

senderPublicKey
required

Hex encoded value of the public key of the Senders account.

string

signatures
required

< string > array

TransactionResponse

Name Schema

data
required

meta
optional

object

TransactionsResponse

Name Schema

data
required

< Transaction > array

meta
optional