bnc-sdk

library4.6.9jsnpmunverified

A lightweight JavaScript/TypeScript SDK (v4.6.9+, semver) that connects to Blocknative's Ethereum backend via WebSocket to provide real-time transaction monitoring and address notifications. It supports both Node.js and browser environments, requires an API key, and ships with TypeScript types. Key differentiators: uses Blocknative's prediction engine for early tx status (pending, confirmed, failed), event-based architecture (txPool, txConfirmed, all), and an account watcher. Alternatives like ethers.js or web3.js only provide lower-level event polling.

blockchain

npm install bnc-sdk

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BNC-SDK

bnc-sdk

blockchainjavascriptv4.6.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (BlocknativeSdk)

✓ import BlocknativeSdk from 'bnc-sdk'

✗ const BlocknativeSdk = require('bnc-sdk')

ESM-only since v3; CommonJS require() is not supported. The package uses default export.

BlocknativeSdk type (TypeScript)

✓ import type { BlocknativeSdk } from 'bnc-sdk'

✗ import { BlocknativeSdk } from 'bnc-sdk' // value import might work but type-only import is correct for type usage

TypeScript types are included; use type import to avoid runtime overhead.

initialize SDK

✓ const sdk = new BlocknativeSdk(options)

✗ const sdk = new BlocknativeSdk.default(options) // no .default needed

The default export is a constructor; do not add .default after import.

Initializes Blocknative SDK with WebSocket, monitors a transaction hash for pool and confirmation events.

// Install: npm install bnc-sdk ws web3 import WebSocket from 'ws'; import BlocknativeSdk from 'bnc-sdk'; import Web3 from 'web3'; const web3 = new Web3('ws://localhost:8546'); // replace with your node const options = { dappId: process.env.BLOCKNATIVE_API_KEY ?? '', networkId: 4, // Rinkeby ws: WebSocket // required for Node.js // transactionHandlers: [event => console.log(event.transaction)] }; const blocknative = new BlocknativeSdk(options); // Monitor a transaction const txHash = '0x...'; // hash from web3.eth.sendTransaction const { emitter } = blocknative.transaction(txHash); emitter.on('txConfirmed', transaction => { console.log('Transaction confirmed!', transaction); }); emitter.on('all', transaction => { console.log('Event:', transaction.eventCode); });

Debug

Known issues

breakingESM-only: package no longer supports CommonJS require() since v3.

fix

Use import BlocknativeSdk from 'bnc-sdk' (ESM) or switch to dynamic import if needed.

affects: >=3.0.0

gotchaWebSocket library 'ws' is required in Node.js but omitted in browser. Forgetting to pass 'ws' in Node throws WebSocket connection error.

fix

Install 'ws' and pass it as 'ws' option: { ws: WebSocket }

affects: >=1.0.0

gotchadappId is mandatory but easily mistaken as optional. Missing it causes authentication failure.

fix

Always provide a valid Blocknative API key in options.dappId.

affects: >=1.0.0

deprecatedThe 'transactionHandlers' option is deprecated since v4. Use 'emitter.on' events instead.

fix

Remove transactionHandlers and attach event listeners via emitter.on('txPool', ...) etc.

affects: >=4.0.0 <5.0.0

Errors

Common errors & fixes

TypeError: WebSocket is not a constructor

Missing 'ws' dependency in Node.js or not passing WebSocket class in options.

fix

Install 'ws' and pass it: import WebSocket from 'ws'; { ws: WebSocket }

Error: dappId is required

Missing or empty 'dappId' in options object.

fix

Provide a valid Blocknative API key: { dappId: 'your-key' }

SyntaxError: Unexpected token 'export'

Attempting to require('bnc-sdk') in a CommonJS module (Node < v12 or without 'type':'module').

fix

Use import syntax or dynamic import: const sdk = await import('bnc-sdk')

Upgrade

Version history

4.6.9latest on npm

Audit

Dependencies

wsoptionalWebSocket implementation required in Node.js environment (not needed in browser)

Agent activity

46 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/blocknative/sdk ↗

packagebnc-sdk ↗

homepagehttps://github.com/blocknative/sdk#readme ↗