Petrova docs

BuiltFixture onlyChecked 16 November 2026

In short

  • Petrova is the account your agent calls. Your agent does the work.
  • One balance pays for tools first, then models and memory, each through quote, hold and settle.
  • Anthropic and OpenAI formats both work.

Everything your agent needs. One balance.

Petrova is not live. No real money has moved and no real tool has been paid. Everything below is what the code in this repository does today, in test mode. The payers for real tools and the deposit page are built and were rehearsed on local copies ("forks") of Base, Tempo and Robinhood Chain with the real token contracts, never on the real chains. Going live needs a server, the company wallets and a few dollars (status). Each promise names the test that proves it. Where the code does not keep a promise, the page says so.

Pages:

How it works

Petrova is the account your agent calls. Your agent does the work; Petrova does not run agents. Petrova holds the money, pays each tool, and keeps every call inside the limits a person set.

Four products, one at a time

  1. Tools: paid APIs your agent can call from one balance. Built in test mode; this comes first.
  2. Cheaper inference: models at a lower price. Built in test mode against fixtures; comes second.
  3. Memory: repo memory and saved memories. Built in test mode; comes third.
  4. Computer: comes last. Not built.

Each one is made to work well before the next one starts.

The agent is the customer

  1. The agent signs itself up: POST /v1/agents/start (pet start --name ..., or the MCP start tool). It gets a key at once, a $0 balance, and no owner yet. No email, no person.
  2. It searches for a tool and calls it with a maximum price. Search and inspect are free.
  3. When it needs money, the answer carries one link and a 6-digit code, and the exact sentence to say to its person.
  4. The person opens the link on a phone, types the code, and pays once on one screen. That one step funds the balance, sets a monthly limit and an "ask me above" line, and makes the person the owner. Today the pay button is a labelled test payment; "Pay with USDG or USDC" is built and was rehearsed on forks.
  5. The agent's next call goes through.

Fund links and approve links need the code; top-up links do not, because paying one only adds money (needsCode() in packages/billing/src/person-links.ts). Five wrong codes close the link, and the agent's next answer brings a new link with a new code. A link lasts 30 minutes and works once. See the agent's journey.

Ways in

  • HTTP API: the /v1/agent/... routes (agent journey).
  • Command line: pet (cli).
  • MCP: pet mcp over stdio, or the hosted server at <your origin>/mcp over Streamable HTTP. Setup is one line to the agent: "Set up Petrova from <your origin>/skill.md" (MCP).
  • TypeScript SDK: packages/sdk, built, not published to npm (sdk). There is no Python SDK yet.

One balance

One balance pays for paid tools, chain.watch events, other agents' listings, and later model calls and memory. Every one of them goes through the same three steps: a quote, a hold, a settlement (billing). Money is counted in whole nano-USD (one billionth of a dollar) as integers. There is no floating point in the money path.

Money comes in as USDG on Robinhood Chain first, or USDC on Base, to an address made for that one link (built, rehearsed on forks). A card is not built. In test mode the balance is funded by a labelled test payment.

Tools

Paid tools are listed in one store and called through POST /v1/agent/calls by provider and path (or tool id), with a maximum price. Over MCP: search, inspect, call, get_call, report_outcome, plus start. Older routes (GET /v1/tools, POST /v1/tools/:id/call) still work.

  • x402 tools: Petrova reads the tool's price challenge, refuses if the price, payee or URL changed or the price plus fee is above your max_cost, then holds, pays and settles.
  • If the tool fails after payment, you are charged nothing and Petrova books the loss. A provider whose losses pass 2% of call value is hidden.
  • Other agents' listings are tools too (agents).
  • MPP tools: a tempo charge in USDC.e (MPP).

Test mode. The payer is a test payer and only loopback hosts can be called. No real tool has been paid. The real x402 and MPP payers are built and rehearsed on forks; the live switch is off (tools).

Tests (tests/integration/tools.test.ts): "happy path: 402, verify, hold, sign, retry, settle at the challenge amount"; "failure after payment: customer charged nothing, Petrova books the loss, provider hidden".

Memory

  • Repo memory. npm run petrova -- index uploads only files Petrova has not seen. Each new file is summarised and the result is frozen per commit. Sending x-petrova-repo: name@<40-hex sha> adds that commit's map (at most 1,500 tokens) as one system block. Nothing else in your request changes. The added tokens are billed as normal input.
  • Saved memories. remember, recall, forget, list, export over HTTP and MCP.

Fixture only. The summariser is a stub; the live one refuses to start. "Forget" deletes the memory; DELETE /v1/repos/:repo erases a repo. What memory stores is on what Petrova keeps.

Tests: tests/integration/memory.test.ts, "index a commit: billed through quote -> hold -> settle, block frozen, status and context readable"; tests/integration/worker.test.ts.

chain.watch

One tool that streams decoded Base chain events: token launches, swaps, liquidity changes and large transfers. You set a filter (or a plain-language query) and pay per delivered event.

  • Petrova holds the price of N events (100 by default), delivers up to N, and charges exactly delivered × price. The rest is released.
  • Replays are free. Two streams on one watch are charged once.
  • When a hold is refused the stream ends with an error event. It never overspends.

Fixture only. Events come from recorded test blocks. No chain node is contacted.

Tests (tests/integration/chain.test.ts): "stream delivers events with summaries and charges exactly delivered x price, in blocks of N"; "running out of balance ends the stream with billing_error; the balance never goes negative".

Models (the second product)

The model gateway is built and tested against fixtures. It comes after tools.

Claude format

POST /v1/messages and POST /v1/messages/count_tokens accept Anthropic's Messages format. Claude Code connects by setting ANTHROPIC_BASE_URL to Petrova and ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) to a Petrova key. See docs/setup/claude-code.md.

  • The body is kept as raw bytes and sent on unchanged, so cache markers, tools and thinking signatures survive.
  • Only anthropic-* headers go to the supplier. Your Petrova key never does.
  • Streams are passed through chunk by chunk.
  • The model must be an exact id from the price table or a dated snapshot of it. Any other name is refused, never priced by guess.

Tests (tests/integration/messages.test.ts): "the body reaches the upstream unchanged and only anthropic-* headers are forwarded"; "stream is passed through byte for byte, pings kept, receipt in headers and trailer"; "streams over a real socket as Claude Code would consume them".

OpenAI format

POST /v1/chat/completions and POST /v1/responses (the format Codex CLI uses) are translated into a Messages request and run through the same gateway. Caps, holds, failover and loop pause are the same. Tests: tests/integration/openai.test.ts and tests/unit/openai.test.ts.

Not supported: previous_response_id (Petrova stores no responses), hosted tools, and mapping of reasoning settings. Errors are shown in OpenAI's shape (limits).

Prices

Prices come from one table: packages/catalog/src/rates.ts. It lists, for every model, the input, output, cache read, 5-minute and 1-hour cache write price, copied from Anthropic's published pricing, with the date it was read. The default model is claude-opus-5-5. Batch is half of every price.

A call is charged its supplier cost plus a 5.5% fee, rounded up once (feeNusd). In fixture mode the supplier cost is the list price in that table. A lower sale price through DIEM keys and resellers is planned, not built (supply).

Test: tests/unit/pricing.test.ts, "the catalog lists exactly the published prices for every model, with no global multipliers".

GET /v1/models returns this catalog: each model id (claude-opus-5-5, ...), its catalog id, status and context size. Test: tests/integration/foundation.test.ts, "health/readiness are available, unsupported paid APIs cannot execute".

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.