The agent's journey

BuiltFixture onlyChecked 16 November 2026

In short

  • The agent signs itself up, searches and calls; its person says yes to money once, on one phone screen.
  • Every answer has a kind, a reason and the exact next step.
  • Built in test mode: no real money moves.

Test mode. No real money moves. Payments are fixture payments and only local tools can be paid. Paying with USDG or USDC is built and was rehearsed on local copies of Robinhood Chain and Base, not on the real chains.

The agent is the customer. A person only says yes to money: once, on one phone screen.

StepThe agent sendsPetrova answers
0Any request with no key402 key_required with start: the sign-up call, the skill.md link, that search, inspect and quote are free, and the first command
1pet start --name research-bot (POST /v1/agents/start, MCP start)A key at once, $0, unclaimed
2pet search "web search with sources" (POST /v1/agent/search)Tools by provider and path, each with its price and trust tier. Free
3pet call exa /search --max-cost 0.05 (POST /v1/agent/calls)needs_funding, one link with a 6-digit code, and the sentence for the person
4The person opens the link, types the code and presses one buttonMoney added, monthly limit and ask-me-above set, the person owns the agent
5pet status (GET /v1/agent/status)ok (reason ready), the balance and limit, and news once
6The same command again, the same keyok: the result, the cost, the balance left, a receipt

The one call route

POST /v1/agent/calls is the only paid call route for agents. The SDK (petrova.agent.call), the CLI (pet call) and the MCP call tool all use it. It takes:

  • the tool: provider + path (+ method when the path serves more than one), or tool_id
  • its inputs: path_params, query, headers and body where the API takes them, or one inputs object checked against the tool's schema
  • max_cost (USD string) or max_cost_nusd: the most it may charge, fee included. Default $1.00
  • idempotency_key: new for new work; the same key to retry, recover a lost answer or accept terms
  • accept_terms: to pay a price above the maximum that an earlier answer offered
  • optional credential_mode: customer + connection_id (the customer's own provider account), run_id, wait_ms, and the x-petrova-partition header for an application's end user

GET /v1/agent/calls/{id} and GET /v1/agent/calls?idempotency_key= give the same answer again. They never run or pay anything.

The answer

Every answer has one shape, whichever route, SDK, CLI command or MCP tool produced it (start, status, link, search and inspect use the same envelope):

FieldWhat it is
kindOne of the ten below
refused_byWho stopped it: auth, person, policy, balance, budget, cap, resolution, request, listing, payment, provider; null when nothing did
reasonA short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ...
messageThe same in plain words, always saying what was charged
next_actionkind, message, the exact CLI command, the MCP tool with its arguments, and, when a person is needed, the link and say_to_person (pass it on word for word). accept_terms or approval_id when they apply
receiptThe call id, key, charged_nusd, price, fee, who paid, payment reference, hold. null when no call was started
balanceWhat is left: balance, monthly limit, what the next call can spend, the ask-me-above line
warningslow_balance when the next call could run out, with a top-up link (or the owner to ask)
newsTold once, on the first answer after the person paid
responseThe provider's status and body, on ok
termsOn price_changed: the price, fee, total, the agent's maximum, whether it fits
kindMeaningChargedNext action
okThe answer and its receiptThe price plus the fee, only for a 2xx that passed its checksreport_outcome
needs_fundingNo money yet (first link: fund, set limits, claim) or not enough (top-up link)$0Pass the link on; then the same call (nothing was sent: same key) or new work (a call ended unpaid: new key)
over_limitAbove the monthly or per-call limit$0Tell the person; the agent cannot raise it
needs_approvalAbove ask-me-above; a link for a yes or no (a card key gets the approval_id)$0 until it runsWait; read it with the same key
price_changedThe price is above the maximum (reason: price_above_max, terms on offer) or the tool asked more than it lists$0accept_terms with the same call and key, only if it fits; or a new key and a higher maximum; or another tool
failedThe tool failed, sent junk, did not offer its listed terms, or the outcome is unknown$0Try the next tool from search
pendingStill runningNot yetget_call with the same key; never buy again to check
pausedThe person (or the key's owner) paused it$0Wait
refusedStopped: a no, a refused key, a rule, a request that is wrong$0As refused_by says
not_startedNothing began with that key$0Safe to send the call again with that key

The two shapes this replaces map across: responded became ok (or failed when the provider's answer was not billed), requires_action became price_changed (terms for the agent) or needs_approval (a person), refused became needs_funding, over_limit, price_changed, paused, failed or refused by who refused, invocation_not_found became not_started, and status's unfunded/ready and start's started became needs_funding/ok. next_step and say_to_person moved into next_action; money is balance; billing is receipt.

Examples (test mode, abbreviated)

The first paid call of an agent nobody owns yet:

{ "kind": "needs_funding", "refused_by": "balance", "reason": "insufficient_balance",
  "message": "No money yet: your person has not added any. Charged $0.",
  "next_action": { "kind": "pass_link_to_person",
    "message": "Pass the link and the sentence to your person word for word. When status says ok, send this same call again with the same key: nothing was sent, so it is safe.",
    "command": "pet call exa /search --method POST --idempotency-key k-1",
    "tool": { "name": "call", "arguments": { "provider": "exa", "path": "/search", "method": "POST", "idempotency_key": "k-1" } },
    "link": { "purpose": "fund", "url": "http://127.0.0.1:4100/you/#/pay/pl_…", "code": "482913", "amount_nusd": "10000000000" },
    "say_to_person": "research-bot needs $10.00 to pay for tools (first: exa /search). Open this link to add it and set a monthly limit. One screen, test mode, no real money: http://127.0.0.1:4100/you/#/pay/pl_… . When it asks for a code, type 482 913. It works once and expires in 30 minutes." },
  "receipt": null, "balance": { "claimed": false, "balance_nusd": "0", "can_spend_nusd": "0" }, "warnings": [] }

The same command once the person paid:

{ "kind": "ok", "refused_by": null, "reason": "answered", "message": "Done. It cost $0.01055.",
  "next_action": { "kind": "report_outcome", "command": "pet report 7f0c… succeeded", "link": null, "say_to_person": null },
  "receipt": { "call_id": "7f0c…", "idempotency_key": "k-1", "charge_status": "finalized", "charged_nusd": "10550000", "paid_by": "wallet" },
  "balance": { "claimed": true, "balance_nusd": "9989450000", "monthly_limit_nusd": "10000000000", "can_spend_nusd": "9989450000" },
  "warnings": [], "news": "Your person added money and now owns you. …", "response": { "status": 200, "body": { … } } }

A price above the maximum, with terms on offer:

{ "kind": "price_changed", "refused_by": "cap", "reason": "price_above_max",
  "message": "The tool asks $2.11 with the fee, above your max of $1.00. Nothing is held. Charged $0.",
  "next_action": { "kind": "accept_terms", "accept_terms": "5c1e…",
    "command": "pet call exa /search --method POST --idempotency-key k-2 --accept-terms 5c1e…" },
  "terms": { "cost_nusd": "2110000000", "your_max_nusd": "1000000000", "within_your_limit": true, "expires_at": "…" } }

One link, 32 random bytes, stored as a hash. It works once, ends in 30 minutes, and is bound to its agent, purpose and amount (a database trigger refuses any change). Paying needs the page's own token (an HMAC of the link), JSON, and an allowed Origin. The page is served with no framing and no referrer. Paying a first link adds the money, sets the limits and makes the payer the owner in one transaction, and sets an HttpOnly, SameSite=Strict session cookie for the person's other screens.

The code

A link that gives power also has a 6-digit code. The agent gets both (next_action.link.code, and say_to_person says "When it asks for a code, type 482 913"). The page asks the person to type the code before anything happens, so someone who only sees the URL (in chat history, a log, a link-preview bot, browser history or a screenshot) cannot use it.

LinkCodeWhy
fund (the first link)YesPaying makes the payer the owner of the agent and sets its limits
approveYes, for yes and for noA yes lets one waiting paid call spend
topupNoPaying only adds money. Limits and the owner stay as they are
  • The code is 6 random digits (leading zeros count), new for every link. Asking again while the link is open gives the same link and the same code.
  • It is stored sealed (like the link) and as a keyed hash, checked in constant time, and never logged.
  • POST /v1/links/view needs no code; it says needs_code: true and code_tries_left.
  • POST /v1/links/pay (fund) and POST /v1/links/decide send it as code. Missing: code_required (400). Wrong: code_wrong (400). Both say tries_left, and nothing changes. A missing or malformed code is not counted; a wrong one is.
  • The 5th wrong code closes the link: code_locked (410), "Ask the agent for a new link." Wrong codes sent at the same time are counted one at a time, so they never count past 5. The agent's next status, call or pet link makes a new link with a new code.
ErrorHTTPWhat to do
code_required400Type the 6-digit code your agent gave you with this link, then press the button again.
code_wrong400Check the code with your agent and type it again. After 5 wrong codes the link closes.
code_locked410Ask the agent for a new link.

Only an agent that signed itself up has links. A card key or a builder's application key gets needs_funding with ask_owner and no link: nobody can pay a link to take over a builder's account.

MCP

The default MCP tools are start, search, inspect, call, get_call, report_outcome. start with a name signs an MCP-only agent up: the key stays in the MCP server (and, under pet mcp, in the profile file); the model never sees it. The answer is the agent's status, with the one link when it needs money. start again is the status.

The person's screens

/you/#/pay/<token> and /you/#/approve/<token> (the link; a fund or approve link asks for the code above its button, and the button waits until 6 digits are typed), /you/#/feed (every call with its cost, failed ones at $0), /you/#/limits (limits per agent and Pause all agents). The feed and limits read GET /v1/owner/feed and GET /v1/owner/agents; changes go to PATCH /v1/owner/agents/{id} and POST /v1/owner/pause-all, each with the session cookie, x-petrova-csrf and Origin. An API key, an agent's included, is never accepted there.

In test mode the button is a labelled test payment. With real money on (not switched on yet) the page also offers Pay with USDG or USDC: USDG on Robinhood Chain first, USDC on Base second, to an address made for that one link (packages/billing/src/deposits.ts). The person types the code before the address is shown. A payment is credited after the confirmations, exactly once, and the link is then paid as if paid on the page (limits, owner). Less than asked is held until the rest arrives; more is all credited; a payment after the link was paid is a top-up. A card is not built.

Sign-up limits

5 sign-ups an hour from one address, 200 an hour from everyone, and an account nobody funds expires after 72 hours (its key stops working, its link dies). No free money. An agent nobody owns yet can never use a customer's own provider account (refused, unclaimed_agent).

Own wallet

POST /v1/x402/tools/{id}/call, or POST /v1/x402/call by provider and path, with no key: see the own-wallet design. It is off in live mode (its facilitator is a fixture). Its answers use the same shape (needs_funding with reason payment_required is the 402).

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.