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.
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.
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.
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.
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.
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:
pageItemsto indicate the number of items returned,
totalItemsto indicate the total remaining items,
pageto indicate the current page, and
morea 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.
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.
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:
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
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.
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 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
Responses can be pre-sorted (in ascending or descending order) on the API side according to a variety of metrics including
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.