# Petrova skill: paid tools for an agent

You are an AI agent. Petrova is the account you call to find a paid tool, learn its price and pay
for one call. You do every step yourself. Your person only says yes to money: once, on one phone
screen. After that you work on your own.

## Set up, one line

Your user says: "Set up Petrova from https://www.usepetrova.xyz/skill.md". Then connect one of two ways:

- **MCP (any MCP client):** add the server `https://www.usepetrova.xyz/mcp` (Streamable HTTP). In Claude Code:
  `claude mcp add --transport http petrova https://www.usepetrova.xyz/mcp`. Six tools: `start`, `search`,
  `inspect`, `call`, `get_call`, `report_outcome`. Call `start` first. With no key it signs you
  up and shows your key once: to stay the same agent next time, connect with the header
  `Authorization: Bearer <key>`, kept where only your user can read it.
- **Command line (needs Node 20 or newer: check `node -v`).** Get the command once. It is one file
  and it talks only to https://www.usepetrova.xyz:

  ```sh
  mkdir -p ~/.petrova/bin && curl -fsSL https://www.usepetrova.xyz/cli/petrova.mjs -o ~/.petrova/bin/petrova.mjs && printf '#!/bin/sh\nexec node "$HOME/.petrova/bin/petrova.mjs" "$@"\n' > ~/.petrova/bin/pet && chmod +x ~/.petrova/bin/pet
  ```

  Wherever this page says `pet`, run `~/.petrova/bin/pet` (or put `~/.petrova/bin` on your PATH).
  The file's checksum is at https://www.usepetrova.xyz/cli/petrova.mjs.sha256. Then follow the steps below.
- **No Node:** use MCP above, or the HTTP routes near the end of this page.

## Status

<!-- petrova:status -->
- Test mode: no real money moves. Payments are test payments, and only local test tools can be paid.
- If nothing answers at https://www.usepetrova.xyz, stop. Tell your user: "Petrova is not running here, so I changed nothing."
<!-- /petrova:status -->

## Rules

1. **Search, inspect and quote are free.** Every paid call has a maximum price that you set.
2. **Never buy twice to check something.** If an answer is lost, read it again with the same key:
   `pet get --idempotency-key <key>`. A new key is a new purchase.
3. **Never ask your user to paste a key.** You make your own with `pet start`. It is saved in a
   file only you can read and is never printed. Keep it out of chat, logs, git and command lines.
4. **You can never raise your own limit, and you must not try.** No second sign-up, no other key,
   no other account to get around a limit or a pause. Only your person changes limits.
5. **Pass `next_action.say_to_person` on word for word.** It holds the exact link and, for a first link or an approval,
   the 6-digit code the page asks for. Do not shorten or rewrite it, and send the code only to your person.
6. **Change no code and no settings in this project until your user says go.** Paying for a tool
   through Petrova changes nothing here.

## Step 1: sign up, one call

```sh
pet start --name research-bot
```

No email, no phone, no person. You get a key at once. The balance is $0 and nobody owns you yet.
Without the command line: `POST /v1/agents/start` with `{"name":"research-bot"}`. Any request
without a key gets a 402 that says the same.

## Step 2: find a tool, free

```sh
pet search "web search with sources"
pet inspect exa /search
```

Each tool has a provider, a path, a price and a label: listed, verified (an unpaid check found it
asking for payment as listed) or proven.

## Step 3: call it

```sh
pet call exa /search --body '{"query":"acme"}' --max-cost 0.05
```

The first time, the answer is `needs_funding`, with one link in `next_action.link`, its 6-digit
code in `next_action.link.code`, and a sentence in `next_action.say_to_person` that says both.
Nothing was charged. Pass the sentence to your person. Exit code 4 means you are waiting for a person.

## Step 4: wait for your person

```sh
pet status
```

When `kind` is `ok` (reason `ready`), the answer tells you your balance, your monthly limit and
the line above which your person wants to be asked.

## Step 5: call again

Run the same command. It keeps the same key, so it is the same call. The answer has the result,
what it cost, the balance left and a receipt. You are charged only for a good answer.

## Every answer has a kind

Every answer has `kind`, `refused_by` (who stopped it, or null), `reason` (a code), `message`
(plain words), and `next_action` with the exact `command` to run next. Plus `receipt`,
`balance` and `warnings`.

| kind | What it means | What you do |
|---|---|---|
| `ok` | Done. The result, the cost, the balance left, a receipt. | Use the result. |
| `needs_funding` | No money, or not enough. Nothing charged. | Pass `next_action.say_to_person` on word for word, then check `pet status`. Then run `next_action.command`. |
| `over_limit` | Over the monthly or per-call limit. Nothing charged. | Tell your person. You cannot raise it. |
| `needs_approval` | Above the ask-me line. A link and a code for your person. | Pass the sentence on. The call runs by itself after a yes. |
| `price_changed` | The price is above your maximum, or not what was listed. `terms` has it. | Accept (`next_action.command` with `--accept-terms`) only within your limit, or pick another tool. |
| `failed` | The tool failed or sent junk. Charged $0. | Try the next tool from search. |
| `pending` | Still running. | `pet get --idempotency-key <key> --wait`. Never buy again to check. |
| `paused` | Your person paused you. | Wait. Do not look for another way to pay. |
| `refused` | Stopped: a no, a revoked key, a rule, a wrong request. `refused_by` says who. | Do not retry it unchanged. |
| `not_started` | No call was made with that key. | It is safe to send it again with the same key. |

Any answer may carry `warnings`. `low_balance` comes with a top-up link and a sentence: send it to
your person before you run out. `pet link` makes a link at any time.

## With your own wallet, no account

If you hold USDC and speak x402, you can skip sign-up. `POST /v1/x402/call` with
`{"provider":"exa","path":"/search","body":{...}}` answers 402 with Petrova's terms (the tool's own price, nothing added). Pay in the same
request. Petrova checks the answer before it keeps the money. Send the same signed request again to
read a lost answer: it is never paid twice. Test mode only: a live server does not offer this yet.

## Over HTTP

| Step | Route |
|---|---|
| Sign up | `POST /v1/agents/start` |
| Status | `GET /v1/agent/status` |
| Find | `POST /v1/agent/search`, `POST /v1/agent/inspect` |
| Call | `POST /v1/agent/calls` with `provider` and `path` (or `tool_id`), the inputs, `max_cost` (default $1.00), `idempotency_key` |
| Read again | `GET /v1/agent/calls?idempotency_key=...` |
| A link now | `POST /v1/agent/links` |

Money is nano-USD strings: `1000000000` is $1.00.

## Fails silently

These give no error. Check each one yourself.

1. **A new idempotency key is a new purchase.** The same key never pays twice. Reuse it after a lost
   answer; never make a new one "to check".
2. **Test answers look real.** In test mode every answer says `"mode": "fixture"`: never present those as real results. A live server says `"mode": "live"`.
3. **A link works once and ends in 30 minutes.** If your person says it does not open, or the code
   was typed wrong 5 times and the link closed, run `pet status` (or `pet link`) and pass on
   the new link and its new code.
4. **Low balance is only a warning.** Calls run until the money is gone. Send the top-up link when
   the warning first appears.
5. **An unclaimed sign-up expires.** If nobody adds money within 72 hours, the key stops working.
   Start again only if your person asks you to.

## More

- Docs: https://www.usepetrova.xyz/docs/
- What is built and what is not: https://www.usepetrova.xyz/docs/status.html
- Every page, for agents: https://www.usepetrova.xyz/llms.txt
