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:

In the terminal
npm i @liskhq/lisk-api-client

Then require it as dependency and create the API client:

In a javascript file
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

Syntax
api.transactions.get(options)

Where options can be any of the params described in the API specification: GET /transactions

Get transaction by ID
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);
    })
Get transaction by recipient ID
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

Syntax
api.blocks.get(options)

Where options can be any of the params described in the API specification: GET /blocks

Get block by height
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

Syntax
api.accounts.get(options)

Where options can be any of the params described in the API specification: GET /accounts

Get all 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.

Private properties
  • 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-readable passphrase.

Public properties
  • address: The public address of this account. Example: 12345L

  • publicKey: The cryptographic representation of the human-readable address.

Create new account credentials
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.

Example: Initializing an account by sending a transfer transaction
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 recipientId with the account address.

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.