# polkadot-api

Latest version **3.1.0** (published 2026-09-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install polkadot-api
pnpm add polkadot-api
yarn add polkadot-api
bun add polkadot-api
```

Provides the commands `papi`, `polkadot-api`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2026-09-01 |
| First published | 2024-04-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 20 |
| Unpacked size | 838.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 156 |
| Author | Josep M Sobrepere (https://github.com/josepot) |
| Maintainers | josepot, voliva |

## Links

- npm: https://www.npmjs.com/package/polkadot-api
- Repository: https://github.com/polkadot-api/polkadot-api
- npm.io page: https://npm.io/package/polkadot-api

## Dependencies (20)

- [@rx-state/core](https://npm.io/package/@rx-state/core.md) ^0.1.4
- [@polkadot-api/cli](https://npm.io/package/@polkadot-api/cli.md) 0.22.1
- [@polkadot-api/utils](https://npm.io/package/@polkadot-api/utils.md) 0.4.0
- [@polkadot-api/smoldot](https://npm.io/package/@polkadot-api/smoldot.md) 0.4.7
- [@polkadot-api/pjs-signer](https://npm.io/package/@polkadot-api/pjs-signer.md) 0.8.1
- [@polkadot-api/tx-creator](https://npm.io/package/@polkadot-api/tx-creator.md) 0.2.0
- [@polkadot-api/sm-provider](https://npm.io/package/@polkadot-api/sm-provider.md) 0.3.8
- [@polkadot-api/ws-provider](https://npm.io/package/@polkadot-api/ws-provider.md) 0.9.1
- [@polkadot-api/known-chains](https://npm.io/package/@polkadot-api/known-chains.md) 0.12.3
- [@polkadot-api/ink-contracts](https://npm.io/package/@polkadot-api/ink-contracts.md) 0.7.1
- [@polkadot-api/logs-provider](https://npm.io/package/@polkadot-api/logs-provider.md) 0.2.0
- [@polkadot-api/ws-middleware](https://npm.io/package/@polkadot-api/ws-middleware.md) 0.4.1
- [@polkadot-api/raw-tx-creator](https://npm.io/package/@polkadot-api/raw-tx-creator.md) 0.4.1
- [@polkadot-api/signers-common](https://npm.io/package/@polkadot-api/signers-common.md) 0.3.1
- [@polkadot-api/substrate-client](https://npm.io/package/@polkadot-api/substrate-client.md) 0.7.0
- [@polkadot-api/json-rpc-provider](https://npm.io/package/@polkadot-api/json-rpc-provider.md) 0.2.0
- [@polkadot-api/metadata-builders](https://npm.io/package/@polkadot-api/metadata-builders.md) 0.15.1
- [@polkadot-api/observable-client](https://npm.io/package/@polkadot-api/observable-client.md) 0.19.1
- [@polkadot-api/substrate-bindings](https://npm.io/package/@polkadot-api/substrate-bindings.md) 0.21.1
- [@polkadot-api/metadata-compatibility](https://npm.io/package/@polkadot-api/metadata-compatibility.md) 0.7.1

## Recent versions

- 3.1.0 (latest) — 2026-09-01
- 3.1.1-canary.49bdaa9 (canary) — 2026-09-01
- 3.0.0-rc.5 (rc) — 2026-07-29
- 3.1.1-canary.786fa29 — 2026-09-01
- 3.0.1-canary.2bce46a — 2026-08-20
- 3.0.1-canary.e24aebd — 2026-08-20
- 3.0.0 — 2026-08-18
- 3.0.1-canary.d8b2d3d — 2026-08-18
- 3.0.1-canary.8c00f44 — 2026-08-17
- 2.2.2 — 2026-07-31
- 3.0.1-canary.57eb571 — 2026-07-29
- 3.0.1-canary.996069a — 2026-07-29
- 3.0.1-canary.7f105ae — 2026-07-28
- 2.2.1 — 2026-07-21
- 3.0.1-canary.9390531 — 2026-07-20
- … 255 more at https://npm.io/package/polkadot-api/versions

## README

# polkadot-api

## Features

- Light client first: built on top of the [new JSON-RPC spec](https://paritytech.github.io/json-rpc-interface-spec/) to fully leverage the potential of light-clients (i.e: [smoldot](https://www.npmjs.com/package/smoldot)).
- Delightful TypeScript support with types and docs generated from on-chain metadata.
- First class support for storage reads, constants, transactions, events and runtime-calls.
- Performant and lightweight: ships with multiple subpaths, so dApps don't bundle unnecessary assets.
- Uses native [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt), instead of large BigNumber libraries
- Leverages dynamic imports to favour faster loading times.
- Promise-based and Observable-based APIs: use the one that best suit your needs and/or coding style.
- Use signers from your browser extension, or from a private key.
- Easy integration with PJS-based extensions.

... and a lot lot more.

## Overview

#### `smoldot.ts`

```ts
import { startFromWorker } from "polkadot-api/smoldot/from-worker"
import SmWorker from "polkadot-api/smoldot/worker?worker"

// Starting smoldot on a Worker (strongly recommended)
export const smoldot = startFromWorker(new SmWorker())

// Alternatively, we could have smoldot running on the main-thread, e.g:
// import { start } from "polkadot-api/smoldot"
// export const smoldot = start()
```

#### `main.ts`

```ts
import { createClient } from "polkadot-api"
import { getSmProvider } from "polkadot-api/sm-provider"
import { polkadotTypes } from "@polkadot-api/descriptors"
import { smoldot } from "./smoldot"

// dynamically importing the chainSpec improves the performance of your dApp
const smoldotRelayChain = import("polkadot-api/chains/polkadot").then(
  ({ chainSpec }) => smoldot.addChain({ chainSpec }),
)

// getting a `JsonRpcProvider` from a `smoldot` chain.
const jsonRpcProvider = getSmProvider(smoldotRelayChain)

// we could also create a `JsonRpcProvider` from a WS connection, eg:
// const jsonRpcProvider = WsProvider("wss://some-rpc-endpoint.io")

const polkadotClient = createClient(jsonRpcProvider)

// logging blocks as they get finalized
polkadotClient.finalizedBlock$.subscribe((block) => {
  console.log(`#${block.number} - ${block.hash} - parentHash: ${block.parent}`)
})

// pulling the latest finalized block
const block = await polkadotClient.getFinalizedBlock()

// obtaining a delightfully typed interface from the descriptors
// previously generated from the metadata
const polkadotApi = polkadotClient.getTypedApi(polkadotTypes)

// presenting the transferrable amount of a given account
const {
  data: { free, frozen },
} = await polkadotApi.query.System.Account.getValue(
  "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5",
)
console.log(`Transferrable amount: ${free - frozen}`)
```

## [Documentation](https://polkadot-api.github.io/polkadot-api-docs/)

---
_Source: https://npm.io/package/polkadot-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._