Tools

Fixture onlyChecked 16 November 2026

In short

  • Paid tools on the same balance, with the price known before the call.
  • If a tool fails after it was paid, you pay nothing.
  • 27,755 tools listed; 25,351 answered a free check on 6 Nov 2026. In test mode only local test tools can be paid.

Petrova is not live. In test mode (the default) only tools on this machine (loopback hosts) can be called, with a test payer, and a call to any other host is refused with 403 live_tools_disabled. No real tool has been paid. The real payers are built and were rehearsed on local copies ("forks") of Base and Tempo with the real token contracts, not on the real chains: see live mode.

Tools are Petrova's first product. Models (cheaper inference), memory and computer come after it.

Your agent finds a paid tool, sees its price first, and pays for it from the same balance as its model calls. Every tool call goes through the same quote, hold and settle steps as a model call (billing).

How big is the catalog

  • 27,755 listings from the x402 Bazaar and the MPP directory (both downloaded 5 November 2026), all searchable. Near-identical endpoints from one host (a "template farm") are folded into one listing with a variants count, and 78,406 mass-generated rows were left out.
  • Labels, from a free unpaid check on 6 November 2026: 25,351 answered with a valid payment ask (verified), 2,405 did not (listed), and 357 of those were hidden as gone (404, 410 or no answer). 0 are proven: no tool has had a real paid call yet. That run checked the payee, not the price.
  • 980 listings on 42 hosts also accept USDG on Robinhood Chain in their payment terms (979 of them accept USDC on Base too). No MPP service names Robinhood Chain.
  • The test suite still uses 134 recorded test tools (tests/fixtures/x402-bazaar.json), plus Petrova's own chain.watch tool and listings other Petrova agents make.

How a tool is paid

Each tool is paid in the coin it asks for: most x402 tools ask for USDC on Base, MPP tools ask for USDC.e on Tempo. The agent sees one balance in dollars; Petrova's payer wallet pays the tool.

RailPayerHow far it got
x402, USDC on BaseEIP-3009 signer (packages/tools/src/eip3009-signer.ts)Rehearsed on a local fork of Base with the real USDC contract and the official @x402/evm facilitator settling
MPP, USDC.e on TempoTempo charge, pull mode (packages/tools/src/tempo-mpp-payer.ts)Rehearsed on a local fork of Tempo mainnet against a local MPP server. Not tried against a real MPP server
USDG on Robinhood ChainNot builtThe payer signs USDC on Base only

Live mode: built, not switched on

PETROVA_LIVE_TOOLS is off unless set (apps/api/src/live-tools.ts). The server refuses to start with it on unless the readiness report passed on that exact commit in the last 24 hours, the founder signed the approval, and the payer key, caps and an https address are set. In code, the caps can never be raised above $1 a call and $50 a day; the starting settings are $0.10 a call and $5 a day (.env.production.example). With it on, real listings become callable when a payer can pay them, only live accounts (real deposits, no test money) can spend, and only the agent journey routes answer. Nobody has switched it on.

Find a tool

curl -s "http://127.0.0.1:4100/v1/tools?query=weather&max_price_nusd=10000000" \
  -H "authorization: Bearer $PETROVA_API_KEY"

Filters: query (words in the provider, description or category), category, max_price_nusd (nano-USD: 10000000 is $0.01) and limit. Needs catalog:read. Over MCP: tools_discover and tools_inspect.

None of these spend, hold or contact a tool:

RouteWhat it doesMCP
POST /v1/tools/searchDescribe a task in plain words and get ranked candidates. card_aware: true (or card_id) keeps only what that card may call and can still affordtools_search
GET /v1/tools/discoverFind by provider or capability. provider_match says if the host really is that provider, or the listing only calls itself that. Takes card_aware tootools_discover
GET /v1/tools/providers, GET /v1/tools/statsTools grouped by who controls them; what the catalog holds
GET /v1/tools/:id/inspectExact inputs, where each one goes, cost and evidencetools_inspect
POST /v1/tools/:id/quoteCheck inputs and get the cost of one call. callable is false when the call would be refused: a card's rules, what is left of its allowance, a budget, the balance, or a seller's own listingtools_quote
POST /v1/tools/:id/ratingRate one of your own calls. Needs quote:writetools_rate

listing_status says what is known, and nothing more: listed means a directory lists it, checked means it answered an unpaid request with a valid challenge, and passed_paid_call means a real payment got a real result. A fixture payment never raises it, so today nothing has that last status. In test mode callable is false, with not_callable_reason: fixture_only, for every tool off this machine. In live mode callable follows whether a payer can pay the tool. The agent interface shows these as trust tiers: listed, verified (checked) and proven (passed_paid_call).

Checks. npm run tools:checks -- --from-file results.jsonl imports a free, unpaid check of the catalog (one JSON line per listing: url_key = "METHOD URL", verdict, status, at). A healthy verdict makes a tool verified; any other verdict lowers it to listed; a check never makes one proven. Verified also needs the listed price where the challenge states one: a line may carry price_nusd, the price the challenge asked in canonical nano-USD; if it is not exactly the listed price, the check is recorded as price_mismatch and the tool stays listed. A line with no price_nusd checks the payee only. The 6 November run carried no prices, so its 25,351 verified tools had their payee checked, not their price. A 404, 410 or no answer also hides it from search until a later check finds it. An older check never overrides a newer one. Every check is kept in tool_checks with when and how it was made (unpaid_probe or the nightly health_check). Search ranks proven, then verified, then listed, among the tools that say enough of the task.

A listing's provider is its own claim. provider_key is who controls the host, and it is what losses, hiding, risk limits and a card's allowed services go by.

Each tool shows its price per call, its payment scheme, a health mark and how many payers used it:

sourceWhat it isCan it be paid?
x402_bazaarAn HTTP tool that asks for payment with an x402 challengeYes (fixture only)
mppA tool from the MPP directory, paid with the HTTP "Payment" schemeYes, a tempo charge in USDC.e or pathUSD (fixture only). Sessions and other methods are listed and refused
manualAdded by an operatorYes (fixture only)
petrova_sellerAnother Petrova account's endpoint (Earn-to-Run)Yes, inside Petrova's ledger
petrova_nativeServed by Petrova itself: chain.watchYes

A provider whose losses pass 2% of call value is hidden from the list, with every listing on its provider_key.

Call a tool by provider and path

Agents that know a provider's API call it as they would the provider itself, through the one call route. See the answer for its shape and kinds, and MCP for the six tools.

curl -s http://127.0.0.1:4100/v1/agent/calls -H "authorization: Bearer $PETROVA_API_KEY" -H 'content-type: application/json' \
  -d '{"provider":"exa","path":"/search","body":{"query":"machine payments"},"max_cost":"0.05","idempotency_key":"try-1"}'

A provider's slug (exa) is bound once to who controls the host, or to the curated MPP directory entry, and never moves: a listing on another host that calls itself Exa gets its own host's name. POST /v1/agent/inspect returns each input with its type, whether it is required and where it goes.

Call a tool by id

curl -s http://127.0.0.1:4100/v1/tools/<tool id>/call \
  -H "authorization: Bearer $PETROVA_API_KEY" -H 'content-type: application/json' \
  -d '{"inputs":{"city":"Lisbon"},"max_cost_nusd":"10550000","idempotency_key":"try-1"}'
  • max_cost_nusd is the most you will pay. A tool call carries no fee: you pay the tool's own price. If that price is above your maximum, the call is refused with 402 over_max_cost before anything is paid.
  • Petrova reads the tool's price challenge and stops with 409 price_changed or 409 payto_changed if the price or the payee is not what the listing said.
  • x402 "exact": you pay the challenge price. x402 "upto": you pay what the tool actually settled; the rest of the ceiling comes back.
  • Each input goes where the listing says: path, query, header or body. An input cannot set a credential or payment header, and is refused with 400 invalid_inputs.
  • If the tool fails after Petrova paid it, you pay nothing. Petrova books the loss. A 2xx is not enough: a reply that is empty, shaped like an error, or the wrong shape for a tool with an output schema is not charged, and its body is not handed over (what can and cannot be detected).
  • Reusing an idempotency_key never pays twice. On this route a key used before answers 409 duplicate_call. To read the earlier answer, use POST /v1/calls.
  • Needs quote:write. Over MCP: tools_call.

POST /v1/calls takes the same call and records it before anything is sent, so it survives a dropped connection, and the same key finds the same call. A tool that can only be listed, such as an MPP session tool, is refused with 400 tool_not_callable. See cards, calls and approvals. Over MCP: tools_call.

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".

chain.watch: blockchain data

One tool that streams decoded Base chain events: token launches, swaps, liquidity added or removed, and large transfers.

curl -s http://127.0.0.1:4100/v1/chain/watch -H "authorization: Bearer $PETROVA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"filter":{"types":["token_launch","swap"]},"hold_events":100}'
  • Set a filter (event types, addresses, wallets, a minimum dollar size) or a plain-language query. The query is turned into a filter and not kept.
  • Price: $0.00005 per event delivered. This price is all-in.
  • Petrova holds the price of hold_events events (100 by default), delivers up to that many, and charges exactly delivered × price. The rest comes back.
  • Read events as a stream (GET /v1/chain/watch/{id}/events) or by polling (GET /v1/chain/watch/{id}/poll?cursor=). Replays are free. Stop with DELETE.
  • When your balance or a cap runs out, the stream ends with an error event. It never overspends.
  • Over MCP: chain_watch_create, chain_watch_poll, chain_watch_stop.

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".

Sell your own tool

Any account can list an HTTP endpoint as a paid tool for other agents. See Earn-to-Run.

Not built

  • A real paid call to any tool. The payers are built and rehearsed on forks; going live needs a server, the company wallets and a few dollars.
  • Paying in USDG on Robinhood Chain directly.
  • Paying MPP sessions (the per-token LLM endpoints: OpenAI, Anthropic and OpenRouter through MPP use them), MPP push mode, MPP subscriptions, and MPP methods other than tempo (stripe, evm). See MPP.
  • Server-side web search or page fetch as a built-in tool.

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.