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
agentpay wallet --jsonIf 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:
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:
agentpay admin setupThe command prompts locally for the vault password when needed. Keep that step local. Do not paste the vault password into chat or shared logs.
The daemon locks out admin authentication after 5 consecutive failed attempts for 30 seconds. If you hit the lockout, wait before retrying.
For non-interactive environments (CI, automation), use --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
--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 <name>
Set the active network during setup
--restore-wallet-from <path>
Restore from an encrypted offline backup
--backup-output <path>
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:
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 exactlyOVERWRITEType 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.
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 <backup.json> instead of resetting. Treat the vault password and the backup as the master recovery credentials.
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:
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 <path>. Otherwise export one afterward with agentpay admin wallet-backup export --output <path>.
For non-interactive backup creation during setup:
Verify a backup
Verify that a backup file is intact and the password is correct:
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:
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.
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.
Example host request
If you are using a host with the skill pack installed, a good first request is:
After setup, continue directly to Funding.
Last updated