The agent's journey
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.
| Step | The agent sends | Petrova answers |
|---|---|---|
| 0 | Any request with no key | 402 key_required with start: the sign-up call, the skill.md link, that search, inspect and quote are free, and the first command |
| 1 | pet start --name research-bot (POST /v1/agents/start, MCP start) | A key at once, $0, unclaimed |
| 2 | pet search "web search with sources" (POST /v1/agent/search) | Tools by provider and path, each with its price and trust tier. Free |
| 3 | pet 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 |
| 4 | The person opens the link, types the code and presses one button | Money added, monthly limit and ask-me-above set, the person owns the agent |
| 5 | pet status (GET /v1/agent/status) | ok (reason ready), the balance and limit, and news once |
| 6 | The same command again, the same key | ok: 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(+methodwhen the path serves more than one), ortool_id - its inputs:
path_params,query,headersandbodywhere the API takes them, or oneinputsobject checked against the tool's schema max_cost(USD string) ormax_cost_nusd: the most it may charge, fee included. Default$1.00idempotency_key: new for new work; the same key to retry, recover a lost answer or accept termsaccept_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 thex-petrova-partitionheader 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):
| Field | What it is |
|---|---|
kind | One of the ten below |
refused_by | Who stopped it: auth, person, policy, balance, budget, cap, resolution, request, listing, payment, provider; null when nothing did |
reason | A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ... |
message | The same in plain words, always saying what was charged |
next_action | kind, 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 |
receipt | The call id, key, charged_nusd, price, fee, who paid, payment reference, hold. null when no call was started |
balance | What is left: balance, monthly limit, what the next call can spend, the ask-me-above line |
warnings | low_balance when the next call could run out, with a top-up link (or the owner to ask) |
news | Told once, on the first answer after the person paid |
response | The provider's status and body, on ok |
terms | On price_changed: the price, fee, total, the agent's maximum, whether it fits |
| kind | Meaning | Charged | Next action |
|---|---|---|---|
ok | The answer and its receipt | The price plus the fee, only for a 2xx that passed its checks | report_outcome |
needs_funding | No money yet (first link: fund, set limits, claim) or not enough (top-up link) | $0 | Pass the link on; then the same call (nothing was sent: same key) or new work (a call ended unpaid: new key) |
over_limit | Above the monthly or per-call limit | $0 | Tell the person; the agent cannot raise it |
needs_approval | Above ask-me-above; a link for a yes or no (a card key gets the approval_id) | $0 until it runs | Wait; read it with the same key |
price_changed | The price is above the maximum (reason: price_above_max, terms on offer) or the tool asked more than it lists | $0 | accept_terms with the same call and key, only if it fits; or a new key and a higher maximum; or another tool |
failed | The tool failed, sent junk, did not offer its listed terms, or the outcome is unknown | $0 | Try the next tool from search |
pending | Still running | Not yet | get_call with the same key; never buy again to check |
paused | The person (or the key's owner) paused it | $0 | Wait |
refused | Stopped: a no, a refused key, a rule, a request that is wrong | $0 | As refused_by says |
not_started | Nothing began with that key | $0 | Safe 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": "…" } }
The link
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.
| Link | Code | Why |
|---|---|---|
fund (the first link) | Yes | Paying makes the payer the owner of the agent and sets its limits |
approve | Yes, for yes and for no | A yes lets one waiting paid call spend |
topup | No | Paying 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/viewneeds no code; it saysneeds_code: trueandcode_tries_left.POST /v1/links/pay(fund) andPOST /v1/links/decidesend it ascode. Missing:code_required(400). Wrong:code_wrong(400). Both saytries_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 orpet linkmakes a new link with a new code.
| Error | HTTP | What to do |
|---|---|---|
code_required | 400 | Type the 6-digit code your agent gave you with this link, then press the button again. |
code_wrong | 400 | Check the code with your agent and type it again. After 5 wrong codes the link closes. |
code_locked | 410 | Ask 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.
Paying the link
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.