Skip to main content
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>

​
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: 
{
  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...',
            }
          ]
        }
      ]
    }
  ]
}