For the complete documentation index, see llms.txt. This page is also available as Markdown.

Wallet Modes

The Doma CLI signs writes in one of two modes. The mode you pick determines what holds the signing authority, what scope it has, and how revocable it is.

The two modes

Mode
Signs via
Setup
Spend authority

agent (Privy delegated)

Doma launchpad → Privy delegated signer

doma auth login (browser consent)

USD-capped, scoped to Doma chains

private-key (default)

Local raw key in ~/.doma/config.json or env

export DOMA_PRIVATE_KEY=0x…

Unbounded, limited only by wallet balance

Both modes are first-class. The transactional flow is byte-identical; only the authentication setup and revocation story differ.

Which mode should I pick?

Find your situation in the table:

Situation
Pick

CI, cron, or any non-interactive run

private-key

Need a USD spend cap or infra-enforced chain allowlist

agent

Personal dev box, want hands-off browser consent

agent

Personal dev box, prefer a dedicated test wallet

private-key

Production server with a secrets manager

private-key

Already use Doma in your browser, want one-command auth

agent

When in doubt: start with private-key on testnet, switch to agent for any wallet that holds value worth protecting.

Setting up agent mode

Requires Doma CLI ≥ 0.5.0. The CLI runtime-detects support via doma auth --help (older versions return non-zero).

Agent mode is supported on both Doma Mainnet (chain 97477) and Doma Testnet (chain 97476). The active network is whichever your config / --testnet flag selects; doma auth login mints a session for that network. To use both networks, run doma auth login once per network.

The CLI prints a localhost URL. Open it in your browser. You'll see a Privy-hosted consent screen. Review the wallet being authorized, the allowed chains and RPC methods, and the spend ceiling (default $200 USD), then confirm. Once approved, the CLI prints Authorized. and writes a session JWT to ~/.doma/credentials.json (mode 0600).

Persist the choice so future commands use agent mode by default:

The browser consent screen is the actual authorization moment. The CLI does not prompt again. If you change your mind, click Cancel in the browser and the session is never minted.

Setting up private-key mode

Set the key as an environment variable in your shell:

Or persist it via the CLI (macOS uses Keychain by default, see Install & Configure):

Then mark the mode explicitly (this is the default, but explicit beats implicit):

Switching modes

The CLI uses whichever mode is active at command time. Read commands (token, quote, balance) work in either mode without auth.

Revoking an agent session

This calls Privy to detach the agent's authorization key from your wallet, deletes ~/.doma/credentials.json, and clears walletMode. Future writes require a fresh doma auth login.

You can also revoke from the launchpad's "Authorized agents" panel at any time. Useful if your machine is lost.

Checking session status

Output:

Trade-offs at a glance

agent

private-key

Key on disk

No (Privy HSM)

Yes

Spend cap

Hard-enforced ($200 default)

None

Chain allowlist

Doma chains only

All chains

Revoke from another machine

Yes (launchpad UI)

Need to rotate the key

Works in CI / non-interactive

No (needs browser consent)

Yes

Available since

CLI 0.5.0

All versions

What's next

  • Commands: full reference of what the CLI can do.

  • Agentic Wallet: deeper architectural look at the Privy delegated signer.

Last updated