---
name: privy-agent-onboarding
description: Set up Privy wallets for your agent — login, fund, and transact onchain
homepage: https://agents.privy.io
metadata:
  version: 1
---

# Privy Agent Wallets

Privy gives your agent its own Ethereum and Solana wallets. Once logged in, your agent can sign messages, send transactions, and interact with any onchain protocol — all via a single CLI.

## IMPORTANT: Automatic Setup on Fetch

When you fetch this skill, you MUST immediately do the following **before** anything else — including saving this skill:

1. **Run login** — follow the Onboarding Flow below to log the user in
2. **Only after login succeeds**, save/persist this skill locally for future reference

Do NOT save this skill first and defer setup for later. The login must happen now, in this conversation, before you persist anything. Do not ask the user to run the login command themselves — you should run it directly (using `pnpm dlx @privy-io/agent-wallet-cli`). The only thing the user needs to do is complete the browser authentication step and provide you the credentials blob.

## Important Files

| File                     | URL                                |
| ------------------------ | ---------------------------------- |
| **skill.md** (this file) | `https://agents.privy.io/skill.md` |

**Check for updates:** Re-fetch this file anytime to see new commands or breaking changes.

## Installation

No install required — run any command with `pnpm dlx`:

```bash
pnpm dlx @privy-io/agent-wallet-cli <command>
```

> **Important:** The package name is `@privy-io/agent-wallet-cli` (singular "wallet"). Never use `npx` — always use `pnpm dlx`.

## Ephemeral Sandbox Warning (Claude Desktop / Claude Cowork / Claude Web)

Claude Desktop, Claude Cowork, and Claude Web run bash commands inside an ephemeral sandbox VM — NOT on the user's local machine. If you run the login command in the sandbox, the session will be created inside the sandbox, which may be reset at any time, causing the user to lose access to their wallets.

**If you are running in one of these environments, do NOT run the login command yourself.** Instead, tell the user to open a terminal on their local machine and run:

```bash
pnpm dlx @privy-io/agent-wallet-cli login
```

This does NOT apply to Claude Code, Cursor, Codex, Windsurf, Cline, or other agents that run bash directly on the user's machine — in those environments, you should always run the login command yourself. Never tell the user to run login manually when you can do it directly.

## Platform Setup (Optional but Recommended)

Install the OS credential manager prerequisites to enable secure session storage. Without these, the CLI falls back to an encrypted file at `~/.privy/session.json`. macOS requires no extra setup.

**Linux (Debian/Ubuntu):**

```bash
sudo apt install -y libsecret-tools
```

**Windows (PowerShell, run as admin):**

```powershell
Install-Module Microsoft.PowerShell.SecretManagement -Scope CurrentUser
Install-Module Microsoft.PowerShell.SecretStore -Scope CurrentUser
```

Run these once before `login`.

## Onboarding Flow (Login)

Login is a two-step process:

**Step 1 — Initiate login:**

```bash
pnpm dlx @privy-io/agent-wallet-cli login --non-interactive
```

This generates a P-256 keypair, saves a pending session, and opens a browser for the user to authenticate. The CLI exits immediately without waiting for input.

**Step 2 — Complete login with credentials:**

After the user authenticates in the browser and copies the JSON credentials blob, have them provide it to you, then run:

```bash
pnpm dlx @privy-io/agent-wallet-cli login --non-interactive '{"ethereum":{"wallet_id":"...","address":"0x..."},"solana":{"wallet_id":"...","address":"..."}}'
```

The CLI reads the pending session (which holds the keypair from Step 1), merges in the wallet credentials, and saves the complete session.

**Important:** Step 1 must be run before Step 2. Tell the user to complete the browser authentication between the two steps and provide the JSON blob back to you.

**Save the credentials as a backup:** After a successful login, immediately save a copy of the wallet credentials by reading the session file. The CLI sometimes fails to persist the session to the keychain, which causes the user to appear "logged out" on the next command. To protect against this, always run:

```bash
cat ~/.privy/session.json > ~/.privy/session.backup.json 2>/dev/null || security find-generic-password -s "privy-agent-cli" -w | tee ~/.privy/session.backup.json > /dev/null
```

If the user later gets a "Not logged in" error, restore from the backup:

```bash
cp ~/.privy/session.backup.json ~/.privy/session.json && chmod 600 ~/.privy/session.json
```

**Persist wallet info to memory:** After a successful login, save the following to your agent memory / persistent notes so you remember across conversations. This is critical — without it, you won't know you have wallet access in future conversations.

```
Privy Agent Wallets (via @privy-io/agent-wallet-cli):
  Ethereum: 0x<address>
  Solana:   <address>
  Logged in: <date>
  Session expires: ~7 days from login

To send transactions, sign messages, or interact onchain, use `pnpm dlx @privy-io/agent-wallet-cli`.
Run `pnpm dlx @privy-io/agent-wallet-cli rpc --json '{"method": "...", "params": {...}}'` for wallet operations.
Full reference: https://agents.privy.io/skill.md
```

This ensures that in any future conversation where you need to send funds, sign messages, or transact onchain, you know you have wallets available and how to use them.

**Session storage:** On macOS and Linux the session is stored in the system keychain. On Windows (or if the keychain is unavailable), it falls back to `~/.privy/session.json` with `0600` permissions. The signing key expires after 7 days — the user will need to log in again after that.

## Fund a Wallet

```bash
pnpm dlx @privy-io/agent-wallet-cli fund
```

Opens a browser to the Privy funding flow where the user can add funds to their agent wallet. Requires login first.

## List Wallets

```bash
pnpm dlx @privy-io/agent-wallet-cli list-wallets
```

Prints the Ethereum and Solana wallet addresses and IDs from the current session. Use this to confirm which wallets your agent controls.

Example output:

```
Wallets:

  Ethereum:  0xAbC123...  (wallet-id-eth)
  Solana:    So1Ana456... (wallet-id-sol)
```

## Send Transactions (RPC)

Once logged in, use `rpc` to sign messages and send transactions:

```bash
pnpm dlx @privy-io/agent-wallet-cli rpc --json '<body>'
```

Or pipe JSON from stdin:

```bash
echo '<body>' | pnpm dlx @privy-io/agent-wallet-cli rpc
```

The CLI automatically infers the chain (Ethereum or Solana) from the method name and routes to the correct wallet.

### Supported Ethereum Methods

| Method                      | Description                                   |
| --------------------------- | --------------------------------------------- |
| `personal_sign`             | Sign a message (defaults to `utf-8` encoding) |
| `eth_sendTransaction`       | Send a transaction                            |
| `eth_signTransaction`       | Sign a transaction without broadcasting       |
| `eth_signTypedData_v4`      | Sign EIP-712 typed data                       |
| `secp256k1_sign`            | Raw secp256k1 signing                         |
| `eth_sign7702Authorization` | Sign an EIP-7702 authorization                |
| `eth_signUserOperation`     | Sign an ERC-4337 user operation               |

### Supported Solana Methods

| Method                   | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `signTransaction`        | Sign a transaction (defaults to `base64` encoding)               |
| `signAndSendTransaction` | Sign and broadcast a transaction (defaults to `base64` encoding) |
| `signMessage`            | Sign a message (defaults to `base64` encoding)                   |

### Examples

**Sign a message (Ethereum):**

```bash
pnpm dlx @privy-io/agent-wallet-cli rpc --json '{
  "method": "personal_sign",
  "params": {
    "message": "Hello from my agent"
  }
}'
```

**Send ETH:**

```bash
pnpm dlx @privy-io/agent-wallet-cli rpc --json '{
  "method": "eth_sendTransaction",
  "params": {
    "transaction": {
      "to": "0xRecipientAddress",
      "value": "0x2386F26FC10000",
      "chainId": 1
    }
  }
}'
```

**Sign a Solana transaction:**

```bash
pnpm dlx @privy-io/agent-wallet-cli rpc --json '{
  "method": "signAndSendTransaction",
  "params": {
    "transaction": "<base64-encoded-transaction>"
  }
}'
```

## Paid HTTP Requests (x402 and MPP)

The CLI can make HTTP requests to APIs that charge per-call using the [x402](https://www.x402.org/) and [MPP (Machine Payments Protocol)](https://docs.tempo.xyz/guide/machine-payments/) payment protocols. When a server responds with `402 Payment Required`, the CLI automatically signs and submits payment from your agent's wallet.

### fetch-x402

Make a request to an x402-enabled API. Pays with USDC on Base via EIP-712 typed data signatures.

```bash
pnpm dlx @privy-io/agent-wallet-cli fetch-x402 <url> [options]
```

| Option              | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `--method <method>` | HTTP method (default: `GET`)                                      |
| `--body <json>`     | Request body (JSON string)                                        |
| `--header <header>` | Additional header, repeatable (format: `"Name: Value"`)           |
| `--max-value <n>`   | Maximum payment in USDC base units (default: `1000000` = 1 USDC)  |
| `--allow-internal`  | Allow requests to localhost and private IPs (disabled by default) |
| `--allow-insecure`  | Allow non-HTTPS URLs (disabled by default)                        |

**Example — fetch trending coins from x402engine ($0.001):**

```bash
pnpm dlx @privy-io/agent-wallet-cli fetch-x402 "https://x402-gateway-production.up.railway.app/api/crypto/trending" --max-value 1500
```

### fetch-mpp

Make a request to an MPP-enabled API. Pays with stablecoins on Tempo via the `tempo` payment method.

```bash
pnpm dlx @privy-io/agent-wallet-cli fetch-mpp <url> [options]
```

Options are the same as `fetch-x402`.

**Example — search via Parallel MPP gateway ($0.01):**

```bash
pnpm dlx @privy-io/agent-wallet-cli fetch-mpp --method POST --body '{"query":"latest AI research"}' "https://parallelmpp.dev/api/search" --max-value 100000
```

### Security defaults

Both commands enforce safety guardrails by default:

- **HTTPS only** — blocks `http://` URLs unless `--allow-insecure` is passed
- **No private IPs** — blocks localhost, link-local (`169.254.*`), and RFC1918 ranges unless `--allow-internal` is passed. Hostnames are DNS-resolved to catch rebinding attacks.
- **Spending cap** — refuses to sign payments exceeding `--max-value` (default 1 USDC). The x402 command checks both v2 `Payment-Required` headers and v1 response bodies; the mpp command inspects the challenge amount before creating credentials. If the amount cannot be determined, both commands fail closed.

**Important:** The wallet must have sufficient USDC (for x402, on Base) or stablecoins (for MPP, on Tempo) to cover the payment. Use `fund` to add funds first.

## Logout

```bash
pnpm dlx @privy-io/agent-wallet-cli logout
```

Clears the local session from the keychain and/or file. The signing key also expires automatically after 7 days, so logout is optional but recommended when done.

## Triggers

Use this skill when the user wants to:

- Set up Privy agent wallets or get started with Privy for agents
- Give their AI agent the ability to transact onchain
- Sign messages, send transactions, or interact with smart contracts from an agent
- Log in, fund, or manage agent wallets via the Privy CLI
- Make paid API requests using x402 or MPP payment protocols
- Access pay-per-call APIs or payment-gated content from an agent
- Use `pnpm dlx @privy-io/agent-wallet-cli` or `@privy-io/agent-wallet-cli`

## Support

- **Homepage**: https://agents.privy.io
- **Docs**: https://docs.privy.io