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. |
{
//[...]
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.
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
Paths
Requests account data.
GET /accounts/{address}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
address |
The binary address in hex format as defined in LIP-0018. |
string |
Requests block data
GET /blocks
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query |
height |
height of the searching block. |
integer |
Requests block data
GET /blocks/{id}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
id of the searching block in hex format |
string |
Requests delegates data.
GET /delegates
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
limit |
Limit applied to results. |
integer (int32) |
|
Query |
offset |
Offset value for results. |
integer (int32) |
|
Requests next forgers data.
GET /forgers
Requests node information
GET /node/info
Requests unprocessed transactions data.
GET /node/transactions
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
limit |
Limit applied to results. |
integer (int32) |
|
Query |
offset |
Offset value for results. |
integer (int32) |
|
Requests peers data.
GET /peers
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
limit |
Limit applied to results. |
integer (int32) |
|
Query |
offset |
Offset value for results. |
integer (int32) |
|
Query |
state |
Current state of the network. |
enum (connected, disconnected) |
Submits signed transaction for processing.
POST /transactions
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
transaction |
Transaction object for processing by the transaction pool. |
Requests transaction data
GET /transactions/{id}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
id of the searching transaction in hex format |
string |
Definitions
Account
Name | Description | Schema |
---|---|---|
address |
The binary address in hex format as defined in LIP-0018. |
string |
dpos |
||
keys |
||
sequence |
||
token |
dpos
Name | Schema |
---|---|
delegate |
|
sentVotes |
< sentVotes > array |
unlocking |
< unlocking > array |
delegate
Name | Schema |
---|---|
consecutiveMissedBlocks |
number |
isBanned |
boolean |
lastForgedHeight |
number |
pomHeights |
< number > array |
totalVotesReceived |
string |
username |
string |
sentVotes
Name | Schema |
---|---|
amount |
string |
delegateAddress |
string |
unlocking
Name | Schema |
---|---|
amount |
string |
delegateAddress |
string |
unvoteHeight |
number |
keys
Name | Description | Schema |
---|---|---|
mandatoryKeys |
Hex encoded value of mandatory multi-signature account members public keys |
< string > array |
numberOfSignatures |
Number of required signatures |
number |
optionalKeys |
Hex encoded value of optional multi-signature account members public keys |
< string > array |
sequence
Name | Description | Schema |
---|---|---|
nonce |
The current nonce associated to account for transaction processing. |
string |
token
Name | Description | Schema |
---|---|---|
balance |
The current balance of the account in Beddows. |
string |
BlockAsset
Name | Description | Schema |
---|---|---|
maxHeightPreviouslyForged |
The largest height of any block previously forged by the forging delegate. |
number |
maxHeightPrevoted |
The largest height of any block previously prevoted by the forging delegate. |
number |
seedReveal |
Hex encoded value that contains the new seed value revealed each round by the forging delegate. |
string |
BlockHeader
Name | Description | Schema |
---|---|---|
asset |
Object stored in the block header as defined by the application |
|
generatorPublicKey |
Hex encoded value of public key of the delegate who forged the block. |
string |
height |
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 |
Hex encoded value of the unique identifier of the block. |
string |
previousBlockID |
Hex encoded value of the ID of the previous block of the chain. |
string |
reward |
The reward for the delegate. |
string |
signature |
Hex encoded value of the signature for the block. |
string |
timestamp |
Unix timestamp of block created in second |
number |
transactionRoot |
Hex encoded value of Merkle tree root of transaction IDs |
string |
version |
Versioning for future upgrades of the Lisk protocol. |
number |
BlockResponse
Name | Schema |
---|---|
data |
|
meta |
object |
data
Name | Schema |
---|---|
header |
|
payload |
< Transaction > array |
BlocksResponse
Name | Schema |
---|---|
data |
< data > array |
meta |
object |
data
Name | Schema |
---|---|
header |
|
payload |
< Transaction > array |
ErrorResponse
Name | Schema |
---|---|
errors |
< errors > array |
errors
Name | Description | Schema |
---|---|---|
message |
Error message containing details of the error. |
string |
Forger
Name | Description | Schema |
---|---|---|
address |
The binary address in hex format as defined in LIP-0018. |
string |
nextForgingTime |
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. |
number |
totalVotesReceived |
The total votes received by the delegate.
Represents the total amount of token that the delegates voters voted this delegate. |
string |
username |
The delegates username.
A delegate chooses the username by registering a delegate on the network.
It is unique and cannot be changed later. |
string |
ForgersResponse
Name | Description | Schema |
---|---|---|
data |
List of forgers. |
< Forger > array |
meta |
object |
GenesisBlockAsset
Name | Description | Schema |
---|---|---|
accounts |
Array of of initial forging delegate accounts. |
< Account > array |
initDelegates |
Array of public keys of initial forging delegates. |
< string > array |
initRounds |
Number of rounds for bootstrapping period. |
number |
Meta
Name | Description | Schema |
---|---|---|
limit |
Limit applied to results. |
integer |
offset |
Offset value for results. |
integer (int32) |
NodeInfo
Name | Description | Schema |
---|---|---|
finalizedHeight |
The largest height with precommits by at least 68 delegates.
See https://github.com/LiskHQ/lips/blob/master/proposals/lip-0014.md |
integer |
genesisConfig |
||
height |
Current block height of the node.
Represents the current number of blocks in the chain on the node. |
integer |
lastBlockID |
ID of the last processed block. |
string |
networkIdentifier |
Hex encoded value of the network identifier as per LIP-0009. |
string |
networkVersion |
The protocol version of Lisk Core that the peer node runs on. |
string |
syncing |
True if the node is syncing with other peers. |
boolean |
unconfirmedTransactions |
Number of unprocessed transactions in the pool. |
integer |
version |
The application version that the node is running on. |
string (version) |
genesisConfig
Name | Description | Schema |
---|---|---|
activeDelegates |
Number of active delegates per round. |
integer |
blockTime |
Block time interval in seconds. |
integer |
communityIdentifier |
The unique name of the relevant community as a string encoded in UTF-8 format. |
string |
delegateListRoundOffset |
Number of rounds before in which the list of delegates will be used for the current round. |
integer |
maxPayloadLength |
Maximum size of transactions allowed per block. |
integer |
rewards |
||
standbyDelegates |
Number of standby delegates per round. |
integer |
totalAmount |
Total amount of LSK available in network before rewards milestone started |
string |
rewards
Name | Description | Schema |
---|---|---|
distance |
Distance in height between each milestone. |
integer |
milestones |
Array of rewards. |
< string > array |
offset |
height in which reward distribution starts. |
integer |
Peer
Name | Description | Schema |
---|---|---|
ipAddress |
IPv4 address of the peer node. |
string |
networkIdentifier |
Hex encoded value of the network identifier as per LIP-0009. |
string |
networkVersion |
The protocol version of Lisk Core that the peer node runs on. |
string |
options |
Optional field defined by application |
object |
port |
The port the peer node uses for P2P communication. |
integer |
state |
The state of the peer. |
enum (connected, disconnected) |
Transaction
Name | Description | Schema |
---|---|---|
asset |
Object stored per transaction type |
object |
assetID |
Asset Id for transaction asset |
number |
fee |
Transaction fee associated with this transaction. |
string |
id |
Hex encoded value of the unique identifier of the transaction. |
string |
moduleID |
Module Id for transaction asset |
number |
nonce |
Unique sequence of number per account. |
string |
senderPublicKey |
Hex encoded value of the public key of the Senders account. |
string |
signatures |
< string > array |
TransactionCreateResponse
Name | Schema |
---|---|
data |
|
meta |
object |
data
Name | Schema |
---|---|
transactionId |
string |
TransactionRequest
Name | Description | Schema |
---|---|---|
asset |
Object stored per transaction type |
object |
assetID |
Asset Id for transaction asset |
number |
fee |
Transaction fee associated with this transaction. |
string |
moduleID |
Module Id for transaction asset |
number |
nonce |
Unique sequence of number per account. |
string |
senderPublicKey |
Hex encoded value of the public key of the Senders account. |
string |
signatures |
< string > array |
TransactionsResponse
Name | Schema |
---|---|
data |
< Transaction > array |
meta |