> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Privy Agent Wallet Sandbox

**The Privy Agent Wallet Sandbox gives agents a simple way to spin up, fund, and manage wallets without any integration work. Users track agent spending activity, manage funds, and stay in control at [agents.privy.io](https://agents.privy.io/).** The sandbox CLI (`@privy-io/agent-wallet-cli`) enables authentication, funding, and transactions directly from assistants like OpenClaw, Claude Code, and more.

> [!NOTE]
>
> The sandbox is built entirely on Privy. Its web app and CLI demonstrate the agent wallet
> experience your app can embed under its own brand: wallet creation, onramp funding, one-time
> browser approval with [Agent Authorization](https://docs.privy.io/agent-wallets/agent-authorization.md), activity
> tracking, and x402 and MPP payments. See [agent wallets](https://docs.privy.io/agent-wallets/overview.md) to build the
> same experience into your app.

## Getting started

> [tab] For humans
>
> **1. Visit the agent sandbox**
>
> Go to [agents.privy.io](https://agents.privy.io) to create an account, view wallets, and manage agent activity.
>
> **2. Install the CLI**
>
> Install the agent sandbox CLI globally:
>
> ```bash theme={"system"}
> npm install -g @privy-io/agent-wallet-cli
> ```
>
> Or run it directly with `npx`:
>
> ```bash theme={"system"}
> npx @privy-io/agent-wallet-cli login
> ```
>
> **3. Log in**
>
> Start the authentication flow. The CLI displays a verification URL and a short code, then waits for approval.
>
> ```bash theme={"system"}
> privy-agent-wallets login
> ```
>
> Open the URL in a browser and sign in to the agent sandbox. Enter the code shown in the terminal to approve agent access. The CLI automatically completes once approval is confirmed.
>
> **4. Fund wallets**
>
> Open the agent sandbox in a browser to add funds via onramp:
>
> ```bash theme={"system"}
> privy-agent-wallets fund
> ```
>
> The agent sandbox at [agents.privy.io](https://agents.privy.io) provides a visual interface to view balances, review transaction history, and onramp funds into the wallet.
>
> **5. View wallets**
>
> List the Ethereum and Solana wallet addresses linked to the session:
>
> ```bash theme={"system"}
> privy-agent-wallets list-wallets
> ```
>
> Output:
>
> ```
> Ethereum:  0x1a2b...3c4d  (wallet_id_xxx)
> Solana:    7hQ5p...mN9r   (wallet_id_yyy)
> ```
>
> **6. Send transactions**
>
> Use the `rpc` command to sign messages and send transactions. Pass the RPC body as JSON:
>
> ```bash theme={"system"}
> privy-agent-wallets rpc --json '{"method": "eth_sendTransaction", "params": {"to": "0xRecipient", "value": "0.01"}}'
> ```
>
> The body can also be piped from stdin:
>
> ```bash theme={"system"}
> echo '{"method": "personal_sign", "params": {"message": "hello"}}' | privy-agent-wallets rpc
> ```

> [tab] For agents
>
> ```
> Set up https://agents.privy.io/skill.md
> ```

## Supported RPC methods

### Ethereum

| Method | Description |
| - | - |
| `personal_sign` | Sign a plaintext message |
| `eth_sendTransaction` | Send a transaction |
| `eth_signTransaction` | Sign without broadcasting |
| `eth_signTypedData_v4` | Sign EIP-712 typed data |
| `secp256k1_sign` | Raw secp256k1 signature |
| `eth_sign7702Authorization` | EIP-7702 authorization |
| `eth_signUserOperation` | Sign a user operation (ERC-4337) |

### Solana

| Method | Description |
| - | - |
| `signTransaction` | Sign a Solana transaction |
| `signAndSendTransaction` | Sign and broadcast a transaction |
| `signMessage` | Sign an arbitrary message |

## Design principles

* **CLI-first distribution**: Agents already execute shell commands. A CLI is the most natural interface for agent-driven wallets.
* **Skill-based discovery**: The [skill file](https://agents.privy.io/skill.md) teaches agents how to authenticate and transact without human guidance beyond the initial login.
* **Browser-based funding**: The human owner retains a visual dashboard to check balances, view transaction history, and onramp funds, keeping the human in control.
* **Cryptographic authorization**: Each transaction uses an ephemeral signing key obtained by exchanging an OAuth access token. The agent is never given the wallet private key or app secret.

## How it works

1. The CLI calls Privy's device authorization endpoint and displays a short verification URL and code.
2. The human visits the URL, signs in through Privy, and approves agent access.
3. The CLI polls until approval is confirmed and stores the resulting access and refresh tokens in the OS credential manager.
4. For every transaction, the CLI exchanges the access token for an ephemeral signing key, signs the request, and submits it directly to Privy's wallet API. See [Authorized wallet access for self-hosted agents](https://docs.privy.io/agent-wallets/agent-authorization.md) for the full API flow.

## Session and credential storage

The CLI attempts to use the OS-backed credential manager when available, and otherwise falls back to storing session data in an encrypted file at `~/.privy/session.json`. It is the responsibility of the agent or user to install any required prerequisites for the OS credential manager.

| Platform | Credential manager | Prerequisites |
| - | - | - |
| macOS | Keychain (`security` CLI) | None (available by default) |
| Linux | libsecret (`secret-tool` CLI) | `sudo apt install -y libsecret-tools` (Debian/Ubuntu) |
| Windows | PowerShell SecretManagement | `Install-Module Microsoft.PowerShell.SecretManagement` |

When the OS credential manager is not available (e.g., Docker containers, headless servers, or missing prerequisites), the CLI falls back to an encrypted file at `~/.privy/session.json`. This file is not portable between machines.

Each session contains:

* The app ID for the Privy agent wallet app
* Ethereum and Solana wallet IDs and addresses
* The OAuth access token and refresh token
* A creation timestamp

Sessions remain active for up to 30 days. The access token refreshes automatically on each transaction; the refresh token rotates on each use. To end a session early:

```bash theme={"system"}
privy-agent-wallets logout
```

Users can always revoke agent access to their wallet via the agent sandbox at [agents.privy.io/manage](https://agents.privy.io/manage).

## Learn more

> [card] [Privy Agent Wallet Sandbox](https://agents.privy.io)
>
> Track agent activity, view balances, and manage wallets.

> [card] [Agentic wallets](https://docs.privy.io/recipes/agent-integrations/agentic-wallets.md)
>
> Build developer-controlled agent wallets with policy guardrails.

> [card] [x402 payments](https://docs.privy.io/recipes/agent-integrations/x402.md)
>
> Enable HTTP-native payments for APIs and digital content.

> [card] [MPP integration](https://docs.privy.io/recipes/agent-integrations/mpp.md)
>
> Machine-to-machine payments over HTTP with Privy wallets.

> [card] [Gas sponsorship](https://docs.privy.io/wallets/gas-and-asset-management/gas/overview.md)
>
> Sponsor gas fees for agent transactions.

> [card] [Agent authorization](https://docs.privy.io/agent-wallets/agent-authorization.md)
>
> Let agents from any platform access user wallets in your own Privy app.