Upgrade to v1

This guide covers the migration from the legacy API structure to the new v1 API. The refactoring introduces versioned endpoints, standardized query parameters, improved batching support, and consistent naming conventions.

Note

EVM = Ethereum Virtual Machine

Used to describe endpoints supporting EVM-based chains (e.g. base, bsc, mainnet, …).

SVM = Solana Virtual Machine

Used to describe endpoints supporting Solana (currently the only SVM chain supported).

🔑 Breaking Changes Summary

1. API Versioning

All endpoints now use the /v1 prefix.

Before:

1GET /balances/evm2GET /nft/items/contract/:contract/token_id/:token_id

After:

1GET /v1/evm/balances2GET /v1/evm/nft/items

2. Route Structure Reorganization

2.1 EVM Endpoints

Consolidated under /v1/evm/*

Old Endpoint	New Endpoint
`/balances/evm`	`/v1/evm/balances`
`/historical/balances/evm`	`/v1/evm/balances/historical`
`/holders/evm/:contract`	`/v1/evm/holders`
`/tokens/evm/:contract`	`/v1/evm/tokens`
`/transfers/evm`	`/v1/evm/transfers`
`/pools/evm`	`/v1/evm/pools`
`/swaps/evm`	`/v1/evm/swaps`
`/dexes/evm`	`/v1/evm/dexes`
`/ohlc/prices/evm/:contract`	(removed)
`/ohlc/pools/evm/:pool`	`/v1/evm/pools/ohlc`
`/nft/ownerships/evm/:address`	`/v1/evm/nft/ownerships`
`/nft/collections/evm/:contract`	`/v1/evm/nft/collections`
`/nft/items/evm/contract/:contract/token_id/:token_id`	`/v1/evm/nft/items`
`/nft/holders/evm/:contract`	`/v1/evm/nft/holders`
`/nft/activities/evm`	`/v1/evm/nft/transfers`
`/nft/sales/evm`	`/v1/evm/nft/sales`

Important: The NFT endpoint /nft/activities has been renamed to /v1/evm/nft/transfers to better reflect its purpose.

Important: The EVM Token OHLCV Data endpoint /ohlc/prices/evm/{contract} has been removed. You can use /v1/evm/pools to find stablecoin pairs for your contract and /v1/evm/pools/ohlc for OHLCV data for that pair.

2.2 New EVM native balances endpoint

Native balances for EVM chains can be found under /v1/evm/balances/native. They will not show up in the /v1/evm/balances endpoint.

Other endpoints can still use native token under the 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee contract.

2.3 SVM Endpoints

Consolidated under /v1/svm/*

Old Endpoint	New Endpoint
`/balances/svm`	`/v1/svm/balances`
`/balances/native/svm`	`/v1/svm/balances/native`
`/holders/svm/:contract`	`/v1/svm/holders`
`/tokens/svm/:mint`	`/v1/svm/tokens`
`/transfers/svm`	`/v1/svm/transfers`
`/pools/svm`	`/v1/svm/pools`
`/swaps/svm`	`/v1/svm/swaps`
`/dexes/svm`	`/v1/svm/dexes`
`/owner/svm/:account`	`/v1/svm/owner`
`/ohlc/pools/svm/:pool`	`/v1/svm/pools/ohlc`

📝 Parameter Changes

3. Path Parameters → Query Parameters

All path parameters have been moved to query parameters.

Before:

1GET /balances/evm/:address2GET /holders/evm/:contract3GET /nft/items/evm/contract/:contract/token_id/:token_id

After:

1GET /v1/evm/balances?network=mainnet&address=0x...2GET /v1/evm/holders?network=mainnet&contract=0x...3GET /v1/evm/nft/items?network=mainnet&contract=0x...&token_id=5712

4. Standardized Parameter Naming

All query parameters have been standardized to use snake_case naming convention.

Old Parameter	New Parameter	Notes
`network_id`	`network`	Renamed, `matic` has also been renamed to `polygon`
`anyAddress`	`address`	Matches either `from` or `to` address
`from`, `fromAddress`, `offererAddress`	`from_address`, `offerer`	-
`to`, `toAddress`, `recipientAddress`	`to_address`, `recipient`	-
`startTime`	`start_time`	Default: `1735689600` (`2025-01-01`)
`endTime`	`end_time`	Default: `9999999999`
-	`start_block`	New parameter, default: `0`
-	`end_block`	New parameter, default: `9999999999`
-	`include_null_balances`	New parameter, default: `false`
`tx_hash`	`transaction_id`	-
`token`	`input_token`, `output_token`	More explicit for pool queries
`pool`	`amm_pool`	-
`orderBy`, `orderDirection`	(removed)	Always sorted by most recent timestamp first

Important: The network_id parameter has been renamed to network.

Important: matic network has been renamed to polygon.

5. Batched Parameters

Many parameters now support batching - accepting single values or comma-separated strings.

Supported Batched Parameters:

address, from_address, to_address
contract, token_id
factory, pool
owner, token_account, mint
transaction_id, signature

Examples:

1# Single value2?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc234# Comma-separated, single parameter5?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb4867# Repeated parameter values8?contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&contract=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

6. New Parameters

`include_null_balances`

Added to balance endpoints to optionally include zero/null balances.

1?include_null_balances=true

Default: false

🔄 Response Changes

7. Pagination Changes

Pagination responses have been simplified. The API no longer computes total result counts due to performance and accuracy considerations when working with ClickHouse views and materialized tables.

Before:

1{2  "pagination": {3    "previous_page": 1,4    "current_page": 2,5    "next_page": 3,6    "total_pages": 107  },8  "total_results": 12349}

After:

1{2  "pagination": {3    "previous_page": 1,4    "current_page": 25  }6}

Removed fields:

next_page
total_pages
total_results

Important: To retrieve all results, continue incrementing the page parameter until the API returns an empty data array. This indicates you’ve reached the end of the results.

8. Removed Parameters

The following deprecated parameters have been removed:

orderBy - Results are now ordered by timestamp/block by default
orderDirection - Always descending (newest first)

📚 Example Migrations

Old vs New: Get Token Balances

Before:

1GET /balances/evm/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?network_id=mainnet&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2

After:

1GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2

New Feature: Batched Queries

Query balances for multiple contracts in a single request:

1GET /v1/evm/balances?network=mainnet&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&contract=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2,0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

⚠️ Important Notes

Backward Compatibility: The old endpoints are deprecated and will be removed in the future. Migrate by Oct 30, 2025.
Default Sorting: All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported.
Pagination: Continue paging through results by incrementing the page parameter until you receive an empty data array. The API no longer provides total counts due to performance optimizations with ClickHouse.
Time Defaults: If you previously relied on fetching all historical data without time filters, note that start_time now defaults to 2025-01-01. Adjust accordingly if you need earlier data.