@polkadot/api

class ApiPromise

class ApiPromise extends ApiBase<'promise'> {}

• # @polkadot/api/promise

  ## Overview

  ApiPromise 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 Also

  • [[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.subscribeNewHeads((header) => {
      console.log(`Chain is at #${header.number}`);
    });

    Subscribing to chain state -

    import { ApiPromise, WsProvider } from '@polkadot/api';
    
    // 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.account(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}`);
        });
    });

class ApiRx

class ApiRx extends ApiBase<'rxjs'> {}

• # @polkadot/api/rx

  ## Overview

  ApiRx

  ApiRx is a powerful RxJS Observable wrapper around the RPC and interfaces on the Polkadot network. As a full Observable API, all interface calls return RxJS Observables, including the static .create(...). In the same fashion and subscription-based methods return long-running Observables that update with the latest values.

  The API is well suited to real-time applications where the latest state is needed, unlocking the subscription-based features of Polkadot (and Substrate) clients. Some familiarity with RxJS is a requirement to use the API, however just understanding .subscribe and .pipe on Observables will unlock full-scale use thereof.

  See Also

  • [[ApiPromise]]

    ## Usage

    Making rpc calls -

    import ApiRx from '@polkadot/api/rx';
    
    // initialize via Promise & static create
    const api = await ApiRx.create().toPromise();
    
    // make a call to retrieve the current network head
    api.rpc.chain.subscribeNewHeads().subscribe((header) => {
      console.log(`Chain is at #${header.number}`);
    });

    Subscribing to chain state -

    import { combineLatest, pairwise, switchMap } from 'rxjs';
    import { ApiRx, WsProvider } from '@polkadot/api';
    
    
    // initialize a provider with a specific endpoint
    const provider = new WsProvider('wss://example.com:9944')
    
    // initialize via isReady & new with specific provider
    new ApiRx({ provider })
      .isReady
      .pipe(
        switchMap((api) =>
          combineLatest([
            api.query.timestamp.blockPeriod(),
            api.query.timestamp.now().pipe(pairwise())
          ])
        )
      )
      .subscribe(([blockPeriod, timestamp]) => {
         const elapsed = timestamp[1].toNumber() - timestamp[0].toNumber();
         console.log(`timestamp ${timestamp[1]} \nelapsed ${elapsed} \n(${blockPeriod}s target)`);
      });

    Submitting a transaction -

    import { first, switchMap } from 'rxjs';
    import ApiRx from '@polkadot/api/rx';
    
    // import the test keyring (already has dev keys for Alice, Bob, Charlie, Eve & Ferdie)
    import testingPairs from '@polkadot/keyring/testingPairs';
    const keyring = testingPairs();
    
    // get api via Promise
    const api = await ApiRx.create().toPromise();
    
    // retrieve nonce for the account
    api.query.system
      .account(keyring.alice.address)
      .pipe(
         first(),
         // pipe nonce into transfer
         switchMap(([nonce]) =>
           api.tx.balances
             // create transfer
             .transferAllowDeath(keyring.bob.address, 12345)
             // sign the transaction
             .sign(keyring.alice, { nonce })
             // send the transaction
             .send()
         )
      )
      // subscribe to overall result
      .subscribe(({ status }) => {
        if (status.isInBlock) {
          console.log('Completed at block hash', status.asFinalized.toHex());
        }
      });

class SubmittableResult

class SubmittableResult implements ISubmittableResult {}