Balance

Check your private balances in Privacy Cash

Get SOL Balance

Retrieve your private SOL balance from Privacy Cash.

const balance = await client.getPrivateBalance(abortSignal?: AbortSignal)

Parameters

Parameter	Type	Required	Description
abortSignal	AbortSignal	No	Optional signal to abort the request

Returns

{
  lamports: number // Balance in lamports
}

Example

import { PrivacyCash } from 'privacycash'

const client = new PrivacyCash({
  RPC_url: process.env.SOLANA_RPC_URL!,
  owner: process.env.PRIVATE_KEY!
})

const balance = await client.getPrivateBalance()

console.log('Private balance:', balance.lamports, 'lamports')
console.log('Private balance:', balance.lamports / 1_000_000_000, 'SOL')

---

Get SPL Token Balance

Retrieve your private balance for any supported SPL token.

import { PublicKey } from '@solana/web3.js'

const balance = await client.getPrivateBalanceSpl(
  mintAddress: PublicKey | string
)

Parameters

Parameter	Type	Required	Description
mintAddress	PublicKey | string	Yes	The SPL token mint address

Returns

{
  amount: number // Balance in base units
}

Example

import { PublicKey } from '@solana/web3.js'

// USDC mint address
const USDC_MINT = new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v')

const balance = await client.getPrivateBalanceSpl(USDC_MINT)

console.log('Private USDC:', balance.amount, 'base units')
console.log('Private USDC:', balance.amount / 1_000_000, 'USDC') // USDC has 6 decimals

---

Get USDC Balance

Convenience method specifically for USDC.

const balance = await client.getPrivateBalanceUSDC()

Returns

{
  amount: number // Balance in base units (1 USDC = 1,000,000 base units)
}

Example

const balance = await client.getPrivateBalanceUSDC()

console.log('Private USDC:', balance.amount / 1_000_000, 'USDC')

---

Supported Tokens

Token	Mint Address	Decimals	Units per Token
SOL	Native	9	1,000,000,000
USDC	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6	1,000,000
USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB	6	1,000,000
ZEC	A7bdiYdS5GjqGFtxf17ppRHtDKPkkRqbKtR27dxvQXaS	8	100,000,000
ORE	oreoU2P8bN6jkk3jbaiVxYnG1dCXcYxwhwyK9jSybcp	11	100,000,000,000
STORE	sTorERYB6xAZ1SSbwpK3zoK2EEwbBrc7TZAzg1uCGiH	11	100,000,000,000

---

How Balance Checking Works

1. Fetch Encrypted UTXOs

   The SDK fetches all encrypted UTXOs from the relayer API

2. Decrypt Your UTXOs

   Using your encryption key, the SDK decrypts UTXOs that belong to you

3. Check Spent Status

   Each UTXO is checked on-chain to see if it has been spent

4. Sum Unspent

   The amounts of all unspent UTXOs are summed to get your balance

Caching

The SDK caches decrypted UTXOs locally for faster subsequent balance checks:

// First call: fetches and decrypts all UTXOs (slower)
const balance1 = await client.getPrivateBalance()

// Second call: uses cached data + fetches only new UTXOs (faster)
const balance2 = await client.getPrivateBalance()

// Force refresh: clear cache and fetch everything
await client.clearCache()
const balance3 = await client.getPrivateBalance()

---

Aborting Balance Requests

For long-running balance checks, you can abort the request:

const controller = new AbortController()

// Start balance check
const balancePromise = client.getPrivateBalance(controller.signal)

// Abort after 10 seconds
setTimeout(() => controller.abort(), 10000)

try {
  const balance = await balancePromise
  console.log('Balance:', balance.lamports)
} catch (error) {
  if (error.message === 'aborted') {
    console.log('Balance check was cancelled')
  }
}

---

Complete Example

import { PrivacyCash } from 'privacycash'
import { PublicKey } from '@solana/web3.js'

async function checkAllBalances() {
  const client = new PrivacyCash({
    RPC_url: process.env.SOLANA_RPC_URL!,
    owner: process.env.PRIVATE_KEY!
  })

  // Check SOL balance
  const solBalance = await client.getPrivateBalance()
  console.log('SOL:', solBalance.lamports / 1e9)

  // Check USDC balance
  const usdcBalance = await client.getPrivateBalanceUSDC()
  console.log('USDC:', usdcBalance.amount / 1e6)

  // Check USDT balance
  const USDT_MINT = new PublicKey('Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB')
  const usdtBalance = await client.getPrivateBalanceSpl(USDT_MINT)
  console.log('USDT:', usdtBalance.amount / 1e6)

  // Check ORE balance
  const ORE_MINT = new PublicKey('oreoU2P8bN6jkk3jbaiVxYnG1dCXcYxwhwyK9jSybcp')
  const oreBalance = await client.getPrivateBalanceSpl(ORE_MINT)
  console.log('ORE:', oreBalance.amount / 1e11)
}

checkAllBalances()