Interact with the API
This guides describes how to interact with a blockchain network powered by the Lisk SDK.
To interact with the blockchain, communicate with the API of a node, that is connected to the network.
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 install it 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, you want to send the API request to. |
It is of course possible to write an API client based on other languages than javascript and typescript. It is also possible to do the API requests directly from the command line with programs like curl or Lisk Commander. |
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
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 = [];
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);
Create new accounts
First it is needed 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 associated to the account, too.
Last but not least an address
is generated, also referred to as the "account ID".
While all these properties belong now to this specific account, it is important to notice what information is public, and what needs to be kept private.
-
passphrase
: The 12 word mnemonic passphrase, keep this private and safe! If gets lost, the 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 might have noticed that for creating a new account, we actually did not send any API request to the network. That means there is no record yet about 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 (what can happen), it is needed 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 later on.
const { APIClient } = require('@liskhq/lisk-api-client');
const transactions = require('@liskhq/lisk-transactions');
const {getNetworkIdentifier} = require('@liskhq/lisk-cryptography');
// Generate the network identifier for Devnet
const networkIdentifier = getNetworkIdentifier(
"23ce0366ef0a14a91e5fd4b1591fc880ffbef9d988ff8bebf8f3666b0c09597d",
"Lisk",
);
const API_BASEURL = "http://localhost:4000";
const api = new APIClient([API_BASEURL]);
let tx = new transactions.TransferTransaction({
asset: {
amount: '1',
recipientId: '12345678L',
},
networkIdentifier: networkIdentifier,
});
// Replace the passphrase with the passphrase of the newly created account
tx.sign('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 initialize an account conveniently, transfer the funds to back itself.
Just replace the value of 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, refer to the Broadcast a transaction guide.
Further interactions
For a complete reference of all available requests and options, check the Lisk SDK API specification.
Click here to see the complete reference of the Lisk API client.