Field guide · agents.privy.io
How to set up a Privy agent wallet so an AI agent can transact onchain — deploy contracts, swap, bridge, sign — while the private key never leaves Privy's custody and never passes through the agent at all. This is the exact setup we ran, written up so anyone can repeat it.
Privy's Agentic Sandbox (agents.privy.io) gives an agent its own wallet. You approve access once in your browser; after that, the agent transacts using short-lived, per-transaction ephemeral signing keys. Three ideas make it safe to hand an agent a wallet:
Keys live in Privy's custody. The CLI asks Privy to sign; the agent only ever handles the transaction itself, never the material that authorizes it.
Login is a device-authorization flow: the CLI shows a code, you approve it in your own browser, and you can revoke the session any time at agents.privy.io/manage.
The balance is the guardrail. Keep only what the agent needs for the task at hand in the wallet — treat everything in it as money the agent could spend.
Five steps, about ten minutes. Steps 1–3 need no funds at all — you can test the whole login flow with an empty wallet before deciding anything.
The official package is @privy-io/agent-wallet-cli (Apache-2.0). Run it with pnpm dlx, or install it into a project folder and pin the version so it can't change underneath you:
# one-off run
pnpm dlx @privy-io/agent-wallet-cli list-wallets
# or a pinned local install (what we used)
mkdir privy-agent-cli && cd privy-agent-cli
pnpm add @privy-io/agent-wallet-cli@0.3.11
./node_modules/.bin/privy-agent-wallet list-wallets
The binary is called privy-agent-wallet. Ignore the "official Privy MCP servers" in package directories — the ones we checked are unofficial community builds wrapping the REST API, and Privy's own MCP server only reads documentation. The CLI is the real signing path.
privy-agent-wallet login
The CLI prints a short code. Open agents.privy.io in your browser, sign in, and approve the code after reviewing the permissions. The session is stored locally at ~/.privy/session.json and lasts up to 30 days with automatic token rotation — one approval covers weeks of agent work, and you can kill it any time from the manage page.
Login doesn't connect an existing wallet — it provisions a new one. Check what you got:
privy-agent-wallet list-wallets
You'll get an Ethereum wallet and a Solana wallet, both fresh and empty. These are the addresses your agent will act from. Ours — public addresses, safe to share — are:
Ethereum · EVM
0x0A1D2730f4Ae736Bac3D772FaB8607BFd7F650C4
Solana
5bCEvVTuseDNGDQaKnfCf1BrsAqgbfNZwqD1cgyrrdjx
Send a small amount from your own wallet to the agent address, on the chain you want the agent to work on. In our setup the first funds were 3 USDC on Arc and 1 POL on Polygon — enough to register an identity and start testing, small enough to lose. The CLI's fund command just opens the funding flow in a browser; the transfer itself always comes from you.
Start with one chain. Gas needs differ per chain, and bridges can move small amounts between them later — we used Relay to turn Arc USDC into gas ETH on Base and then on Robinhood Chain, a few cents at a time.
Everything the agent does goes through the rpc command, addressed by CAIP-2 chain ID (eip155:<chain_id>):
# read a balance (no signature needed)
privy-agent-wallet rpc --method eth_getBalance \
--caip2 eip155:5042 \
--params '{"address": "0x0A1D2730f4Ae736Bac3D772FaB8607BFd7F650C4", "blockTag": "latest"}'
# send a transaction (Privy signs, agent never sees a key)
privy-agent-wallet rpc --method eth_sendTransaction \
--caip2 eip155:5042 \
--params '{"transaction": {"to": "0x…", "value": "0x…", "data": "0x…"}}'
The same channel handles contract calls, personal_sign, and typed-data signing — enough to deploy tokens, manage liquidity, and verify ownership on explorer sites. Two more commands cover agent payments: fetch-x402 pays x402-priced APIs in USDC on Base, and fetch-mpp pays MPP endpoints. Both are typed-data payments, so treat them as spending, not reads.
The whole CLI surface is seven commands. That's the point — there is very little to misconfigure.
| Command | What it does |
|---|---|
login | Start the device-code flow; you approve in a browser. Provisions the wallets on first login. |
logout | End the local session. |
list-wallets | Show the agent's wallets — also the quickest session health check. |
fund | Open the funding flow at agents.privy.io in a browser. |
rpc | Any chain call by CAIP-2 ID: reads, eth_sendTransaction, personal_sign, typed-data signing. |
fetch-x402 | Fetch a URL, paying its x402 price in USDC on Base. |
fetch-mpp | Fetch a URL, paying via MPP (Tempo / PathUSD). |
This is the part nobody documents, and it cost us seven broken logins in two days. The CLI encrypts ~/.privy/session.json with a key derived from your machine's hostname and machine-id. On a laptop that never changes, you'll never notice. But if the machine is a VM or container that gets replaced — a new instance, a rebuilt environment — it boots with a fresh random machine-id, the saved session can no longer be decrypted, and list-wallets reports "Not logged in" even though the session file is sitting right there.
Save your machine-id and hostname somewhere that survives a machine replacement (inside your home directory or workspace), and restore them before every CLI call. A tiny script does it:
#!/usr/bin/env bash
# Restore the machine identity the Privy session was created under.
# Keep ./machine-identity/ somewhere persistent (home dir / workspace),
# NOT in /etc — system paths are exactly what gets replaced.
set -e
DIR="$(cd "$(dirname "$0")" && pwd)/machine-identity"
MID="$(cat "$DIR/machine-id")"
HN="$(cat "$DIR/hostname")"
[ "$(cat /etc/machine-id 2>/dev/null)" = "$MID" ] || \
echo "$MID" | sudo tee /etc/machine-id >/dev/null
[ -f /var/lib/dbus/machine-id ] && \
echo "$MID" | sudo tee /var/lib/dbus/machine-id >/dev/null
[ "$(hostname)" = "$HN" ] || sudo hostname "$HN"
echo "machine identity restored: $HN / $MID"
Create the two saved files once, while your session is healthy:
mkdir -p machine-identity
cat /etc/machine-id > machine-identity/machine-id
hostname > machine-identity/hostname
Then make the restore a habit — in scripts, cron jobs, and agent instructions alike:
bash restore-privy-machine-identity.sh
privy-agent-wallet list-wallets
The real run, November 6–7, 2026 (GMT+7) — including the parts that went wrong, since those are the parts worth learning from.