Interact with the API
This guides describes how to interact with a blockchain network powered by the Lisk SDK.
To interact with a blockchain, it is necessary to communicate with the API of a blockchain node.
As an alternative to the Lisk SDK API, you can use and customize Lisk Service and its API to provide a more extensive API for your interfaces. |
By default, it is only allowed to make API requests to a node from the localhost. To make API requests from remote, use a node with a public API, or deploy your own node and whitelist your IP to make API requests. |
Common interactions
Some examples for most common interactions are listed here.
For JavaScript developers, it is most convenient to use the @liskhq/lisk-api-client.
First perform the installation with npm:
npm i @liskhq/lisk-api-client
Then require it as dependency and create the API client:
const { APIClient } = require('@liskhq/lisk-api-client');
const API_BASEURL = "http://localhost:4000"; (1)
const api = new APIClient([API_BASEURL]);
1 | Replace http://localhost:4000 with the address of the node where you wish to send the API request. |
It is also possible to do the API requests directly from the command line with programs like Curl or Lisk Commander. In addition, it is of course also possible to write an API client based on other languages apart from JavaScript and TypeScript. |
Get transactions
api.transactions.get(options)
Where options
can be any of the params described in the API specification: GET /transactions
const { APIClient } = require('@liskhq/lisk-api-client');
const API_BASEURL = "http://localhost:4000";
const api = new APIClient([API_BASEURL]);
api.transactions.get({ id: '222675625422353767' })
.then(res => {
console.log(res.data);
})
const { APIClient } = require('@liskhq/lisk-api-client');
const API_BASEURL = "http://localhost:4000";
const api = new APIClient([API_BASEURL]);
api.transactions.get({ recipientId: '123L' })
.then(res => {
console.log(res.data);
});
Get blocks
api.blocks.get(options)
Where options
can be any of the params described in the API specification: GET /blocks
const { APIClient } = require('@liskhq/lisk-api-client');
const API_BASEURL = "http://localhost:4000";
const api = new APIClient([API_BASEURL]);
api.blocks.get({ height: '123456' })
.then(res => {
console.log(res.data);
});
Get accounts
await api.accounts.get(options)
Where options
can be any of the params described in the API specification: GET /accounts
const { APIClient } = require('@liskhq/lisk-api-client');
const API_BASEURL = "http://localhost:4000";
const api = new APIClient([API_BASEURL]);
let offset = 0;
let accounts = [];
const accountsArray = [];
async function getAccounts() {
do {
const retrievedAccounts = await api.accounts.get({ limit: 100, offset });
accounts = retrievedAccounts.data;
accountsArray.push(...accounts);
if (accounts.length === 100) {
offset += 100;
}
} while (accounts.length === 100);
return accountsArray;
}
getAccounts().then(accountsArray => console.log(accountsArray));
Create new accounts
First it is necessary to generate a mnemonic passphrase, which will be the 12 word passphrase that belongs to the new account.
This passphrase is then used to generate a public/private key pair that is now also associated to the account.
Last but not least an address
is generated, this is also referred to as the "account ID".
Whilst all these properties now belong to this specific account, it is important to be aware of which information is public, and which information needs to be kept private.
-
passphrase
: The 12 word mnemonic passphrase, ensures all is kept private and safe! However, if this passphrase is lost, then access to the funds of this account is lost as well. -
privateKey
: The cryptographic representation of the human-readablepassphrase
.
-
address
: The public address of this account. Example: 12345L -
publicKey
: The cryptographic representation of the human-readableaddress
.
const cryptography = require('@liskhq/lisk-cryptography');
const { Mnemonic } = require('@liskhq/lisk-passphrase');
const createCredentials = () => {
const passphrase = Mnemonic.generateMnemonic();
const keys = cryptography.getPrivateAndPublicKeyFromPassphrase(
passphrase
);
const credentials = {
address: cryptography.getAddressFromPublicKey(keys.publicKey),
passphrase: passphrase,
publicKey: keys.publicKey,
privateKey: keys.privateKey
};
return credentials;
};
const credentials = createCredentials();
console.log(credentials);
You may have noticed that for creating a new account, there was no API request sent to the network. Therefore there is no record yet regarding this account on the blockchain. For this account to become part of the blockchain, it is necessary to transfer at least 1 token to the newly created account. This balance transfer will create a new record for the account on the blockchain. |
To ensure that no other user can generate the same address from a different passphrase (which could occur), it is necessary to initialize the new account, by sending an outgoing transaction.
This initialization will bind your public key to the address, and ensure the account cannot be hijacked at any point in the future.
const { APIClient } = require('@liskhq/lisk-api-client');
const { TransferTransaction, utils } = require('@liskhq/lisk-transactions');
const {getNetworkIdentifier} = require('@liskhq/lisk-cryptography');
// Generate the network identifier for Devnet
const networkIdentifier = getNetworkIdentifier(
"19074b69c97e6f6b86969bb62d4f15b888898b499777bda56a3a2ee642a7f20a",
"Lisk",
);
const API_BASEURL = "http://localhost:4000";
const api = new APIClient([API_BASEURL]);
let tx = new TransferTransaction({
asset: {
amount: '1',
recipientId: '12345678L',
},
fee: utils.convertLSKToBeddows('0.1'),
nonce: '0',
});
// Replace the passphrase with the passphrase of the newly created account
tx.sign(networkIdentifier,'creek own stem final gate scrub live shallow stage host concert they');
api.transactions.broadcast(tx.toJSON()).then(res => {
console.log("++++++++++++++++ API Response +++++++++++++++++");
console.log(res.data);
console.log("++++++++++++++++ Transaction Payload +++++++++++++++++");
console.log(tx.stringify());
console.log("++++++++++++++++ End Script +++++++++++++++++");
}).catch(err => {
console.log(JSON.stringify(err.errors, null, 2));
});
To conveniently initialize an account, transfer the funds back to the original account.
Just replace the value of the In this case, only the transaction fee needs to be paid to initialize the account. |
If the API responds with a success message in res.data
, the transaction was broadcasted successfully.
Send transactions
To find out how to send a transaction to the network, please refer to the Broadcast a transaction guide.
Further interactions
For a complete reference of all available requests and options, please see the Lisk SDK API specification.
Click here to see the complete reference of the Lisk API client.