nibiru Reference Notes

Supporting reference for nibiru-cli.

GitHub source ↗Original Markdown ↓
On this page Overview

EVM via nibiru

Use these commands when the user wants EVM-related state through the Nibiru CLI rather than Ethereum JSON-RPC.

Start on the intended network first:

ud nibi cfg prod
nibiru config

This selects the default, non-archive mainnet RPC and JSON output. The commands in this reference read current EVM state, so do not add --archive. Assume the active CLI config is already set to JSON output unless the user says otherwise.

nibiru q evm account

This is the fastest CLI check for an EVM account’s native gas balance on Nibiru. It accepts either a hex 0x... address or a Bech32 nibi1... address and returns both forms in the response.

ADDR_HEX="0x7027d536380F0474B7Ec119c2c5250821902e6dC"
ADDR_BECH32="nibi1wqna2d3cpuz8fdlvzxwzc5jssgvs9ekufm3uj2"
nibiru q evm account "$ADDR_HEX"
nibiru q evm account "$ADDR_BECH32"

Returned fields:

  • balance_wei: native EVM balance in wei
  • nonce: account nonce
  • code_hash: code hash at the address
  • eth_address: normalized hex form
  • bech32_address: normalized Bech32 form

Reminder:

  • The empty-account code hash appears as 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470; seeing that value is a quick hint that the address is not holding deployed EVM bytecode.

Offline normalization only:

ADDR="0x7027d536380F0474B7Ec119c2c5250821902e6dC"
nibiru q evm account "$ADDR" --offline

With --offline, the CLI only normalizes the address forms. It does not query live chain state, so balance_wei and code_hash come back empty and nonce defaults to 0.

nibiru q evm balance

This is the workhorse command for checking USDC balances on Nibiru, especially for Sai operations where USDC is the primary currency. It queries token balances in Nibiru’s multi-VM context and returns both ERC20 and Bank representations when available.

It accepts either address format for the account argument:

  • EVM hex address, e.g. 0x8fB11A655B6cb989085c8B21AB044Ec19685942D
  • Bech32 address, e.g. nibi137c35e2mdjucjzzu3vs6kpzwcxtgt9pdnvj5ll

It accepts either token format for the token argument:

  • ERC20 address, e.g. mainnet USDC 0x0829F361A05D993d5CEb035cA6DF3446b060970b
  • Bank denom, e.g. erc20/0x0829F361A05D993d5CEb035cA6DF3446b060970b
  • Native bank denom, e.g. unibi

Mainnet Sai USDC reference:

USDC_ERC20="0x0829F361A05D993d5CEb035cA6DF3446b060970b"
USDC_BANK="erc20/0x0829F361A05D993d5CEb035cA6DF3446b060970b"

The examples from nibiru q evm balance --help are the canonical quick-start:

# USDC on Nibiru mainnet
addr="0xYourAddr" token="0x0829F361A05D993d5CEb035cA6DF3446b060970b"
nibiru query evm balance "$addr" "$token"

# NIBI via bank denom
addr="0xYourAddr" token="unibi"  # Bank coin denom works
nibiru query evm balance "$addr" "$token"

# NIBI via canonical WNIBI ERC20
addr="0xYourAddr" token="0x0CaCF669f8446BeCA826913a3c6B96aCD4b02a97" # ERC20 addr works
nibiru query evm balance "$addr" "$token"

For a Bech32 keyring address, use the key address directly:

ADDR="$(nibiru keys show sai-perp-admin -a)"
TOKEN="0x0829F361A05D993d5CEb035cA6DF3446b060970b"
nibiru q evm balance "$ADDR" "$TOKEN" | jq .

Useful output fields:

  • addr_evm and addr_bech32: normalized account address forms.
  • erc20_balance_human / erc20_balance_base: ERC20 balance.
  • bank_balance_human / bank_balance_base: Bank coin balance for the mapped denom.
  • bank_coin_denom: bank denom corresponding to the ERC20 token.
  • erc20_decimals / bank_decimals: decimal metadata for display conversion.

Rule of thumb:

  • Prefer nibiru q evm balance "$ADDR" "$USDC_ERC20" for Sai USDC balance checks because it shows both EVM/ERC20 and Bank-side holdings in one response.
  • Use nibiru q bank balances "$ADDR" --denom "$USDC_BANK" only when you specifically need the Bank module view.

balance_wei and bank unibi

balance_wei from nibiru q evm account and bank unibi from nibiru q bank balances represent the same native NIBI balance, just at different granularities.

  • unibi means micro NIBI (μ NIBI)
  • 1 NIBI = 1_000_000 unibi
  • 1 NIBI = 10^18 wei
  • Therefore 1 unibi = 10^12 wei

Examples:

ADDR="nibi1wqna2d3cpuz8fdlvzxwzc5jssgvs9ekufm3uj2"
DENOM="unibi"
nibiru q evm account "$ADDR"
nibiru q bank balances "$ADDR" --denom "$DENOM"

Rule of thumb:

  • Use q evm account when the user thinks in EVM/native-gas terms or has a 0x... address.
  • Use q bank balances --denom unibi when the user wants the Cosmos bank representation.

nibiru q evm funtoken

Use this to query the mapping between a bank denom and its ERC20 representation.

COIN_OR_ERC20="unibi"
nibiru q evm funtoken "$COIN_OR_ERC20"

COIN_OR_ERC20="0x7D4B7B8CA7E1a24928Bb96D59249c7a5bd1DfBe6"
nibiru q evm funtoken "$COIN_OR_ERC20"

nibiru tx evm scope

On this CLI build, nibiru tx evm is for FunToken and bank/ERC20 conversion flows, not generic Ethereum wallet-like transactions.

Available commands:

  • nibiru tx evm convert-coin-to-evm
  • nibiru tx evm convert-evm-to-coin
  • nibiru tx evm create-funtoken

Use other surfaces when appropriate:

  • nibiru tx bank for native bank sends
  • nibiru tx wasm for CosmWasm contract execution and instantiation
  • evm-rpc for receipts, traces, and eth_* / debug_* RPC workflows