To maximize the effectiveness and efficiency of the API, we recommend following these best practices.

By structuring your workflow according to these guidelines, you will ensure that your application or analysis is robust, scalable, and performs optimally.

​
Maintain an up-to-date cache of projects and metrics

Token Terminal regularly updates the list of supported projects and metrics. To ensure your application or analysis remains current, it is best practice to maintain your own cache or index.

We recommend caching the responses from the /projects and /metrics endpoints. This allows you to quickly reference available projects and supported metrics without making redundant API calls.

The responses should be updated periodically based on your needs, ideally daily or weekly, depending on how frequently you expect changes in the data.

// Get the list of projects
GET https://api.tokenterminal.com/v2/projects

// Get the list of metrics
GET https://api.tokenterminal.com/v2/metrics

By caching responses from these endpoints, you can easily reference available projects and supported metrics.

​
Utilize metric endpoints for detailed data

The most flexible and powerful way to interact with Token Terminal data is via metric endpoints.

They allow you to retrieve detailed metrics for specific projects, chains, and time ranges.

The following call retrieves revenue metrics for Uniswap and Aave projects on Ethereum between specified dates:

GET https://api.tokenterminal.com/v2/metrics/revenue?project_ids=uniswap,aave&chain_ids=ethereum&start_date=2025-01-01&end_date=2025-03-01

​
Use breakdown aggregation API for summarized responses

Instead of fetching time series data first, and then aggregating it, you can directly request summarized data using the breakdown API. This is particularly useful for reducing the amount of data transferred and speeding up response times.

The following call retrieves the revenue breakdown aggregation for Uniswap and Aave projects for the specified date range and applying aggregations like avg, change, sum and trend:

GET https://api.tokenterminal.com/v2/metrics-breakdown/revenue?project_ids=uniswap,aave&start_date=2024-01-01&end_date=2024-03-01

​
Handling errors and missing data

Proper error handling ensures your application remains stable even when data is temporarily unavailable or incorrect parameters are provided.

Check HTTP response status codes:

  • 200: Successful response
  • 400: Bad request (invalid parameters)
  • 404: Data not found (possibly unsupported project/metric)
  • 429: Too many requests (rate limiting)

Here’s an example of how to handle errors in Python:

import requests
import os

def fetch_data():
    # Get API key and set up headers once before the loop
    api_key = os.environ.get('TOKEN_TERMINAL_API_KEY', '')
    headers = {
        'Authorization': f'Bearer {api_key}'
    }
    current_wait_time = wait_time  # Use a local variable for exponential backoff

    for attempt in range(retry_attempts):
        response = requests.get(
            'https://api.tokenterminal.com/v2/metrics/revenue',
            headers=headers,
            params={
                'project_ids': 'uniswap',
                'chain_ids': 'ethereum',
                'start_date': '2024-01-01',
                'end_date': '2024-03-01'
            }
        )

        # Handle success case
        if response.status_code == 200:
            print("Successfully fetched data:")
            print(response.json())
            return # Exit after success

        # Handle rate limit case
        if response.status_code == 429:
            print(f"Rate limited. Waiting for {current_wait_time} seconds.")
            time.sleep(current_wait_time)
            current_wait_time *= 2  # exponential backoff
        else:
            # For other errors, print message and stop retrying
            print(f"Unexpected error: {response.status_code}")
            print(f"Response: {response.text}")
            return

    print(f"Failed to fetch data after {retry_attempts} attempts.")

if __name__ == "__main__":
    fetch_data()

​
Managing rate limiting

Token Terminal implements rate limiting to ensure fair usage. You should handle rate limits gracefully by implementing exponential backoff or retry logic.

Rate limit recommendation: Monitor for HTTP 429 responses and implement retry logic.

Here’s an example of how to handle rate limiting in Python:

import requests
import os
import time

retry_attempts = 3
wait_time = 5  # seconds

def fetch_data():
    for attempt in range(retry_attempts):
    # Get API key from environment variable or set directly
    # For security reasons, it's better to use environment variables
    api_key = os.environ.get('TOKEN_TERMINAL_API_KEY', '')

    # Set up headers with API key
    headers = {
        'Authorization': f'Bearer {api_key}'
    }

    response = requests.get(
        'https://api.tokenterminal.com/v2/metrics/revenue',
        headers=headers,
        params={
            'project_ids': 'uniswap',
            'chain_ids': 'ethereum',
            'start_date': '2024-01-01',
            'end_date': '2024-03-01'
        }
    )

    # Here, just handle the rate limit case
    if response.status_code == 429:
        print(f"Rate limited. Waiting for {wait_time} seconds.")
        time.sleep(wait_time)
        wait_time *= 2  # exponential backoff
    else:
        print(f"Unexpected error: {response.status_code}")
        print(f"Response: {response.text}")

if __name__ == "__main__":
    fetch_data()