@polkadot/api-derive

What is @polkadot/api-derive?

@polkadot/api-derive is a collection of derived methods for interacting with the Polkadot and Substrate blockchains. It provides higher-level abstractions over the basic API calls, making it easier to work with complex blockchain data.

What are @polkadot/api-derive's main functionalities?

Account Balances

This feature allows you to retrieve all balance-related information for a specific account, including free balance, reserved balance, and more. The code sample demonstrates how to use the `all` method from the balances derive module to fetch this data.

const { ApiPromise, WsProvider } = require('@polkadot/api');
const { all } = require('@polkadot/api-derive/balances');

async function main() {
  const provider = new WsProvider('wss://rpc.polkadot.io');
  const api = await ApiPromise.create({ provider });
  const account = '5F3sa2TJAWMqDhXG6jhV4N8ko9rLh5N1zWQ4i5Q3r1uXkP4q';
  const balances = await all(api, account);
  console.log(balances);
}

main().catch(console.error);

Staking Information

This feature provides detailed staking information for a specific account, such as the staking ledger, rewards, and nominations. The code sample shows how to use the `info` method from the staking derive module to obtain this information.

const { ApiPromise, WsProvider } = require('@polkadot/api');
const { staking } = require('@polkadot/api-derive');

async function main() {
  const provider = new WsProvider('wss://rpc.polkadot.io');
  const api = await ApiPromise.create({ provider });
  const stakingInfo = await staking.info(api, '5F3sa2TJAWMqDhXG6jhV4N8ko9rLh5N1zWQ4i5Q3r1uXkP4q');
  console.log(stakingInfo);
}

main().catch(console.error);

Chain Information

This feature allows you to access chain-related information, such as the best block number. The code sample demonstrates how to use the `bestNumber` method from the chain derive module to get the current best block number.

const { ApiPromise, WsProvider } = require('@polkadot/api');
const { chain } = require('@polkadot/api-derive');

async function main() {
  const provider = new WsProvider('wss://rpc.polkadot.io');
  const api = await ApiPromise.create({ provider });
  const bestNumber = await chain.bestNumber(api);
  console.log(`Best block number: ${bestNumber}`);
}

main().catch(console.error);

Other packages similar to @polkadot/api-derive

@polkadot/api

@polkadot/api is the main API library for interacting with Polkadot and Substrate nodes. It provides the foundational methods for querying and interacting with the blockchain, whereas @polkadot/api-derive builds on top of it to offer higher-level abstractions and derived data.

ethers

Ethers.js is a library for interacting with the Ethereum blockchain. While it is not specific to Polkadot, it offers similar functionalities for Ethereum, such as querying account balances and interacting with smart contracts. It provides a comprehensive API for Ethereum, similar to how @polkadot/api-derive provides derived methods for Polkadot.

web3

Web3.js is another library for interacting with the Ethereum blockchain. Like ethers.js, it provides methods for interacting with Ethereum nodes, querying blockchain data, and sending transactions. It serves a similar purpose for Ethereum as @polkadot/api-derive does for Polkadot, offering higher-level abstractions over basic API calls.

README

@polkadot/api-derive

Collection of high-level utility functions built on top of the @polkadot/api library. Designed to simplify the process of querying complex on-chain data by combining multiple RPC calls, storage queries, and runtime logic into a single, callable function.

Instead of manually fetching and processing blockchain data, developers can use api.derive methods to retrieve information.

Available Derive Namespaces

The derive functions are categorized into namespaces based on different common Substrate modules. Accesible by calling api.derive.NAMESPACE (e.g. api.derive.balances). The available modules are as follows:

• accounts
• alliance
• bagsList
• balances
• bounties
• chain
• contracts
• council
• crowdloan
• democracy
• elections
• imOnline
• membership
• parachains
• session
• society
• staking
• technicalCommittee
• treasury
• tx

Changelog

16.2.2 Jun 17, 2025

Changes:

• feat(types-codec): Add maximum depth limit in decodeU8a functions (#6168)
• bump polkadotjs/common to 13.5.2 (#6170)