| name | warp-balances |
| description | Check token balances for each leg of a warp route. Shows collateral locked (for collateral/native legs) and total circulating supply (for synthetic legs). Use when you want to inspect the current state of a warp route's liquidity. |
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 arbitrum
-
If 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> --raw
-
Report 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
--raw applies to all balance values and the mismatch summary (base units, no decimals)Error in 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
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)
