rtClient.delegateWallet

A delegate wallet is a second wallet that belongs to the person, beside their main wallet. They name it in the protocol's rt-delegates registry, and from then on it may act for them in any product: it pays, and whatever it buys belongs to the person. A connected assistant spends from the delegate wallet and never from the main wallet, so what an assistant can reach is what the person put there. The SDK names it delegateWallet, as the routes do.

Every method runs on the person's own Privy session and takes the access token from usePrivy().getAccessToken(). An assistant's call is refused. Money only ever moves between the person's two wallets: rt-api resolves both addresses from the person's own records, so no method takes an address. Each write closes on broadcast and returns its transaction id.

Nothing is made until the server can sign for it. A delegate wallet has its own signing key on the server. While that key is not configured, open answers 503 and makes no wallet.

Methods

rtClient.delegateWallet.get(privyToken)

The delegate wallet and its balances, or delegateWallet: null when the person has none. status is CREATED (made, not yet named), NAMED (in the registry) or RESIGNED (ended by either side).

const { delegateWallet } = await rtClient.delegateWallet.get(token);
// delegate wallet?.balances.sats, delegate wallet?.balances.ustx: decimal strings of whole sats / microSTX

The two balances are separate and never added together. A balance that could not be read is null, never "0": show it as unknown, not as empty.

rtClient.delegateWallet.open(privyToken)

Makes the delegate wallet if the person has none, then has their main wallet name it in the registry. Returns the delegate wallet and the set-delegate transaction id, or txId: null when it was already named.

rtClient.delegateWallet.fundStx(privyToken, amountUstx) / fundSats(privyToken, amountSats)

Moves STX (in microSTX) or sats from the main wallet into the delegate wallet. The amount is a whole number, passed as a bigint, number or decimal string; the transaction is pinned to exactly that amount.

rtClient.delegateWallet.empty(privyToken)

Moves everything back to the main wallet: all the delegate wallet's sats, and its STX less the network fee. Returns what moved in each currency, with a transaction id for each leg. It answers 409 when the delegate wallet holds sats but no STX to pay the fee for moving them.

rtClient.delegateWallet.resign(privyToken)

Ends the delegation, so the delegate wallet can no longer act for the person. The delegate wallet signs the removal when it can pay the fee, and the main wallet when it cannot; by says which.

Errors

A person with no delegate wallet gets 409 with code: "NO_DELEGATE_WALLET" from every write except open. A person who signs in with their own wallet has no server-held wallet to make a delegate wallet beside, and gets 403.