Skip to main content

Wallet & funding

The proxy pays for every request from one funded Algorand wallet. It signs each payment automatically, without asking you each time.

For most people that wallet is the account they already use in the chat app, brought over with zs-proxy wallet login. That's the setup in the Quick start. This page covers everything else.

The wallet​

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

wallet export reveals your recovery phrase. Anyone who has it controls the wallet and the funds in it. Treat it like a password: write it down offline and never paste it anywhere else. See Recovery.

Where the wallet lives​

A signed release (the binary from Homebrew, Scoop, or the installer) creates the wallet in your OS's secure keychain: macOS Keychain, Windows Credential Manager, or the Linux Secret Service. It stays locked until your session is unlocked. A build from source creates it in an encrypted file instead, and asks for its passphrase; set ZEROSIGNAL_KEYSTORE_PASSPHRASE to supply it without a prompt.

The wallet stays where it was created: any later zs-proxy, or another ZeroSignal program on the same machine, opens it there. ZEROSIGNAL_KEYRING_BACKEND makes a program use a different backend, and zs-proxy wallet import --force with your own recovery phrase moves the wallet to that backend.

Other ways to set up your wallet​

The first time you run zs-proxy proxy start with no wallet, it asks:

No wallet found. Set one up for mainnet:
  [w] Web     — sign in to the zerosignal web app with your passkey (no paste)
                No account yet? Create one at https://zerosignal.ai first.
  [i] Import  — paste the 24-word phrase from the web app (Settings → Recovery)
  [n] New     — create a fresh wallet
Choose [W/i/n]:

Each choice is also a command you can run on its own at any time: Web is zs-proxy wallet login (the Quick start walks through it), and the other two are covered below.

The proxy never creates a wallet unless you ask it to. With no terminal to ask on (an OS service, a script, or piped input), it stops and lists these options instead of making an empty wallet.

No browser on this machine​

Over SSH or on a headless machine, have wallet login print the sign-in link instead of opening a browser:

zs-proxy wallet login --no-browser

The last step of the sign-in sends the wallet to a temporary listener on this machine's 127.0.0.1, on the port named in the printed URL (port=). A browser on another computer can only reach it through a forwarded port. While wallet login is waiting, open a second SSH session from that computer that forwards the port, then open the URL:

ssh -L <port>:127.0.0.1:<port> <host>

wallet login waits 3 minutes, so do the forward and the browser sign-in within that time, or run it again.

If you can't forward a port, use wallet import instead. The sign-in page itself offers a way to copy the phrase for that: Browser didn't redirect? Copy the phrase instead.

Import a recovery phrase​

zs-proxy wallet import

Paste the 24-word phrase from Settings → Recovery in the chat app (see Recovery), or a 25-word classic Algorand mnemonic. The paste is hidden and never touches your shell history. For scripts, pipe the phrase in with --stdin or point --file at it. At a terminal, the proxy shows the address the phrase derives and asks you to confirm it; --yes skips that question. With --stdin there's no terminal to ask on, so it doesn't ask.

A separate wallet for an agent​

zs-proxy wallet new
zs-proxy fund

wallet new generates a fresh, empty 24-word wallet, so an agent or a dev setup gets its own balance and budget, separate from your main account. Fund it with zs-proxy fund (see Funding). You can import its phrase into the chat app later.

The proxy holds one wallet per OS user. Run wallet new on a machine or user account set aside for the agent, not on one already signed in to your main account: there it refuses, and with --force it would replace your main account (see below). A mnemonic in the environment is the other way to give one process its own wallet.

Switch to a different account​

wallet login, wallet import, and wallet new refuse to replace a wallet that's already set up. Add --force to replace it. Back up the old phrase first with wallet export if it holds funds.

A running proxy loads its wallet once, at start, and keeps paying from the old one until it restarts. After switching, run zs-proxy proxy restart.

Servers and CI: a mnemonic in the environment​

On a server, in CI, or anywhere without a keychain, give the proxy its signer through the environment instead of the wallet commands:

  • Any variable ending in _MNEMONIC, for example PAYER_MNEMONIC="word1 word2 …". Either form works: the 24-word phrase from the chat app, or a 25-word Algorand mnemonic.
  • ZS_MNEMONIC_URLS, a comma-separated list of name=url pairs that fetch the mnemonic from AWS Secrets Manager (awssecretsmanager://), AWS Parameter Store (awsparamstore://), GCP Secret Manager (gcpsecretmanager://), Azure Key Vault (azurekeyvault://), or a local file (file:///path?decoder=string). Each uses its cloud's standard credentials.

With either one set, proxy start skips the wallet prompt entirely. Keep mnemonics out of config.yaml; it has no field for them. Four things to know:

  • Any variable ending in _MNEMONIC counts, including one you set for another Algorand tool (such as DEPLOYER_MNEMONIC). If the proxy ends up with more than one signer, from the environment or alongside a wallet set up with the commands above, it refuses to start until you set zs.proxy_payer_addr to the address that pays; see Configuration.
  • status, fund, slots, withdraw, and doctor read only a wallet set up with the wallet commands, so they don't work with an environment signer.
  • proxy install-service doesn't use an environment signer either, because a service doesn't inherit your shell's environment. To run the service on one, render the unit with zs-proxy proxy install-service --print and add the variable to it yourself.
  • An empty variable doesn't count.

Funding​

Your balance is USDC on Algorand, the same as in the chat app.

If the proxy uses your chat-app account, add funds in the chat app: a card, Apple Pay, Google Pay, or crypto, converted to dollars for you. See Funding. The proxy spends from that same balance.

For a wallet only the proxy uses, fund it from the terminal:

zs-proxy fund               # deposit address + QR code
zs-proxy fund --wait        # also wait 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

fund prints the deposit address and a QR code. Send ALGO and USDC to it from any Algorand wallet or exchange. Send about 2 ALGO first: it covers the account's own minimum balance, the USDC opt-in (an account has to opt in before it can hold USDC), and the prepaid pool. Then run fund --wait, or re-run fund once the ALGO lands, to finish the opt-in and fund the pool. Then send USDC.

A request that fails with 402 wallet_unfunded means your wallet doesn't have enough to cover the request plus the prepaid pool; 402 mbr_pool_underfunded means specifically that the pool needs more ALGO. Add funds, then check with zs-proxy status.

The prepaid ticket pool​

Every paid request opens a small on-chain escrow box. Like every Algorand box, it needs a minimum-balance reserve (≈0.115 ALGO, fully recoverable). Instead of funding that reserve on each request, the proxy draws it from a prepaid pool. The pool is sized for several requests in flight at once: 10 slots, about 1.15 ALGO, by default (see zs.concurrent_slots). The proxy sets it up on your first request, and zs-proxy fund tops it up. All of it is recoverable; these commands resize it or return its ALGO to your wallet:

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

To run more requests at once, use slots; see Concurrency slots. withdraw reclaims ALGO without changing your target. It takes only the unreserved portion, the ALGO not backing a request in flight; the contract rejects a larger amount. close-deposit refunds everything, plus the one-time opt-in reserve, and opts the wallet back out, so run it only when nothing is in flight.

When the proxy uses your chat-app account, this is the same pool the chat app uses: slots, withdraw, and close-deposit change it for both.

What's next​

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