HTTP API plugin

Provides a RESTful HTTP API for a Lisk node.

To use the HTTP API, it is necessary to register the HTTP API plugin to the application.

API access options in the configuration
{
  //[...]
  plugins: {
    httpApi: { (1)
		port: 4000,
		whiteList: ['127.0.0.1'], (2)
		cors: {
			origin: '*',
			methods: ['GET', 'POST', 'PUT'],
		},
		limits: {
			max: 0,
			delayMs: 0,
			delayAfter: 0,
			windowMs: 60000,
			headersTimeout: 5000,
			serverSetTimeout: 20000,
		},
	},
  }
}
1 Contains options for the API module.
2 This parameter allows connections to the API by IP. Defaults to only allow local host.
If the options are not present in the config, you can manually add them in under the plugins property of your configuration object.

The recommended setup is to configure a whitelist for only trusted IP addresses, such as your home connection. Use IPV4 addresses only as the whitelist does not support IPV6.

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 show the descriptions, details and examples.

Version information

Version : 1.0.32

Contact information

Contact Email : admin@lisk.io

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

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 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 second

number

transactionRoot
required

Hex encoded value of Merkle tree root of 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 second 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 token that the delegates voters voted 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

GenesisBlockAsset

Name Description Schema

accounts
required

Array of 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 rounds before 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 network before 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 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 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 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 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 transaction asset

number

fee
required

Transaction fee associated with this transaction.

string

moduleID
required

Module Id for 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