Hi everyone!
First, a quick update: We’ve managed to secure funding for the basic maintenance of PAPI for 2026, for now covering just one of us. We’re still in conversations about bringing additional work for new features and improvements, though progress is slower than we would hope.
During the end of 2025 we worked on a Polkadot-API v2. This was one of the items included in our previous proposal, which brings a clearer and more consistent API across the library, along with performance improvements and new features.
Since January, we’ve focused on stabilizing the new API. We are currently on Release Candidate 5, and are planning to release the final version very soon.
You can try it out with:
npm i polkadot-api@rc
You can also find a migration guide in our docs (which has been structured so that AI tools can also assist with migrations 
).
We kept the breaking changes as lean as possible to make migration easier. We believe small, periodic breaking changes are preferable to accumulating technical debt, especially in an ecosystem that evolves quickly, while still maintaining valuable stability.
Here are some highlights of the v2 improvements.
WebSocket enhancer
To support older polkadot-sdk nodes in v1, we offered a withPolkadotSdkCompat enhancer that translated and fixed the messages sent and received through those RPCs.
However, it was often confusing to know whether that enhancer was needed or not. In v2, PAPI automatically detects node capabilities and applies the necessary compatibility patches when required.
The end result is a simpler API, and for some operations a better performance overall. What previously required a few lines of code:
// v1
import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws-provider";
import { withPolkadotSdkCompat } from "polkadot-api/polkadot-sdk-compat";
const client = createClient(
withPolkadotSdkCompat(
getWsProvider("wss://rpc.ibp.network/polkadot")
)
);
is now simply:
// v2
import { createWsClient } from "polkadot-api/ws";
const client = createWsClient("wss://rpc.ibp.network/polkadot");
Less boilerplate, more focus on building things.
StaticApi
For synchronous operations that don’t require a request to the node, such as accessing constants or building storage keys, v1 introduced a token that you would obtain after initialization, which could then be used to access those APIs synchronously.
However, this was often confusing and also hid an important detail: those operations depend on the runtime of a specific block.
For this reason, all synchronous APIs are now accessed through await typedApi.getStaticApis({ at }): This returns all the information available in the runtime of the block you select (defaulting to the finalized one).
Uint8Array
Very early on, v1 introduced Binary, a class intended to provide a consistent API for working with binary data.
However, this added friction in some APIs. In v2, PAPI now uses JavaScript’s native Uint8Array, while Binary becomes a set of utilities to convert binary data into different formats (HexString, text, opaques, etc.).
Chain renames
In v1 we used the chain name defined in the chain specs to identify networks. Some of these names were not very human-friendly (for example ksmcc3 for Kusama or westend2 for Westend).
They now use their actual names instead: kusama, westend, etc.
API consistency
Finally, we reviewed several APIs that had similar functionality but slightly different interfaces.
For example, some interfaces (like storage queries) took the target block as an optional parameter, while others exposed that option as a property inside an options object.
Another example was:
client.watchBlockBody(at: HexString)
The name didn’t really make sense since the body of a block is immutable. It has now been renamed to:
client.getBlockBody$(at: HexString)
Small changes individually, but together they add up to a better developer experience.
Try it out!
There’s plenty more explained in the migration guide. Give it a try by upgrading with:
npm i polkadot-api@rc
We’ve already upgraded the Staking Optimizer and the PAPI Console, as well as our examples, and we’re very happy with the results so far. We’ve also received positive feedback from some early adopters.
If you give the RC a try, we’d love to hear your feedback. It will help us polish things before the final 2.0.0 release.