Configuration

Files pay reads on every invocation — pay.toml, accounts.yml, and the PAY_* environment variables.

pay reads three sources, in this order of precedence:

Explicit flags (--sandbox, --account, …)
PAY_* environment variables
pay.toml (looked up via $PAY_CONFIG, then ./pay.toml, then ~/.config/pay/pay.toml)
Built-in defaults

Accounts live separately in ~/.config/pay/accounts.yml. That file is mandatory once you have a non-ephemeral wallet.

`~/.config/pay/accounts.yml`

The on-disk registry of wallets, grouped by network. Schema version 2:

version: 2
accounts:
  mainnet:
    default:
      keystore: apple-keychain # apple-keychain | gnome-keyring | windows-hello | file | ephemeral
      active: true # used when multiple accounts share a network
      auth_required: true # mainnet defaults to true; sandbox defaults to false
      pubkey: 96WoyH3JmANSMsQLGC3MKyiGiXCymZyM9SLaWjcRrKuD
  localnet:
    sandbox-abc123:
      keystore: ephemeral
      pubkey: 5jSk… # base58
      secret_key_b58: 4xZ… # only for keystore: ephemeral
      created_at: 2026-05-02T17:21:03Z

Field	Required	Description
`keystore`	yes	Where the secret key lives. `apple-keychain`, `gnome-keyring`, `windows-hello`, `file`, or `ephemeral`.
`active`	no	Which account to use when multiple accounts share a network. If no account is marked `active`, pay falls back to the first alphabetically.
`auth_required`	no	Require an OS prompt before signing. `true` by default on mainnet, `false` on sandbox/localnet.
`pubkey`	yes	Cached base58 public key.
`path`	only `file`	Path to the JSON key file on disk.
`secret_key_b58`	only `ephemeral`	Inline base58 secret. Used for sandbox-generated wallets.
`created_at`	only `ephemeral`	RFC 3339 timestamp.
`subscriptions`	no	Map of subscription IDs to local subscription state, written by `pay subscriptions`.

Keystore backends

Backend	Platform	Notes
`apple-keychain`	macOS	Default on macOS. Stored in the user's login keychain.
`gnome-keyring`	Linux	Default on Linux when the Secret Service is available.
`windows-hello`	Windows	Default on Windows.
`file`	any	Plain JSON key file at `path`. Use only when secure storage isn't available.
`ephemeral`	sandbox only	Auto-generated by `--sandbox` calls and persisted under `localnet:`.

`~/.config/pay/pay.toml`

Optional defaults applied to every invocation. All keys are optional.

auto_pay   = false                                  # auto-satisfy 402 challenges
keypair    = "~/.config/solana/id.json"             # legacy keypair for non-payment commands
rpc_url    = "https://api.mainnet-beta.solana.com"  # RPC override
log_format = "text"                                 # text | json

Key	Type	Default	Description
`auto_pay`	bool	`false`	Automatically satisfy HTTP 402 challenges without prompting.
`keypair`	string	—	Path to a Solana keypair file, for commands that read pay.toml directly.
`rpc_url`	string	—	Mainnet RPC override. Subordinate to `--sandbox`/`--local`/`--mainnet` and to `PAY_RPC_URL`.
`log_format`	string	`"text"`	`"text"` or `"json"`.

Discovery order: $PAY_CONFIG, then ./pay.toml, then ~/.config/pay/pay.toml. Any PAY_* environment variable wins over the file.

Environment variables

See Global flags → Environment variables for the full table. The two you reach for most:

Variable	What it does
`PAY_ACTIVE_ACCOUNT`	Force a named account, overriding `active: true` in `accounts.yml`.
`NO_DNA`	Mark the caller as an AI agent: enables auto-pay and JSON-shaped output.

~/.config/pay/accounts.yml

Keystore backends

~/.config/pay/pay.toml

Environment variables

On this page

`~/.config/pay/accounts.yml`

`~/.config/pay/pay.toml`