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.

Time: 10 minutesTest build: no real money
Fixture chain only. Do not send real USDC.Nothing here talks to a Base node. Transfers come from a local test file. Signatures use a test scheme that browser wallets cannot make yet.

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.

  1. 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.
  2. 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-bot and capped at $5. Top-ups above $50 wait for you.

  3. Owner: fund the wallet

    $HELPER fund --amount 20
    # prints a USDC-on-Base payment request for the agent's address
  4. Agent: buy credits

    $HELPER topup --amount 20   # prints Petrova's deposit request
    $HELPER topup --tx 0x…       # after the transfer: report it

    To finish this step locally, give the gateway a fixture transfer. Start it with PETROVA_FIXTURE_TRANSFERS_FILE=transfers.json npm run dev, where transfers.json is:

    {
      "head": "2000",
      "transfers": [
        { "tx_hash": "0x<64 hex characters>", "from": "<agent wallet address>",
          "to": "<PETROVA_DEPOSIT_ADDRESS>", "amount_units": "20000000", "block_number": "1980" }
      ]
    }

    amount_units is USDC with 6 decimals (20000000 = $20). It needs 12 confirmations: head - block_number + 1 must be at least 12. Use the same tx_hash with $HELPER topup --tx. In the sandbox, press Simulate deposit instead.

  5. 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"}'
  6. 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 printed

    The 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_funded on $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.