Chains API

Overview

The Chains API provides a list of all blockchain networks supported by OneBalance. This includes both mainnet and testnet chains, along with their metadata for proper identification and display.

API Methods

getChains

Retrieve the complete list of supported blockchain chains.

chainsApi.getChains(): Promise<Chain[]>

Parameters

This method takes no parameters.

Returns

array

Array of all supported blockchain chains

Show Chain Structure

ChainMetadata

Chain identification information in CAIP-2 format

Show ChainMetadata properties

string

Chain name/identifier

string

Blockchain namespace (e.g., “eip155” for Ethereum-compatible chains)

string

Chain ID or reference identifier (e.g., “1” for Ethereum mainnet)

boolean

Whether this is a testnet chain

Example

import { chainsApi } from '@/lib/api/chains';

const chains = await chainsApi.getChains();

console.log(`Found ${chains.length} supported chains`);

// Display each chain
chains.forEach(chain => {
  const chainId = chain.chain.reference;
  const isTest = chain.isTestnet ? ' (Testnet)' : '';
  console.log(`Chain ${chainId}: ${chain.chain.chain}${isTest}`);
});

const data: Chain[] = await chainsApi.getChains();

Example Response

[
  {
    "chain": {
      "chain": "Ethereum Mainnet",
      "namespace": "eip155",
      "reference": "1"
    },
    "isTestnet": false
  },
  {
    "chain": {
      "chain": "Polygon",
      "namespace": "eip155",
      "reference": "137"
    },
    "isTestnet": false
  },
  {
    "chain": {
      "chain": "Arbitrum",
      "namespace": "eip155",
      "reference": "42161"
    },
    "isTestnet": false
  },
  {
    "chain": {
      "chain": "Base",
      "namespace": "eip155",
      "reference": "8453"
    },
    "isTestnet": false
  },
  {
    "chain": {
      "chain": "Optimism",
      "namespace": "eip155",
      "reference": "10"
    },
    "isTestnet": false
  }
]

Chain Configuration

OneBalance provides additional chain metadata through the CHAIN_CONFIG constant:

export const CHAIN_CONFIG: Record<string, ChainConfig> = {
  '1': {
    name: 'Ethereum Mainnet',
    logoUrl: 'https://storage.googleapis.com/onebalance-public-assets/networks/1.svg',
  },
  '10': {
    name: 'Optimism',
    logoUrl: 'https://storage.googleapis.com/onebalance-public-assets/networks/10.svg',
  },
  '137': {
    name: 'Polygon',
    logoUrl: 'https://storage.googleapis.com/onebalance-public-assets/networks/137.svg',
  },
  '8453': {
    name: 'Base',
    logoUrl: 'https://storage.googleapis.com/onebalance-public-assets/networks/8453.svg',
  },
  '42161': {
    name: 'Arbitrum',
    logoUrl: 'https://storage.googleapis.com/onebalance-public-assets/networks/42161.svg',
  },
  // ... more chains
};

Utility Functions

The chains module provides several utility functions for working with chain data:

getChainName

Get the human-readable name for a chain ID.

getChainName(chainId: string | number): string

import { getChainName } from '@/lib/types/chains';

const name = getChainName('1');
console.log(name); // "Ethereum Mainnet"

const name2 = getChainName(137);
console.log(name2); // "Polygon"

const name3 = getChainName('99999');
console.log(name3); // "Chain 99999" (fallback)

getChainLogoUrl

Get the logo URL for a chain.

getChainLogoUrl(chainId: string | number): string

import { getChainLogoUrl } from '@/lib/types/chains';

const logoUrl = getChainLogoUrl('1');
console.log(logoUrl);
// "https://storage.googleapis.com/onebalance-public-assets/networks/1.svg"

const noLogo = getChainLogoUrl('99999');
console.log(noLogo); // "" (empty string for unsupported chains)

getChainConfig

Get complete configuration for a chain.

getChainConfig(chainId: string | number): ChainConfig | null

import { getChainConfig } from '@/lib/types/chains';

const config = getChainConfig('1');
if (config) {
  console.log(config.name);    // "Ethereum Mainnet"
  console.log(config.logoUrl); // Logo URL
}

const unknown = getChainConfig('99999');
console.log(unknown); // null

extractChainIdFromCAIP

Extract chain ID from CAIP chain identifier.

extractChainIdFromCAIP(caipChainId: string): string

import { extractChainIdFromCAIP } from '@/lib/types/chains';

const chainId = extractChainIdFromCAIP('eip155:1');
console.log(chainId); // "1"

const solana = extractChainIdFromCAIP('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp');
console.log(solana); // "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"

extractChainIdFromAssetType

Extract chain ID from CAIP-19 asset type.

extractChainIdFromAssetType(assetType: string): string

import { extractChainIdFromAssetType } from '@/lib/types/chains';

const chainId = extractChainIdFromAssetType(
  'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
);
console.log(chainId); // "1"

const polygonId = extractChainIdFromAssetType(
  'eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174'
);
console.log(polygonId); // "137"

Real-World Implementation

const fetchChains = async () => {
  try {
    const data: Chain[] = await chainsApi.getChains();
    setChains(data);
  } catch (err) {
    setError(err instanceof Error ? err.message : 'Failed to fetch chains');
  } finally {
    setLoading(false);
  }
};

useEffect(() => {
  fetchChains();
}, []);

import { getChainName, getChainLogoUrl } from '@/lib/types/chains';

function ChainBadge({ chainId }: { chainId: string }) {
  const name = getChainName(chainId);
  const logoUrl = getChainLogoUrl(chainId);
  
  return (
    <div className="chain-badge">
      {logoUrl && <img src={logoUrl} alt={name} width={20} height={20} />}
      <span>{name}</span>
    </div>
  );
}

Supported Chains

OneBalance currently supports the following chains:

Ethereum

Chain ID: 1The original smart contract platform

Optimism

Chain ID: 10Ethereum Layer 2 for lower fees

Polygon

Chain ID: 137Fast and low-cost EVM sidechain

Base

Chain ID: 8453Coinbase’s Ethereum L2

Arbitrum

Chain ID: 42161Popular Ethereum Layer 2

Linea

Chain ID: 59144ConsenSys zkEVM L2

Avalanche

Chain ID: 43114High-throughput blockchain

Unichain

Chain ID: 130Uniswap’s dedicated chain

Solana

Chain ID: 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpHigh-performance blockchain

Filtering Chains

const mainnets = chains.filter(chain => !chain.isTestnet);
console.log(`${mainnets.length} mainnet chains available`);

const testnets = chains.filter(chain => chain.isTestnet);
console.log(`${testnets.length} testnet chains for testing`);

const ethereum = chains.find(chain => chain.chain.reference === '1');
if (ethereum) {
  console.log('Found Ethereum:', ethereum.chain.chain);
}

Building Chain Selectors

import { chainsApi } from '@/lib/api/chains';
import { getChainName, getChainLogoUrl } from '@/lib/types/chains';
import { useState, useEffect } from 'react';

function ChainSelector({ onSelect }: { onSelect: (chainId: string) => void }) {
  const [chains, setChains] = useState<Chain[]>([]);
  
  useEffect(() => {
    chainsApi.getChains().then(data => {
      // Filter out testnets for production
      setChains(data.filter(c => !c.isTestnet));
    });
  }, []);
  
  return (
    <select onChange={(e) => onSelect(e.target.value)}>
      <option value="">Select a chain...</option>
      {chains.map(chain => {
        const chainId = chain.chain.reference;
        const name = getChainName(chainId);
        
        return (
          <option key={chainId} value={chainId}>
            {name}
          </option>
        );
      })}
    </select>
  );
}

Understanding CAIP-2

Chain identifiers use the CAIP-2 standard:

{namespace}:{reference}

Examples:
eip155:1                                    → Ethereum Mainnet
eip155:137                                  → Polygon
eip155:42161                                → Arbitrum
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp    → Solana Mainnet

namespace: Blockchain type (e.g., eip155 for EVM, solana for Solana)
reference: Chain-specific identifier (chain ID for EVM chains)

Caching Strategy

Chain lists are relatively static. Cache them to improve performance.

let cachedChains: Chain[] | null = null;

async function getChainsWithCache(): Promise<Chain[]> {
  if (cachedChains) {
    return cachedChains;
  }
  
  cachedChains = await chainsApi.getChains();
  return cachedChains;
}

Error Handling

try {
  const chains = await chainsApi.getChains();
  return chains;
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to fetch chains:', error.message);
    
    // Provide fallback chain list
    return [
      {
        chain: { chain: 'Ethereum Mainnet', namespace: 'eip155', reference: '1' },
        isTestnet: false
      }
    ];
  }
  
  throw error;
}

Best Practices

Cache Results

Chains change very rarely - cache indefinitely or until app restart

Use Utility Functions

Use provided utilities like getChainName() for consistent display

Show Chain Logos

Display chain logos for better visual identification

Filter Appropriately

Hide testnets in production, show them in development

Assets API - Asset entities reference chain IDs
Balances API - Individual balances include chain information
Transactions API - Transactions include chain operations

Chain - Complete chain structure
ChainMetadata - Chain identification
ChainConfig - Display configuration

API Modules

React Hooks

Types

Overview

API Methods

getChains

Parameters

Returns

Example

Example Response

Chain Configuration

Utility Functions

getChainName

getChainLogoUrl

getChainConfig

extractChainIdFromCAIP

extractChainIdFromAssetType

Real-World Implementation

Supported Chains

Ethereum

Optimism

Polygon

Base

Arbitrum

Linea

Avalanche

Unichain

Solana

Filtering Chains

Building Chain Selectors

Understanding CAIP-2

Caching Strategy

Error Handling

Best Practices

Cache Results

Use Utility Functions

Show Chain Logos

Filter Appropriately

​Overview

​API Methods

​getChains

​Parameters

​Returns

​Example

​Example Response

​Chain Configuration

​Utility Functions

​getChainName

​getChainLogoUrl

​getChainConfig

​extractChainIdFromCAIP

​extractChainIdFromAssetType

​Real-World Implementation

​Supported Chains

Ethereum

Optimism

Polygon

Base

Arbitrum

Linea

Avalanche

Unichain

Solana

​Filtering Chains

​Building Chain Selectors

​Understanding CAIP-2

​Caching Strategy

​Error Handling

​Best Practices

Cache Results

Use Utility Functions

Show Chain Logos

Filter Appropriately

​Related APIs

​Related Types

Overview

API Methods

getChains

Parameters

Returns

Example

Example Response

Chain Configuration

Utility Functions

getChainName

getChainLogoUrl

getChainConfig

extractChainIdFromCAIP

extractChainIdFromAssetType

Real-World Implementation

Supported Chains

Filtering Chains

Building Chain Selectors

Understanding CAIP-2

Caching Strategy

Error Handling

Best Practices

Related APIs

Related Types