Links
🧰

Blast SDK

JavaScript/TypeScript SDK which handles rate limiting by automatically delaying your requests so you will have a smooth experience.

Installation

npm install @bwarelabs/blast-sdk-js

Example Usage

import {Blast, BlastNetwork, BlastSubscriptionPlan, BlastConfig} from "@bwarelabs/blast-sdk-js";
const config: BlastConfig = {
projectId: '<insert-your-project-id-here>',
network: BlastNetwork.ETH_MAINNET,
rateLimit: BlastSubscriptionPlan.Free,
};
const blast = new Blast(config);
const gasPrice = await blast.apiProvider.eth.getGasPrice();

Initialization

const blast = new Blast(config); // type of config is BlastConfig

Usage

The above blast object has 2 members:
  • blast.apiProvider - a provider for the https blast API
  • blast.wsProvider - a provider for the web sockets blast API
Both of them are Web3 objects of web3.js. which have an extra functionality of handling rate limiting. So they expose the same interface as web3.js and can be used exactly in the same way.

Config

BlastConfig has 3 parameters:
  • projectId: string - your project id
  • network: BlastNetwork - the network for which you want to use the SDK
  • rateLimit: BlastSubcriptionPlan | number | undefined - the maximum number of requests per second your plan allows (or undefined if you want to disable rate limiting handling (more info right below))

rateLimit

In order to enable rate limiting handling the rateLimit argument can be either:
  • a number (representing the maximum number of requests per second of your plan - useful for custom plans)
  • a value of the BlastSubscriptionPlan enum: Free, Developer or Startup (they default to the maximum number of requests per second of the Free, Developer and Startup plans)
In order to disable rate limiting handling the rateLimit argument needs to be:
  • undefined

BlastNetwork

This is an enum with all our available networks and it can be used like this:
BlastNetwork.<network> where <network> is one of:
  • ARBITUM_GOERLI
  • ARBITUM_ONE
  • ARBITUM_NOVA
  • ARBITUM_SEPOLIA
  • ASTAR_MAINNET
  • BASE_GOERLI
  • BASE_MAINNET
  • BSC_MAINNET
  • BSC_TESTNET
  • ETH_MAINNET
  • ETH_SEPOLIA
  • ETH_GOERLI
  • EVMOS_MAINNET
  • FANTOM_MAINNET
  • FANTOM_TESTNET
  • GNOSIS_MAINNET
  • LINEA_GOERLI
  • LINEA_MAINNET
  • MANTLE_GOERLI
  • MANTLE_MAINNET
  • METIS_MAINNET
  • MOONBASE_ALPHA
  • MOONBEAM_MAINNET
  • MOONRIVER_MAINNET
  • OKTC_MAINNET
  • OPTIMISM_MAINNET
  • OPTIMISM_GOERLI
  • PALM_MAINNET
  • PALM_TESTNET
  • POLYGON_MAINNET
  • POLYGON_TESTNET
  • SCROLL_ALPHANET
  • SCROLL_MAINNET
  • SCROLL_SEPOLIA
  • SHIDEN_MAINNET
  • SHIDEN_SHIBUYA
Below networks can be found in the enum but are not supported by the SDK yet:
  • APTOS_MAINNET
  • APTOS_TESTNET
  • AVALANCHE_MAINNET
  • AVALANCHE_TESNTET
  • ELROND_MAINNET_API
  • ELROND_MAINNET_GATEWAY
  • ELROND_DEVNET_API
  • ELROND_TESTNET
  • STARKNET_TESTNET
  • STARKNET_MAINNET

Builder API

In order to use the new builder API create the blast config as above and run one of the blast methods
const config: BlastConfig = {
projectId: '<insert-your-project-id-here>',
network: BlastNetwork.ETH_MAINNET,
rateLimit: BlastSubscriptionPlan.Free,
};
const blast = new Blast(config);
const result = await blast.builder.getTransaction('0x067ce4942cb3c65fe74e21063c35f786eb666712ba5d074d2dff56a6d28c1ba3')
console.log(result)
The builder API works only on supported networks and only using a paid plan.

Builder API supported networks

The Builder API supports only the following networks:
  • ARBITRUM_ONE
  • BASE_MAINNET
  • ETH_MAINNET
  • OPTIMISM_MAINNET

Rate limit handling

This feature is enabled by default, but it can be disabled in the blast config. If disabled, every time the plan's throughput is exceeded, a Rate limit reached error will be returned. If enabled, this error will be handled by the SDK.

How it works?

Using the plan provided in the blast config, the SDK queues the requests and every time a request would cause a Rate limit reached error, the entire queue is delayed exactly the amount of milliseconds needed for the error not to happen.
For example, if 42 requests are sent at once, in a free plan scenario (40 requests/second), the first 40 requests are made instantly, then the 41st and 42nd requests wait the minimum time necessary until they are allowed to be executed.
Because unexpected delays may occur between the SDK and the server, these calculations cannot always be exact. Thus, sometimes some requests could get a Rate limit reached error. This happens only internally and we handle them by placing them back in the queue to be executed again. Thus, all of the user's requests are executed and never receive a Rate limit reached error.