Getting started

Fixture onlyChecked 16 November 2026

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
  • --spend gives the key quote:write, which it needs to call models. Without it the key can only read, and /v1/messages answers 403.
  • --spend --caps also gives budget: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

ClientBase URLKey goes in
Claude Code, Anthropic SDKhttp://127.0.0.1:4100 (no /v1)x-api-key (or Authorization: Bearer)
OpenAI SDK, Codexhttp://127.0.0.1:4100/v1 (with /v1)Authorization: Bearer
Every other Petrova route (/v1/balance, /v1/receipts, ...)http://127.0.0.1:4100Authorization: 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

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.