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/*

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/*

📝 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.

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)

9. Cached Queries

Queries are now cached on the ClickHouse side for better performance.

You can specifically request to not use the cache by setting the Cache-Control header to no-cache.

Example

Cache

1$ curl -s 'https://token-api.thegraph.com/v1/...' | jq .statistics2{3  "bytes_read": 221,4  "rows_read": 1,5  "elapsed": 0.0022120656}

No cache

1$ curl -s 'http://localhost:8000/v1/...' --header 'Cache-Control: no-cache' | jq .statistics2{3  "bytes_read": 14621174348,4  "rows_read": 223244390,5  "elapsed": 0.9710640666}

📚 Example Migrations

Example 1: Get Token Balances

Before:

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

After:

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

Example 2: Get NFT Items

Before:

1GET /nft/items/evm/contract/0xbd3531da5cf5857e7cfaa92426877b022e612cf8/token_id/5712?network_id=mainnet

After:

1GET /v1/evm/nft/items?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&token_id=5712

Example 3: Get Token Transfers with Time Filter

Before:

1GET /token/transfers/evm?network_id=mainnet&from=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&startTime=1735689600&endTime=1767225600

After:

1GET /v1/evm/transfers?network=mainnet&from_address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045&start_time=1735689600&end_time=1767225600

Example 4: Get NFT Transfer Activities

Before:

1GET /nft/activities/evm?network_id=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&anyAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045

After:

1GET /v1/evm/nft/transfers?network=mainnet&contract=0xbd3531da5cf5857e7cfaa92426877b022e612cf8&address=0xd8da6bf26964af9d7eed9e03e53415d37aa96045

Example 5: Get Pool OHLC Data

Before:

1GET /token/ohlc/pools/evm/0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640?network_id=mainnet&interval=1h&startTime=1735689600

After:

1GET /v1/evm/pools/ohlc?network=mainnet&pool=0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640&interval=1h&start_time=1735689600

Example 6: Batched Query (New Feature)

Query balances for multiple contracts in a single request:

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

Query transfers from multiple addresses:

1GET /v1/evm/transfers?network=mainnet&from_address=0xabc...,0xdef...,0x123...&start_time=1735689600

⚠️ Important Notes

1. Migration Notes: The old endpoints were deprecated and removed on October 30, 2025. Please ensure all integrations have been migrated to the new Token API v1 endpoints.

2. Default Sorting: All results are now sorted by timestamp (descending) by default. Custom sorting is no longer supported.

3. 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.

4. 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.