> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unlink.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading data and status

> Read balances and transaction history, track transaction status, and use admin backend reads.

## Read balances

```ts theme={null}
const { balances } = await client.getBalances();
```

Filter by token:

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

## Read transactions

```ts theme={null}
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, and `fundsUsable`.

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.

```ts theme={null}
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"
console.log(confirmed.fundsUsable); // true when private effects are usable
```

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

```ts theme={null}
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:

```ts theme={null}
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](/errors).

## Backend reads

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

```ts theme={null}
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](/custody-models) for how the admin client
is wired.