Field guide · agents.privy.io

Give an AI agent a wallet, not your keys

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.

Tool · @privy-io/agent-wallet-cli 0.3.11Login · device code, approved in your browserSessions · up to 30 daysPrivate key shared · never

How it works

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:

01 · The agent never sees a key

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.

02 · Approval is yours, once

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.

03 · Fund small, always

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.

The one catch — read this first: Privy can only sign for wallets Privy created. Delegated signing works for Privy embedded and server wallets — not for an existing standalone wallet you made somewhere else. The only way to bring an outside wallet under Privy would be importing its private key, and you should never do that. So this setup gives your agent a brand-new wallet, not control of the wallet you already have. That is a feature: your main wallet stays exactly as separate as it was.

The setup, step by step

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.

Step 1 · Install the Privy Agent CLI

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.

Step 2 · Log in with the device code

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.

Step 3 · Meet your agent's new wallets

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

Step 4 · Fund it — small, and only what it needs

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.

Step 5 · Let the agent transact

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.

Command reference

The whole CLI surface is seven commands. That's the point — there is very little to misconfigure.

CommandWhat it does
loginStart the device-code flow; you approve in a browser. Provisions the wallets on first login.
logoutEnd the local session.
list-walletsShow the agent's wallets — also the quickest session health check.
fundOpen the funding flow at agents.privy.io in a browser.
rpcAny chain call by CAIP-2 ID: reads, eth_sendTransaction, personal_sign, typed-data signing.
fetch-x402Fetch a URL, paying its x402 price in USDC on Base.
fetch-mppFetch a URL, paying via MPP (Tempo / PathUSD).

The session trap — and the fix

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.

The fix: pin the machine identity

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
Rule of thumb: Never re-login just because list-wallets fails. Restore the machine identity first — in our test, deliberately randomizing the machine-id and hostname broke the session, the restore script brought the same wallets back instantly, and no new approval was needed. Only if it still fails after a restore is the session genuinely gone. And don't try to fix this with a boot service: anything installed outside your home directory disappears in the same replacement that broke the session.

Guardrails worth setting

How this played out for us

The real run, November 6–7, 2026 (GMT+7) — including the parts that went wrong, since those are the parts worth learning from.

  1. Nov 6 · morning — The research. Starting question: can an agent do onchain work without the user pasting a private key? We found agents.privy.io, confirmed there was no Privy connector built into our agent environment, that Privy's MCP server is docs-only, and that the Agent CLI was the genuine route — version 0.3.11, checked on npm before installing anything.
  2. Nov 6 · 14:14 — First login. "Test the CLI first" — a read-only trial before committing. The device code was approved in the browser, login succeeded on the first attempt, and the new Ethereum and Solana wallets above were provisioned. No funds moved.
  3. Nov 6 · 14:15 — The decision. One minute later: use the Privy wallet as the agent wallet, funded small. The user's pre-existing wallet stayed untouched as the human-signs backup — it still signs everything the agent shouldn't.
  4. Nov 6 · evening — Funding and first bridges. 3 USDC on Arc and 1 POL on Polygon arrived from the user's own wallet, then three small Relay bridges put gas where it was needed: Arc USDC → Base USDC, Arc USDC → ETH on Base, Base USDC → ETH on Robinhood Chain. Total bridge cost across all three: a few cents.
  5. Nov 6–7 — What it unlocked. Everything since has run through this wallet and the CLI — no key ever seen by the agent: ERC-8004 agent identity registrations on Base, Arc, Polygon, and Robinhood Chain; two token launches ($MUSE on Arc, $RMUSE on Robinhood Chain); a 1,850-wallet airdrop; and the agent's own trading. All of it traceable to one address on public explorers.
  6. Nov 7 · ~07:50 — The session fix. After the seventh "Not logged in" break — every one coinciding with a machine replacement — we traced the cause to the hostname + machine-id key derivation and shipped the pinning fix described above. Verified by simulation: break it on purpose, restore, wallets back, no re-login. It hasn't broken since.
  7. Still open — The one unfinished step. A full spending policy (chain allowlist, per-transaction cap, contract allowlist) is written and ready but not yet attached — the sandbox wallet signs under the small-balance rule until it is. Attaching it is a dashboard job, and it's the first thing to do before funding the wallet with anything serious.