> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebalance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregated Assets

> Learn how OneBalance aggregates assets across chains into a unified balance, simplifying cross-chain token management and tracking.

Aggregated assets are OneBalance's unified token representation that combines the same token across multiple blockchain networks into a single asset ID. Instead of tracking USDC separately on Ethereum, Polygon, and Arbitrum, you simply work with one `ob:usdc` asset that represents all your USDC holdings across supported chains.

<Tip>
  Think of aggregated assets as your "universal wallet view" - one asset ID that automatically manages all your cross-chain token holdings behind the scenes.
</Tip>

## How Aggregated Assets Work

When you interact with an aggregated asset like `ob:usdc`, OneBalance automatically:

1. **Aggregates balances** across all supported chains where you hold that token
2. **Optimizes routing** to spend from the most efficient chain for your transaction
3. **Handles bridging** automatically when cross-chain operations are needed
4. **Provides unified pricing** and fiat value calculations

### The Magic Behind the Scenes

Instead of you having to:

* Track USDC balances on 5 different chains
* Decide which chain has enough balance for your transaction
* Manually bridge tokens when needed
* Handle different contract addresses and decimals

OneBalance does this for you automatically. You just say "spend 100 USDC" and we handle all the complexity.

## Supported Aggregated Assets

Each aggregated asset includes:

* **Unique ID**: Like `ob:usdc` or `ob:eth`
* **Symbol and name**: Human-readable identifiers
* **Decimals**: Precision for the aggregated asset
* **Individual assets**: The specific chain tokens that make up the aggregated asset

<Card title="List Supported Assets" icon="coins" href="/api-reference/assets/list">
  Retrieve all supported aggregated assets and their underlying chain-specific tokens
</Card>

### Example: USDT Aggregated Asset

```json theme={null}
{
  "aggregatedAssetId": "ob:usdt",
  "symbol": "USDT",
  "name": "Tether USD",
  "decimals": 6,
  "aggregatedEntities": [
    {
      "assetType": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "decimals": 6,
      "name": "Tether USD",
      "symbol": "USDT"
    },
    {
      "assetType": "eip155:42161/erc20:0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
      "decimals": 6,
      "name": "Tether USD", 
      "symbol": "USDT"
    }
  ]
}
```

## Asset Identification Formats

OneBalance supports two types of asset identifiers, each serving different use cases:

### Aggregated Assets

* **Format**: `ob:tokenSymbol` (e.g., `ob:usdc`, `ob:eth`)
* **Purpose**: Unified representation across all supported chains
* **Usage**: Use this for 99% of your applications - it provides automatic chain abstraction and optimization
* **Benefits**: OneBalance automatically finds the best chain to execute from and handles cross-chain operations

<Info>
  The `ob:` prefix stands for "OneBalance" and indicates you're working with our aggregated asset system. This is the recommended format for most integrations.
</Info>

### Chain-Specific Assets

* **Format**: CAIP-19 standard (e.g., `eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`)
* **Purpose**: Target specific chain implementations only
* **Usage**: Only when you need to force execution on a particular blockchain
* **Trade-offs**: You lose automatic optimization and may need to handle bridging manually

<Warning>
  For new tokens that haven't been added to our aggregated list yet, they will temporarily appear as separate chain-specific assets until aggregation is available.
</Warning>

<Card title="List Supported Chains" icon="network" href="/api-reference/chains/list">
  View all blockchain networks integrated with OneBalance platform
</Card>

## Working with Aggregated Assets

<CardGroup cols={2}>
  <Card title="Check Aggregated Balances" icon="wallet" href="/api-reference/balances/aggregated-balance">
    Get unified token balances across all supported chains for any address
  </Card>

  <Card title="Create Unified Quotes" icon="hand-coins" href="/api-reference/quotes/get-quote">
    Request quotes for swaps and transfers using aggregated assets
  </Card>
</CardGroup>

### API Examples

**Listing Available Assets:**

```bash theme={null}
curl -X 'GET' \
  'https://be.onebalance.io/api/assets/list' \
  -H 'x-api-key: ONEBALANCE_API_KEY'
```

**Checking Aggregated Balances:**

```bash theme={null}
curl -X 'GET' \
  'https://be.onebalance.io/api/v2/balances/aggregated-balance?address=0x123...' \
  -H 'x-api-key: ONEBALANCE_API_KEY'
```

**Creating Quotes with Aggregated Assets:**

```json theme={null}
{
  "from": {
    "account": { /* account details */ },
    "asset": { "assetId": "ob:eth" },
    "amount": "1000000000000000000"
  },
  "to": {
    "asset": { "assetId": "ob:usdc" }
  }
}
```

<Note>
  The amount shown above represents 1 ETH (1000000000000000000 wei). For testing, ensure you use amounts worth at least \$1 to avoid gas cost issues.
</Note>

## Advanced Operations

<CardGroup cols={2}>
  <Card title="Contract Calls" icon="code" href="/api-reference/quotes/prepare-call-quote">
    Prepare contract interactions using aggregated assets as funding
  </Card>

  <Card title="Execute Quotes" icon="play" href="/api-reference/quotes/execute-quote">
    Execute prepared quotes for aggregated asset operations
  </Card>
</CardGroup>

## Benefits of Aggregated Assets

<CardGroup cols={2}>
  <Card title="Simplified Integration" icon="code">
    Work with one asset ID instead of managing multiple chain-specific tokens
  </Card>

  <Card title="Automatic Optimization" icon="gauge">
    OneBalance routes transactions through the most efficient chains
  </Card>

  <Card title="Unified Balances" icon="scale">
    See total holdings across all chains in one view
  </Card>

  <Card title="Seamless Bridging" icon="arrow-left-right">
    Cross-chain operations happen automatically when needed
  </Card>
</CardGroup>

## Monitoring and Status

<CardGroup cols={2}>
  <Card title="Quote Status" icon="history" href="/api-reference/status/get-quote-status">
    Monitor execution progress of aggregated asset transactions
  </Card>

  <Card title="Transaction History" icon="clock" href="/api-reference/status/get-transaction-history">
    View complete history of aggregated asset operations
  </Card>
</CardGroup>

## Best Practices

1. **Use aggregated assets by default** for the best user experience
2. **Fall back to specific assets** only when you need chain-specific behavior
3. **Check supported assets** regularly as new tokens and chains are added
4. **Monitor aggregated balances** to understand your users' cross-chain holdings

## Common Issues and Solutions

### Testing with Small Amounts

<Warning>
  When testing, use at least \$1 worth of tokens. Testing with very small amounts (like \$0.30) can cause transactions to fail due to gas costs exceeding the transaction value.
</Warning>

### New Token Availability

Most established tokens are automatically aggregated across chains. For newly launched tokens:

* Initially, they may only be available as chain-specific assets
* Aggregation is added once the token is verified across multiple chains

### Asset ID Prefix

If you encounter asset ID issues:

* Always use `ob:` prefixed assets for the best experience
* Double-check the asset ID format in our [supported assets list](/api-reference/assets/list)
* Contact support if a commonly used token isn't available as an aggregated asset

## Related Resources

<CardGroup cols={2}>
  <Card title="Account Management" icon="user" href="/api-reference/account/predict-address">
    Set up smart accounts for aggregated asset operations
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key setup and authentication for accessing aggregated assets
  </Card>

  <Card title="Error Handling" icon="triangle-alert" href="/api-reference/errors">
    Common issues and troubleshooting for aggregated asset operations
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/rate-limits">
    API usage guidelines and rate limiting information
  </Card>
</CardGroup>