hyperlane-xyz Warp Route Balances
Run hyperlane warp balances to display the token balance of each leg in a warp route.
Usage
hyperlane warp balances \
--warp-route-id <SYMBOL/chains> \
--registry <path-or-url>
Options
| Flag | Description |
|---|---|
--warp-route-id / -w |
Warp route ID (e.g. ETH/ethereum-arbitrum). Prompts interactively if omitted. |
--registry / -r |
Registry path or URL. Defaults to the public Hyperlane registry. |
--chains |
Filter to specific chains (space-separated). |
--out / -o |
Write results to a JSON or YAML file. |
--address |
User address to check balances for. Shows the user's token balance on each chain instead of collateral/supply. |
--raw |
Show balances in base units (without decimal formatting). |
Output columns
| Column | Description |
|---|---|
(index) |
Chain name |
Symbol |
Token symbol |
Standard |
Token standard (e.g. EvmHypCollateral, EvmHypSynthetic) |
Address |
Router contract address |
Balance |
Collateral locked / circulating supply (default), or user's token balance (with --address) |
Instructions
Determine the warp route ID and registry to use. If not provided, ask the user.
Run the command:
hyperlane warp balances --warp-route-id <ID> --registry <REGISTRY>If the user wants to save the output, add
--out balances.json.If the user wants to filter to specific chains:
hyperlane warp balances --warp-route-id <ID> --registry <REGISTRY> --chains ethereum arbitrumIf the user wants to check their own token balance on each leg, add
--address:hyperlane warp balances --warp-route-id <ID> --registry <REGISTRY> --address <USER_ADDRESS>If the user wants raw base-unit amounts (no decimal formatting), add
--raw:hyperlane warp balances --warp-route-id <ID> --registry <REGISTRY> --rawReport the balances to the user, noting:
- Without
--address: collateral legs show locked/backing balance; synthetic legs show total circulating supply - With
--address: every leg shows the user's token balance on that chain --rawapplies to all balance values and the mismatch summary (base units, no decimals)Errorin the Balance column means the RPC call failed for that leg- Without
--address: a status line is printed after the table — green if collateral == synthetic total, yellow warning with diff if they diverge
- Without
Common use cases
- Sanity check after deployment: verify collateral and synthetic supplies are in sync
- Investigate imbalance: compare collateral locked vs synthetic supply across legs
- Audit liquidity: see how much of the bridged asset is available on each chain
- Check user holdings: see how much of the token a specific address holds on each chain
Example — route liquidity
hyperlane warp balances --warp-route-id USDC/base-optimism --registry ~/hyperlane-registry
Warp route balances:
┌──────────┬────────┬──────────────────────┬────────────┬────────────────┐
│ (index) │ Symbol │ Standard │ Address │ Balance │
├──────────┼────────┼──────────────────────┼────────────┼────────────────┤
│ base │ USDC │ EvmHypCollateral │ 0x5244... │ 4,231,876.12 │
│ optimism │ USDC │ EvmHypSynthetic │ 0x2DBe... │ 4,231,876.12 │
└──────────┴────────┴──────────────────────┴────────────┴────────────────┘
Status: collateral matches synthetic supply (4,231,876.12)
Example — user balances
hyperlane warp balances --warp-route-id USDC/base-optimism --registry ~/hyperlane-registry --address 0xYourAddress
Warp route balances for 0xYourAddress:
┌──────────┬────────┬──────────────────────┬────────────┬──────────┐
│ (index) │ Symbol │ Standard │ Address │ Balance │
├──────────┼────────┼──────────────────────┼────────────┼──────────┤
│ base │ USDC │ EvmHypCollateral │ 0x5244... │ 500.00 │
│ optimism │ USDC │ EvmHypSynthetic │ 0x2DBe... │ 250.00 │
└──────────┴────────┴──────────────────────┴────────────┴──────────┘
Example — raw base units
hyperlane warp balances --warp-route-id USDC/base-optimism --registry ~/hyperlane-registry --raw
Warp route balances:
┌──────────┬────────┬──────────────────────┬────────────┬───────────────┐
│ (index) │ Symbol │ Standard │ Address │ Balance │
├──────────┼────────┼──────────────────────┼────────────┼───────────────┤
│ base │ USDC │ EvmHypCollateral │ 0x5244... │ 4231876120000 │
│ optimism │ USDC │ EvmHypSynthetic │ 0x2DBe... │ 4231876120000 │
└──────────┴────────┴──────────────────────┴────────────┴───────────────┘
Status: collateral matches synthetic supply (4231876120000)