Explore the concept of computational units, their purpose, and the calculation process for API products

Background

To ensure clarity and consistency in pricing for our API, we have introduced the concept of a computational unit (CU). This serves as a standard unit of measurement for estimating the cost of a request within our product.

CU cost calculation

The CU cost of a request is determined by using the following formula:

total CUs = (base fee + input complexity) / blockchain complexity

To better understand, let's analyze the components of the formula:

Base fee

The processing complexity fee is charged for each endpoint based on various actions involved in handling a request, such as extraction, processing, storage, activation, and delivery. Each of these actions is considered to consume 1 CU. The processing complexity fee is determined before implementing an endpoint and remains constant even in minor version updates.

Base fee costs

ComponentEndpointBase FeeICs to consider
Tsunami APIGet Events8topics, op_code, range, limit
Tsunami APIGet Calls8topics, op_code, range, limit
Tsunami APIGet Decoded Events12topics, op_code, range, limit
Tsunami APIGet Decoded Calls12topics, op_code, range, limit
Tsunami APIGet Single Block4
Tsunami APIGet Block Range6
Tsunami APIGet Wallet Transactions32range, limit
Tsunami APIGet Transaction6
Tsunami APIGet Transaction Logs16
Tsunami APIGet Wallet Transfers32asset_type, range, limit
Tsunami APIGet Token Transfers32asset_type, range, limit
Tsunami APIGet Contract Self-Destruct6range, limit
Tsunami APIGet Contract Create6range, limit
Real-Time StreamingReal-time Filter Create0
Real-Time StreamingReal-time Filter List0
Real-Time StreamingReal-time Filter Delete0
NFT APIAddress Inventory16metadata, sale_prices, limit
NFT APIAddress Inventory History16metadata, sale_prices, limit
NFT APIToken Ownership History16metadata, sale_prices, limit
NFT APIToken Metadata16metadata, sale_prices, limit
NFT APIContract Metadata8
NFT APICurrent Collection Owners16metadata, sale_prices, limit
Balances APIGet Balances by Address16
Balances APIGet Balances by Contract16
Balances APIGet Contract Metadata16

Input complexity (IC)

The Input complexity (IC) measures how complex a user's request is based on their inputs. It mainly applies to raw data requests for most endpoints. Base inputs, such as "origin", "contract", and "op_code", are already included in the base cost and will not incur additional CU costs. However, other factors, such as "topics", "range", and "asset_type", can increase the IC and incur additional charges.

Topics

Topics play a significant role in determining the IC cost. The more topics you provide, the more expensive the request will get. Introducing topics by adding "topicN" to the query incurs a cost of "CUtopic_introduction". Each additional value added to the "topicN" array incurs an extra charge of "CUtopic_value".

ParametersTopic cost (in CUs)
contract=0x000
contract=0x000&origin=0x00010
contract=0x00&topic0=val016
contract=0x00&topic0=val0,val118
contract=0x000&topic0=val0,val1&topic2=val034
contract=0x000&topic0=val0,val1&topic2=val0,val1,val238

Range

When making a request, the specified range values will also affect the IC. The multiplier of range complexity is determined by the range given and can be calculated in the following manner:

ParametersRange multiplier
The multiplier of range complexity within a single block does not affect the cost of request.

block_start=1&block_end=1
1
If the range falls between 1 and 1,000,000, a multiplier of 4 is applied to request cost.

block_start=1&block_end=1,000,000
4
If the range reaches or exceeds 1,000,000, a multiplier of 8 is applied to request cost.

block_start=1&block_end=1,000,001
8

Asset type

The endpoints with the asset_type parameter increase difficulty when introducing a new asset type. One asset type is always included with the base fee of the request. Submitting a new asset type should add CUasset_type to the price of the request.

ParametersAsset type cost (in CUs)
asset_type=ft0
asset_type=ft,nft32
asset_type=ft,nft,multi64

Blockchain complexity (BC)

When calculating the CU cost, the complexity of the blockchain being queried is multiplied by a factor called "blockchain complexity." Below is a list of our available blockchains and their corresponding BC value, usually set to 1.0.

NameValue
Ethereum Mainnet1.0
Polygon PoS1.0
Polygon zkEVM1.0
BNB Smart Chain Mainnet1.0
Avalanche C-Chain1.0
Arbitrum One1.0
Metis Andromeda1.0
Ethereum Sepolia1.0
Ethereum Görli1.0
Polygon Mumbai1.0
BNB Smart Chain Testnet1.0

You can determine the pricing for various requests by understanding how to calculate CU costs. To estimate the CU of your requests, consider the base fee, input complexity, and blockchain complexity.