> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dzimiks/onebalance-chain-abstracted-swap/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
export interface BalancesResponse {
  balanceByAggregatedAsset: BalanceByAssetDto[];
  totalBalance: TotalBalance;
}
```

### Properties

<ResponseField name="balanceByAggregatedAsset" type="BalanceByAssetDto[]" required>
  Array of balance information for each aggregated asset held by the account. See [BalanceByAssetDto](#balancebyassetdto) below.
</ResponseField>

<ResponseField name="totalBalance" type="TotalBalance" required>
  Total portfolio balance information. See [TotalBalance](#totalbalance) below.
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
export interface BalanceByAssetDto {
  aggregatedAssetId: string;
  balance: string;
  fiatValue: number;
  individualAssetBalances: IndividualAssetBalance[];
  symbol?: string;
  decimals?: number;
}
```

### Properties

<ResponseField name="aggregatedAssetId" type="string" required>
  The OneBalance aggregated asset identifier

  Format: `ob:{symbol}` (e.g., `ob:eth`, `ob:usdc`, `ob:dai`)
</ResponseField>

<ResponseField name="balance" type="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)
</ResponseField>

<ResponseField name="fiatValue" type="number" required>
  Total fiat value of the aggregated asset in USD
</ResponseField>

<ResponseField name="individualAssetBalances" type="IndividualAssetBalance[]" required>
  Array of individual asset balances that compose this aggregated asset. See [IndividualAssetBalance](#individualassetbalance) below.
</ResponseField>

<ResponseField name="symbol" type="string">
  Token symbol (e.g., `"USDC"`, `"ETH"`, `"DAI"`)
</ResponseField>

<ResponseField name="decimals" type="number">
  Number of decimals for the token (e.g., 18 for ETH, 6 for USDC)
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
export interface IndividualAssetBalance {
  assetType: string;
  balance: string;
  fiatValue: number;
}
```

### Properties

<ResponseField name="assetType" type="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)
</ResponseField>

<ResponseField name="balance" type="string" required>
  The balance of the individual asset as a string (BigInt with token decimals)

  Example: `"1500000000000000000"` represents 1.5 ETH (18 decimals)
</ResponseField>

<ResponseField name="fiatValue" type="number" required>
  Fiat value of this specific asset balance in USD
</ResponseField>

### Example

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

***

## TotalBalance

Total portfolio balance information.

```typescript theme={null}
export interface TotalBalance {
  fiatValue: number;
}
```

### Properties

<ResponseField name="fiatValue" type="number" required>
  Total fiat value across all assets in the portfolio, denominated in USD
</ResponseField>

### Example

```typescript theme={null}
const total: TotalBalance = {
  fiatValue: 25750.50
};
```

***

## Understanding CAIP-19 Asset Types

OneBalance uses the [CAIP-19](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md) standard for asset identification. This provides a chain-agnostic way to reference assets across different blockchains.

### Format

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

### Components

<ResponseField name="namespace" type="string">
  Blockchain ecosystem identifier (e.g., `eip155` for Ethereum-compatible chains)
</ResponseField>

<ResponseField name="chainId" type="string">
  Specific chain identifier within the namespace (e.g., `1` for Ethereum Mainnet, `137` for Polygon)
</ResponseField>

<ResponseField name="assetNamespace" type="string">
  Asset type identifier:

  * `erc20`: ERC-20 token
  * `slip44`: Native blockchain token
  * `erc721`: NFT (not currently used in balances)
</ResponseField>

<ResponseField name="assetReference" type="string">
  Asset-specific identifier:

  * For ERC-20: Contract address (e.g., `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`)
  * For native tokens (slip44): Coin type (e.g., `60` for ETH)
</ResponseField>

### Common Examples

<Tabs>
  <Tab title="USDC">
    ```typescript theme={null}
    // USDC on Ethereum
    "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

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

    // USDC on Base
    "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
    ```
  </Tab>

  <Tab title="ETH">
    ```typescript theme={null}
    // ETH on Ethereum Mainnet
    "eip155:1/slip44:60"

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

    // ETH on Arbitrum
    "eip155:42161/slip44:60"
    ```
  </Tab>

  <Tab title="Other Tokens">
    ```typescript theme={null}
    // DAI on Ethereum
    "eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f"

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

    // USDT on Ethereum
    "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7"
    ```
  </Tab>
</Tabs>

***

## Usage Example

Here's a complete example of working with balance data:

```typescript theme={null}
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)}`);
```