# Set up or reuse a wallet All wallets created by AgentPay SDK are **non-custodial**. Private keys are generated and stored on the operator's machine. Signing and broadcast happen locally. WLFI does not host, custody, or have access to any wallet or private key. Throughout this documentation, "wallet" always refers to this non-custodial, operator-controlled wallet. Before creating a new wallet, check whether this machine already has one you can reuse. ## Check for an existing wallet ```bash agentpay wallet --json ``` * If the command succeeds, the machine already has a wallet profile that can be reused. * If it fails because wallet metadata is unavailable, move to the first-time setup path below. Do not guess based on files alone - this is the supported reuse check. Key fields in the output: | Field | Purpose | | ------------------------------ | --------------------------------------- | | `address` | Wallet address - use this for funding | | `policyAttachment` | `AllPolicies` or a specific `PolicySet` | | `attachedPolicyIds` | Active policy IDs | | `balances[].balance.formatted` | Human-readable balance per token/chain | ## Run first-time setup Use: ```bash agentpay admin setup ``` The command prompts locally for the vault password when needed. Keep that step local. Do not paste the vault password into chat or shared logs. {% hint style="warning" %} The daemon locks out admin authentication after 5 consecutive failed attempts for 30 seconds. If you hit the lockout, wait before retrying. {% endhint %} For non-interactive environments (CI, automation), use `--vault-password-stdin`: ```bash echo "$VAULT_PASSWORD" | agentpay admin setup --vault-password-stdin ``` The `--vault-password` inline flag and `AGENTPAY_VAULT_PASSWORD` environment variable are blocked for security. The CLI will reject them with an error. Use `--vault-password-stdin` or a local TTY prompt instead. Because setup installs or refreshes a root-managed local daemon, it can also require local machine authorization during the setup flow. ### Notable setup flags | Flag | Purpose | | ------------------------------ | ------------------------------------------------------------------ | | `--plan` | Dry-run preview - shows what setup would do without making changes | | `--yes` / `-y` | Skip the interactive confirmation prompt | | `--reuse-existing-wallet` | Reattach the current local vault instead of creating a new wallet | | `--vault-password-stdin` | Read the vault password from stdin (CI / automation) | | `--network ` | Set the active network during setup | | `--restore-wallet-from ` | Restore from an encrypted offline backup | | `--backup-output ` | Create an encrypted wallet backup after setup | | `--non-interactive` | Disable all interactive prompts (CI) | The full list includes policy flags (`--per-tx-max-wei`, `--daily-max-wei`, `--weekly-max-wei`, etc.), token/recipient registration, and advanced gas controls. Run `agentpay admin setup --help` for the complete reference. ## What setup creates `agentpay admin setup` is the supported first-run path. It: * stores the vault password securely * installs or refreshes the managed local daemon * waits for the daemon to become ready * creates the vault key and agent key * imports agent auth material into macOS Keychain * prints the wallet address and related identifiers A typical successful run ends with values like: ``` setup complete address: 0x... vault key id: ... agent key id: ... daemon socket: /Library/AgentPay/run/daemon.sock state file: /var/db/agentpay/daemon-state.enc chain: bsc agent auth token: stored in macOS Keychain keychain service: agentpay-agent-auth-token ``` If you rerun setup on a machine that already has wallet metadata, the CLI can ask for confirmation before overwriting the current wallet attachment. Without `--yes`, setup prompts: * `Type OVERWRITE to replace the current wallet:` - you must type exactly `OVERWRITE` * `Type REUSE to reattach the current local vault:` - when using `--reuse-existing-wallet` Use `--plan` for a dry-run preview that shows what setup would do without making changes. {% hint style="warning" %} **Vault password recovery.** If you forget the vault password and do not have a valid encrypted offline backup, there is no recovery path for the existing encrypted daemon state. The only option is `agentpay admin reset`, which discards the current wallet and allows you to create a new one. If you do have a backup, use `agentpay admin setup --restore-wallet-from ` instead of resetting. Treat the vault password and the backup as the master recovery credentials. {% endhint %} ## Wallet backup and restore The SDK supports encrypted offline wallet backups. A backup captures the wallet private key and metadata in an encrypted file protected by a separate backup password. The backup file uses **scrypt** key derivation + **AES-256-GCM** authenticated encryption, written with mode `0600` (owner-only). The outer JSON contains public wallet metadata for identification; the private key is inside the encrypted ciphertext. ### Create a backup After first-time setup, create an encrypted backup: ```bash agentpay admin wallet-backup export --output ~/agentpay-backups/backup.json ``` The CLI prompts for a backup password. Do not reuse the vault password for the backup. Store the backup file and password separately from the machine. Interactive first-time setup skips the offline backup wizard by default so the first-run path stays short. If you want a backup during setup, pass `--backup-output `. Otherwise export one afterward with `agentpay admin wallet-backup export --output `. For non-interactive backup creation during setup: ```bash agentpay admin setup --backup-output ~/agentpay-backups/backup.json --backup-password-stdin ``` ### Verify a backup Verify that a backup file is intact and the password is correct: ```bash agentpay admin wallet-backup verify ~/agentpay-backups/backup.json ``` Verification decrypts the backup and confirms the metadata matches without importing anything. ### Restore from a backup If the wallet is lost or you are setting up a new machine, restore from the backup: ```bash agentpay admin setup --restore-wallet-from ~/agentpay-backups/backup.json ``` The CLI prompts for both the backup password and the new vault password. The restored wallet retains the same address and key material as the original. {% hint style="info" %} Backup passwords are never accepted as inline flags or environment variables. The CLI rejects `--backup-password` and any environment variable form for security. Use a local TTY prompt or `--backup-password-stdin`. {% endhint %} ## Example host request If you are using a host with the skill pack installed, a good first request is: ``` Check whether this machine already has a crypto wallet. If not, guide me through setup and show me the wallet address when it is ready. ``` After setup, continue directly to [Funding](/agentpay-sdk/workflows/funding.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.worldlibertyfinancial.com/agentpay-sdk/workflows/wallet-setup.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.