Skip to main content
Last updated

Chainweb streaming client

Kadena Chainweb clients are application programming interfaces that provide TypeScript-based calls for interacting with Chainweb nodes on the Kadena network.

The chainweb-stream client for browsers and node.js enables you to stream account, module, and event transactions, including their confirmation depth.

The chainweb-stream client introduces and normalizes the following features across environments:

  • Reconnect with exponential backoff
  • Initial connection timeout
  • Stale connection detection
  • Transaction confirmation status classification (unconfirmed/confirmed)
  • Server/client configuration compatibility checks


Alpha version / unstable.


With npm

npm install @kadena/chainweb-stream-client
npm install @kadena/chainweb-stream-client

With yarn

yarn add @kadena/chainweb-stream-client
yarn add @kadena/chainweb-stream-client


import { ChainwebStreamClient } from '@kadena/chainweb-stream-client'; const client = new ChainwebStreamClient({  network: 'mainnet01',  type: 'event',  id: 'coin',  host: 'http://localhost:4000/',}); client.on('confirmed', (txn) => console.log('confirmed', txn)); client.connect();
import { ChainwebStreamClient } from '@kadena/chainweb-stream-client'; const client = new ChainwebStreamClient({  network: 'mainnet01',  type: 'event',  id: 'coin',  host: 'http://localhost:4000/',}); client.on('confirmed', (txn) => console.log('confirmed', txn)); client.connect();

Find more detailed examples under src/examples.

Constructor options

KeyRequiredDescriptionExample Values
networkYesChainweb networkmainnet01/testnet04/...
typeYesTransaction type to stream (event/account)event/account
idYesAccount ID or module/event namek:abcdef01234..
hostYesChainweb-stream backend URLhttp://localhost:4000
limitNoInitial data load limit100
connectTimeoutNoConnection timeout in ms10_000
heartbeatTimeoutNoStale connection timeout in ms30_000
maxReconnectsNoHow many reconnections to attempt before giving up5
confirmationDepthNoHow many confirmations for a transaction to be considered final6

Considerations ⚠️

Ensure configuration compatibility

Make sure that your client and server confirmationDepth values are compatible.

If your client confirmationDepth is larger than the server's, the confirmed event will never fire. The client will automatically detect this condition, emit an error event and disconnect.

If your client's configured network does not match the server's, the client will emit an error event and disconnect.

If your client heartbeatTimeout is smaller than the server heartbeat interval, the client will automatically adapt its heartbeat timeout to 2500ms larger than the server value.

Handle temporary and permanent connection failures

When the connection is interrupted or determined to be stale (no heartbeats received within the heartbeatTimeout interval), a reconnection attempt will be made (up to maxReconnects times.)

It is recommended to handle the fired will-reconnect and error events.


ChainwebStreamClient is an EventEmitter. You can subscribe to the following events using .on('event-name', callback).

You can look up named types in src/types.ts.


Emitted when the connection to the backend is first established. Reconnections to not fire this event, see reconnect instead.

Callback type: () => void


Emitted when a reconnection is established. If a connection is dropped or intentionally killed (e.g. due to staleness/heartbeat timeout) the client will attempt reconnections at exponential intervals.

Callback type: () => void


Emitted when a confirmed transaction is received from the backend. Confirmation depends on the CONFIRMATION_DEPTH

Callback type: (txn: ITransaction) => void


Emitted when an unconfirmed transaction is received from the backend. Multiple unconfirmed events will be fire for the same transaction, as each time the backend detects a confirmation depth update, it will send the data again with the latest confirmation depth.

Hint: You can rely on the value to de-duplicate the underlying unconfirmed transactions

Callback type: (txn: ITransaction) => void


Emitted when a heights event is received by the server. This carries the maximum height as seen from stream-server's corresponding chainweb-data. This event is mostly intended for calculating minheight when reconnecting, but the event itself is exposed to users in case they have use cases beyond that, such as detecting a stalled cw-data.

Callback type: (maxChainwebDataHeight: number) => void


Emitted when any transaction payload is received (unconfirmd and confirmed.)


Emitted when the client encounters a retryable error, such as a stale connection that will be disconnected and retried.

Callback type: (message: string) => void


Emitted when the client encounters a non-retryable error, such as when connection retries are exhausted.

Callback type: (message: string) => void


Emitted when the client encounters an error that will be retried, signaling intent to reconnect.

Callback type: ({ attempts: number, timeout: number, message: string }) => void


Developer event emitted whenever anything significant happens. You can attach a console log to see what is going on internally if you are encountering unexpected behaviors.

Callback type: (dbg: IDebugMsgObject) => void