Skip to content
On this page


The sub-api is a powerful utility developed by KodaDot for managing connections with multiple parachains in a network. This documentation provides an overview of its key features and shows how to use them effectively.

To use it check out the documentation in the following link: SubApi@Github


To add the sub-api package to your project, use the following command:

yarn add @kodadot1/sub-api



The ApiFactory class is responsible for establishing and managing a connection to a parachain. The example below demonstrates how to establish a connection to a parachain:

import { ApiFactory } from '@kodadot1/sub-api'

const endpoint = 'wss://'
const api = await ApiFactory.useApiInstance(endpoint)


The InstaApi class provides you with direct control over the connection management process. This class is suitable for applications requiring only a single connection:

import { InstantApi as Api } from '@kodadot1/sub-api'

const endpoint = 'wss://'
const API = await (new API(endpoint)).getInstance()


The sub-api package comes with a set of helper functions that make common tasks easier:

import { balanceOf, currentBlock } from '@kodadot1/sub-api'

const API = await ApiFactory.useApiInstance(endpoint)
const balance = await balanceOf(API, acc)
const block = await currentBlock(API)
console.log(balance, block)


The package provides an onApiConnect hook that gets triggered when the API connects:

import { onApiConnect } from '@kodadot1/sub-api'


More readable type definitions are provided in the sub-api package. For instance, SubmittableExtrinsic<'promise'> is exported as Extrinsic.

Usage Examples

Here is an example demonstrating how to fetch chain properties using the ApiFactory:

import { ApiFactory } from '@kodadot1/sub-api'

async function getChainProperties() {
  const endpoint = 'wss://'
  const API = await ApiFactory.useApiInstance(endpoint)
  const { chainSS58, chainDecimals, chainToken } = API.registry
  console.log('[API] Connect <3', { chainSS58, chainDecimals, chainToken })

In the following example, the onApiConnect hook is used to listen for the connect event and retrieve data when the connection is ready:

import { onApiConnect } from '@kodadot1/sub-api'

const endpoint = 'wss://'
onApiConnect(endpoint, async (API) => {
  const block = await API.query.system.number()
  console.log('[API] Connected to', endpoint, 'block', block)

These examples should provide you with a solid foundation to start using the sub-api package in your application. The sub-api package is an integral part of KodaDot's developer toolbox and should simplify the task of connecting to and interacting with multiple parachains.

VitePress generated at SubWork, some pictures from KodaDot