0
# @polkadot/api
1

2
@polkadot/api provides comprehensive JavaScript/TypeScript wrappers around the Polkadot and Substrate blockchain RPC interfaces. It offers clean abstractions for querying blockchain state, submitting transactions, subscribing to chain events, and interacting with smart contracts through both Promise-based and RxJS Observable patterns.
3

4
## Package Information
5

6
- **Package Name**: @polkadot/api
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @polkadot/api`
10

11
## Core Imports
12

13
```typescript
14
import { ApiPromise, WsProvider } from "@polkadot/api";
15
```
16

17
For RxJS-based API:
18

19
```typescript
20
import { ApiRx, WsProvider } from "@polkadot/api";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { ApiPromise, WsProvider } = require("@polkadot/api");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { ApiPromise, WsProvider } from "@polkadot/api";
33

34
// Connect to a Polkadot node
35
const provider = new WsProvider("wss://rpc.polkadot.io");
36
const api = await ApiPromise.create({ provider });
37

38
// Query chain state
39
const [chain, nodeName, nodeVersion] = await Promise.all([
40
  api.rpc.system.chain(),
41
  api.rpc.system.name(),
42
  api.rpc.system.version()
43
]);
44

45
console.log(`Connected to chain ${chain} using ${nodeName} v${nodeVersion}`);
46

47
// Query account balance
48
const account = "1FRMM8PEiWXYax7rpS6X4XZX1aAAxSWx1CrKTyrVYhV24fg";
49
const { data: balance } = await api.query.system.account(account);
50
console.log(`Account balance: ${balance.free.toHuman()}`);
51

52
// Subscribe to new blocks  
53
const unsubscribe = await api.rpc.chain.subscribeNewHeads((header) => {
54
  console.log(`New block #${header.number} has hash ${header.hash}`);
55
});
56
```
57

58
## Architecture
59

60
@polkadot/api is built around several key components:
61

62
- **Dual API Design**: `ApiPromise` for Promise-based async operations and `ApiRx` for RxJS Observable streams
63
- **Provider Abstraction**: Pluggable providers (`WsProvider`, `HttpProvider`, `ScProvider`) for different connection types
64
- **Dynamic Interface Generation**: API endpoints are dynamically populated from the blockchain's runtime metadata
65
- **Type Safety**: Full TypeScript integration with runtime-aware type generation
66
- **Subscription Support**: Real-time blockchain data through WebSocket subscriptions
67
- **Transaction Pipeline**: Complete transaction lifecycle from creation to finalization with status tracking
68

69
## Capabilities
70

71
### API Initialization
72

73
Core API creation and connection management for both Promise and RxJS patterns.
74

75
```typescript { .api }
76
class ApiPromise {
77
  static create(options?: ApiOptions): Promise<ApiPromise>;
78
  constructor(options?: ApiOptions);
79
  get isReady(): Promise<ApiPromise>;
80
  get isReadyOrError(): Promise<ApiPromise>;
81
  clone(): ApiPromise;
82
  connect(): Promise<void>;
83
  disconnect(): Promise<void>;
84
  setSigner(signer?: Signer): void;
85
  combineLatest<T>(fns: CombinatorFunction[], callback: CombinatorCallback<T>): Promise<() => void>;
86
  
87
  /**
88
   * Query blockchain state at a specific block hash
89
   * @param blockHash - Block hash to query at
90
   * @param knownVersion - Optional runtime version for optimization
91
   * @returns Promise resolving to query interface bound to the block
92
   */
93
  queryAt(blockHash: Uint8Array | string, knownVersion?: RuntimeVersion): Promise<QueryableStorage<'promise'>>;
94
  
95
  /**
96
   * Make runtime calls at a specific block hash
97
   * @param blockHash - Block hash to query at  
98
   * @param knownVersion - Optional runtime version for optimization
99
   * @returns Promise resolving to call interface bound to the block
100
   */
101
  callAt(blockHash: Uint8Array | string, knownVersion?: RuntimeVersion): Promise<QueryableCalls<'promise'>>;
102
  
103
  /**
104
   * Sign raw data using keyring pair or external signer
105
   * @param address - KeyringPair or address string for signing
106
   * @param data - Raw data to sign
107
   * @param options - Signing options including external signer
108
   * @returns Promise resolving to hex signature
109
   */
110
  sign(address: KeyringPair | string, data: SignerPayloadRawBase, options?: { signer?: Signer }): Promise<string>;
111
}
112

113
class ApiRx {
114
  static create(options?: ApiOptions): Observable<ApiRx>;
115
  constructor(options?: ApiOptions);
116
  get isReady(): Observable<ApiRx>;
117
  clone(): ApiRx;
118
  connect(): Promise<void>;
119
  disconnect(): Promise<void>;
120
  setSigner(signer?: Signer): void;
121
  
122
  /**
123
   * Query blockchain state at a specific block hash
124
   * @param blockHash - Block hash to query at
125
   * @param knownVersion - Optional runtime version for optimization
126
   * @returns Observable emitting query interface bound to the block
127
   */
128
  queryAt(blockHash: Uint8Array | string, knownVersion?: RuntimeVersion): Observable<QueryableStorage<'rxjs'>>;
129
  
130
  /**
131
   * Make runtime calls at a specific block hash
132
   * @param blockHash - Block hash to query at
133
   * @param knownVersion - Optional runtime version for optimization
134
   * @returns Observable emitting call interface bound to the block
135
   */
136
  callAt(blockHash: Uint8Array | string, knownVersion?: RuntimeVersion): Observable<QueryableCalls<'rxjs'>>;
137
  
138
  /**
139
   * Sign raw data using keyring pair or external signer
140
   * @param address - KeyringPair or address string for signing
141
   * @param data - Raw data to sign
142
   * @param options - Signing options including external signer
143
   * @returns Promise resolving to hex signature
144
   */
145
  sign(address: KeyringPair | string, data: SignerPayloadRawBase, options?: { signer?: Signer }): Promise<string>;
146
}
147

148
interface ApiOptions {
149
  provider?: ProviderInterface;
150
  types?: RegistryTypes;
151
  rpc?: Record<string, Record<string, DefinitionRpc | DefinitionRpcSub>>;
152
  derives?: DeriveCustom;
153
  metadata?: Record<string, HexString>;
154
  noInitWarn?: boolean;
155
  throwOnConnect?: boolean;
156
  throwOnUnknown?: boolean;
157
  signer?: Signer;
158
  registry?: Registry;
159
  initWasm?: boolean;
160
  isPedantic?: boolean;
161
  rpcCacheCapacity?: number;
162
  runtime?: DefinitionsCall;
163
  signedExtensions?: ExtDef;
164
  source?: ApiBase<any>;
165
}
166
```
167

168
[API Initialization](./api-initialization.md)
169

170
### Blockchain Queries
171

172
Query blockchain state, constants, and runtime information through dynamic interfaces.
173

174
```typescript { .api }
175
interface QueryableStorage<ApiType> {
176
  [section: string]: {
177
    [method: string]: (...args: any[]) => QueryableStorageEntry<ApiType>;
178
  };
179
}
180

181
interface QueryableConsts<ApiType> {
182
  [section: string]: {
183
    [constant: string]: any;
184
  };
185
}
186

187
interface QueryableStorageMulti<ApiType> {
188
  <T extends any[]>(
189
    queries: (QueryableStorageEntry<'rxjs'> | [QueryableStorageEntry<'rxjs'>, ...any[]])[],
190
    callback?: (values: T) => void
191
  ): ApiType extends 'rxjs' ? Observable<T> : Promise<T>;
192
}
193

194
interface AllDerives<ApiType> {
195
  [section: string]: {
196
    [method: string]: (...args: any[]) => ApiType extends 'rxjs' ? Observable<any> : Promise<any>;
197
  };
198
}
199
```
200

201
[Blockchain Queries](./blockchain-queries.md)
202

203
### RPC Operations
204

205
Direct access to node RPC methods for chain information, state queries, and system operations.
206

207
```typescript { .api }
208
interface DecoratedRpc<ApiType, RpcInterface> {
209
  chain: {
210
    getBlock: (hash?: Hash) => ApiType extends 'rxjs' ? Observable<SignedBlock> : Promise<SignedBlock>;
211
    subscribeNewHeads: (callback?: (header: Header) => void) => ApiType extends 'rxjs' ? Observable<Header> : UnsubscribePromise;
212
  };
213
  state: {
214
    getStorage: (key: StorageKey, at?: Hash) => ApiType extends 'rxjs' ? Observable<StorageData> : Promise<StorageData>;
215
    subscribeStorage: (keys: StorageKey[], callback?: (changes: StorageChangeSet) => void) => ApiType extends 'rxjs' ? Observable<StorageChangeSet> : UnsubscribePromise;
216
  };
217
  system: {
218
    chain: () => ApiType extends 'rxjs' ? Observable<Text> : Promise<Text>;
219
    name: () => ApiType extends 'rxjs' ? Observable<Text> : Promise<Text>;
220
    version: () => ApiType extends 'rxjs' ? Observable<Text> : Promise<Text>;
221
  };
222
}
223
```
224

225
[RPC Operations](./rpc-operations.md)
226

227
### Transaction Submission
228

229
Create, sign, and submit transactions with full lifecycle tracking and event monitoring.
230

231
```typescript { .api }
232
interface SubmittableExtrinsics<ApiType> {
233
  [section: string]: {
234
    [method: string]: (...args: any[]) => SubmittableExtrinsic<ApiType>;
235
  };
236
}
237

238
interface SubmittableExtrinsic<ApiType> {
239
  sign(account: AddressOrPair, options?: Partial<SignerOptions>): SubmittableExtrinsic<ApiType>;
240
  signAndSend(account: AddressOrPair, callback?: (result: SubmittableResult) => void): ApiType extends 'rxjs' ? Observable<SubmittableResult> : Promise<Hash>;
241
  signAndSend(account: AddressOrPair, options?: Partial<SignerOptions>, callback?: (result: SubmittableResult) => void): ApiType extends 'rxjs' ? Observable<SubmittableResult> : Promise<Hash>;
242
}
243

244
class SubmittableResult {
245
  readonly status: ExtrinsicStatus;
246
  readonly events: EventRecord[];
247
  readonly dispatchError?: DispatchError;
248
  readonly txHash: Hash;
249
  get isCompleted(): boolean;
250
  get isError(): boolean;
251
  get isFinalized(): boolean;
252
  get isInBlock(): boolean;
253
}
254
```
255

256
[Transaction Submission](./transaction-submission.md)
257

258
### Network Providers
259

260
Connection providers for different transport protocols and connection types.
261

262
```typescript { .api }
263
class WsProvider implements ProviderInterface {
264
  constructor(endpoint?: string | string[], autoConnectMs?: number, headers?: Record<string, string>);
265
  connect(): Promise<void>;
266
  disconnect(): Promise<void>;
267
  send(method: string, params: unknown[]): Promise<any>;
268
}
269

270
class HttpProvider implements ProviderInterface {
271
  constructor(endpoint?: string, headers?: Record<string, string>);
272
  send(method: string, params: unknown[]): Promise<any>;
273
}
274

275
class ScProvider implements ProviderInterface {
276
  constructor(spec: string | ChainSpec, config?: ScProviderConfig);
277
  connect(): Promise<void>;
278
  disconnect(): Promise<void>;
279
  send(method: string, params: unknown[]): Promise<any>;
280
}
281

282
class Keyring {
283
  constructor(options?: KeyringOptions);
284
  addFromUri(suri: string, meta?: KeyringPair$Meta, type?: KeypairType): KeyringPair;
285
  getPairs(): KeyringPair[];
286
}
287
```
288

289
[Network Providers](./network-providers.md)
290

291
### Events and Metadata
292

293
Access runtime events, errors, and metadata for dynamic API behavior.
294

295
```typescript { .api }
296
interface DecoratedEvents<ApiType> {
297
  [section: string]: {
298
    [event: string]: EventMetadata;
299
  };
300
}
301

302
interface DecoratedErrors<ApiType> {
303
  [section: string]: {
304
    [error: string]: RegistryError;
305
  };
306
}
307
```
308

309
[Events and Metadata](./events-metadata.md)
310

311
## Common Types
312

313
```typescript { .api }
314
type ApiTypes = 'promise' | 'rxjs';
315

316
type AddressOrPair = string | KeyringPair;
317

318
type UnsubscribePromise = Promise<() => void>;
319

320
type CombinatorCallback<T> = (...args: T) => void;
321

322
type CombinatorFunction = (callback: (value: any) => void) => UnsubscribePromise;
323

324
interface ChainSpec {
325
  chainSpec: string;
326
  database?: string;
327
}
328

329
interface ScProviderConfig {
330
  config?: any;
331
  database?: string;
332
}
333

334
interface StorageChangeSet {
335
  block: Hash;
336
  changes: [StorageKey, StorageData | null][];
337
}
338

339
interface EventRecord {
340
  phase: Phase;
341
  event: Event;
342
  topics: Vec<Hash>;
343
}
344

345
interface RegistryTypes {
346
  [typeName: string]: any;
347
}
348

349
interface KeyringPair {
350
  address: string;
351
  publicKey: Uint8Array;
352
  sign(message: Uint8Array): Uint8Array;
353
}
354

355
interface Signer {
356
  signPayload(payload: SignerPayload): Promise<SignerResult>;
357
  signRaw?(raw: SignerPayloadRaw): Promise<SignerResult>;
358
}
359

360
interface SignerPayloadRawBase {
361
  data: string | Uint8Array;
362
  type?: 'bytes' | 'payload';
363
}
364

365
type DecorateFn<T> = (...args: any[]) => Observable<T>;
366

367
type CodecReturnType<T extends (...args: unknown[]) => Observable<Codec>> =
368
  T extends (...args: any) => infer R
369
    ? R extends Observable<Codec>
370
      ? ObsInnerType<R>
371
      : never
372
    : never;
373

374
interface DecorateMethodOptions {
375
  methodName?: string;
376
  overrideNoSub?: any;
377
}
378

379
type StorageEntryPromiseOverloads = (...args: unknown[]) => Promise<any> | UnsubscribePromise;
380

381
type ObsInnerType<T> = T extends Observable<infer U> ? U : never;
382
```
383

384
## Utility Methods
385

386
Both ApiPromise and ApiRx instances provide utility methods for working with runtime metadata:
387

388
```typescript { .api }
389
interface ApiUtilityMethods {
390
  /**
391
   * Find call definition by index
392
   * @param callIndex - Call index bytes
393
   * @returns Call function definition
394
   */
395
  findCall(callIndex: Uint8Array | string): CallFunction;
396
  
397
  /**
398
   * Find error definition by index
399
   * @param errorIndex - Error index bytes
400
   * @returns Registry error definition
401
   */
402
  findError(errorIndex: Uint8Array | string): RegistryError;
403
  
404
  /** Access multi-query interface */
405
  get queryMulti(): QueryableStorageMulti<ApiType>;
406
  
407
  /** Access derived query interface */
408
  get derive(): AllDerives<ApiType>;
409
  
410
  /** Runtime metadata */
411
  get runtimeMetadata(): Metadata;
412
  
413
  /** Runtime version information */
414
  get runtimeVersion(): RuntimeVersion;
415
  
416
  /** Chain name */
417
  get runtimeChain(): Text;
418
  
419
  /** Genesis hash */
420
  get genesisHash(): Hash;
421
  
422
  /** Connection status */
423
  get isConnected(): boolean;
424
}
425
```
426

427
## Additional Exports
428

429
Beyond the main API classes, @polkadot/api exports several utility functions and constants:
430

431
```typescript { .api }
432
/**
433
 * Package information containing name, version, and type
434
 */
435
const packageInfo: {
436
  name: string;
437
  version: string; 
438
  path: string;
439
  type: string;
440
};
441

442
/**
443
 * Decorator function that converts RxJS observables to Promise-based methods
444
 * @param method - The method to convert from Observable to Promise
445
 * @param options - Decoration options for method behavior
446
 * @returns Promise-based version of the method
447
 */
448
function toPromiseMethod<M extends DecorateFn<CodecReturnType<M>>>(
449
  method: M, 
450
  options?: DecorateMethodOptions
451
): StorageEntryPromiseOverloads;
452

453
/**
454
 * Decorator function for RxJS-based methods (identity function)
455
 * @param method - The method to return as-is for RxJS usage
456
 * @returns The same method for RxJS compatibility
457
 */
458
function toRxMethod<M extends DecorateFn<Codec>>(method: M): M;
459
```