Guides / First call in 2 minutes

First call in 2 minutes

Get a key, point your agent at Petrova, make one call, and read its receipt.

For: A developer with an agent on Claude Code, Codex, or the Anthropic or OpenAI SDK.

Time: 2 minutesTest build: no real money
Today this runs on your machine.The gateway is the Petrova repository running locally (npm run dev, base URL http://127.0.0.1:4100). Answers are canned test fixtures; no real model is called. The hosted address is not live. You can also do the whole flow in the sandbox dashboard without installing anything.
  1. Get a key that can spend

    In the sandbox: sign up, pick the Agent preset, copy the key. It is shown once. Locally:

    npm ci
    npm run dev                          # gateway on http://127.0.0.1:4100
    npm run sandbox:key -- --spend       # prints a ptrv_test_ key once

    A key from plain npm run sandbox:key can only read. It gets 403 on model calls. --spend adds "Call models" (quote:write).

  2. Point your agent at Petrova

    export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
    export ANTHROPIC_API_KEY=ptrv_test_...
    claude -p "say hello"
    curl -s http://127.0.0.1:4100/v1/messages \
      -H "x-api-key: ptrv_test_..." \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{"model":"claude-opus-5-5","max_tokens":256,"messages":[{"role":"user","content":"hello"}]}' -i
    from openai import OpenAI
    client = OpenAI(base_url="http://127.0.0.1:4100/v1", api_key="ptrv_test_...")
    print(client.chat.completions.create(model="claude-opus-5-5",
          messages=[{"role": "user", "content": "hello"}]).choices[0].message.content)
    # ~/.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"

    Anthropic format: no /v1 on the base URL. OpenAI format: with /v1.

  3. Read the receipt

    Every answer has an x-petrova-receipt header. Look it up:

    curl -s http://127.0.0.1:4100/v1/receipts/<receipt id> -H "authorization: Bearer ptrv_test_..."

    Or open Receipts in the dashboard. A standard Opus 5.5 call reads like this: we held $0.099086 before sending it (the most it could cost), it used 2,000 input and 500 output tokens, list price $0.018000 plus the 5.5% fee $0.000990, so $0.018990 was charged and $0.080096 came back at once.

What you should see

  • A 200 with an answer and an x-petrova-receipt header.
  • Your balance down by the charge, never by more than the hold.

What can go wrong

You seeIt meansDo this
401 authentication_errorThe key was not acceptedCopy all of it, including ptrv_test_
403 permission_errorThe key cannot spendMake a key with "Call models"
400 invalid_request_errorUnknown model idUse an exact id like claude-opus-5-5 (models)
402 billing_error (OpenAI routes: 429 insufficient_quota)Balance is emptyAdd funds (billing)

Next

Checked against the code on 16 November 2026.