Wallets and Balances

A member's wallet is their on chain account. In the default non-custodial configuration the member holds the key and XKOVA never sees the private material. The wallet is provisioned at first sign in, bound to the member's sign-in credential, and used to sign every transfer the member authorizes.

Member in-app wallets

Each member has an in-app wallet, typically a Thirdweb in-app wallet bound to the member's sign-in credential (a passkey, biometric, or social login, depending on how the tenant authenticates members). The wallet is the member's on chain account: it holds balances and signs the member's transfers. In the non-custodial model the key lives in the wallet and never leaves the member's control; XKOVA brokers the flows but never holds the key. See the Non-custodial Model for how a signed transfer reaches the chain.

The wallet provider and custody model are configured per tenant at onboarding. Non-custodial Thirdweb in-app wallets are the default; other vendors and custody arrangements plug in through the same seam. See Wallet Providers.

How a wallet is derived

A wallet is provisioned the first time a member signs in, through a short handshake between the member's browser and the wallet provider. The member never hands a key to XKOVA. The steps:

Challenge. XKOVA mints a short lived challenge token for the member.
Sign. The member's browser hands the challenge to the in-app wallet, which the member unlocks with their sign-in credential and which returns a member token.
Register. The browser sends the resulting wallet address back, and XKOVA records the address against the member.

The address is deterministic for a given member identity, so the same member resolves to the same wallet. Throughout this dance XKOVA sees only short lived tokens and the public address, never the sign-in credential or any private material.

Balances

A balance is the member's holding of a workspace token, maintained as a running total that XKOVA updates as it observes the wallet's on-chain activity and keeps in sync with the chain through continuous reconciliation (rather than fetching a live chain read on every request). Sandbox wallets hold Fuji testnet USDC, and production wallets hold mainnet USDC. Each balance entry carries a numeric chain_id that identifies the chain it lives on (one of the chains described in Supported Networks); the full embedded chain descriptor is carried on the wallet resource, not on individual balance rows.

The account holder behind the wallet

Every member wallet hangs off an account holder: the member record your backend provisions, either explicitly or just in time on the member's first sign in. The record carries far more than the wallet: self-service balances and bank sub-accounts, a contacts address book, policy consents, a right-to-access data export, an avatar, and the compliance hold and release actions. See Account Holders for the full surface.

What a wallet is used for

Signing transfers. The member signs payment and escrow intents in their wallet, and the XKOVA Relayer submits them. See Payments and Escrow and Claims.
Holding assets. The wallet holds the member's stablecoin balance and any tokens issued to it through XKOVA TAMS.

See Wallet Providers for the custodial and non-custodial vendors that plug in per tenant, and the interactive reference for the wallet and wallet derivation operations.

Was this helpful?