Arkenaarkena/docs

Arkena Docs

Read account state

What you can read directly from the provider, and what you fetch from the Arkena backend.

The provider exposes a small set of read methods for state the wallet already knows: which accounts the user has, which network they're on, and their native balances. For everything else — full activity, NFT ownership, swap intents, LP quotes — you fetch from the Arkena backend with a SIWC JWT.

This split is intentional. There's one source of truth for ledger state (the indexed backend), and the provider doesn't duplicate it.

  1. Read accounts

    Code
    const accounts: string[] = await provider.request({
  method: "canton_getAccounts",
});

    Currently always a single-element array (one primary account per origin). The plural shape exists so future multi-account support won't break clients that already wrote for it.

  2. Read network

    Code
    const network: "devnet" | "testnet" | "mainnet" = await provider.request({
  method: "canton_getNetwork",
});

    The user picks the network in the extension's settings. Your dApp can only observe — it cannot request a switch programmatically. Display a prompt if the network isn't the one your backend supports.

  3. Read native balance

    Code
    const { cc, usdcx } = await provider.request({
  method: "canton_getBalance",
});

    Fast — the wallet caches balances locally. Fine for a first paint. For richer data (per-NFT counts, activity history), use the backend.

  4. Read full state from the backend

    Activity, NFT gallery, swap intents — all backend calls. Once you have a SIWC token:

    Code
    const { cc, usdcx } = await fetch(`/api/wallet/balance/${party}`, {
  headers: { Authorization: `Bearer ${jwt}` },
}).then((r) => r.json());

    The backend reads from the Participant Query Store (PQS) — its indexed view of the ledger — so this is fast.

    Same pattern for the user's NFTs, listings, swap history:

    Code
    await fetch(`/api/nft/owner/${party}`, {
  headers: { Authorization: `Bearer ${jwt}` },
});

await fetch(`/api/swap/history?taker=${party}`, {
  headers: { Authorization: `Bearer ${jwt}` },
});

    See REST API overview for the full surface.

Caching guidance

  • Provider state (accounts, network, balance) — cache for the life of the page. Refresh on the corresponding event (accountsChanged, networkChanged).
  • Backend reads (activity, NFT counts) — refetch on user-visible refresh signals: pull-to-refresh, periodic polling for active screens, or in response to txChanged events when you're awaiting a settlement.

The backend exposes the same data you'd get from the ledger directly, but indexed. There's no benefit to bypassing it.

What's next