Balance Types

Type definitions for account balance queries and aggregated asset balances

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 identifier

Format: 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 asset

Format: {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

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

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

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

ETH

// ETH on Ethereum Mainnet
"eip155:1/slip44:60"

// ETH on Optimism
"eip155:10/slip44:60"

// ETH on Arbitrum
"eip155:42161/slip44:60"

Other Tokens

// DAI on Ethereum
"eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f"

// MATIC on Polygon
"eip155:137/slip44:966"

// USDT on Ethereum
"eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"

---

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)}`);