@polkadot/api/promise
Overview
name: ApiPromise
description: ApiPromise is a standard JavaScript wrapper around the RPC and interfaces on the Polkadot network. As a full Promise-based, all interface calls return Promises, including the static .create(...). Subscription calls utilise (value) => {} callbacks to pass through the latest values.
The API is well suited to real-time applications where either the single-shot state is needed or use is to be made of the subscription-based features of Polkadot (and Substrate) clients.
see: ApiRx
Usage
Making rpc calls -
import ApiPromise from '@polkadot/api/promise';
// initialise via static create
const api = await ApiPromise.create();
// make a subscription to the network head
api.rpc.chain.subscribeNewHead((header) => {
console.log(`Chain is at #${header.blockNumber}`);
});
Subscribing to chain state -
import { ApiPromise } from '@polkadot/api';
import WsProvider from '@polkadot/rpc-provider/ws';
// initialise a provider with a specific endpoint
const provider = new WsProvider('wss://example.com:9944')
// initialise via isReady & new with specific provider
const api = await new ApiPromise(provider).isReady;
// retrieve the block target time
const blockPeriod = await api.query.timestamp.blockPeriod().toNumber();
let last = 0;
// subscribe to the current block timestamp, updates automatically (callback provided)
api.query.timestamp.now((timestamp) => {
const elapsed = last
? `, ${timestamp.toNumber() - last}s since last`
: '';
last = timestamp.toNumber();
console.log(`timestamp ${timestamp}${elapsed} (${blockPeriod}s target)`);
});
Submitting a transaction -
import ApiPromise from '@polkadot/api/promise';
ApiPromise.create().then((api) => {
const nonce = await api.query.system.accountNonce(keyring.alice.address());
api.tx.balances
// create transfer
transfer(keyring.bob.address(), 12345)
// sign the transcation
.sign(keyring.alice, nonce)
// send the transaction (optional status callback)
.send((status) => {
console.log(`current status ${status.type}`);
})
// retrieve the submitted extrinsic hash
.then((hash) => {
console.log(`submitted with hash ${hash}`);
});
});
Hierarchy
ApiBase<Rpc, QueryableStorage, SubmittableExtrinsics>
↳ ApiPromise
Implements
ApiBaseInterface<Rpc,QueryableStorage,SubmittableExtrinsics>ApiPromiseInterface
Constructors
constructor
⊕ new ApiPromise(wsProvider?: WsProvider): ApiPromise
Overrides ApiBase.constructor
Defined in promise/index.ts:128
description: Creates an instance of the ApiPromise class
example:
import Api from '@polkadot/api/promise';
new Api().isReady.then((api) => {
api.rpc.subscribeNewHead((header) => {
console.log(`new block #${header.blockNumber.toNumber()}`);
});
});
Parameters:
| Name | Type | Description |
|---|---|---|
Optional wsProvider |
WsProvider |
WebSocket provider from rpc-provider/ws. If not specified, it will default to connecting to the localhost with the default port, i.e. `ws://127.0.0.1:9944` |
Returns: ApiPromise
Accessors
genesisHash
getgenesisHash(): Hash
Inherited from ApiBase.genesisHash
Defined in Base.ts:70
description: Contains the genesis Hash of the attached chain. Apart from being useful to determine the actual chain, it can also be used to sign immortal transactions.
Returns: Hash
isReady
getisReady(): Promise<ApiPromise>
Defined in promise/index.ts:161
description: Promise that returns the first time we are connected and loaded
Returns: Promise<ApiPromise>
query
getquery(): QueryableStorage
Defined in Base.ts:108
description: Contains all the chain state modules and their subsequent methods in the API. These are attached dynamically from the runtime metadata.
All calls inside the namespace, is denoted by section.method and may take an optional query parameter. As an example, api.query.timestamp.now() (current block timestamp) does not take parameters, while api.query.system.accountNonce(<accountId>) (retrieving the associated nonce for an account), takes the AccountId as a parameter.
example:
api.query.balances.freeBalance(<accountId>, (balance) => {
console.log('new balance', balance);
});
Returns: QueryableStorage
rpc
getrpc(): Rpc
Defined in Base.ts:128
description: Contains all the raw rpc sections and their subsequent methods in the API as defined by the jsonrpc interface definitions. Unlike the dynamic api.query and api.tx sections, these methods are fixed (although extensible with node upgrades) and not determined by the runtime.
RPC endpoints available here allow for the query of chain, node and system information, in addition to providing interfaces for the raw queries of state (usine known keys) and the submission of transactions.
example:
api.rpc.chain.subscribeNewHead((header) => {
console.log('new header', header);
});
Returns: Rpc
runtimeMetadata
getruntimeMetadata(): RuntimeMetadata
Inherited from ApiBase.runtimeMetadata
Defined in Base.ts:79
description: Yields the current attached runtime metadata. Generally this is only used to construct extrinsics & storage, but is useful for current runtime inspection.
Returns: RuntimeMetadata
runtimeVersion
getruntimeVersion(): RuntimeVersion
Inherited from ApiBase.runtimeVersion
Defined in Base.ts:88
description: Contains the version information for the current runtime.
Returns: RuntimeVersion
tx
gettx(): SubmittableExtrinsics
Defined in Base.ts:147
description: Contains all the extrinsic modules and their subsequent methods in the API. It allows for the construction of transactions and the submission thereof. These are attached dynamically from the runtime metadata.
example:
api.tx.balances
.transfer(<recipientId>, <balance>)
.sign(<keyPair>, <accountNonce>, <blockHash (optional)>)
.send((status) => {
console.log('tx status', status);
});
Returns: SubmittableExtrinsics
Methods
combineLatest
▸ combineLatest(fns: Array<CombinatorFunction>, callback: CombinatorCallback): Combinator
Defined in promise/index.ts:189
description: Creates a combinator that can be used to combine the latest results from multiple subscriptions
example:
const address = '5DTestUPts3kjeXSTMyerHihn1uwMfLj8vU8sqF7qYrFacT7';
// combines values from balance & nonce as it updates
api.combineLatest([
(cb) => api.rpc.chain.subscribeNewHead(cb),
(cb) => api.query.balances.freeBalance(address, cb),
(cb) => api.query.system.accountNonce(address, cb)
], ([head, balance, nonce]) => {
console.log(`#${head.number}: You have ${balance} units, with ${nonce} transactions sent`);
});
Parameters:
| Name | Type | Description |
|---|---|---|
| fns | Array<CombinatorFunction> |
An array of function to combine, each in the form of `(cb: (value: void)) => void` |
| callback | CombinatorCallback | A callback that will return an Array of all the values this combinator has been applied to |
Returns: Combinator
on
▸ on(type: ApiInterface$Events, handler: function): void
Defined in Base.ts:172
description: Attach an eventemitter handler to listen to a specific event
example:
api.on('disconnected', () => {
console.log('API has been connected to the endpoint');
});
api.on('disconnected', () => {
console.log('API has been disconnected from the endpoint');
});
Parameters:
| Name | Type | Description |
|---|---|---|
| type | ApiInterface$Events |
The type of event to listen to. Available events are `connected`, `disconnected` and `ready` |
| handler | function |
The callback to be called when the event fires. Depending on the event type, it could fire with additional arguments. |
Returns: void
<Static> create
▸ create(wsProvider?: WsProvider): Promise<ApiPromise>
Defined in promise/index.ts:126
description: Creates an ApiPromise instance using the supplied provider. Returns an Promise containing the actual Api instance.
example:
import Api from '@polkadot/api/promise';
Api.create().then(async (api) => {
const timestamp = await api.query.timestamp.now();
console.log(`lastest block timestamp ${timestamp}`);
});
Parameters:
| Name | Type | Description |
|---|---|---|
Optional wsProvider |
WsProvider |
WebSocket provider that is passed to the class contructor |
Returns: Promise<ApiPromise>