Skip to main content

​
Overview

The Balance types define the structure for querying and representing account balances, including both aggregated assets across multiple chains and individual asset breakdowns.

​
BalancesResponse

The complete balance response structure containing aggregated balances and total portfolio value. 
export interface BalancesResponse {
  balanceByAggregatedAsset: BalanceByAssetDto[];
  totalBalance: TotalBalance;
}

​
Properties

​
balanceByAggregatedAsset
BalanceByAssetDto[]
required
Array of balance information for each aggregated asset held by the account. See BalanceByAssetDto below.
​
totalBalance
TotalBalance
required
Total portfolio balance information. See TotalBalance below.

​
Example

const balances: BalancesResponse = {
  balanceByAggregatedAsset: [
    {
      aggregatedAssetId: "ob:usdc",
      balance: "5000000000", // 5000 USDC
      fiatValue: 5000.00,
      symbol: "USDC",
      decimals: 6,
      individualAssetBalances: [
        {
          assetType: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          balance: "3000000000",
          fiatValue: 3000.00
        },
        {
          assetType: "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
          balance: "2000000000",
          fiatValue: 2000.00
        }
      ]
    },
    {
      aggregatedAssetId: "ob:eth",
      balance: "2500000000000000000", // 2.5 ETH
      fiatValue: 8750.00,
      symbol: "ETH",
      decimals: 18,
      individualAssetBalances: [
        {
          assetType: "eip155:1/slip44:60",
          balance: "1500000000000000000",
          fiatValue: 5250.00
        },
        {
          assetType: "eip155:10/slip44:60",
          balance: "1000000000000000000",
          fiatValue: 3500.00
        }
      ]
    }
  ],
  totalBalance: {
    fiatValue: 13750.00
  }
};

​
BalanceByAssetDto

Balance information for a single aggregated asset, including breakdown by chain. 
export interface BalanceByAssetDto {
  aggregatedAssetId: string;
  balance: string;
  fiatValue: number;
  individualAssetBalances: IndividualAssetBalance[];
  symbol?: string;
  decimals?: number;
}

​
Properties

​
aggregatedAssetId
string
required
The OneBalance aggregated asset identifierFormat: ob:{symbol} (e.g., ob:eth, ob:usdc, ob:dai)
​
balance
string
required
Total balance of the aggregated asset across all chains, as a string (BigInt with token decimals)Example: "5000000000" represents 5000 USDC (6 decimals)
​
fiatValue
number
required
Total fiat value of the aggregated asset in USD
​
individualAssetBalances
IndividualAssetBalance[]
required
Array of individual asset balances that compose this aggregated asset. See IndividualAssetBalance below.
​
symbol
string
Token symbol (e.g., "USDC", "ETH", "DAI")
​
decimals
number
Number of decimals for the token (e.g., 18 for ETH, 6 for USDC)

​
Example

const assetBalance: BalanceByAssetDto = {
  aggregatedAssetId: "ob:usdc",
  balance: "10000000000", // 10,000 USDC
  fiatValue: 10000.00,
  symbol: "USDC",
  decimals: 6,
  individualAssetBalances: [
    {
      assetType: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      balance: "6000000000",
      fiatValue: 6000.00
    },
    {
      assetType: "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      balance: "4000000000",
      fiatValue: 4000.00
    }
  ]
};

​
IndividualAssetBalance

Balance information for a specific asset on a single blockchain. 
export interface IndividualAssetBalance {
  assetType: string;
  balance: string;
  fiatValue: number;
}

​
Properties

​
assetType
string
required
CAIP-19 format identifier for the individual assetFormat: {namespace}:{chainId}/{assetNamespace}:{assetReference}Examples:
  • "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" (USDC on Ethereum)
  • "eip155:137/slip44:60" (ETH on Polygon)
  • "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" (USDC on Base)
​
balance
string
required
The balance of the individual asset as a string (BigInt with token decimals)Example: "1500000000000000000" represents 1.5 ETH (18 decimals)
​
fiatValue
number
required
Fiat value of this specific asset balance in USD

​
Example

const individualBalance: IndividualAssetBalance = {
  assetType: "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  balance: "2500000000", // 2500 USDC on Ethereum
  fiatValue: 2500.00
};

​
TotalBalance

Total portfolio balance information. 
export interface TotalBalance {
  fiatValue: number;
}

​
Properties

​
fiatValue
number
required
Total fiat value across all assets in the portfolio, denominated in USD

​
Example

const total: TotalBalance = {
  fiatValue: 25750.50
};

​
Understanding CAIP-19 Asset Types

OneBalance uses the CAIP-19 standard for asset identification. This provides a chain-agnostic way to reference assets across different blockchains.

​
Format

{namespace}:{chainId}/{assetNamespace}:{assetReference}

​
Components

​
namespace
string
Blockchain ecosystem identifier (e.g., eip155 for Ethereum-compatible chains)
​
chainId
string
Specific chain identifier within the namespace (e.g., 1 for Ethereum Mainnet, 137 for Polygon)
​
assetNamespace
string
Asset type identifier:
  • erc20: ERC-20 token
  • slip44: Native blockchain token
  • erc721: NFT (not currently used in balances)
​
assetReference
string
Asset-specific identifier:
  • For ERC-20: Contract address (e.g., 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48)
  • For native tokens (slip44): Coin type (e.g., 60 for ETH)

​
Common Examples

// USDC on Ethereum
"eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

// USDC on Polygon
"eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174"

// USDC on Base
"eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"

​
Usage Example

Here’s a complete example of working with balance data: 
import { BalancesResponse, BalanceByAssetDto } from './types/balances';

// Function to get total balance for a specific asset
function getAssetBalance(
  balances: BalancesResponse,
  assetId: string
): BalanceByAssetDto | undefined {
  return balances.balanceByAggregatedAsset.find(
    (asset) => asset.aggregatedAssetId === assetId
  );
}

// Function to format balance with decimals
function formatBalance(balance: string, decimals: number): string {
  const value = BigInt(balance);
  const divisor = BigInt(10 ** decimals);
  const whole = value / divisor;
  const fraction = value % divisor;
  
  return `${whole}.${fraction.toString().padStart(decimals, '0')}`;
}

// Example usage
const balances: BalancesResponse = await fetchBalances(userAddress);

// Get USDC balance
const usdcBalance = getAssetBalance(balances, 'ob:usdc');
if (usdcBalance) {
  console.log(`Total USDC: ${formatBalance(usdcBalance.balance, usdcBalance.decimals!)}`);
  console.log(`Fiat Value: $${usdcBalance.fiatValue.toFixed(2)}`);
  
  // Show breakdown by chain
  usdcBalance.individualAssetBalances.forEach((individual) => {
    const chainId = individual.assetType.split(':')[1].split('/')[0];
    console.log(`  Chain ${chainId}: ${formatBalance(individual.balance, usdcBalance.decimals!)}`);
  });
}

// Show total portfolio value
console.log(`Total Portfolio Value: $${balances.totalBalance.fiatValue.toFixed(2)}`);

Build docs developers (and LLMs) love

Get started for freeTalk to us