Agent wallet: an agent that funds itself

Fixture onlyChecked 16 November 2026

In short

  • An agent gets its own wallet, asks its owner for funds and makes its own capped key.
  • Top-ups above $50 wait for the owner's OK.
  • Fixture chain only: do not send real USDC.

The main way an agent gets money now is the agent's journey: it signs itself up and its person pays one link (with a 6-digit code), with a test payment or, once real money is on, USDG on Robinhood Chain or USDC on Base. This page is the older wallet flow.

Fixture only. Petrova credits transfers from a fixture chain. Nothing here sends a transaction or talks to a Base node, and no real USDC is credited. Do not send real money.

An agent gets its own Base wallet, asks its operator for funding, buys Petrova credits with USDC, makes its own API key and runs. Top-ups above a threshold (default $50) need the operator's OK.

The agent side is the wallet skill in the petrova-guard plugin (plugins/petrova-guard/skills/wallet/) and the wallet commands of the plugin's helper script, plugins/petrova-guard/bin/petrova (it runs petrova-wallet.mjs; Node 20+, no dependencies). This helper is not the pet command. pet has no wallet commands: with pet, an agent gets money from its person through pet start and pet link. Below, $HELPER stands for the helper's path.

1. Agent: make the wallet

HELPER=plugins/petrova-guard/bin/petrova
$HELPER wallet

This makes a secp256k1 key with node:crypto, writes it once to ~/.petrova/wallet.json (mode 600, folder mode 700) and prints only the address. Running it again shows the same address; it never overwrites the key. The key is never printed or logged. Change the place with PETROVA_STATE_DIR or PETROVA_WALLET_FILE.

2. Operator: register the wallet

With an operator key that has budget:write (the agent's own key never has it):

curl -s http://127.0.0.1:4100/v1/agent-wallets \
  -H "authorization: Bearer $PETROVA_OPERATOR_KEY" -H 'content-type: application/json' \
  -d '{"address":"0x…","agent_id":"research-bot","default_cap_nusd":"5000000000"}'
  • agent_id: every key the agent makes is bound to this id.
  • default_cap_nusd: the cap each of the agent's keys gets, and the agent's own cap if you have not set one (nano-USD; 5000000000 = $5).
  • approval_threshold_nusd (optional): top-ups above this need your OK. Default TOPUP_APPROVAL_THRESHOLD_NUSD, which defaults to $50.
  • operator_public_key (optional): your operator wallet's public key, if you want to approve by signed message. Make one with $HELPER wallet --operator.

3. Operator: fund the agent's wallet

$HELPER fund --amount 20

prints an EIP-681 request: ethereum:<USDC on Base>@8453/transfer?address=<agent>&uint256=<units>.

4. Agent: buy credits

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

POST /v1/topups/onchain takes the tx hash in a message signed by the wallet. The watcher credits the account once the transfer has TOPUP_CONFIRMATIONS confirmations (default 12). It checks that it is USDC on Base, sent to Petrova's deposit address (PETROVA_DEPOSIT_ADDRESS, default a fixture address) from this wallet. A tx hash is credited once, to one account, ever. Wrong token, wrong recipient, another sender or a failed transaction is rejected.

The credit uses the same journal pattern as ledger funding: an advisory lock on the reference, the account lock, then one sealed journal (onchain_topup: debit usdc_received, credit customer_liability).

No split on a deposit. A top-up is your money, not Petrova's income, so nothing is split when it is credited. The FeeSplitter shares (10% burn, 20% allowance pool, 10% stakers, 60% reserve) apply only to Petrova's fee revenue, when a fee is earned, and are recorded in fee_splits (migration 028). The older topup_splits table is kept for history but no longer written. On chain, the CreditPurchase contract would send a deposit whole to custody (contracts).

Locally: make the transfer exist on the fixture chain

There is no Base node in this build. The API reads "transfers that happened" from a JSON file named by PETROVA_FIXTURE_TRANSFERS_FILE (apps/api/src/topups.ts, FixtureTransferSource.fromFile in packages/billing/src/topups.ts). Without it the fixture chain is empty and $HELPER key always answers "Fund this wallet first".

{
  "head": "1100",
  "transfers": [
    {
      "tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "from": "<the agent wallet address from step 1>",
      "to": "0x00000000000000000000000000000000000fee01",
      "amount_units": "20000000",
      "block_number": "1000"
    }
  ]
}
  • to is the fixture deposit address (or your PETROVA_DEPOSIT_ADDRESS).
  • amount_units is USDC with 6 decimals: 20000000 is $20.
  • Confirmations are head - block_number + 1. With the numbers above that is 101, more than the 12 needed, so the top-up is credited as soon as it is reported. Lower head to see it wait.
  • token is optional (default: USDC on Base). "success": "false" makes a failed transaction.
  • The file is read when the API starts. Restart npm run dev after you change it:
PETROVA_FIXTURE_TRANSFERS_FILE=./transfers.json npm run dev
$HELPER topup --tx 0x1111111111111111111111111111111111111111111111111111111111111111
$HELPER key

5. Operator: approve a big top-up

A top-up above the threshold waits as awaiting_approval. Either:

  • Dashboard: GET /v1/topups/approvals, then POST /v1/topups/approvals/<id>/decide with {"decision":"approve"} or "reject" (operator key, budget:write).
  • Signed message: PETROVA_KEY=<operator key> $HELPER approve <id> (or --reject). It signs the approval id, tx hash, amount and a one-time nonce with your operator wallet; only the operator key registered for that agent wallet is accepted, and a signature for one approval cannot approve another.

6. Agent: make its own key

$HELPER key
export PETROVA_KEY_FILE=~/.petrova/agent-key

Only after a credited top-up. The key has balance:read, catalog:read and quote:write, is bound to the agent id (every hold is booked to that agent, whatever the headers say), and has a key cap equal to default_cap_nusd. The secret is written to a mode-600 file and only its prefix is printed. Petrova stores only its hash.

Signatures (fixture scheme)

Wallet-signed routes (/v1/agent-wallets/status, /v1/agent-wallets/keys, /v1/topups/onchain, /v1/topups/approvals/<id>/decide-signed) take no API key. The body is { message, public_key, signature }. The message is petrova-wallet/1 followed by name: value lines (action, address, time, nonce, ...). The signature is ECDSA secp256k1 over SHA-256 of the message. The server derives the address from the public key (Keccak-256) and checks it. Messages expire after 5 minutes and can be used once.

This is not EIP-191. A browser wallet cannot produce it. Going live needs EIP-191 or EIP-712 verification with key recovery.

Not built

  • Sending the USDC transaction from the agent's wallet (signing and broadcasting on Base).
  • A live transfer source: a Base node or RPC, confirmation depth for reorgs, and a real deposit address or the FeeSplitter contract.
  • A dashboard page; the "dashboard" is the HTTP route above.

Last checked against the code: 16 November 2026. Something wrong? The source of this page is in the repository, so a fix is one edit.