Accounts and wallets

pay stores wallet keys in the OS secure store wherever possible. Mainnet signing should remain user-authorized unless the user explicitly chooses an automation path such as --no-dna, NO_DNA, or a deliberate auto_pay config.

Agent summary

• Do not create, replace, export, or delete accounts unless the user asked.
• Prefer sandbox mode for tests — it uses an ephemeral local account.
• Use pay account list (or pay whoami) before assuming which mainnet account exists.
• Payment-bearing commands trigger pay setup automatically on a fresh install — see Auto-setup.

Setup

pay setup
pay account list
pay topup

Supported secure storage: macOS Keychain, GNOME Secret Service (Linux), Credential Manager (Windows), and 1Password. Pick the backend explicitly with pay setup --backend <name> if needed; otherwise pay uses the OS default.

pay topup opens an interactive TUI offering two paths: scan a Solana Pay QR from a mobile wallet, or onramp via PayPal/Venmo/Apple Pay through the gateway. See Account commands → pay topup for the full flow.

You do not need to fund a mainnet wallet for sandbox examples — sandbox mode creates and funds an ephemeral local account on demand.

Auto-setup on first use

A payment-bearing command (pay claude, pay curl, pay topup, pay send, …) on a fresh install with no mainnet account triggers the setup wizard automatically before the requested command runs. Sandbox and local paths skip this — they generate ephemeral wallets on first use. Full list and exact prompts: see Install.

Account management

pay account new --name work
pay account import ./keypair.json --name imported
pay account default work
pay account export --name work
pay account remove work

Use --account <name> with top-level pay commands to select a named account.

Where accounts live

Account metadata is stored in ~/.config/pay/accounts.yml (schema version 2). The actual private key is held in the OS secure store; only the public key, network, and backend metadata are written to the YAML file. See Configuration → accounts.yml for the full schema.