What is the Polkadot API and how do you choose the right one?

Quick decision guide: which Polkadot API should you use?

Before diving into the details, here's a practical way to decide which client library fits your project. The Polkadot ecosystem has three main JavaScript/TypeScript APIs, and the choice depends on your priorities: type safety, maintenance status, and whether you want to use a light client or a remote RPC endpoint.

If you're starting a new project, Polkadot-API is the recommended choice by the ecosystem. It's modern, fully typed, and built for the light client. If you're maintaining an existing app that already uses Polkadot.js, you can continue, but be aware it's in maintenance mode. Dedot is a solid alternative if you prefer a different API style.

For the RPC endpoint, you can use a public endpoint, but for production, consider a reliable RPC provider like OnFinality. OnFinality offers RPC endpoints for Polkadot and many other networks, with pricing that scales with your needs.

What is the Polkadot API?

The Polkadot API is a set of libraries and interfaces that allow developers to interact with Polkadot and Substrate-based chains. It provides methods to query chain state, submit transactions, and listen to events. The API abstracts the underlying JSON-RPC calls, handling encoding and decoding of data, so you can focus on building your application.

There are several implementations, each with its own philosophy and features. The most prominent are Polkadot-API (often called papi), Polkadot.js API, and Dedot. Understanding their differences is crucial for choosing the right tool for your project.

Polkadot-API (papi): the modern, type-safe choice

Polkadot-API is a relatively new suite of libraries designed with a "light-client first" philosophy. It is built on the new JSON-RPC spec and leverages the power of light clients like Smoldot. This means you can run a node in the browser, reducing reliance on centralized RPC endpoints.

Key features include:

• Fully typed API: Types and documentation are generated from on-chain metadata, so your IDE provides autocomplete and type checking for every operation.
• First-class support for storage reads, constants, transactions, events, and runtime calls: You get a comprehensive API for all chain interactions.
• Multiple connections: You can connect to multiple chains simultaneously, which is useful for cross-chain applications.
• Runtime upgrade compatibility: Generate multiple descriptors and perform compatibility checks to prepare for runtime updates.
• Lightweight: The main bundle is under 50kB, and it uses dynamic imports to keep your dApp fast.
• Native BigInt: Uses JavaScript's native BigInt instead of large BigNumber libraries.
• Promise and Observable APIs: Choose the style that fits your coding preferences.

Here's a quick example of how to use Polkadot-API to query an account balance:

import { createClient } from "polkadot-api";
import { getSmProvider } from "polkadot-api/sm-provider";
import { startFromWorker } from "polkadot-api/smoldot/from-worker";
import { chainSpec } from "polkadot-api/chains/polkadot";

const smoldot = startFromWorker(new Worker("./smoldot.js"));
const chain = await smoldot.addChain({ chainSpec });
const client = createClient(getSmProvider(chain));

const api = client.getTypedApi();
const balance = await api.query.System.Account.getValue("ADDRESS");
console.log(balance);

This example uses a light client, but you can also connect to a remote RPC endpoint using getWsProvider from polkadot-api/ws-provider.

Polkadot.js API: the legacy standard

The Polkadot.js API has been the standard for years. It provides easy-to-use wrappers around JSON-RPC calls and handles all the encoding and decoding. However, it is now in maintenance mode and no longer actively developed. The official Polkadot developer docs recommend new projects use Polkadot-API or Dedot instead.

Despite this, many existing projects still rely on it. If you're working with a legacy codebase, you might need to use it. Here's a basic example:

const { ApiPromise, WsProvider } = require("@polkadot/api");

async function main() {
  const provider = new WsProvider("wss://rpc.polkadot.io");
  const api = await ApiPromise.create({ provider });

  const balance = await api.query.system.account("ADDRESS");
  console.log(balance.toHuman());
}

main();

Note that the Polkadot.js API dynamically generates its interface based on the chain's metadata. It offers three main categories: api.consts, api.query, and api.tx.

Dedot: a TypeScript-first alternative

Dedot is another actively maintained TypeScript-first API. It aims to provide a more ergonomic and type-safe experience than Polkadot.js. It supports both light clients and remote RPC endpoints. If you prefer a different API design, Dedot is worth considering.

RPC endpoints: public vs. private

When using any Polkadot API, you need an RPC endpoint to connect to. Public endpoints, like wss://rpc.polkadot.io, are free but often rate-limited and may not be reliable for production. For production applications, you should use a dedicated RPC provider that offers higher throughput, archive data, and better uptime.

OnFinality provides Polkadot RPC endpoints that are reliable and scalable. You can also check supported networks to see all available chains. For pricing details, visit RPC pricing.

How to connect to a Polkadot RPC endpoint

Regardless of the API library you choose, you'll need to configure the endpoint. Here's an example using Polkadot-API with a WebSocket provider:

import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws-provider";

const client = createClient(getWsProvider("wss://rpc.polkadot.io"));
const api = client.getTypedApi();

// Now you can query chain state
const header = await api.query.System.Number.getValue();
console.log("Current block number:", header);

For Polkadot.js, you can use the WsProvider as shown earlier. Always ensure your endpoint supports WebSocket for real-time subscriptions.

Common pitfalls and troubleshooting

When working with the Polkadot API, you might encounter issues. Here are some common ones and how to resolve them:

• Connection errors: If you're using a public endpoint, it might be rate-limited or down. Switch to a reliable provider or use a light client.
• Type mismatches: If you're using Polkadot-API, ensure you have the correct chain spec and that your descriptors are up to date after runtime upgrades.
• Transaction failures: Check the error messages and ensure you have enough balance for fees. Use api.tx methods correctly.
• Performance issues: For heavy queries, consider using archive nodes or dedicated infrastructure.

Key Takeaways

• The Polkadot API is essential for interacting with Polkadot-based chains.
• Polkadot-API is the modern, type-safe, and actively maintained choice for new projects.
• Polkadot.js API is in maintenance mode; use it only for legacy projects.
• Dedot is a viable alternative with TypeScript-first design.
• Choose a reliable RPC provider like OnFinality for production workloads.

Frequently Asked Questions

What is the difference between Polkadot-API and Polkadot.js API?

Polkadot-API is a modern, fully typed, and light-client-first library, while Polkadot.js API is older, dynamically typed, and in maintenance mode. New projects should prefer Polkadot-API.

Can I use a light client with Polkadot-API?

Yes, Polkadot-API is built for light clients, allowing you to run a node in the browser without relying on remote RPC endpoints.

What RPC endpoint should I use for production?

For production, use a reliable RPC provider like OnFinality to ensure high availability and performance. Public endpoints are not recommended for production workloads.

Is Polkadot.js API deprecated?

It is in maintenance mode, meaning it is no longer actively developed. It still works, but new projects are encouraged to use Polkadot-API or Dedot.

How do I choose between Polkadot-API and Dedot?

Both are actively maintained and type-safe. Polkadot-API has a stronger focus on light clients and is the ecosystem's recommended choice. Dedot offers a different API style; you can evaluate both to see which fits your project better.