Configure Balance Display

The Para Modal provides comprehensive balance display capabilities, allowing users to view their wallet balances across multiple assets and networks. You can configure how balances are displayed and aggregated, and programmatically access balance data using the useProfileBalance hook.

Balance Display Configuration

You can customize how balances are displayed and calculated through the paraModalConfig.balances property in your ParaProvider configuration. This setting will impact both the Para Modal’s balance display and instances where you use the useProfileBalance hook. Para supports two primary balance display modes, AGGREGATED and CUSTOM_ASSET. You can also specify whether to fetch balances for both MAINNET_AND_TESTNET (default) or one or the other only (MAINNET or TESTNET).

Defining Custom Networks and Assets

To include custom assets when fetching connected wallet balances, you will need to supply implementation metadata for each asset, including:

Each asset must include basic metadata, including name, symbol, and logoUrl (optional).
Each asset must include an implementations array for each network you wish to query for balances.
- Each implementation object must include:
  - Price data:
    - For a fixed price:
      - Include a price object with the asset’s price in the format { value: number; currency: 'USD' }.
    - For a volatile price:
      - Include a priceUrl string. This endpoint must respond to GET requests with a JSON object with the asset’s current price in the format { value: number; currency: 'USD' }.
  - Network information:
    - For a custom EVM network:
      - Include a network object specifying the network’s name, evmChainId, and an rpcUrl where asset balances can be queried.
        
        If the network is a testnet, include isTestnet: true.
        
        Include a nativeTokenSymbol if the network’s native token is not Ethereum (ETH).
        
        Optional: Include a logoUrl for the network.
        
        Optional: Include an explorer object for the network, including:
        
        The explorer’s display name name.
        
        The explorer’s homepage URL url.
        
        An explorer URL template txUrlFormat for broadcast transactions, using {HASH} as the placeholder for the transaction hash. Example: https://etherscan.io/tx/{HASH}
      - If the asset is the network’s native token:
        
        No additional configuration is needed.
      - If the asset is an ERC-20 token:
        
        Include a contractAddress string.
    - For a standard EVM or Solana network:
      - Include a network string, matching one of the networks enumerated in the TNetwork type. For example, 'ETHEREUM' or 'SOLANA'.
      - Include a contractAddress string.

Refer to the code snippets below for example configurations.

Aggregated Mode (Default)

Aggregated Mode automatically aggregates balances across all detected chains and assets and displays them in USD value. If you supply additional assets and price data, these totals will be included in the calculation.

The aggregated total will include most commonly used assets across many networks. If you want to only include totals from your customized tokens, set excludeStandardAssets to true.

An example configuration with additional assets is below:

<ParaProvider
  // ... other config
  paraModalConfig={{
    // ... other config
    balances: {
      displayType: "AGGREGATED",
      requestType: 'MAINNET_AND_TESTNET',
      // Include only balances for your custom assets:
      excludeStandardAssets: true,
      additionalAssets: [
        {
          name: 'Custom Asset',
          symbol: 'CUSTOM',
          logoUrl: '<logo-url>',
          // A price endpoint for the asset:
          priceUrl: '<price-url-endpoint>',
          implementations: [
            // A custom EVM network where the asset is the native token:
            {
              network: {
                name: 'Custom Chain',
                evmChainId: '12345',
                rpcUrl: 'https://rpc.customexplorer.com',
                logoUrl: 'https://cdn.customexplorer.com/logo.png',
                nativeTokenSymbol: 'CUSTOM',
                explorer: {
                  name: 'Custom Chain Explorer',
                  url: 'https://customexplorer.com',
                  txUrlFormat: 'https://customexplorer.com/tx/{HASH}',
                }
              },
            },
            // A custom EVM network where the asset is an ERC-20 token:
            {
              network: {
                name: 'Another Custom Chain',
                evmChainId: '12345',
                rpcUrl: '<rpc-url>',
                logoUrl: '<logo-url>',
                explorer: {
                  name: 'Another Custom Chain Explorer',
                  url: 'https://anothercustomexplorer.com',
                  txUrlFormat: 'https://anothercustomexplorer.com/tx/{HASH}',
                }
              },
              contractAddress: '0x...',
            },
            // An implementation of the token on Solana:
            {
              network: 'SOLANA',
              contractAddress: 'Ep4r...',
            },
            // A testnet ERC-20 implementation of the token:
            {
              network: {
                name: 'Custom Chain Testnet',
                evmChainId: '12346',
                rpcUrl: '<testnet-rpc-url>',
                logoUrl: '<testnet-logo-url>',
                nativeTokenSymbol: 'CUSTOM',
                explorer: {
                  name: 'Custom Chain Testnet Explorer',
                  url: 'https://testnet.customexplorer.com',
                  txUrlFormat: 'https://testnet.customexplorer.com/tx/{HASH}',
                },
                isTestnet: true,
              },
              contractAddress: '0x...',
            },
          ],
        },
        {
          name: 'Custom Stablecoin',
          symbol: 'CSTABLE',
          logoUrl: '<logo-url.png>',
          // A fixed price for the asset
          price: {
            value: 1,
            currency: 'USD',
          },
          networks: [
            // A custom network where the asset is an ERC-20 token:
            {
              network: {
                name: 'Custom Chain',
                evmChainId: '12345',
                rpcUrl: '<rpc-url>',
                logoUrl: '<logo-url>',
                nativeTokenSymbol: 'CUSTOM',
                explorer: {
                  name: 'Custom Chain Explorer',
                  url: 'https://customexplorer.com',
                  txUrlFormat: 'https://customexplorer.com/tx/{HASH}',
                }
              },
              contractAddress: '0x...',
            },
          ],
        },
      ]
    }
  }}
>
  {children}
</ParaProvider>

Balance Overrides

In Aggregated Mode, if you wish, you can manually override the displayed fiat balance for each wallet in the Para Modal. This is useful if you are using a custom chain with many assets that are not included in the calculated total. You can replace the default USD balance for each connected wallet.

The override will alter both the per-wallet USD balance displayed in the ‘Profile’ modal screen and the cumulative USD balance displayed on the main ‘Account’ screen. It will also alter the result from the useProfileBalance hook.

To do this, you first set the useBalanceOverrides flag to true in your ParaProvider modal configuration:

<ParaProvider
  // ... other config
  paraModalConfig={{
    // ... other config
    balances: {
      // ... other config
      useBalanceOverrides: true,
    }
  }}
>
  {children}
</ParaProvider>

Then, within the ParaProvider, you can calculate and set an override object using the useSetBalanceOverrides hook. Pass an object where the keys are the addresses for your connected wallets (available in the useAccount hook) and the values are numbers representing the USD balance for each wallet. An example usage:

App.tsx

import { useAccount, useSetBalanceOverrides } from "@getpara/react-sdk";
import { fetchAdditionalBalances } from "@your-domain/your-api-library";

// Assuming your API function accepts an array of wallet addresses and returns a Record<string, number>:
declare global {
  fetchAdditionalBalances: (opts: { addresses: string[] }) => Promise<Record<string, number>>;
}

export const App = () => {
  const { embedded: embeddedWallets } = useAccount();
  const setBalanceOverrides = useSetBalanceOverrides();
  useEffect(() => {
     const interval = setInterval(async () => {
       const balances = await fetchAdditionalBalances({ addresses: embeddedWallets.map(w => w.address!) });

       // Example response:
       // {
       //   '0x123...': 123.45,
       //   '0x456...': 6.78,
       // }

       // Set the balance overrides:
       setBalanceOverrides(balances);
     }, 30000);

     return () => clearInterval(interval);
   }, [embeddedWallets]);

   // ...
};

Custom Asset Mode

In Custom Asset Mode, the Para Modal will only display balances of a chosen asset, with no fiat currency conversion. This is ideal for cases where your app uses a particular token that may not have price information available. Like in Aggregated Mode, you will need to supply implementation metadata for the asset, including any custom network definitions so that its balances can be queried for the session’s connected wallets. However, in this mode, you do not need to include a price object or a price URL.

<ParaProvider
  // ... other config
  paraModalConfig={{
    // ... other config
    balances: {
      displayType: 'CUSTOM_ASSET',
      asset: {
        name: 'Custom Asset',
        symbol: 'CUSTOM',
        logoUrl: '<logo-url>',
        networks: [
          // A custom network where the asset is the native token:
          {
            network: {
              name: 'Custom Chain',
              evmChainId: '12345',
              rpcUrl: '<rpc-url>',
              logoUrl: '<logo-url>',
              nativeTokenSymbol: 'CUSTOM',
              explorer: {
                name: 'Custom Chain Explorer',
                url: 'https://customexplorer.com',
                txUrlFormat: 'https://customexplorer.com/tx/{HASH}',
              }
            },
          },
          // A known network where the asset is an ERC-20 token:
          {
            contractAddress: '0x...',
            network: 'ETHEREUM',
          }
        ],
      },
    },
  }}
>
  {children}
</ParaProvider>

useProfileBalance Hook

The useProfileBalance hook allows you to query the current aggregated or custom asset balance of all wallets in the current session. Balances are normally cached on the server for five minutes. You can supply a refetchTrigger to the hook to manually refetch balances when desired, using a unique number or string.

import { useProfileBalance } from "@getpara/react-sdk";

function BalanceDisplay() {
  const [refetchTrigger, setRefetchTrigger] = useState(0);

  const { data: profileBalance, isLoading, error } = useProfileBalance({
    // Balances will be refetched whenever `refetchTrigger` changes
    refetchTrigger,
  });

  if (isLoading) return <div>Loading balances...</div>;
  if (error) return <div>Error loading balances: {error.message}</div>;
  if (!profileBalance) return <div>No balance data available</div>;

  return (
    <div>
      <h2>Total Balance: ${profileBalance.value.value.toFixed(2)}</h2>
      <div>
        {profileBalance.wallets.map((wallet) => (
          <div key={wallet.address}>
            <h3>Wallet: {wallet.address}</h3>
            {wallet.assets.map((asset) => (
              <div key={asset.symbol}>
                <span>{asset.symbol}: ${asset.balance}</span>
                <span>(${asset.value.value.toFixed(2)})</span>
              </div>
            ))}
          </div>
        ))}
      </div>
      <button onClick={() => setRefetchTrigger(prev => prev + 1)}>Refresh Balances</button>
    </div>
  );
}

Depending on the display type, the ProfileBalance object returned by useProfileBalance has the following structure:

Aggregated
Custom Asset

{
  value: {
    value: 200,
    currency: 'USD',
  },
  wallets: [
    {
      type: 'EVM',
      address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      value: {
        value: 200,
        currency: 'USD',
      },
      assets: [
        {
          metadata: {
            internalId: 'ETHEREUM',
            zerionId: 'eth',
            name: 'Ethereum',
            symbol: 'ETH',
            rpcUrl: 'https://eth.llamarpc.com',
            logoUrl: 'https://cdn.zerion.io/eth.png',
            explorer: {
              name: 'Etherscan',
              url: 'https://etherscan.io',
              txUrlFormat: 'https://etherscan.io/tx/{HASH}',
            },
            price: {
              value: 4000,
              currency: 'USD',
            }
          },
          quantity: 0.03,
          value: {
            value: 120,
            currency: 'USD',
          },
          networks: [
            {
              metadata: {
                internalId: 'ETHEREUM',
                zerionId: 'ethereum',
                evmChainId: '1',
                name: 'Ethereum',
                rpcUrl: 'https://eth.llamarpc.com',
                logoUrl: 'https://cdn.zerion.io/eth.png',
                explorer: {
                  name: 'Etherscan',
                  url: 'https://etherscan.io',
                  txUrlFormat: 'https://etherscan.io/tx/{HASH}',
                }
              },
              quantity: 0.02,
              value: {
                value: 80,
                currency: 'USD',
              },
            },
            {
              metadata: {
                internalId: 'BASE',
                zerionId: 'base',
                evmChainId: '8453',
                name: 'Base',
                rpcUrl: 'https://base.llamarpc.com',
                logoUrl: 'https://cdn.zerion.io/base.png',
                explorer: {
                  name: 'Basescan',
                  url: 'https://basescan.org',
                  txUrlFormat: 'https://basescan.org/tx/{HASH}',
                }
              },
              quantity: 0.01,
              value: {
                value: 40,
                currency: 'USD',
              },
            }
          ]
        },
        {
          metadata: {
            internalId: 'USDC',
            zerionId: 'usdc',
            name: 'USD Coin',
            symbol: 'USDC',
            price: {
              value: 1,
              currency: 'USD',
            }
          },
          quantity: 80,
          value: {
            value: 80,
            currency: 'USD',
          },
          networks: [
            {
              metadata: {
                internalId: 'ETHEREUM',
                zerionId: 'ethereum',
                evmChainId: '1',
                name: 'Ethereum',
                rpcUrl: 'https://eth.llamarpc.com',
                logoUrl: 'https://cdn.zerion.io/eth.png',
                explorer: {
                  name: 'Etherscan',
                  url: 'https://etherscan.io',
                  txUrlFormat: 'https://etherscan.io/tx/{HASH}',
                }
              },
              quantity: 50,
              value: {
                value: 50,
                currency: 'USD',
              },
              contractAddress: '0x...',
            },
            {
              metadata: {
                internalId: 'BASE',
                zerionId: 'base',
                evmChainId: '8453',
                name: 'Base',
                rpcUrl: 'https://base.llamarpc.com',
                logoUrl: 'https://cdn.zerion.io/base.png',
                explorer: {
                  name: 'Basescan',
                  url: 'https://basescan.org',
                  txUrlFormat: 'https://basescan.org/tx/{HASH}',
                }
              },
              quantity: 20,
              value: {
                value: 20,
                currency: 'USD',
              },
              contractAddress: '0x...',
            },
            {
              metadata: {
                internalId: 'SOLANA',
                name: 'Solana',
              },
              quantity: 10,
              value: {
                value: 10,
                currency: 'USD',
              },
              contractAddress: '0x...',
            }
          ]
        }
      ],
      networks: [
        {
          metadata: {
            internalId: 'ETHEREUM',
            zerionId: 'ethereum',
            evmChainId: '1',
            name: 'Ethereum',
          },
          value: {
            value: 130,
            currency: 'USD',
          },
          assets: [
            {
              metadata: {
                internalId: 'ETHEREUM',
                zerionId: 'ethereum',
                evmChainId: '1',
                name: 'Ethereum',
                symbol: 'ETH',
                rpcUrl: 'https://eth.llamarpc.com',
                logoUrl: 'https://cdn.zerion.io/eth.png',
                explorer: {
                  name: 'Etherscan',
                  url: 'https://etherscan.io',
                  txUrlFormat: 'https://etherscan.io/tx/{HASH}',
                }
              },
              quantity: 0.02,
              value: {
                value: 80,
                currency: 'USD',
              },
              contractAddress: '0x...',
            },
            {
              metadata: {
                internalId: 'USDC',
                zerionId: 'usdc',
                name: 'USD Coin',
                symbol: 'USDC',
                price: {
                  value: 1,
                  currency: 'USD',
                },
              },
              quantity: 50,
              value: {
                value: 50,
                currency: 'USD',
              },
              contractAddress: '0x...',
            }
          ]
        },
        {
          metadata: {
            internalId: 'BASE',
            zerionId: 'base',
            evmChainId: '8453',
            name: 'Base',
            logoUrl: 'https://cdn.zerion.io/base.png',
            rpcUrl: 'https://base.llamarpc.com',
            explorer: {
              name: 'Basescan',
              url: 'https://basescan.org',
              txUrlFormat: 'https://basescan.org/tx/{HASH}',
            }
          },
          value: {
            value: 60,
            currency: 'USD',
          },
          assets: [
            {
              metadata: {
                internalId: 'ETHEREUM',
                zerionId: 'eth',
                evmChainId: '1',
                name: 'Ethereum',
                logoUrl: 'https://cdn.zerion.io/eth.png',
              },
              quantity: 0.01,
              value: {
                value: 40,
                currency: 'USD',
              },
              contractAddress: '0x...',
            },
            {
              metadata: {
                internalId: 'USDC',
                zerionId: 'usdc',
                name: 'USD Coin',
                symbol: 'USDC',
                logoUrl: 'https://cdn.zerion.io/usdc.png',
                price: {
                  value: 1,
                  currency: 'USD',
                },
              },
              quantity: 20,
              value: {
                value: 20,
                currency: 'USD',
              },
              contractAddress: '0x...',
            }
          ]
        },
        {
          metadata: {
            internalId: 'SOLANA',
            name: 'Solana',
            rpcUrl: 'https://api.mainnet-beta.solana.com',
            logoUrl: 'https://cdn.zerion.io/solana.png',
            explorer: {
              name: 'Solana Explorer',
              url: 'https://explorer.solana.com/',
              txUrlFormat: 'https://explorer.solana.com/tx/{HASH}',
            }
          },
          value: {
            value: 10,
            currency: 'USD',
          },
          assets: [
            {
              metadata: {
                internalId: 'USDC',
                zerionId: 'usdc',
                name: 'USD Coin',
                symbol: 'USDC',
                price: {
                  value: 1,
                  currency: 'USD',
                },
              },
              quantity: 10,
              value: {
                value: 10,
                currency: 'USD',
              },
              contractAddress: '0x...',
            }
          ]
        }
      ]
    }
  ]
}

{
  wallets: [
    {
      type: 'EVM',
      address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      assets: [
        {
          metadata: {
            name: 'Custom Asset',
            symbol: 'CUSTOM',
            customAssetId: 'custom_CUSTOM',
            logoUrl: '<logo-url>',
          },
          quantity: 1.5,
          networks: [
            {
              metadata: {
                internalId: 'ETHEREUM',
                zerionId: 'ethereum',
                name: 'Ethereum',
                evmChainId: '1',
                rpcUrl: 'https://eth.llamarpc.com',
                logoUrl: 'https://cdn.zerion.io/eth.png',
                explorer: {
                  name: 'Etherscan',
                  url: 'https://etherscan.io',
                  txUrlFormat: 'https://etherscan.io/tx/{HASH}',
                }
              },
              quantity: 1.0,
              contractAddress: '0x...',
            },
            {
              metadata: {
                customNetworkId: 'custom_12345',
                name: 'Custom Chain',
                evmChainId: '12345',
                rpcUrl: 'https://rpc.customexplorer.com',
                logoUrl: 'https://cdn.customexplorer.com/logo.png',
                nativeTokenSymbol: 'CUSTOM',
                explorer: {
                  name: 'Custom Chain Explorer',
                  url: 'https://customexplorer.com',
                  txUrlFormat: 'https://customexplorer.com/tx/{HASH}',
                }
              },
              quantity: 0.5,
              contractAddress: '0x...',
            }
          ]
        }
      ],
      networks: [
        {
          metadata: {
            internalId: 'ETHEREUM',
            zerionId: 'ethereum',
            name: 'Ethereum',
            evmChainId: '1',
            rpcUrl: 'https://eth.llamarpc.com',
            logoUrl: 'https://cdn.zerion.io/eth.png',
            explorer: {
              name: 'Etherscan',
              url: 'https://etherscan.io',
              txUrlFormat: 'https://etherscan.io/tx/{HASH}',
            }
          },
          assets: [
            {
              metadata: {
                name: 'Custom Asset',
                symbol: 'CUSTOM',
                customAssetId: 'custom_CUSTOM',
              },
              quantity: 1.5,
              contractAddress: '0x...',
            }
          ]
        },
        {
          metadata: {
            customNetworkId: 'custom_12345',
            name: 'Custom Chain',
            evmChainId: '12345',
            rpcUrl: 'https://rpc.customexplorer.com',
            logoUrl: 'https://cdn.customexplorer.com/logo.png',
            explorer: {
              name: 'Custom Chain Explorer',
              url: 'https://customexplorer.com',
              txUrlFormat: 'https://customexplorer.com/tx/{HASH}',
            }
          },
          assets: [
            {
              metadata: {
                name: 'Custom Asset',
                symbol: 'CUSTOM',
                customAssetId: 'custom_CUSTOM',
              },
              quantity: 0.5,
              contractAddress: '0x...',
            }
          ]
        }
      ]
    }
  ]
}

Quick Start

Set Up Your Framework

Configure Developer Portal

Configure Your Modal

Sign with Para

Ethereum / EVM

Solana

Cosmos

Smart Accounts

Sessions & Auth

Programmatic Wallets

Custom Integrations

Build with Hooks

Troubleshooting

Configure Balance Display

Balance Display Configuration

Defining Custom Networks and Assets

Aggregated Mode (Default)

Balance Overrides

Custom Asset Mode

useProfileBalance Hook

Quick Start

Set Up Your Framework

Configure Developer Portal

Configure Your Modal

Sign with Para

Ethereum / EVM

Solana

Cosmos

Smart Accounts

Sessions & Auth

Programmatic Wallets

Custom Integrations

Build with Hooks

Troubleshooting

​Balance Display Configuration

​Defining Custom Networks and Assets

​Aggregated Mode (Default)

​Balance Overrides

​Custom Asset Mode

​useProfileBalance Hook

Balance Display Configuration

Defining Custom Networks and Assets

Aggregated Mode (Default)

Balance Overrides

Custom Asset Mode

useProfileBalance Hook