Skip to main content

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

A list of supported tokens received from the tokens subdomain

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.

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.