Reading data and status

Read balances

const { balances } = await client.getBalances();

Each token includes a display balance and its accounting breakdown:

const [{ amount, spendable, pending_change }] = balances;

amount is the wallet-facing balance: spendable + pending_change.
spendable is backed by unspent, unreserved notes and is the value to use when deciding whether a new transfer, withdrawal, or execute can be prepared.
pending_change is the user’s expected private output from unresolved spends, usually change. It does not include another user’s pending transfer or an unconfirmed deposit.

Private spends consume whole notes and mint change. While a spend is in flight, the consumed inputs are reserved and disappear from spendable, but their expected owned outputs remain in pending_change. A wallet rendering amount therefore does not show the temporary input-note dip. If the spend fails or an atomic execute reverts, the input reservation is released and the full amount returns to spendable. The guarantee applies when sync_status is current. When it is syncing, the service has failed closed while its optimistic index catches up. It never adds optimistic-only notes or pending outputs. It may still use an already observed output as negative evidence that an older canonical claim was consumed, so the returned amount is a conservative lower bound rather than an overstatement. Show a syncing state until reads return to current. Filter by token:

const { balances } = await client.getBalances({ token: "0xTokenAddress" });

Read transactions

const { transactions } = await client.getTransactions({
  status: "processed", // optional
  type: "transfer", // optional: "deposit" | "transfer" | "withdraw"
  limit: 20, // optional
  cursor: "...", // optional, for pagination
});

Transaction status

deposit(), transfer(), and withdraw() return a TransactionHandle with txId, status, txHash, and wait(). status is the backend processing state. The wait result also includes confirmationStatus, the user-facing lifecycle state. Public lifecycle states:

pending: preparing, proving, or waiting for an on-chain hash.
relayed: submitted on chain, but private effects are not observed yet.
confirmed: receipt or indexed evidence has observed the transaction effects, and those effects are visible to API reads.
processed: durable state persistence has completed.
failed: terminal failure.

By default, wait() resolves at user-facing confirmation (confirmed, processed, or failed). It does not wait for durable canonical processing unless you ask for it.

const tx = await client.transfer({ recipientAddress, token, amount });
const confirmed = await tx.wait({
  intervalMs: 2000, // optional, default 2s
  timeoutMs: 60000, // optional, default 60s
  signal: ac.signal, // optional AbortSignal
  onStatus: (s) => log(s), // optional progress callback
});

console.log(confirmed.confirmationStatus); // "confirmed" | "processed" | "failed"

The API now reports usability as usable: true once every private output the transaction creates is a spendable, owner-attributed note. It replaces funds_usable, which was only ever true for deposit owners and transfer recipients — never for a transfer’s sender holding the change note, and never for a withdrawal. The SDK’s fundsUsable is not yet wired to it and currently falls back to status === "processed", so it reads false during the confirmed window. Wait on processed rather than branching on it.

Wait for durable canonical processing when a backend reliability check needs finality:

const finalized = await tx.wait({ until: "finalized" });
console.log(finalized.confirmationStatus); // "processed" | "failed"

finalized is an alias for backend processed, which is reached at the configured canonical boundary. If you already have a transaction ID, poll directly:

const result = await client.pollTransactionStatus(txId, {
  until: "confirmed", // optional; default. Use "processed" or "finalized" for durability.
  intervalMs: 2000,
  timeoutMs: 60000,
  signal: ac.signal,
});

Polling throws TimeoutError if the timeout elapses before the selected wait target. See Error handling.

Backend reads

Use admin reads for backend dashboards and support tooling, and the user client for signed actions.

const user = await admin.users.get({ address: unlinkAddress });

const { balances } = await admin.users.getBalances({
  address: unlinkAddress,
});

const { transactions } = await admin.users.getTransactions({
  address: unlinkAddress,
  type: "transfer",
  status: "processed",
  limit: 20,
});

const auth = await admin.authorizationTokens.issue({
  unlinkAddress,
  expiresInSeconds: 900,
});

Call admin.users.register(payload) from your backend when a browser or server client registers. See Custody models for how the admin client is wired.

Get Started

Concepts

Build

Reference

Tutorial

Reading data and status

Read balances

Read transactions

Transaction status

Backend reads

​Read balances

​Read transactions

​Transaction status

​Backend reads

Read balances

Read transactions

Transaction status

Backend reads