Aggregated Assets

Aggregated assets are OneBalance’s solution for representing the same token across multiple blockchain networks as a single unified asset. Instead of managing USDC on Ethereum, USDC on Polygon, and USDC on Arbitrum separately, you work with one aggregated ds:usdc asset.

​

How Aggregated Assets Work

When you interact with an aggregated asset like ds: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

​

Supported Aggregated Assets

Each aggregated asset includes:

• Unique ID: Like ds:usdc or ds: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

​

Example: USDT Aggregated Asset

{
  "aggregatedAssetId": "ds: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:

​

Aggregated Assets

• Format: ds:tokenSymbol (e.g., ds:usdc, ds:eth)
• Purpose: Unified representation across all supported chains
• Usage: Optimal for most applications wanting chain abstraction

​

Specific Assets

• Format: CAIP-19 standard (e.g., eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48)
• Purpose: Target specific chain implementations
• Usage: When you need precise control over which chain to use

​

Working with 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": "ds:eth" },
    "amount": "1000000000000000000"
  },
  "to": {
    "asset": { "assetId": "ds:usdc" }
  }
}

​

Advanced Operations

​

Benefits of Aggregated Assets

​

Monitoring and Status

​

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

​

Related Resources