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.
Think of aggregated assets as your “universal wallet view” - one asset ID that automatically manages all your cross-chain token holdings behind the scenes.

​
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

List Supported Assets

Retrieve all supported aggregated assets and their underlying chain-specific tokens

​
Example: USDT Aggregated Asset

{
  "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
The ob: prefix stands for “OneBalance” and indicates you’re working with our aggregated asset system. This is the recommended format for most integrations.

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

List Supported Chains

View all blockchain networks integrated with OneBalance platform

​
Working with Aggregated Assets

Check Aggregated Balances

Get unified token balances across all supported chains for any address

Create Unified Quotes

Request quotes for swaps and transfers using aggregated assets

​
API Examples

Listing Available Assets: 
curl -X 'GET' \
  'https://be.onebalance.io/api/assets/list' \
  -H 'x-api-key: ONEBALANCE_API_KEY'
Checking Aggregated Balances: 
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: 
{
  "from": {
    "account": { /* account details */ },
    "asset": { "assetId": "ob:eth" },
    "amount": "1000000000000000000"
  },
  "to": {
    "asset": { "assetId": "ob:usdc" }
  }
}
The amount shown above represents 1 ETH (1000000000000000000 wei). For testing, ensure you use amounts worth at least $1 to avoid gas cost issues.

​
Advanced Operations

Contract Calls

Prepare contract interactions using aggregated assets as funding

Execute Quotes

Execute prepared quotes for aggregated asset operations

​
Benefits of Aggregated Assets

Simplified Integration

Work with one asset ID instead of managing multiple chain-specific tokens

Automatic Optimization

OneBalance routes transactions through the most efficient chains

Unified Balances

See total holdings across all chains in one view

Seamless Bridging

Cross-chain operations happen automatically when needed

​
Monitoring and Status

Quote Status

Monitor execution progress of aggregated asset transactions

Transaction History

View complete history of aggregated asset operations

​
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

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.

​
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
  • Contact support if a commonly used token isn’t available as an aggregated asset

Account Management

Set up smart accounts for aggregated asset operations

Authentication

API key setup and authentication for accessing aggregated assets

Error Handling

Common issues and troubleshooting for aggregated asset operations

Rate Limits

API usage guidelines and rate limiting information