# Petrova agent sign-up

**Status: built in test mode.** `POST /v1/agents/start` exists in the Petrova API. No real money
moves, and https://www.usepetrova.xyz is a placeholder address: a local API answers at http://127.0.0.1:4100.

An agent signs itself up with one call: no email, no phone, no person, no form. It gets a key at
once, unclaimed, at $0. A person claims it later by paying its first link, on one phone screen.

## Rules for the agent

- Never ask a person to paste a key. Never show them the key.
- Keep the key out of chat, logs, git and command lines. `pet start` saves it privately.
- When an answer has `next_action.say_to_person`, pass it on word for word.

## 1. Sign up

```http
POST /v1/agents/start
{ "name": "research-bot" }
```

The answer:

```json
{
  "kind": "ok",
  "reason": "signed_up",
  "next_action": { "kind": "search", "command": "pet search \"<one task>\"" },
  "key": { "id": "...", "secret": "ptrv_test_...", "shown_once": true },
  "agent": { "id": "...", "name": "research-bot", "claimed": false, "expires_at": "..." },
  "free": ["search", "inspect", "quote"],
  "balance": { "balance_nusd": "0", "monthly_limit_nusd": "0", "claimed": false },
  "mode": "fixture"
}
```

The key is shown once and stored only as a hash.

## 2. Limits on sign-up

| Limit | Test-mode value |
|---|---|
| Sign-ups from one address | 5 an hour |
| Sign-ups from everyone | 200 an hour |
| An account nobody funds | Expires after 72 hours, and its key stops working |
| Free money | None. Search, inspect and quote are free; calls need money. |

Over a limit the answer is 429 `rate_limited` with `retry-after`.

## 3. The first paid call

The answer is `needs_funding` with `next_action.link.url`, `next_action.link.code` (6 digits) and
`next_action.say_to_person`. The person opens the link, sees which agent is asking and what for, the
amount, the monthly limit and the ask-me-above line, types the code, and presses one button. Paying
adds the money, sets the limits and makes them the owner.

The link works once, ends in 30 minutes, is bound to this agent and this amount, and cannot be
guessed. The page refuses a request that did not come from itself. Someone who sees only the URL
cannot pay it: without the code nothing happens, and 5 wrong codes close the link. An approval link
has a code too. A top-up link has none: paying it only adds money.

## 4. After that

`GET /v1/agent/status` says `ok` (reason `ready`), with the balance and the limit, and `news` once. The agent
can never raise its own limit: only the person can, on their limits screen.

| Error | HTTP | Meaning |
|---|---|---|
| `key_required` | 402 | No key. The answer says how to start. |
| `invalid_name` | 400 | Use a short name such as research-bot. |
| `rate_limited` | 429 | Too many sign-ups. Wait. |
| `unauthorized` | 401 | The key is wrong, revoked or expired. |
