Skip to main content

Wallet & funding

The proxy needs one funded Algorand wallet to operate — it signs every request's escrow payment from that wallet, automatically, with no prompt per request. This page covers getting a wallet in place, funding it, and the small reserve it keeps on top of your spendable balance.

The wallet​

zs-proxy wallet show       # address, network, and where it's stored
zs-proxy wallet address    # bare address only (scriptable)
zs-proxy wallet new        # generate a fresh 24-word wallet
zs-proxy wallet import     # import a 24-word (or 25-word Algorand) recovery phrase
zs-proxy wallet login      # sign in with your browser to pull in the chat app's wallet
zs-proxy wallet export     # reveal the recovery phrase (guarded)
zs-proxy wallet opt-in     # opt the account in to USDC

If you run zs-proxy proxy start with no wallet configured yet, it prompts you for one of these the first time — see Quick start. Three ways to get a wallet, in order of how likely you are to want them:

  • wallet login opens your browser to sign in to the chat app with your passkey and brings the wallet across with nothing to copy or paste. Use --no-browser over SSH/headless to get a URL to open elsewhere instead.
  • wallet import takes the 24-word phrase from Settings → Recovery in the chat app (see Recovery), or a 25-word classic Algorand mnemonic. Pipe it in with --stdin or --file to avoid an interactive paste; --yes skips the address-match confirmation.
  • wallet new generates a brand-new 24-word wallet, importable back into the chat app if you ever want to. Good for a dedicated dev or agent account you want to fund and budget independently of your main one.

All three accept --network (default the build's configured network) and --force to replace an existing wallet for that network.

warning

wallet export reveals your recovery phrase — anyone with it controls the wallet and the funds in it. Treat it like a password: write it down offline, never paste it anywhere else. See Recovery.

Where the wallet lives​

A signed release (the binary you get from Homebrew or Scoop) stores the wallet in your OS's secure keychain — macOS Keychain, Windows Credential Manager, or the Linux Secret Service — so nothing is unlocked without your session already being unlocked. A build from source falls back to an encrypted file instead (the storage backend is baked in at build time; ZEROSIGNAL_KEYRING_BACKEND overrides it at runtime).

Funding​

zs-proxy fund               # deposit address + QR code
zs-proxy fund --wait        # also poll until the ALGO arrives, then opt in to USDC
zs-proxy status             # wallet, balance, and funding status at a glance
zs-proxy doctor             # diagnose config → wallet → chain → funding → port, end to end

This is the same funding mechanism as the chat app's Funding panel — a balance held as dollars (USDC on Algorand) that whatever you deposit converts into automatically. fund is just the CLI door into it: it prints the deposit address and a QR code, so you can send from any wallet or exchange. Run with --wait (or re-run fund once the ALGO arrives) to complete the USDC opt-in.

If a request ever fails with 402 wallet_unfunded, this is the fix — your wallet doesn't have enough to cover the request (and the small reserve below).

The prepaid ticket pool​

Every paid request opens a small on-chain escrow box, and that box needs a minimum-balance reserve (≈0.115 ALGO, fully recoverable) the way every Algorand box does. Rather than fund that reserve on every single request, the proxy keeps a small prepaid pool sized for several requests in flight at once (10 slots — about 1.15 ALGO — by default; see zs.concurrent_slots), and draws each ticket's reserve from it instead.

You don't have to think about this in normal use — the pool is established automatically the first time you serve a request, and topped up by zs-proxy fund. It's fully recoverable:

zs-proxy slots              # show the pool: target, what it backs, what's in use
zs-proxy slots 25           # resize it — sets the config and funds/reclaims to match
zs-proxy withdraw 0.5       # reclaim ALGO from the pool back to your wallet (whole ALGO, e.g. 0.5)
zs-proxy close-deposit      # close the pool entirely, refunding the full remaining balance

slots is the one to reach for when you want more requests running at once — see Concurrency slots. withdraw is the manual form, for reclaiming ALGO without changing your target.

withdraw only pulls out the unreserved portion — ALGO not currently backing a request in flight — and the contract rejects asking for more than that. close-deposit refunds everything (plus the one-time opt-in reserve) and opts the wallet back out, so only run it once nothing is in flight.

What's next​

  • Configuration — concurrent_slots, spend caps, and network selection.
  • Quick start — the full install-to-first-request path.
  • Recovery — how the recovery phrase you import/export here also works in the chat app and in other Algorand wallets.