Getting Tokens

Summary

The token endpoints return data about all of the opportunities supported by the API. The responses are formatted such that they are easy to use in many contexts such as displaying a simple list to users, presenting complete token overview pages, creating approval and Portal transactions, and more.

You can use our Token List subdomain to cache a list of supported opportunities on your app to improve responsiveness.

In addition, integrating the v2/tokens endpoint in a way that makes use of the provided filters, search, and sorting methods will ensure that you only retrieve the data you need in the format you need it. This allows the endpoint to have blazingly fast response times and prevents the client from overfetching.

Endpoints

GET all

This subdomain is for retrieving a cached Token List compliant list of tokens supported by the API. You should fetch and store this list on the client as a 'phone book' for displaying possible input/output selections to the user.

NOTE: This list does not include pricing, liquidity, or underlying token data. It only provides the basic information necessary to display a token to the user. Read on to learn how to get more details about each token.

Example

The token list can be used to display a list of all possible input/output token options to the user in an alphabetically sorted manner

After token selection more details can be displayed to the user using the v2/tokens endpoint.

GET v2/tokens

The tokens endpoint is the main entrypoint into the supported opportunities and includes robust search and filtering capabilities making it easy to find opportunities of interest. It returns a paginated list which includes additional information about each token's price, liquidity, underlying token data, and images, in addition to the details returned by the Token List.

Pagination

The v2/tokens endpoint uses pagination to avoid overwhelming callers with large responses. By default, 25 items will be returned, with the optionality to return up to 250 items, per page. The page size can be set with the limit option. To assist with handling pages, the response also includes:

• pageItems to indicate the number of items returned,
• totalItems to indicate the total remaining items,
• page to indicate the current page, and
• more a boolean value indicating whether or not there are additional pages to query.

In order to minimize pagination, it is highly recommended to make use of the search and filter methods described below.

Search

One of the most powerful features of the tokens endpoint is the search field which allows you to quickly find opportunities with high specificity. For example you can search for "beefy dai" to find all of the Beefy vaults that support DAI across all Networks. To further narrow your search, you can make use of the filter methods shown below.

Filters

Making use of filters is the easiest way to reduce overfetching data and reduce load times for end users. The API supports several filters to narrow down search space including:

IDs

If you'd like to find a specific opportunity, you can use the ids filter. Each opportunity is uniquely described by [network:address] to ensure cross-chain specificity. For example you can find the Stargate USDC pool on Ethereum with the query ids=ethereum:0xdf0770df86a8034b3efef0a1bb3c889b8332ff56. If you need to retrieve information about many tokens at once, you can use the addresses field which accepts an array of ids.

Platforms

To increase granularity and return all of a platform's opportunities, you can use the platforms filter which accepts a platformId. For example to get a list of Aave V3 opportunities, you can use the query platforms=aavev3. To request multiple platforms, use the notation platforms=aavev3&platforms=[platformId]. You can find a list of platformIds in the Platforms section.

Networks

You can also filter opportunities by network using the networks filter. For example, to return opportunities from only the arbitrum network, use the networks=arbitrum filter. For a list of networks, see the Networks section.

Liquidity

Liquidity filters allow you to set a minimum and maximum USD threshold and can be useful when querying data from a variety of platforms. For example, Pancakeswap pools are constantly being created but many of them have very little liquidity. To avoid paging through hundreds of pools you're not interested in, you can use the minLiquidity filter to remove pools with less than a desired liquidity amount. To exclude Pancakeswap pools with less than $1000 USD in reserves, you can use the query minLiquidity=1000. Conversely, to exclude pools that have greater than your desired liquidity, use the maxLiquidity filter.

Sorting

Responses can be pre-sorted (in ascending or descending order) on the API side according to a variety of metrics including price, liquidity, name apy, volumeUsd, and more. A common use case for this is to sort your response by liquidity in order to present the most popular opportunities at the top of a list.