Skip to main content

​
Tokens

The Mina SDK provides token discovery to identify which tokens can be bridged from each chain to HyperEVM.

​
Overview

Not all tokens on a chain can be bridged to HyperEVM. The SDK provides methods to discover tokens that have valid bridge routes, along with their metadata including prices and logos.

​
Token Methods

​
getTokens(chainId)

Fetches all tokens available on a specific chain. 
import { Mina } from '@siphoyawe/mina-sdk';

const mina = new Mina({ integrator: 'my-app' });

// Get all tokens on Arbitrum
const { tokens, isStale, cachedAt } = await mina.getTokens(42161);

console.log(`Found ${tokens.length} tokens on Arbitrum`);
tokens.forEach(token => {
  console.log(`${token.symbol}: ${token.address}`);
});

​
getBridgeableTokens(chainId)

Fetches only tokens that can be bridged to HyperEVM from a specific chain. This is the recommended method for building bridge UIs. 
// Get tokens that can actually be bridged to HyperEVM
const { tokens } = await mina.getBridgeableTokens(42161);

console.log(`Found ${tokens.length} bridgeable tokens`);
tokens.forEach(token => {
  console.log(`${token.symbol} - $${token.priceUsd?.toFixed(2) ?? 'N/A'}`);
});
Use getBridgeableTokens() instead of getTokens() when building your bridge UI. This ensures users only see tokens with valid bridge routes.

​
Response Types

​
TokensResponse

Both methods return a response with metadata: 
interface TokensResponse {
  /** Array of token data */
  tokens: Token[];
  /** Whether the data is from stale cache */
  isStale: boolean;
  /** Timestamp when data was cached (null if fresh from API) */
  cachedAt: number | null;
}

​
Token

Each token object contains: 
interface Token {
  /** Token contract address */
  address: string;
  /** Token symbol (e.g., "USDC") */
  symbol: string;
  /** Token name (e.g., "USD Coin") */
  name: string;
  /** Token decimals (e.g., 6 for USDC) */
  decimals: number;
  /** URL to token logo image */
  logoUrl: string;
  /** Current USD price (optional) */
  priceUsd?: number;
  /** Chain ID this token is on */
  chainId: number;
}

​
Native Token Address

The native gas token (ETH, MATIC, etc.) uses a special zero address: 
const NATIVE_TOKEN_ADDRESS = '0x0000000000000000000000000000000000000000';

// Check if a token is the native token
function isNativeToken(token: Token): boolean {
  return token.address.toLowerCase() === NATIVE_TOKEN_ADDRESS;
}

// Get native token for a chain
const { tokens } = await mina.getTokens(42161);
const nativeToken = tokens.find(isNativeToken);
console.log(nativeToken?.symbol); // "ETH" on Arbitrum

​
Common Tokens

​
Source Chain Tokens

Commonly bridged tokens from source chains:
TokenSymbolDecimalsCommon Chains
USD CoinUSDC6Most chains
TetherUSDT6Most chains
Wrapped ETHWETH18L2s
Native ETHETH18All EVM chains

​
HyperEVM Destination Tokens

Tokens receivable on HyperEVM:
TokenSymbolAddressDecimals
USDCUSDC0xb88339cb7199b77e23db6e890353e22632ba630f6
HYPEHYPE0x000000000000000000000000000000000000000018
// HyperEVM USDC address
const HYPEREVM_USDC_ADDRESS = '0xb88339cb7199b77e23db6e890353e22632ba630f';

// Get destination tokens
const destinationTokens = mina.getDestinationTokens();
// Returns USDC and HYPE tokens on HyperEVM

​
Example: Token Selector

Build a token selector that shows bridgeable tokens with USD values: 
import { Mina, Token } from '@siphoyawe/mina-sdk';

const mina = new Mina({ integrator: 'my-app' });

interface TokenOption {
  address: string;
  symbol: string;
  name: string;
  logo: string;
  priceUsd: number | null;
  decimals: number;
}

async function getTokenOptions(chainId: number): Promise<TokenOption[]> {
  const { tokens } = await mina.getBridgeableTokens(chainId);

  return tokens.map(token => ({
    address: token.address,
    symbol: token.symbol,
    name: token.name,
    logo: token.logoUrl,
    priceUsd: token.priceUsd ?? null,
    decimals: token.decimals,
  }));
}

// Usage
const arbitrumTokens = await getTokenOptions(42161);
// [
//   { address: '0x...', symbol: 'USDC', name: 'USD Coin', ... },
//   { address: '0x...', symbol: 'USDT', name: 'Tether', ... },
//   ...
// ]

​
Example: Calculate USD Value

Calculate the USD value of a token amount: 
function calculateUsdValue(
  token: Token,
  amountInSmallestUnit: string
): number | null {
  if (!token.priceUsd) return null;

  const amount = BigInt(amountInSmallestUnit);
  const divisor = BigInt(10 ** token.decimals);
  const tokenAmount = Number(amount) / Number(divisor);

  return tokenAmount * token.priceUsd;
}

// Usage
const { tokens } = await mina.getBridgeableTokens(42161);
const usdc = tokens.find(t => t.symbol === 'USDC');

if (usdc) {
  const usdValue = calculateUsdValue(usdc, '1000000'); // 1 USDC
  console.log(`Value: $${usdValue?.toFixed(2)}`); // "Value: $1.00"
}

​
Caching Behavior

Token data is cached for 15 minutes:
  • Bridgeable tokens and all tokens are cached separately
  • Stale cache is returned if the API fails
  • Cache can be manually invalidated
const { tokens, isStale, cachedAt } = await mina.getBridgeableTokens(42161);

if (isStale) {
  console.warn('Using cached token data from:', new Date(cachedAt!));
}

​
Error Handling

Handle token fetch errors gracefully: 
import { TokenFetchError } from '@siphoyawe/mina-sdk';

try {
  const { tokens } = await mina.getBridgeableTokens(42161);
} catch (error) {
  if (error instanceof TokenFetchError) {
    console.error(`Failed to fetch tokens for chain ${error.chainId}:`, error.message);

    if (error.cachedAvailable) {
      console.log('Stale cache may be available');
    }
  }
}

​
Next Steps

Quotes

Get bridge quotes with token amounts

Execution

Execute bridge transactions