Guides / Give your agent a wallet
Give your agent a wallet
The agent makes a wallet, you register it, it buys credits, you approve big top-ups, it makes its own capped key.
For: An owner who wants an agent to fund itself with USDC, with big top-ups waiting for an OK.
This is the older wallet flow. The agent side is the helper script in the petrova-guard plugin, plugins/petrova-guard/bin/petrova (Node 20+). It is not the pet command: pet has no wallet commands, and with pet an agent gets money from its person through pet start and pet link. Below, $HELPER stands for the path to the helper script. The owner side is a key with "Set caps" (budget:write), or the Wallets and Approvals screens in the sandbox, where you can click through every step.
Agent: make a wallet
HELPER=plugins/petrova-guard/bin/petrova $HELPER wallet # prints only the address. The key is written once to ~/.petrova/wallet.json (mode 600) # Next: ask your owner to register this address.Owner: register it
curl -s http://127.0.0.1:4100/v1/agent-wallets -H "authorization: Bearer $OWNER_KEY" -H 'content-type: application/json' \ -d '{"address":"0x…","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"50000000000"}'Every key the agent makes is bound to
research-botand capped at $5. Top-ups above $50 wait for you.Owner: fund the wallet
$HELPER fund --amount 20 # prints a USDC-on-Base payment request for the agent's addressAgent: buy credits
$HELPER topup --amount 20 # prints Petrova's deposit request $HELPER topup --tx 0x… # after the transfer: report itTo finish this step locally, give the gateway a fixture transfer. Start it with
PETROVA_FIXTURE_TRANSFERS_FILE=transfers.json npm run dev, wheretransfers.jsonis:{ "head": "2000", "transfers": [ { "tx_hash": "0x<64 hex characters>", "from": "<agent wallet address>", "to": "<PETROVA_DEPOSIT_ADDRESS>", "amount_units": "20000000", "block_number": "1980" } ] }amount_unitsis USDC with 6 decimals (20000000 = $20). It needs 12 confirmations:head - block_number + 1must be at least 12. Use the sametx_hashwith$HELPER topup --tx. In the sandbox, press Simulate deposit instead.Owner: approve a big top-up
Small top-ups are credited after 12 confirmations. Above the threshold the top-up waits as "needs your OK":
curl -s http://127.0.0.1:4100/v1/topups/approvals -H "authorization: Bearer $OWNER_KEY" curl -s -X POST http://127.0.0.1:4100/v1/topups/approvals/<id>/decide -H "authorization: Bearer $OWNER_KEY" \ -H 'content-type: application/json' -d '{"decision":"approve"}'Agent: make its own key and run
$HELPER key export PETROVA_KEY_FILE=~/.petrova/agent-key # the secret goes to a mode-600 file; only its prefix is printedThe key can see its balance, see models and tools, and spend. It can never set caps. Every hold is booked to the agent, whatever headers it sends.
What can go wrong
402 not_fundedon$HELPER key: no credited top-up yet.- A top-up is rejected if it is the wrong token, sent to the wrong address, sent from another wallet, or failed on chain. A tx hash is credited once, ever.
approval_closed: someone already decided that top-up.
Next
Checked against the code on 16 November 2026.