`bullpen hyperliquid balances`¶

Last updated: July 13, 2026

Show spot + perp balance and equity breakdown

Usage¶

bullpen hyperliquid balances [OPTIONS]

Live Help¶

Show spot + perp balance and equity breakdown

Usage: bullpen hyperliquid balances [OPTIONS]

Options:
      --address <ADDRESS>
          Ethereum address to query. Defaults to the authenticated account

      --no-multi-wallet-warning
          Suppress the table-mode warning shown when multiple EVM wallet accounts exist

      --output <OUTPUT>
          Output format for command results

          [possible values: table, json]

      --all-dexes
          Query main plus every registered HIP-3 perp DEX

      --env <ENV>
          Target environment to connect to (overrides config.toml)

          [env: BULLPEN_ENV=]
          [possible values: staging, production]

      --config <CONFIG>
          Path to a custom config.toml file (overrides $BULLPEN_CONFIG and the default location).

          Explicit --config and BULLPEN_CONFIG paths fail closed: if the file is missing, the CLI exits validation instead of silently loading defaults. Credentials still resolve via BULLPEN_HOME, so set BULLPEN_HOME too when isolating a session.

      --read-only
          Enable read-only mode: blocks all mutating commands

      --non-interactive
          Suppress interactive prompts; does NOT imply --yes for money-moving commands

          [env: BULLPEN_NON_INTERACTIVE=]

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # Show Hyperliquid balances for an address
  bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111

  # Export Hyperliquid balances as JSON
  bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111 --output json

  # Export balances across main plus registered HIP-3 DEXes
  bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111 --all-dexes --output json

Example Commands¶

bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111
bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111 --output json
bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111 --all-dexes --output json

JSON Output¶

Contract: JSON Output Contract.

Successful output is a single JSON document. The shape below is representative for this command family; commands may add fields without breaking the shared contract.

Schema version: 1 when a command emits schema_version; otherwise treat the current command shape as contract version 1.

Top-level Keys¶

key	type	nullable	notes
`schema_version`	integer	no	JSON schema version for this balances envelope; currently `1`
`address`	string	no	Hyperliquid account address queried
`signer_address`	string	yes	Authenticated signer address when the query is resolved from login state
`dex_scope`	string	yes	Present as `all` only for `--all-dexes` output
`totals`	object	yes	Aggregate balance/equity totals across main plus registered HIP-3 DEXes for `--all-dexes` output
`per_dex`	array	yes	Per-DEX balance breakdown for `--all-dexes`; omitted otherwise
`perp_account_value`	string/decimal	no	Perp account value from clearinghouse state
`perp_total_ntl_pos`	string/decimal	no	Total perp notional position value
`perp_margin_used`	string/decimal	no	Perp margin currently used
`available_usdc`	string/decimal	no	Conservative aggregate: max(0, spot USDC total - spot USDC hold) when hold is positive, otherwise spot USDC total plus perp withdrawable from the same read
`spot_estimated_value`	string/decimal	no	Estimated USD value of priced spot balances
`estimated_total_equity`	string/decimal	no	Perp value plus estimated spot value
`unpriced_spot_balances`	array	yes	Spot coins that could not be priced from market metadata; omitted when empty
`spot_balances`	array	no	Spot balances with total, hold, available, mark price, and estimated value

Example¶

Example JSON output

bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111 --output json

{
  "schema_version": 1,
  "address": "0x1111111111111111111111111111111111111111",
  "perp_account_value": "1250.50",
  "perp_total_ntl_pos": "500.00",
  "perp_margin_used": "125.00",
  "perp_raw_usd": "1125.50",
  "cross_account_value": "1250.50",
  "available_usdc": "1350.50",
  "spot_estimated_value": "100.00",
  "estimated_total_equity": "1350.50",
  "spot_balances": [
    {
      "coin": "USDC",
      "total": "100.0",
      "hold": "0.0",
      "available": "100.0",
      "entry_value": "100.0",
      "mark_px": "1.0",
      "estimated_value": "100.0"
    }
  ]
}

When --all-dexes is passed, the command returns an all-DEX envelope instead of the default main-DEX shape. The totals object sums perp account value, notional, margin, cross-account value, cross-maintenance margin, and withdrawable USDC across main plus registered HIP-3 DEXes. Spot balances are read once and are not duplicated per DEX. Default balances output remains main-DEX scoped for script compatibility.

All-DEX Example¶

All-DEX example JSON output

bullpen hyperliquid balances --address 0x1111111111111111111111111111111111111111 --all-dexes --output json

{
  "schema_version": 1,
  "address": "0x1111111111111111111111111111111111111111",
  "dex_scope": "all",
  "totals": {
    "perp_account_value": "30.75",
    "perp_total_ntl_pos": "13",
    "perp_margin_used": "4",
    "perp_raw_usd": "30.75",
    "cross_account_value": "30.25",
    "cross_maintenance_margin_used": "1",
    "perp_withdrawable": "19",
    "available_usdc": "75"
  },
  "per_dex": [
    {
      "label": "main",
      "registry_index": 0,
      "perp_account_value": "10.5"
    },
    {
      "label": "dex-a",
      "dex": "dex-a",
      "registry_index": 1,
      "perp_account_value": "20.25"
    }
  ],
  "spot_estimated_value": "136.9",
  "estimated_total_equity": "167.65",
  "spot_balances": []
}

Stability¶

Patch releases may add nullable or optional fields. Minor releases may add required fields or increment schema_version. Major releases may remove or rename fields.

bullpen hyperliquid balances¶