Global flags
Flags that select network, account, automation, protocol, and debugger behavior — plus the environment variables that override defaults.
Global flags come before the subcommand. Precedence: explicit flags override environment variables, which override pay.toml, which overrides built-in defaults.
pay --sandbox curl <url>
pay --mainnet --account work curl <url>
pay --no-dna --sandbox curl <url>
pay --debugger claudeNetwork
--sandbox, --local, and --mainnet are mutually exclusive. With no network flag, pay reads the network from the 402 challenge advertisement.
| Flag | Short | What it does |
|---|---|---|
--sandbox | -s | Route to the hosted Surfpool localnet (https://402.surfnet.dev:8899) and auto-fund an ephemeral wallet on first use. Use this for everything except real spend. |
--local | — | Route to a local Surfpool at http://localhost:8899. Useful when developing the validator side. |
--mainnet | — | Force mainnet. Signs with the wallet bound to mainnet in accounts.yml. |
Default endpoints
| Network | RPC URL | Override |
|---|---|---|
| mainnet | https://api.mainnet-beta.solana.com | PAY_MAINNET_RPC_URL, pay.toml: rpc_url |
| sandbox | https://402.surfnet.dev:8899 | PAY_RPC_URL, or pass --local |
localnet (--local) | http://localhost:8899 | PAY_RPC_URL |
The sandbox host is a hosted Surfpool cluster that auto-funds ephemeral wallets on first use — no setup required for tests and examples.
Account
| Flag | Type | Description |
|---|---|---|
--account <NAME> | string | Use a named account from accounts.yml. In sandbox/local modes this selects a wallet within localnet; on mainnet it overrides active: true. |
Automation and logging
| Flag | Short | Description |
|---|---|---|
--no-dna | — | Mark the caller as automation. Forces JSON output and non-interactive defaults. Also set by the NO_DNA environment variable, and implicit when stdout is not a TTY. |
--verbose | -v | Show verbose tracing. Equivalent to RUST_LOG=pay=info,warn. |
When --no-dna is active, 402 challenges and payment events are emitted as structured JSON on stderr; the response body still lands on stdout, so pipelines work unchanged.
Protocol
| Flag | Description |
|---|---|
--x402 | Force the x402 payment protocol. Refuses MPP fallback. Conflicts with --mpp. |
--mpp | Force the MPP payment protocol. Refuses x402 fallback. Conflicts with --x402. |
Without either flag, pay negotiates from the 402 challenge advertisement.
Debugger
pay --debugger claude
pay --debugger curl <url>--debugger launches the Payment Debugger proxy on 0.0.0.0:1402. The PDB UI is served at http://127.0.0.1:1402/; MCP curl requests are routed through it (via PAY_DEBUGGER_PROXY) so every payment exchange is captured and replayable.
Environment variables
| Variable | Purpose | Default |
|---|---|---|
PAY_API_URL | pay-api host (stablecoin balances, onramp). | https://api.gateway-402.com |
PAY_ONRAMP_HOST | Browser onramp host. Hits <host>/onramp, which redirects to MoonPay with the server-side API key. | https://api.gateway-402.com |
PAY_RPC_URL | Solana RPC URL used by the payment client. Set by --sandbox/--local; otherwise read from the challenge or pay.toml. | challenge-driven |
PAY_MAINNET_RPC_URL | Mainnet RPC override for balance queries. | https://api.mainnet-beta.solana.com |
PAY_NETWORK_ENFORCED | Set internally by --sandbox/--mainnet/--local so the MCP curl tool inherits the override. | unset |
PAY_PROTOCOL_ENFORCED | Set internally by --x402/--mpp. | unset |
PAY_ACTIVE_ACCOUNT | Force a specific account name (overrides active: true in accounts.yml). | resolved from accounts.yml |
PAY_CONFIG | Path to a pay.toml config file. | ./pay.toml, then ~/.config/pay/pay.toml |
PAY_DEBUGGER_PROXY | Proxy URL injected into the MCP curl tool. Set by --debugger. | unset |
PAY_API_FEE_PAYER | Fee-payer override for gateway-routed subscription cancellations. | unset |
PAY_ENV | Deployment environment label for telemetry. | unset |
NO_DNA | When set, marks the caller as an AI agent: enables auto-pay and JSON output. | unset |
RUST_LOG | Tracing filter. --verbose sets pay=info,warn; otherwise warn. | warn |
Hidden flags
Two flags exist but are hidden from --help because they're experimental safety gates. Use only when you understand the trade-off.
| Flag | What it does |
|---|---|
--yolo-upto <microunits> | Automatically satisfy 402 challenges up to this stablecoin micro-units cap, without prompting. Subscription currencies that aren't priced against stablecoins still prompt. |
--dev | Alias for --sandbox. Retained for compatibility. |
The flags will likely change shape; don't put them in CI scripts.