Accounts
pay topup, account, setup, send, and subscriptions — manage wallets, fund them, send stablecoins, and track MPP subscriptions.
Account commands manage the local wallets in ~/.config/pay/accounts.yml, fund them, send stablecoins, and track active MPP subscription delegations.
| Command | One-liner |
|---|---|
topup | Fund an account from PayPal, Venmo, Apple Pay, or a mobile wallet. |
account | New / import / list / default / remove / export wallets. |
setup | Generate a keypair, store it, and run the funding flow. |
send | Send stablecoins to a recipient. |
subscriptions | Manage MPP subscription delegations. |
send, account remove, account export, and subscriptions cancel move funds or destroy local state. Treat them
as high-intent — don't run them on a user's behalf without explicit confirmation.
pay setup
Generate a keypair, store it in the OS secure store, and install MCP configs for any detected agent (Claude Code, Cursor, Codex). Ends by launching the topup flow so you can fund the new account immediately.
pay setup
pay setup --force # replace an existing account
pay setup --backend keychain # macOS (default)
pay setup --backend gnome-keyring # Linux (default)
pay setup --backend windows-hello # Windows (default)
pay setup --update # refresh MCP config only — no new account| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | Replace an existing account on the current network. |
--backend | enum | OS default | Storage backend: keychain (macOS), gnome-keyring (Linux), windows-hello (Windows). |
--update | bool | false | Reinstall MCP configs and the agent skill without creating a new account. |
--account | string | derived | Account name. When omitted, pay derives it from $USER / $USERNAME / whoami, sanitized, with default as the final fallback. |
After funds arrive, pay setup prints Setup complete with the received amount and a transaction link. Press Esc to skip funding; pay setup prints Setup aborted with the pay topup command to run later. Sandbox calls work regardless — they generate ephemeral wallets on first use.
pay topup
Fund an account on mainnet (or localnet with --sandbox). Opens an interactive TUI with two paths.
pay topup
pay topup --account <pubkey>
pay topup --sandbox # localnet account instead of mainnet| Flag | Type | Description |
|---|---|---|
--account | string | Account address to receive funds. Defaults to the active mainnet account. |
--sandbox | bool | Fund the sandbox (localnet) account instead of mainnet. |
| Path | What happens |
|---|---|
| Mobile wallet | Renders a Solana Pay QR encoding solana:<pubkey>?amount=<n>&spl-token=<USDC mint>. Scan from Phantom, Solflare, Backpack, etc. |
| Buy stablecoins | Press Enter to open the gateway /onramp redirect in your browser. Pick PayPal, Venmo, or Apple Pay; the gateway hands off to MoonPay with a server-side API key. |
The TUI polls the wallet's stablecoin balance every second (after a 5-second startup delay) for up to 5 minutes. When the balance increases, the success animation fires and the command exits. After 5 minutes idle, polling halts and a yellow ▲ idle 5m — press R to refresh banner appears; press R to restart the cycle.
Override the onramp host or pay-api host via environment variables.
pay whoami
See Pass-through → pay whoami. It's grouped under pass-through because it mirrors the Unix whoami shape, but it inspects the active pay account.
pay account
Manage accounts. With no subcommand, lists accounts and prints the available subcommands. Alias: accounts.
pay account
pay account new work
pay account import work ./keypair.json
pay account list
pay account default work
pay account export work
pay account remove work| Subcommand | Aliases | Purpose |
|---|---|---|
new <NAME> | — | Create a new account. |
import <NAME> <FILE> | — | Import from a JSON key file. |
list | ls | List accounts with balances. |
default <NAME> | — | Set the default account. |
remove <NAME> | rm, destroy | Permanently delete an account. |
export <NAME> [PATH] | backup | Export to a JSON key file. |
pay account new
pay account new work
pay account new work --backend keychain --force| Flag | Type | Description |
|---|---|---|
<NAME> | positional | Account name. Required. |
--backend | enum | keychain, gnome-keyring, or windows-hello. Defaults to OS native. |
--force | bool | Replace an existing account with the same name. |
pay account import
pay account import imported ./keypair.json| Flag | Type | Description |
|---|---|---|
<NAME> | positional | Account name. Required. |
<FILE> | positional | Path to the JSON key file. Required. |
--backend | enum | keychain, gnome-keyring, or windows-hello. |
pay account list
pay account list
pay accounts lsLists every registered account with its non-zero stablecoin balances. Use pay --no-dna account list for machine-readable output.
pay account default
Update the default account.
pay account default work| Flag | Type | Description |
|---|---|---|
<NAME> | positional | Account name to make the default. Required. |
pay account remove
Permanently delete an account and its secret key. Aliases: rm, destroy.
pay account remove work
pay account remove sandbox-abc123 --sandbox --yes| Flag | Type | Description |
|---|---|---|
<NAME> | positional | Account name. Required. |
--sandbox | bool | Remove from localnet instead of mainnet. |
--yes | bool | Skip the confirmation prompt. |
pay account export
Export an account to a JSON key file. Alias: backup.
pay account export work
pay account export work ./work-backup.json
pay account export work - # stdout| Flag | Type | Description |
|---|---|---|
<NAME> | positional | Account name. Required. |
[PATH] | positional | Output file path, or - for stdout. Defaults to ./pay-account-<name>-<pubkey>.json. |
pay send
Send stablecoins to a recipient address or a configured account name. max sends the entire selected stablecoin balance. Alias: push.
pay send 1.25 <recipient>
pay send 1 <recipient> --currency USDC
pay send max <recipient> --currency USDT
pay send 1 <recipient> --memo invoice-123
pay send 1 <recipient> --memo-hex 48656c6c6f
pay send 1 <recipient> --fee-within| Flag | Type | Description |
|---|---|---|
<AMOUNT> | positional | Decimal amount, or max. Required. |
<RECIPIENT> | positional | Base58 pubkey or account name. Required. |
--currency | string | Stablecoin symbol. When omitted, pay picks an eligible balance or prompts when multiple can pay. |
--memo | string | Optional memo. Max 566 bytes. Mutually exclusive with --memo-hex. |
--memo-hex | hex | Hex-encoded UTF-8 memo. Must decode to valid UTF-8. |
--fee-within | bool | Take the fee-payer refund out of AMOUNT instead of adding on top. Implied when AMOUNT is max. |
Non-interactive callers should pass --currency explicitly — otherwise pay prompts when multiple stablecoin balances could fund the transfer.
pay subscriptions
Manage MPP subscription-intent delegations. With no subcommand, lists all subscriptions and prints the available verbs. Aliases: subscription, subs.
pay subscriptions # default = list + help
pay subscriptions list --network mainnet
pay subscriptions status <id>
pay subscriptions new --plan <pda> --mint <mint> --puller <pubkey> --recipient <wallet> --amount 1000000 --period 30d
pay subscriptions cancel <id>
pay subscriptions refresh| Subcommand | Purpose |
|---|---|
list | List subscriptions across every account, or filter. |
status | Show detail for one subscription by base58 ID. |
new | Activate a new subscription against an on-chain Plan PDA. |
cancel | Cancel a subscription. |
refresh | Backfill missing on-chain data on local entries. |
pay subscriptions list
pay subscriptions list
pay subscriptions list --account work
pay subscriptions list --network devnet --json| Flag | Type | Description |
|---|---|---|
--account | string | Filter to a single account name. |
--network | string | Filter to a single network slug (mainnet, devnet, …). |
--json | bool | Emit JSON instead of a table. |
pay subscriptions status
Show detail for a single subscription by its base58 subscription_id.
pay subscriptions status 4xZ…
pay subscriptions status 4xZ… --json| Flag | Type | Description |
|---|---|---|
<SUBSCRIPTION_ID> | positional | Base58 subscription_id (the SubscriptionDelegation PDA from the Payment-Receipt header). Required. |
--json | bool | Emit JSON instead of the formatted view. |
pay subscriptions new
Activate a new subscription against an explicit on-chain Plan PDA. Every required flag corresponds to a field the on-chain program checks.
pay subscriptions new \
--plan PLAN_PDA_BASE58 \
--mint USDC_MINT_BASE58 \
--puller SERVER_PULLER_BASE58 \
--recipient WALLET_BASE58 \
--amount 1000000 \
--period 30d| Flag | Type | Required | Description |
|---|---|---|---|
--plan | base58 | yes | On-chain Plan PDA — the spec's required externalId. |
--mint | base58 | yes | SPL Token or Token-2022 mint. |
--puller | base58 | yes | Server puller pubkey. Must be plan.owner or in plan.pullers. |
--recipient | base58 | yes | Recipient wallet bound to the activation transaction. Must be authorized by plan.destinations. |
--amount | base units | yes | Per-period charge in mint base units (decimal string). |
--period | duration | yes | Billing period (e.g. 30d, 2w). month is rejected per the Solana subscription profile. |
--description | string | no | Optional human-readable label echoed into the local record. |
--network | string | no | Solana network slug (mainnet, devnet, localnet, sandbox). |
--account | string | no | Specific account name within the resolved network. |
--rpc-url | URL | no | RPC URL override. |
--fee-payer-key | base58 | no | Fee-payer pubkey when the server is sponsoring fees. |
pay subscriptions cancel
Cancel a subscription by base58 ID.
pay subscriptions cancel 4xZ…
pay subscriptions cancel 4xZ… --local-only
pay subscriptions cancel 4xZ… --via-gateway https://pay-api.gateway-402.com| Flag | Type | Description |
|---|---|---|
<SUBSCRIPTION_ID> | positional | Base58 subscription_id. Required. |
--local-only | bool | Skip the on-chain cancel tx; only flip the local entry to cancelled. Use when the on-chain side was already cancelled out of band. |
--via-gateway | URL | Force routing through the pay-api gateway, even when the subscriber has enough SOL for a direct broadcast. Auto-routed via $PAY_API_URL when the subscriber's SOL balance is below the per-tx threshold. |
--gateway-fee-payer | base58 | Gateway operator pubkey that signs as fee-payer. Required when routing via the gateway. Defaults to $PAY_API_FEE_PAYER. |
--rpc-url | URL | RPC URL override. Defaults to $PAY_RPC_URL, else the canonical public RPC for the subscription's network. |
pay subscriptions refresh
Backfill missing on-chain data (e.g. activation_signature) on local entries.
pay subscriptions refresh
pay subscriptions refresh --account work --network mainnet| Flag | Type | Description |
|---|---|---|
--account | string | Filter to a single account name. |
--network | string | Filter to a single network slug. |
--rpc-url | URL | Override the lookup RPC. Falls back to the canonical RPC for the subscription's network. |