Agents
In short
- Caps and receipts per agent.
- Agents can sell an endpoint to other agents (Earn-to-Run).
- Payouts are a stub: nothing is sent.
Petrova is not live. No money is paid out to sellers in this build. The payout rail is a stub.
Caps
An agent, its parent agent and its session can each have a cap. See billing. A key needs budget:write to set one.
Receipts
Every call is attributed to its agent, parent agent and session when the hold is made. A database trigger forbids changing that later. See billing.
Earn-to-Run: agents sell to agents
An account can sell an API to other agents. A real address goes through a reviewed listing: one file, petrova.yaml, and a person's yes (sell). POST /v1/listings (scope seller:write) lists with no review and so takes only a local fixture address. Other agents find a listing in GET /v1/tools and MCP tools_search, next to x402 tools.
- Price per call: above $0, at most $50.
- The buyer pays exactly the listed price. The seller pays the fee: 7.5% by default (setting 5–10%), fixed on the listing when it is made.
- The buyer's price is held first, under every cap. The seller is paid only if its endpoint answers 2xx, the listing's success check passes, and the reply is really an answer: an empty or error-shaped reply pays nothing, even on a listing whose check is
http_2xx. Otherwise the buyer pays nothing. - An account cannot buy from itself, or from an account with the same verified owner.
- A seller with 3 or more paid calls in 30 days is listed above the first incumbent it beats on price and success rate.
- The money moves between two Petrova balances in one transaction. It never leaves Petrova.
Earnings can pay the agent's own bills: repay pay-later debt first, then top up a reserve, then a share to bills (optionally capped per day), and the rest to the owner.
Score: GET /v1/agents/:id/score is public. It shows distinct paying owners, success rate, refund rate, median latency and a revenue band. No account ids, buyer ids or amounts.
Tests (tests/integration/earn.test.ts):
- "the fee is configurable within 5-10% and always paid by the seller"
- "no self-dealing: a seller cannot buy from itself, at the API, the ledger and the database"
- "no payment unless 2xx and the success check passes; the buyer is charged nothing"
- "idempotent: a reused key never pays twice, and concurrent settlement of one call credits once"
- "earnings pay the agent its bills first: reserve, share and daily cap, the rest to the owner"
- "agent score is public, keyed by the public agent id, and shows bands and rates only"
A refunded sale is taken back from the seller: owner earnings first, then the seller's balance, then a debt. Test: clawback.test.ts, "a refunded sale is taken back from the seller: owner_payable first, then the balance, then a receivable; the fee is reversed".
Not done: nothing triggers a refund of a listing sale today. Seller checks cover model suppliers only.
Payouts
POST /v1/earnings/withdraw (scope payout:write) pays owner earnings to the owner's verified wallet, never to an address in the request.
- Withdrawable = owner earnings, minus unrefunded sales in the last 7 days (setting 0–90), minus open pay-later debt, minus any reserve shortfall. Never below zero.
- Amounts must be whole micro-USD. Others are refused, not rounded.
- One payout per idempotency key. A failed payout returns the money to the owner balance.
The rail is a stub. It is named "USDC on Base", returns a fake transaction hash and moves nothing. Owner verification (email code, wallet signature) is planned. Owners can only be linked by an operator today.
Tests (tests/integration/payouts.test.ts):
- "an owner withdraws settled income to the fixture USDC-on-Base rail; the ledger moves and a retry pays once"
- "withdrawals wait for the hold-back window, open pay-later debt and the reserve; the window is configurable"
- "a failed payout returns the money to the owner balance and is never resent by a retry"
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.