Chain-Agnostic

Get Balance

Fetch native coin balance for any address on any chain. Discriminated return — EVM gives bigint wei, UTXO gives confirmed + unconfirmed satoshis.

Get balance uses the RPC client to dispatch to the right backend based on the session's active network. The return shape differs per chain family so you can access chain-specific fields (like UTXO's confirmed/unconfirmed split) when needed.

import { rpc, getSession } from '@oviato/connect';

const session = getSession();
const r = await rpc.getBalance({ address: session.address });

if (r.result) {
  console.log(r.result.balance.formatted); // '1.2345'
  console.log(r.result.symbol);            // 'ETH' | 'BTC' | 'USDC' etc.
}

getBalance lives under the rpc client today. A flat top-level getBalance({ address }) with the spec-flattened return shape is on the roadmap — the current form works and is stable for use.

Return shape

The response is a discriminated union keyed on chainType:

EVM

{
  address: string;
  network: string;       // 'eth' | 'base' | ...
  networkName: string;   // 'Ethereum' | 'Base' | ...
  chainType: 'evm';
  balance: {
    raw: string;         // wei as decimal string (avoids bigint-over-JSON)
    formatted: string;   // '1.2345' (native units)
    symbol: string;      // 'ETH' | 'BASE' | ...
    decimals: number;    // 18
  };
  symbol: string;
  decimals: number;
}

UTXO (Bitcoin)

{
  address: string;
  network: string;       // 'bitcoin' | 'bitcointestnet' | ...
  networkName: string;
  chainType: 'utxo';
  balance: {
    raw: number;                    // satoshis
    formatted: string;              // '0.0125'
    symbol: string;                 // 'BTC' | 'tBTC'
    decimals: number;               // 8
    confirmed: {                    // mined-only portion
      raw: number; formatted: string; symbol: string; decimals: number;
    };
    unconfirmed: {                  // pending mempool portion
      raw: number; formatted: string; symbol: string; decimals: number;
    };
  };
  symbol: string;
  decimals: number;
}

EVM raw is a decimal string (e.g. "1234000000000000"), not a bigint — because bigint can't JSON-serialize. Parse with BigInt(raw) or use fromWire() to get back a bigint. UTXO raw is a number (safe since satoshi amounts don't overflow 2⁵³).

Typical usage

Display a user's balance

import { rpc, useOviConnect } from '@oviato/connect/client';
import { useEffect, useState } from 'react';

function BalanceView() {
  const { session } = useOviConnect();
  const [balance, setBalance] = useState<string | null>(null);

  useEffect(() => {
    if (!session) return;
    rpc.getBalance({ address: session.address }).then((r) => {
      if (r.result) setBalance(r.result.balance.formatted);
    });
  }, [session]);

  if (!session) return null;
  return <p>{balance ?? '…'} {/* symbol */}</p>;
}

Pre-check before sending

import { rpc, getSession, fromWire } from '@oviato/connect';

async function canSend(amountWei: bigint) {
  const session = getSession();
  const r = await rpc.getBalance({ address: session!.address });
  if (!r.result || r.result.chainType !== 'evm') return false;

  const available = fromWire(r.result.balance.raw); // string → bigint
  return available >= amountWei;
}

Narrow by chain type

const r = await rpc.getBalance({ address });
if (!r.result) return;

if (r.result.chainType === 'evm') {
  // r.result.balance is { raw: string, formatted, symbol, decimals }
  console.log('ETH balance:', r.result.balance.formatted);
} else {
  // r.result.balance has confirmed + unconfirmed
  console.log('Confirmed BTC:', r.result.balance.confirmed.formatted);
  console.log('Pending BTC:', r.result.balance.unconfirmed.formatted);
}

How it's fetched

EVM — Chainstack RPC eth_getBalance(address, 'latest'). Returns wei, SDK formats with chain decimals.
UTXO — Our Bitcoin indexer (built on mempool.space). Returns confirmed + unconfirmed separately since the UTXO model distinguishes them on-chain.

Both paths go through Oviato's RPC API — no direct Chainstack / indexer calls from your dapp.

What this isn't

getBalance is for the native coin only. For ERC-20 balances, use evm.getTokenBalance. For multiple tokens in one call, use evm.multicall.

EVM → Token Balance — ERC-20 balances
Send Transfers — once you know the balance, send some

Send Transfers

Send native coin to an address. One API for Bitcoin (satoshis) and EVM chains (wei). Single recipient or batch on UTXO.

EVM Overview

The evm namespace — reads, writes, popup flow, nonce tracker, envelope pattern. Everything you need to know before writing EVM code with Oviato.

Get Balance

On this page