Getting started
In short
- Get a key, set the base URL, make one call, read the receipt.
- Claude Code and the Anthropic SDK use the base URL without /v1; OpenAI SDKs and Codex use it with /v1.
- Today the key comes from a local command; the sign-up flow is a preview.
Petrova is not live. Today it runs on your own machine in test mode. No real tool is paid, no real model is called and no money moves. The steps below are the real steps for that local build. On a hosted server only the address changes.
The agent path (tools, the first product)
The agent does the setup itself. Your person only pays once, when the agent asks.
One line. Say this to a coding agent (Claude Code, Codex and others):
Set up Petrova from <your origin>/skill.md
skill.md tells the agent how to connect over MCP (<your origin>/mcp) or the command line, and what to do at each step. The API serves skill.md; the hosted MCP at /mcp runs with the production start (npm run prod:local on this machine, or a server), not with npm run dev.
By hand, with the command line (from this repository: npm run --silent petrova -- <command>):
pet start --name research-bot # signs the agent up: a key at once, $0, no owner yet
pet search "web search with sources" # free: tools with price and label
pet call exa /search --input '{"query":"machine payments"}' --max-cost 0.05
The first paid call answers needs_funding with person_link, person_code (6 digits, such as 482 913) and say_to_person, the sentence to pass on. The person opens the link, types the code and pays once: that funds the balance, sets a monthly limit and an "ask me above" line, and makes them the owner. Then the same command again goes through. In test mode the pay button is a labelled test payment.
See the agent's journey, the command line and MCP.
Models (a later product)
The model gateway comes after tools. It is built and answers from test fixtures.
You need three things: a key, the base URL, and one call.
1. Get a key
Today a key comes from a local command in this repository:
npm ci
# starts the API on http://127.0.0.1:4100 with a $20 test balance
npm run dev
# prints a ptrv_test_... key once
npm run sandbox:key -- --spend
--spendgives the keyquote:write, which it needs to call models. Without it the key can only read, and/v1/messagesanswers 403.--spend --capsalso givesbudget:write, so the key can set caps. Keep cap control on a separate key if you can: a key that can raise its own cap is not much of a cap.- The secret is shown once. Petrova stores only a hash of it.
An agent can also sign itself up (pet start, above). There is no sign-up page for people and no key API yet. The dashboard preview shows the planned flow on test data.
2. Set the base URL
| Client | Base URL | Key goes in |
|---|---|---|
| Claude Code, Anthropic SDK | http://127.0.0.1:4100 (no /v1) | x-api-key (or Authorization: Bearer) |
| OpenAI SDK, Codex | http://127.0.0.1:4100/v1 (with /v1) | Authorization: Bearer |
Every other Petrova route (/v1/balance, /v1/receipts, ...) | http://127.0.0.1:4100 | Authorization: Bearer only |
The model gateway routes (/v1/messages, /v1/messages/count_tokens, /v1/chat/completions, /v1/responses) also accept the key in x-api-key or x-petrova-key, because that is how Claude Code and the SDKs send it. Every other route takes only Authorization: Bearer ptrv_test_....
3. Make your first call
curl -s http://127.0.0.1:4100/v1/messages \
-H "x-api-key: $PETROVA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-opus-5-5","max_tokens":256,"messages":[{"role":"user","content":"Say hello"}]}' -i# pip install anthropic
import anthropic
client = anthropic.Anthropic(base_url="http://127.0.0.1:4100", api_key="ptrv_test_...")
msg = client.messages.create(
model="claude-opus-5-5", max_tokens=256,
messages=[{"role": "user", "content": "Say hello"}],
)
print(msg.content[0].text)// npm install openai
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "http://127.0.0.1:4100/v1", apiKey: process.env.PETROVA_API_KEY });
const res = await client.chat.completions.create({
model: "claude-opus-5-5",
messages: [{ role: "user", content: "Say hello" }],
});
console.log(res.choices[0].message.content);export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
export ANTHROPIC_API_KEY=ptrv_test_...
claude# ~/.codex/config.toml
model = "claude-opus-5-5"
model_provider = "petrova"
[model_providers.petrova]
name = "Petrova"
base_url = "http://127.0.0.1:4100/v1"
env_key = "PETROVA_API_KEY"
wire_api = "responses"The answer is canned in this build. What matters is the receipt.
4. Read the receipt
Every answer has an x-petrova-receipt header. A stream also ends with a comment line: : x-petrova-receipt <id> outcome=completed charged_nusd=....
curl -s http://127.0.0.1:4100/v1/receipts/<receipt id> -H "authorization: Bearer $PETROVA_API_KEY"
The receipt shows what was held before the call, what the call really cost (list price plus the 5.5% fee), and what came back to you. Money is in nano-USD: "1000000000" is $1.00. For example, an Opus 5.5 call with a 9,000-byte body and max_tokens 4,096 holds $0.099086 first. It used 2,000 tokens in and 500 out, so it is charged $0.018990, and $0.080096 comes back at once. See billing.
Next
- Start with an agent and a tool: the agent's journey.
- Put a cap on your agent before it runs for long: billing, caps.
- Connect your coding tool: coding tools.
- Let your agent find costs and tools itself: MCP server.
- Check what each error means: errors.
- See what is built and what is not: status.
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.