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
Component | Endpoint | Base Fee | ICs to consider |
---|---|---|---|
Tsunami API | Get Events | 8 | topics, op_code, range, limit |
Tsunami API | Get Calls | 8 | topics, op_code, range, limit |
Tsunami API | Get Decoded Events | 12 | topics, op_code, range, limit |
Tsunami API | Get Decoded Calls | 12 | topics, op_code, range, limit |
Tsunami API | Get Single Block | 4 | |
Tsunami API | Get Block Range | 6 | |
Tsunami API | Get Wallet Transactions | 32 | range, limit |
Tsunami API | Get Transaction | 6 | |
Tsunami API | Get Transaction Logs | 16 | |
Tsunami API | Get Wallet Transfers | 32 | asset_type, range, limit |
Tsunami API | Get Token Transfers | 32 | asset_type, range, limit |
Tsunami API | Get Contract Self-Destruct | 6 | range, limit |
Tsunami API | Get Contract Create | 6 | range, limit |
Real-Time Streaming | Real-time Filter Create | 0 | |
Real-Time Streaming | Real-time Filter List | 0 | |
Real-Time Streaming | Real-time Filter Delete | 0 | |
NFT API | Address Inventory | 16 | metadata, sale_prices, limit |
NFT API | Address Inventory History | 16 | metadata, sale_prices, limit |
NFT API | Token Ownership History | 16 | metadata, sale_prices, limit |
NFT API | Token Metadata | 16 | metadata, sale_prices, limit |
NFT API | Contract Metadata | 8 | |
NFT API | Current Collection Owners | 16 | metadata, sale_prices, limit |
Balances API | Get Balances by Address | 16 | |
Balances API | Get Balances by Contract | 16 | |
Balances API | Get Contract Metadata | 16 |
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".
Parameters | Topic cost (in CUs) |
---|---|
contract=0x00 | 0 |
contract=0x000&origin=0x0001 | 0 |
contract=0x00&topic0=val0 | 16 |
contract=0x00&topic0=val0,val1 | 18 |
contract=0x000&topic0=val0,val1&topic2=val0 | 34 |
contract=0x000&topic0=val0,val1&topic2=val0,val1,val2 | 38 |
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:
Parameters | Range 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.
Parameters | Asset type cost (in CUs) |
---|---|
asset_type=ft | 0 |
asset_type=ft,nft | 32 |
asset_type=ft,nft,multi | 64 |
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.
Name | Value |
---|---|
Ethereum Mainnet | 1.0 |
Polygon PoS | 1.0 |
Polygon zkEVM | 1.0 |
BNB Smart Chain Mainnet | 1.0 |
Avalanche C-Chain | 1.0 |
Arbitrum One | 1.0 |
Metis Andromeda | 1.0 |
Ethereum Sepolia | 1.0 |
Ethereum Görli | 1.0 |
Polygon Mumbai | 1.0 |
BNB Smart Chain Testnet | 1.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.