API reference

The Token Terminal API allows you to access all of the data that powers the Token Terminal web application.

Users on the Token Terminal Pro plan can query the data with their designated API key, which can be found on their account page. The API key should be kept a secret, so make sure to not share it or store it in publicly accessible areas such as GitHub, client-side code, and so forth.

The API is read-only, supports REST calls, uses predictable resource-oriented URLs, and returns JSON-encoded responses and error messages.

We use standard HTTP response codes
200for success
308 for redirects when e.g. project_id has been renamed (only when projects make a significant rebranding)
400 for when query parameters are invalid, see included JSON formatted error message for advice
402for when subscription isn't valid
403for invalid access
500if we ever mess up

Authentication

The API uses HTTP Token Auth to authenticate requests. This means each request must have an Authorization header (your API key).

Only Pro users have access to the API.

When logged in, each example automatically includes your personal API key. You can find the API key on your personal account page.

Get a list of all projects

API endpoint

Use this endpoint to retrieve a list of all projects that are available on the API.

Click the button on the modal to the right to retrieve live data from the API.

ResponseDescription
nameReturns the project name used on the web application.
project_idRequired input on the API when retrieving data for a project.
symbolReturns the ticker for a project’s token (exists if token is launched).
urlReturns a link to the endpoint for querying a project’s metric availability data.
GET
/v2/projects

Request URL

https://api.tokenterminal.dev/v2/projects

Get metric availability for a project

API endpoint

Use this endpoint to retrieve the metric availability for a project.

Click the button on the modal to the right to retrieve live data from the API.

RequestDescription
project_id(required)Required input on the API when retrieving data for a project.
ResponseDescription
nameReturns the project name used on the web application.
project_idReturns the ID of the project.
symbolReturns the ticker for a project's token (exists if token is launched).
descriptionReturns project's description for who, what, and how.
market_sectorsReturns the market sectors the project belongs to.
chainsReturns the chains the project operates on, e.g. ethereum, avalanche.
linksReturns the links to the project's website, social media, and other resources.
aggregate_by_optionsReturns what a metric can be aggregated by (used in aggregate_by).
metric_availabilityReturns the metrics that are available for the project.
GET
/v2/projects/:project_id
NameDescription
project_id*

(path)

Select...

Request URL

Select required field to get request url

Get historical metrics for a project

API endpoint

Use this endpoint to retrieve historical data for a project. Fill in the required fields on the modal to the right.

Click the button on the modal to the right to retrieve live data from the API.

RequestDescription
project_id(required)Allows you to select one of the projects available. The full list is available on the projects endpoint (see above).
metric_idsAllows you to select one or more of the metrics available for a specific project. When including multiple metrics, separate each one with a comma. Example: fees, volume. If no metric_id is selected, the query defaults to returning all available metrics for the project.
aggregate_byAllows you to query specific metrics in a more granular way. For example, it allows you to query a project's revenue per chain. Note that it is only applicable to certain metrics. For example, it is not possible to aggregate the price metric by chain, whereas the fees metric can be split by chain. The currently supported aggregations are chain, version, and business line.
startAllows you to select the start date for the query. If no start is selected, the query defaults to launch date or the first date for which there is data available for the chosen metric(s).
endAllows you to select the end date for the query. If no end is selected, the query defaults to the latest date for which there is data available for the chosen metric(s).
order_directionAllows you to define how the response is sorted. The response is always sorted by timestamp, and by selecting desc the response starts from the most recent entry, and vice versa for asc. If no order_direction is selected, the response defaults to desc.
ResponseDescription
timestampReturns the historical date for a given metric(s).
project_nameReturns the project name used on the web application.
chain

Returns the chosen metric(s) per chain.

Has to be selected from the aggregate_by parameter.

business_line

Returns the chosen metric(s) per business line.

Has to be selected from the aggregate_by parameter.

version

Returns the chosen metric(s) per version.

Has to be selected from the aggregate_by parameter.

metric_id(s)

Returns the chosen metric(s) for the project. The full list of available metrics can be retrieved from the projects/:project_id endpoint (see above).

The metric_id(s) have to be selected from the metric_ids parameter.

GET
/v2/projects/:project_id/metrics
NameDescription
project_id*

(path)

Select...
metric_ids

(query)

Select...
aggregate_by

(query)

Select...
start

(query)

end

(query)

order_direction

(query)

Select...

Request URL

Select required field to get request url

Get metric aggregations for a project

API endpoint

Use this endpoint to retrieve metric aggregation data for one project.

Click the button on the modal to the right to retrieve live data from the API.

RequestDescription
project_id(required)Allows you to select one of the projects available.
ResponseDescription
project_nameReturns the project name used on the web application.
project_idReturns the project ID used on the web application.
metric_idReturns the chosen metric for the project(s).
metric_aggregation_nameReturns the chosen metric metric aggregation for the project(s).
valueReturns the value of the chosen metric aggregation.
GET
/v2/projects/:project_id/metric-aggregations
NameDescription
project_id*

(path)

Select...

Request URL

Select required field to get request url

Get a list of all metrics

API endpoint

Use this endpoint to retrieve a list of all metrics available on the API.

Click the button on the modal to the right to retrieve live data from the API.

ResponseDescription
metric_idRequired input on the API when retrieving data for a metric.
metric_nameThe metric's name.
urlReturns a link to the endpoint for querying metric-specific data.
GET
/v2/metrics

Request URL

https://api.tokenterminal.dev/v2/metrics

Get metric data for multiple projects

API endpoint

Use this endpoint to retrieve metric data for multiple projects.

Click the button on the modal to the right to retrieve live data from the API.

RequestDescription
metric_id(required)Allows you to select one of the metrics available. The full list is available on the metrics endpoint (see above).
project_idsAllows you to select one or more of the projects available for a specific metric. When including multiple projects, separate each one with a comma. Example: aave,uniswap.
startAllows you to select the start date for the query. If no start is selected, the query defaults to launch date or the first date for which there is data available for the chosen metric(s).
endAllows you to select the end date for the query. If no end is selected, the query defaults to the latest date for which there is data available for the chosen metric(s).
ResponseDescription
timestampReturns the historical date for a given metric(s).
project_nameReturns the project name used on the web application.
metric_idReturns the chosen metric for the project(s).
valueReturns the value of the chosen metric.
GET
/v2/metrics/:metric_id
NameDescription
metric_id*

(path)

Select...
project_ids

(query)

Select...
start

(query)

end

(query)

Request URL

Select required field to get request url

Get metric aggregations for multiple projects

API endpoint

Use this endpoint to retrieve metric aggregations for multiple projects.

Click the button on the modal to the right to retrieve live data from the API.

RequestDescription
project_ids(required)Allows you to select one or more of the projects available for a specific metric. When including multiple projects, separate each one with a comma. Example: aave,uniswap.
metric_idsAllows you to fetch all aggregations for the given comma separated list of metrics available. The full list is available on the metrics endpoint (see above). If no metric_id is selected, the query defaults to returning all available metrics for the project.
ResponseDescription
project_nameReturns the project name used on the web application.
project_idReturns the project ID used on the web application.
metric_idReturns the chosen metric for the project(s).
metric_aggregation_nameReturns the chosen metric metric aggregation for the project(s).
valueReturns the value of the chosen metric aggregation.
GET
/v2/metric-aggregations
NameDescription
project_ids*

(query)

Select...
metric_ids

(query)

Select...

Request URL

Select required field to get request url

Use the API in Google Sheets (no code)

Step by step guide for retrieving data from the API into your Google Sheets in under 5min.

Step 1: Create a new Google spreadsheet
Open a new spreadsheet at https://docs.google.com/spreadsheets

Step 2: Add extension (API Connector)
Click on Extensions > Add-ons > Get add-ons:

A screenshot of Google Sheets with the Add-ons menu pane open

Step 3: Download "API Connector" from the Google Workspace Marketplace
We recommend using a popular extension, such as API Connector by Mixed Analytics. Once downloaded, you will find the new add-on under the "Extensions" tab.

A screenshot of Google Sheets with the market place modal open and filtered by API Connector

Step 4: Open the API Connector extension and fill in the required fields
See steps 1-4 in the picture below.

  1. Paste the full API query here. Please note that you can fetch the full query by copying it (See “Request URL” below the API modal)
  2. Type in “Authorization” in the first box (Key), and type in “Bearer [insert your API key here]” in the second box (Value)
  3. Click on “Set current” to choose Sheet 1, or type in another sheet number
  4. Save the query if you want to save this query (reuse it later). Then click “Run”. Results will appear in the sheet. Enjoy!
A screenshot of Google Sheets with the connector api open with steps on how to configure it

Note The integration to Google Sheets can also be done programatically (by using Google Apps Script). This allows you to automate the process of retrieving and updating the data.