Token list and search

info

Bungee Auto supports trading any token with sufficient liquidity, regardless of whether it appears in the token list responses.

Token Sources and Verification

Bungee maintains a primary data source for token information and categorizes tokens in two ways:

• Verified Tokens: These are recognized by Bungee and are considered verified.
• Unverified Tokens: These are tokens added to our own database that may not be widely listed yet. When these are displayed, we recommend showing a warning to users to exercise caution.

We may add more sources in the future to further expand our token coverage.

How the Endpoints and Parameters Work

• /tokens/list (Default):

  • Returns a curated list of trending tokens, all of which are "verified" (recognized by Bungee).
  • "Trending" is currently determined by trading volume, showing the tokens with the highest volume on each supported network.
  • This list is dynamic, and the trending algorithm may evolve to include other factors for relevance.

• /tokens/list (with list=full parameter):

  • Returns the full, unabridged list of all tokens known to Bungee (including both verified and unverified tokens).
  • Warning: This is a very heavy and slow API call. We strongly recommend not using it in a production frontend application.

• /tokens/search:

  • Designed to find a specific token by its name, symbol, or address (e.g., "USDC").
  • Searches across the entire dataset, including both verified and unverified tokens.

Best Practices

• For the best user experience, we recommend:
  • Using the default /tokens/list to display a relevant, curated list of trending tokens.
  • Maintaining your own list of tokens that are most relevant to your users.
• Most tokens with sufficient liquidity should return a valid route through Bungee, regardless of which list they appear on.

Token list endpoint example usage

The /tokens/list endpoint retrieves a list of available tokens, with optional parameters to customize the response.

API Reference: Token List Endpoint

const BUNGEE_API_BASE_URL = "https://public-backend.bungee.exchange";

async function getTokenList(userAddress, chainIds = [1], isTrending = true) {
  const url = `${BUNGEE_API_BASE_URL}/api/v1/tokens/list`;
  const params = {
    userAddress,
    chainIds: chainIds.join(","),
    list: isTrending ? "trending" : "full",
  };

  const queryParams = new URLSearchParams(params);
  const response = await fetch(`${url}?${queryParams}`);
  const data = await response.json();

  return data;
}

Token search endpoint example usage

The /tokens/search endpoint allows you to search for tokens by address, name, or symbol. Use this endpoint to verify if a specific token can be traded, even if it doesn't appear in the token list.

API Reference: Token Search Endpoint

async function searchToken(query, userAddress) {
  const url = `${BUNGEE_API_BASE_URL}/api/v1/tokens/search`;
  const params = {
    q: query,
    userAddress,
  };

  const queryParams = new URLSearchParams(params);
  const response = await fetch(`${url}?${queryParams}`);
  const data = await response.json();

  return data;
}

Complete Integration Example

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
console.log("Account address:", account.address);

const BUNGEE_API_BASE_URL = "https://public-backend.bungee.exchange";

// Search for a token (by address, symbol, or name)
async function tokenSearch(query, userAddress) {
  try {
    const url = `${BUNGEE_API_BASE_URL}/api/v1/tokens/search`;
    const params = {
      q: query,
      userAddress,
    };

    const queryParams = new URLSearchParams(params);
    const response = await fetch(`${url}?${queryParams}`);
    const data = await response.json();
    const serverReqId = response.headers.get("server-req-id");

    if (!data.success) {
      throw new Error(
        `Search error: ${data.statusCode}: ${data.message}. server-req-id: ${serverReqId}`
      );
    }

    return {
      result: data.result,
      serverReqId,
    };
  } catch (error) {
    console.error("Failed to search for token:", error);
    throw error;
  }
}

// Get token list (trending or complete)
async function tokenList({
  userAddress = "",
  chainIds = [],
  isTrending = null,
} = {}) {
  try {
    const url = `${BUNGEE_API_BASE_URL}/api/v1/tokens/list`;
    const params = {};

    // Only add parameters if they have values
    if (userAddress) {
      params.userAddress = userAddress;
    }

    if (chainIds && chainIds.length > 0) {
      params.chainIds = chainIds.join(",");
    }

    // Only add list parameter if isTrending is explicitly specified
    if (isTrending !== null) {
      params.list = isTrending ? "trending" : "complete";
    }

    const queryParams = new URLSearchParams(params);
    const response = await fetch(`${url}?${queryParams}`);
    const data = await response.json();
    const serverReqId = response.headers.get("server-req-id");

    if (!data.success) {
      throw new Error(
        `List error: ${data.statusCode}: ${data.message}. server-req-id: ${serverReqId}`
      );
    }

    return {
      result: data.result,
      serverReqId,
    };
  } catch (error) {
    console.error("Failed to get token list:", error);
    throw error;
  }
}

// Usage examples
(async () => {
  try {
    let searchResponse;
    // Search for USDC
    searchResponse = await tokenSearch("USDC", account.address);
    console.log(
      "Search results:",
      JSON.stringify(searchResponse.result, null, 2)
    );

    // Search for a token address
    searchResponse = await tokenSearch(
      "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      account.address
    );
    console.log(
      "Search results:",
      JSON.stringify(searchResponse.result, null, 2)
    );

    // Search for a partial token name
    searchResponse = await tokenSearch("Bridged USD Coin", account.address);
    console.log(
      "Search results:",
      JSON.stringify(searchResponse.result, null, 2)
    );

    // Search for a inexisting token
    searchResponse = await tokenSearch("0x123...abc", account.address);
    if (Object.keys(searchResponse.result.tokens).length === 0) {
      console.log(
        "The tokens object is empty, but you can still try to trade this token if it has liquidity"
      );
    }

    let trendingResponse;
    // Get trending tokens on Ethereum and Arbitrum
    trendingResponse = await tokenList({
      userAddress: account.address,
      chainIds: [1, 42161],
      isTrending: true,
    });
    console.log(
      "Trending tokens:",
      JSON.stringify(trendingResponse.result, null, 2)
    );

    // Get complete token list for Optimism with account balances
    trendingResponse = await tokenList({
      userAddress: account.address,
      chainIds: [10],
      isTrending: false,
    });
    console.log(
      "Complete token list:",
      JSON.stringify(trendingResponse.result, null, 2)
    );

    // Get complete token list with account balances
    trendingResponse = await tokenList({ userAddress: account.address });
    console.log(
      "Complete token list:",
      JSON.stringify(trendingResponse.result, null, 2)
    );

    // Get trending token list for Optimism
    trendingResponse = await tokenList({ chainIds: [10] });
    console.log(
      "Trending token list for Optimism:",
      JSON.stringify(trendingResponse.result, null, 2)
    );

    // Get complete token list
    trendingResponse = await tokenList({ isTrending: false });
    console.log(
      "Complete token list:",
      JSON.stringify(trendingResponse.result, null, 2)
    );

    // Get trending token list for all chains
    trendingResponse = await tokenList();
    console.log(
      "Default token list:",
      JSON.stringify(trendingResponse.result, null, 2)
    );
  } catch (error) {
    console.error("Error:", error.message);
  }
})();