- API reference
- Authentication
- Get a list of all projects
- Get metric availability for a project
- Get historical metrics for a project
- Get metric aggregations for a project
- Get financial statement for a project
- Get a list of all metrics
- Get metric data for multiple projects
- Get metric aggregations for multiple projects
- Get trending contracts
- Use the API in Google Sheets
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 API 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 | |
|---|---|
| 200 | for 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 |
| 402 | for when subscription isn't valid |
| 403 | for invalid access |
| 429 | for too many requests (rate limit: 60 requests per minute) |
| 500 | if 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).
When logged in as an API subscriber, 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 endpointUse 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.
| Response | Description |
|---|---|
| name | Returns the project name used on the web application. |
| project_id | Required input on the API when retrieving data for a project. |
| symbol | Returns the ticker for a project’s token (exists if token is launched). |
| url | Returns a link to the endpoint for querying a project’s metric availability data. |
Request URL
https://api.tokenterminal.com/v2/projects
Get metric availability for a project
API endpointUse 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.
| Request | Description |
|---|---|
| project_id(required) | Required input on the API when retrieving data for a project. |
| Response | Description |
|---|---|
| name | Returns the project name used on the web application. |
| project_id | Returns the ID of the project. |
| symbol | Returns the ticker for a project's token (exists if token is launched). |
| description | Returns project's description for who, what, and how. |
| market_sectors | Returns the market sectors the project belongs to. |
| chains | Returns the chains the project operates on, e.g. ethereum, avalanche. |
| links | Returns the links to the project's website, social media, and other resources. |
| aggregate_by_options | Returns what a metric can be aggregated by (used in aggregate_by). |
| metric_availability | Returns the metrics that are available for the project. |
Request URL
Select required field to get request url
Get historical metrics for a project
API endpointUse 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.
| Request | Description |
|---|---|
| project_id(required) | Allows you to select one of the projects available. The full list is available on the projects endpoint (see above). |
| metric_ids | Allows 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_by | Allows 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. |
| start | Allows 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). |
| end | Allows 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_direction | Allows 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. |
| Response | Description |
|---|---|
| timestamp | Returns the historical date for a given metric(s). |
| project_name | Returns 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.
|
Request URL
Select required field to get request url
Get metric aggregations for a project
API endpointUse 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.
| Request | Description |
|---|---|
| project_id(required) | Allows you to select one of the projects available. |
| Response | Description |
|---|---|
| project_name | Returns the project name used on the web application. |
| project_id | Returns the project ID used on the web application. |
| metric_id | Returns the chosen metric for the project(s). |
| metric_aggregation_name | Returns the chosen metric metric aggregation for the project(s). |
| value | Returns the value of the chosen metric aggregation. |
Request URL
Select required field to get request url
Get financial statement for a project
API endpointUse this endpoint to retrieve the financial statement report for a project.
Click the button on the modal to the right to retrieve live data from the API.
| Request | Description |
|---|---|
| project_id(required) | The project ID to retrieve financial statement for. |
| timestamp_granularity | The financial statement time granularity. |
| interval | The time interval to retrieve financial statement for. |
| Response | Description |
|---|---|
| timestamp | The timestamp of the data point. |
| timestamp_label_heading | The heading for granularity, e.g. Q3 2023. |
| timestamp_label_subheading | The subheading for the granularity, e.g. Oct 1 - Dec 31. |
| timestamp_granularity | The date granularity, e.g. quarter. |
| project_name | The project's name. |
| section | The section a metric belongs to, e.g. Income statement. |
| metric_id | The metric ID. |
| value | The value of the metric. |
| pop_change | The change ratio of the metric value to the previous value. |
| definition | The definition of the metric. |
Request URL
Select required field to get request url
Get a list of all metrics
API endpointUse 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.
| Response | Description |
|---|---|
| metric_id | Required input on the API when retrieving data for a metric. |
| metric_name | The metric's name. |
| url | Returns a link to the endpoint for querying metric-specific data. |
Request URL
https://api.tokenterminal.com/v2/metrics
Get metric data for multiple projects
API endpointUse 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.
| Request | Description |
|---|---|
| metric_id(required) | Allows you to select one of the metrics available. The full list is available on the metrics endpoint (see above). |
| project_ids | 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. |
| start | Allows 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). |
| end | Allows 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). |
| Response | Description |
|---|---|
| timestamp | Returns the historical date for a given metric(s). |
| project_name | Returns the project name used on the web application. |
| metric_id | Returns the chosen metric for the project(s). |
| value | Returns the value of the chosen metric. |
Request URL
Select required field to get request url
Get metric aggregations for multiple projects
API endpointUse 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.
| Request | Description |
|---|---|
| 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_ids | Allows 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. |
| Response | Description |
|---|---|
| project_name | Returns the project name used on the web application. |
| project_id | Returns the project ID used on the web application. |
| metric_id | Returns the chosen metric for the project(s). |
| metric_aggregation_name | Returns the chosen metric metric aggregation for the project(s). |
| value | Returns the value of the chosen metric aggregation. |
Request URL
Select required field to get request url
Get trending contracts
API endpointUse this endpoint to retrieve trending contracts.
Click the button on the modal to the right to retrieve live data from the API.
| Request | Description |
|---|---|
| chain_ids | Provide a list of chain IDs to filter the results by. If not provided, the results will include all chains. Note that requesting all chains is a big payload and takes a while to transfer. |
| interval | The time interval to retrieve the Trending contracts data for. For example, a 30d interval will rank contracts based on 30 day gas usage and return the top 1000 contracts. |
| Response | Description |
|---|---|
| project_name | The name of the project this contract belongs to (if applicable). |
| chain_id | The chain of the contract. |
| address | The address of the contract. |
| title | The title of the contract. |
| interval | The time interval for the data point. |
| gas_used_usd | The amount of gas used in USD. |
| gas_used_usd_trend | The trend for gas usage. |
| n_transactions | The number of transactions. |
| n_transactions_trend | The trend for number of transactions. |
| n_interacting_addresses | The number of interacting addresses. |
| n_interacting_addresses_trend | The trend for number of interacting addresses. |
| avg_gas_per_tx_usd | The average gas per transaction in USD. |
| avg_gas_per_tx_usd_trend | The trend for average gas per transaction. |
| pct_gas_market | The percentage of the gas market. |
| pct_gas_market_trend | The trend for percentage of the gas market. |
| inflows_usd | The inflows in USD. |
| inflows_usd_trend | The trend for inflows. |
| outflows_usd | The outflows in USD. |
| outflows_usd_trend | The trend for outflows. |
| deployment_date | The deployment date. |
| is_mev_bot | Whether the contract is a MEV bot. |
| is_erc20 | Whether the contract is an ERC20 token. |
| is_erc721 | Whether the contract is an ERC721 token. |
| is_erc1155 | Whether the contract is an ERC1155 token. |
| is_smart_contract | Whether the contract is a smart contract. |
| is_eoa | Whether the contract is an EOA. |
Request URL
https://api.tokenterminal.com/v2/trending-contracts?interval=30d
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:
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.
Step 4: Open the API Connector extension and fill in the required fields
See steps 1-4 in the picture below.
- 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)
- Type in “Authorization” in the first box (Key), and type in “Bearer [insert your API key here]” in the second box (Value)
- Click on “Set current” to choose Sheet 1, or type in another sheet number
- Save the query if you want to save this query (reuse it later). Then click “Run”. Results will appear in the sheet. Enjoy!
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.