Skip to content

Polkadot.js API

Introduction

The Polkadot.js API uses JavaScript/TypeScript to interact with Polkadot SDK-based chains. It allows you to query nodes, read chain state, and submit transactions through a dynamic, auto-generated API interface.

Dynamic API Generation

Unlike traditional static APIs, the Polkadot.js API generates its interfaces automatically when connecting to a node. Here's what happens when you connect:

  1. The API connects to your node
  2. It retrieves the chain's metadata
  3. Based on this metadata, it creates specific endpoints in this format: api.<type>.<module>.<section>

Available API Categories

You can access three main categories of chain interactions:

  • Runtime constants (api.consts)

    • Access runtime constants directly
    • Returns values immediately without function calls
    • Example - api.consts.balances.existentialDeposit

  • State queries (api.query)

    • Read chain state
    • Example - api.query.system.account(accountId)

  • Transactions (api.tx)

    • Submit extrinsics (transactions)
    • Example - api.tx.balances.transfer(accountId, value)

The available methods and interfaces will automatically reflect what's possible on your connected chain.

Installation

To add the Polkadot.js API to your project:

npm i @polkadot/api

pnpm add @polkadot/api

yarn add @polkadot/api

This command installs the latest stable release, which supports any Polkadot SDK-based chain.

Note

For more installation details, refer to the Installation section in the official Polkadot.js API documentation.

Get Started

Creating an API Instance

To interact with a Polkadot SDK-based chain, you must establish a connection through an API instance. The API provides methods for querying chain state, sending transactions, and subscribing to updates.

To create an API connection:

import { ApiPromise, WsProvider } from '@polkadot/api';

// Create a WebSocket provider
const wsProvider = new WsProvider('wss://rpc.polkadot.io');

// Initialize the API
const api = await ApiPromise.create({ provider: wsProvider });

// Verify the connection by getting the chain's genesis hash
console.log('Genesis Hash:', api.genesisHash.toHex());

Note

All await operations must be wrapped in an async function or block since the API uses promises for asynchronous operations.

Reading Chain Data

The API provides several ways to read data from the chain. You can access:

  • Constants - values that are fixed in the runtime and don't change without a runtime upgrade

    // Get the minimum balance required for a new account
const minBalance = api.consts.balances.existentialDeposit.toNumber();

  • State - current chain state that updates with each block

    // Example address
const address = '5DTestUPts3kjeXSTMyerHihn1uwMfLj8vU8sqF7qYrFabHE';

// Get current timestamp
const timestamp = await api.query.timestamp.now();

// Get account information
const { nonce, data: balance } = await api.query.system.account(address);

console.log(`
  Timestamp: ${timestamp}
  Free Balance: ${balance.free}
  Nonce: ${nonce}
`);

Sending Transactions

Transactions (also called extrinsics) modify the chain state. Before sending a transaction, you need:

  • A funded account with sufficient balance to pay transaction fees
  • The account's keypair for signing

To make a transfer:

// Assuming you have an `alice` keypair from the Keyring
const recipient = 'INSERT_RECIPIENT_ADDRESS';
const amount = 'INSERT_VALUE'; // Amount in the smallest unit (e.g., Planck for DOT)

// Sign and send a transfer
const txHash = await api.tx.balances
  .transfer(recipient, amount)
  .signAndSend(alice);

console.log('Transaction Hash:', txHash);

Note

The alice keypair in the example comes from a Keyring object. See the Keyring documentation for details on managing keypairs.

Where to Go Next

For more detailed information about the Polkadot.js API, check the official documentation.

Edit this page
Last update: November 12, 2024
| Created: November 12, 2024