Read fetches encrypted Private Solana Token Accounts from the indexer with dedicated RPC methods.
Only the user, or anyone the user authorizes, can decrypt balances with their viewing key.
Use it after a private balance changes and before a transfer.

Compare to getBalance / getAccount

getBalance returns public SOL. getAccount returns a public token account.
The RPC returns the public balance.

Get Started

TypeScript Client
Rust Client

Prerequisites

The TypeScript examples require Node.js 24 or later, pnpm 11.18.0, and the Solana CLI.

pnpm add @heliuslabs/zolana @solana/kit

Source: sdk-libs/ts

Connect to Endpoints

Devnet
Localnet

pnpm install
cp .env.example .env

Add a Helius API key:

.env

API_KEY=YOUR_API_KEY
ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json

import { createZolanaClient } from "@heliuslabs/zolana";

const client = await createZolanaClient({
  solanaRpcUrl: "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY",
  indexerUrl: "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com",
  proverUrl: "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com:3001",
  allowInsecureHttp: true,
});

The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See How to Get Devnet SOL.

On localnet the SDK starts the local test validator (:8899), Photon indexer (:8784), and prover (:3001), and the client connects to them automatically without needing endpoint configuration.

cargo install --git https://github.com/helius-labs/zolana --tag v0.1.0-alpha zolana-cli
zolana dev start

import { createZolanaClient } from "@heliuslabs/zolana";

const client = await createZolanaClient({});

Derive the View Tag

import { createZolanaClient } from "@heliuslabs/zolana";

// The view tag is the sender's Solana public key in confidential rings.
// Used by the indexer to fetch the sender's UTXOs.
const senderViewTag =
  senderAddress.confidentialViewTag();

senderViewTag is senderAddress.confidentialViewTag(), the sender’s Solana public key in confidential rings. The indexer uses it to return matching encrypted outputs.

Fetch Transaction Outputs from the Indexer

import { atSlot } from "@heliuslabs/zolana/client";

const depositResponse =
  await client.getShieldedTransactionsByTags(
    { tags: [senderViewTag] },
    atSlot(depositTx.slot),
  );

getShieldedTransactionsByTags fetches the encrypted outputs associated with senderViewTag.
atSlot(depositTx.slot) waits until the indexer has the deposit at that slot.
The indexer returns encrypted output data. It does not decrypt the private balance.

Decrypt to a Private Balance

import { SOL_MINT } from "@heliuslabs/zolana";
import { decryptToBalances } from "@heliuslabs/zolana/transaction";

const balancesAfterDeposit =
  await decryptToBalances({
    keypair: senderKeypair,
    registry: assets,
    transactions: depositResponse.transactions,
  });
const depositBalance =
  balancesAfterDeposit.balance(SOL_MINT);

senderKeypair supplies the sender’s viewing key for local decryption.
decryptToBalances decrypts matching outputs and returns the sender’s private balances.
balancesAfterDeposit.balance(SOL_MINT) reads the private SOL balance.

See Concepts for how owner tagging and Private Solana Token Accounts work.

Full Code Example

Clone and run the example:

git clone https://github.com/helius-labs/zolana-examples.git
cd zolana-examples/typescript-client
pnpm install
pnpm example examples/deposit_transfer_withdraw.ts

The examples use a confidential Ring on local/devnet here.

Prerequisites

The Rust examples require the latest stable Rust toolchain and the Solana CLI v4.0.2. See the Solana installation guide.

Cargo.toml

[dependencies]
zolana-client = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha", features = ["indexer-api", "solana-rpc"] }
zolana-interface = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha", features = ["solana"] }
zolana-keypair = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha" }
zolana-transaction = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha" }

Source: sdk-libs/client

Connect to Endpoints

Devnet
Localnet

Add a Helius API key:

.env

API_KEY=YOUR_API_KEY
ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json

use solana_address::Address;
use zolana_client::{SolanaRpc, ZolanaClient};
use zolana_interface::DEFAULT_TREE_ADDRESS;

let tree: Address = DEFAULT_TREE_ADDRESS.parse()?;
let client = ZolanaClient::from_urls_allowing_insecure_http(
    SolanaRpc::new("https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY"),
    "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com",
    "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com:3001",
    tree,
);

The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See How to Get Devnet SOL.

cargo install --git https://github.com/helius-labs/zolana --tag v0.1.0-alpha zolana-cli
zolana dev start

use solana_address::Address;
use zolana_client::{SolanaRpc, ZolanaClient};
use zolana_interface::DEFAULT_TREE_ADDRESS;

let tree: Address = DEFAULT_TREE_ADDRESS.parse()?;
let client = ZolanaClient::from_urls(
    SolanaRpc::new("http://127.0.0.1:8899"),
    "http://127.0.0.1:8784",
    "http://127.0.0.1:3001",
    tree,
)?;

Derive the View Tag

use zolana_client::Rpc;

let sender_tag = sender_shielded_address.confidential_view_tag()?;

sender_tag is sender_shielded_address.confidential_view_tag(), the sender’s Solana public key in confidential rings. The indexer uses it to return matching encrypted outputs.

Fetch Transaction Outputs from the Indexer

use zolana_client::{IndexerRpcConfig, Rpc};

let response = client.get_shielded_transactions_by_tags(
    vec![sender_tag],
    None,
    Some(50),
    Some(IndexerRpcConfig::at_slot(slot)),
)?;

get_shielded_transactions_by_tags fetches the encrypted outputs associated with sender_tag.
IndexerRpcConfig::at_slot(slot) waits until the indexer has the deposit at that slot.
The indexer returns encrypted output data. It does not decrypt the private balance.

Decrypt to a Private Balance

use anyhow::anyhow;
use zolana_transaction::{decrypt_transactions, SOL_MINT};

let balances = decrypt_transactions(&sender, &response.transactions, &assets)
    .map_err(|e| anyhow!("decrypt sender transactions: {e:?}"))?;
let sender_balance = balances.get_balance(SOL_MINT);

sender supplies the sender’s viewing key for local decryption.
decrypt_transactions decrypts matching outputs and returns the sender’s private balances.
get_balance(SOL_MINT) reads the private SOL balance.

Full Code Example

Clone and run the example:

git clone https://github.com/helius-labs/zolana-examples.git
cd zolana-examples/rust-client
cargo run -p rust-client-example --example deposit_transfer_withdraw

Get Started

Data Streaming & Event Listening

Data APIs & RPCs

Trading

Sending Transactions

Wallet-as-a-Service

Privacy

Guides

Resources

Read a Private Balance

Get Started

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to a Private Balance

Full Code Example

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to a Private Balance

Full Code Example

Deposit

Transfer

Withdraw

Read Private History

Didn’t find what you were looking for?

​Get Started

​Prerequisites

​Derive the View Tag

​Fetch Transaction Outputs from the Indexer

​Decrypt to a Private Balance

​Full Code Example

​Prerequisites

​Derive the View Tag

​Fetch Transaction Outputs from the Indexer

​Decrypt to a Private Balance

​Full Code Example

​Related Guides

Deposit

Transfer

Withdraw

Read Private History

​Didn’t find what you were looking for?

Get Started

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to a Private Balance

Full Code Example

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to a Private Balance

Full Code Example

Related Guides

Didn’t find what you were looking for?