# Install pay

> Install the pay CLI, verify the binary, and update agent integrations.

Install the CLI before running client, agent, or server flows. Payment-bearing commands (`pay claude`, `pay curl`, …) auto-run `pay setup` on a fresh machine, so the typical path is install → first command → guided setup → done.

| Resource    | Link                                                                            |
| ----------- | ------------------------------------------------------------------------------- |
| Source code | [solana-foundation/pay](https://github.com/solana-foundation/pay)               |
| Services    | [solana-foundation/pay-skills](https://github.com/solana-foundation/pay-skills) |
| x402 spec   | [x402.org](https://x402.org)                                                    |
| MPP spec    | [paymentauth.org](https://paymentauth.org)                                      |

## Agent summary

- Prefer Homebrew for normal local setup.
- Use `npx @solana/pay` for one-shot calls without a system install.
- Use `pay setup --update` when pay is installed but the agent MCP config needs refreshing.
- Do not create or replace a mainnet account unless the user asked for account setup.
- Use sandbox mode when the user only needs local testing.

## Install with Homebrew

```sh
brew install pay
pay --version
```

## Install via npm / one-shot via npx

```sh
npm install -g @solana/pay
pay --version
```

Or run any command without a global install:

```sh
npx @solana/pay --sandbox curl https://debugger.pay.sh/mpp/quote/AAPL
npx @solana/pay claude "buy me some flowers"
```

The npm package is a thin wrapper. On first invocation it downloads the right native binary for your platform and libc, caches it under `node_modules/@solana/pay/bin/`, and forwards every argument through. Subsequent runs skip the download and exec the cached binary directly.

## From source

```sh
git clone https://github.com/solana-foundation/pay.git
cd pay
just install pay
pay --version
```

## Wallet setup

```sh
pay setup
pay topup
```

`pay setup` creates a wallet in the OS secure store (macOS Keychain, GNOME Keyring, Windows Hello, or 1Password) and installs the MCP configuration for any detected agent. `pay topup` opens the funding TUI — pick `Top-up from Mobile wallet` to scan a Solana Pay QR, or `Buy stablecoins` to onramp via PayPal, Venmo, or Apple Pay.

You don't need to fund a mainnet wallet for sandbox examples. Sandbox mode generates and funds ephemeral local accounts automatically the first time you run a `--sandbox` command.

### Auto-setup on first run

When a payment-bearing command (`pay claude`, `pay curl`, `pay codex`, `pay topup`, `pay send`, `pay fetch`, `pay http`, `pay wget`) runs on a fresh install with no mainnet account, pay prints

```text
No pay account configured — running `pay setup` first…
```

then runs the setup wizard before executing the original command. Sandbox and local invocations skip this step — they generate ephemeral wallets on first use.

## Update agent config

```sh
pay setup --update
```

`pay setup --update` reinstalls MCP configuration and the agent skill without creating a new account.