API reference
In short
- Every route, how to send the key, and which scope it needs.
- Request and response fields from openapi.json.
- The gateway routes are listed by hand: openapi.json leaves them out.
How to send the key
Every route takes Authorization: Bearer ptrv_test_.... The four model gateway routes also take the key in x-api-key or x-petrova-key, because that is how Claude Code and the SDKs send it. Money is a string of whole nano-USD: "1000000000" is $1.00.
Download openapi.json 140 operations. It does not yet include /v1/messages or /v1/messages/count_tokens, listed by hand below.
Model gateway
POST/v1/messages
Anthropic's Messages format, sent on byte for byte. Petrova adds x-petrova-receipt (the receipt id), x-petrova-loop (warn or pause) and, with repo memory, x-petrova-memory-tokens. Agent and session caps read x-claude-code-agent-id, x-claude-code-parent-agent-id and x-claude-code-session-id.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
billing_error | 402 | No | Add funds. |
rate_limit_error | 429 | No | A cap or loop pause; check x-petrova-loop. |
invalid_request_error | 400 | No | Use an exact model id such as claude-opus-5-5. |
api_error | 502 | Yes | No supplier answered; you paid nothing. |
overloaded_error | 529 | No | All suppliers are out of capacity for today. |
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":"Hello"}]}'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": "Hello"}])import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
baseURL: "http://127.0.0.1:4100", apiKey: process.env.PETROVA_API_KEY });
const msg = await client.messages.create({ model: "claude-opus-5-5",
max_tokens: 256, messages: [{ role: "user", content: "Hello" }] });export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
export ANTHROPIC_API_KEY=ptrv_test_...
claude# ~/.codex/config.toml
# Codex uses POST /v1/responses
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"x-petrova-receipt: 3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f
x-petrova-loop: warn (only when a loop is starting)
: x-petrova-receipt … outcome=completed charged_nusd=18990000POST/v1/messages/count_tokens
Counts the tokens a request would send, the repo memory block included. Passed to the supplier; nothing is held.
Health
GET/health
Is the API process up.
Response fields
status | "ok" | "unavailable" |
mode | "fixture" |
live_spend_enabled | false |
curl -s http://127.0.0.1:4100/health \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/health",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/health", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"status": "ok",
"mode": "fixture",
"live_spend_enabled": false
}GET/ready
Is the API ready to serve (database reachable).
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unavailable | 503 | Yes | Try again shortly. |
Response fields
status | "ok" | "unavailable" |
mode | "fixture" |
live_spend_enabled | false |
curl -s http://127.0.0.1:4100/ready \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/ready",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/ready", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"status": "ok",
"mode": "fixture",
"live_spend_enabled": false
}Balance
GET/v1/balance
Your balance: total, held right now, and available.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
currency | "USD" |
total_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
available_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
reserved_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
mode | "fixture" |
as_of | string (date-time) |
curl -s http://127.0.0.1:4100/v1/balance \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/balance",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/balance", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"currency": "USD",
"total_nusd": "18742360000",
"available_nusd": "18544188800",
"reserved_nusd": "198171200",
"mode": "fixture",
"as_of": "2026-10-24T09:12:03.000Z"
}Models
GET/v1/models
The models you can call, by exact id.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
data | list of objects |
curl -s http://127.0.0.1:4100/v1/models \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/models",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/models", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"data": [
{
"id": "claude-opus-5-5",
"type": "model",
"catalog_id": "anthropic/claude-opus-5-5",
"provider": "anthropic",
"status": "current",
"context_tokens": 1000000,
"availability": "fixture",
"executable": true
}
]
}Reconciliation
GET/v1/reconciliation
Counts of calls waiting for a supplier invoice or charged on an estimate.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mismatched | integer |
awaiting | integer |
estimated optional | integer Charged on a local estimate and not yet trued up |
rows | list of objects |
curl -s http://127.0.0.1:4100/v1/reconciliation \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/reconciliation",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/reconciliation", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mismatched": 1,
"awaiting": 1,
"estimated": 1,
"rows": [
{}
]
}Quotes
POST/v1/quotes
Price the most a call could cost. A quote is bound to your key and the payload.
| Body field | Type |
|---|---|
resource | string |
payload | any |
max_price_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
ttl_seconds optional | integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
quote_id | string (uuid) |
resource | string |
payload_hash | string |
max_price_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
currency | "USD" |
mode | "fixture" |
issued_at | string (date-time) |
expires_at | string (date-time) |
curl -s -X POST http://127.0.0.1:4100/v1/quotes \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"resource":"anthropic/claude-opus-5-5/messages","payload":null,"max_price_nusd":"5000000","ttl_seconds":1}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/quotes",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"resource":"anthropic/claude-opus-5-5/messages","payload":null,"max_price_nusd":"5000000","ttl_seconds":1})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/quotes", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"resource":"anthropic/claude-opus-5-5/messages","payload":null,"max_price_nusd":"5000000","ttl_seconds":1})
});
console.log(await r.json());{
"quote_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"resource": "anthropic/claude-opus-5-5/messages",
"payload_hash": "b6f1…",
"max_price_nusd": "5000000",
"currency": "USD",
"mode": "fixture",
"issued_at": "2026-10-24T09:12:03.000Z",
"expires_at": "2026-10-24T09:12:03.000Z"
}Holds
POST/v1/holds
Hold a quote on your balance. Nothing is sent before this commits.
| Body field | Type |
|---|---|
quote_id | string (uuid) |
payload | any |
idempotency_key | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
reservation_id | string (uuid) |
replayed | boolean |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/holds \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"quote_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","payload":null,"idempotency_key":"idempotency-key"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/holds",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"quote_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","payload":null,"idempotency_key":"idempotency-key"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/holds", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"quote_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","payload":null,"idempotency_key":"idempotency-key"})
});
console.log(await r.json());{
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"replayed": false,
"mode": "fixture"
}Settlements
POST/v1/settlements
Operator only: charge what a call really cost and release the rest.
| Body field | Type |
|---|---|
reservation_id | string (uuid) |
outcome | "completed" | "failed" | "unknown_cost" |
supplier_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
supplier_reference optional | string |
usage optional | object Token usage as the upstream reported it |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
outcome | "completed" | "failed" | "unknown_cost" |
charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
released_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
absorbed_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
fee_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
replayed | boolean |
cost_basis optional | "reported" | "estimated" | "input_only" |
curl -s -X POST http://127.0.0.1:4100/v1/settlements \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"reservation_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"completed","supplier_nusd":"18990000","supplier_reference":"supplier-reference","usage":{"input_tokens":2000,"output_tokens":500,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/settlements",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"reservation_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"completed","supplier_nusd":"18990000","supplier_reference":"supplier-reference","usage":{"input_tokens":2000,"output_tokens":500,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/settlements", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"reservation_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"completed","supplier_nusd":"18990000","supplier_reference":"supplier-reference","usage":{"input_tokens":2000,"output_tokens":500,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}})
});
console.log(await r.json());{
"outcome": "completed",
"charged_nusd": "18990000",
"released_nusd": "80095600",
"absorbed_nusd": "0",
"fee_nusd": "990000",
"replayed": false,
"cost_basis": "reported"
}Caps (budgets)
POST/v1/budgets
Set a cap for the account, a project, a key, an agent or a session.
| Body field | Type |
|---|---|
scope | "account" | "project" | "key" | "agent" | "session" |
ref optional | string agent/session: the x-claude-code-agent-id or x-claude-code-session-id value (required). project/key: a project or key id of this account (default: the calling key's own). account: omit |
limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
scope | "account" | "project" | "key" | "agent" | "session" |
ref | string |
limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
committed_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
remaining_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/budgets \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"scope":"account","ref":"ref","limit_nusd":"5000000000"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/budgets",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"scope":"account","ref":"ref","limit_nusd":"5000000000"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/budgets", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"scope":"account","ref":"ref","limit_nusd":"5000000000"})
});
console.log(await r.json());{
"scope": "account",
"ref": "ref",
"limit_nusd": "5000000000",
"committed_nusd": "3900000000",
"remaining_nusd": "1100000000",
"mode": "fixture"
}Receipts
GET/v1/receipts
Your receipts, newest first; filter by agent or session.
| Parameter | In · type |
|---|---|
session_id optional | query · string |
agent_id optional | query · string |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
total_charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/receipts \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/receipts",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/receipts", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"resource": "anthropic/claude-opus-5-5/messages",
"upstreams_attempted": [
"fixture-primary"
],
"refund_nusd": "0",
"true_up_refunded_nusd": "0",
"cost_basis": "reported",
"list_nusd": "18000000",
"saving_nusd": "0",
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"created_at": "2026-10-24T09:12:03.000Z",
"settled_at": "2026-10-24T09:12:03.000Z",
"model": "claude-opus-5-5",
"upstream": "fixture-secondary",
"agent_id": "research-bot",
"parent_agent_id": "planner",
"session_id": "sess_7f2a91",
"input_tokens": 2000,
"output_tokens": 500,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"held_nusd": "99085600",
"list_price_nusd": "18000000",
"fee_nusd": "990000",
"charged_nusd": "18990000",
"absorbed_nusd": "0",
"released_nusd": "80095600",
"status": "held",
"checked": true,
"check_verdict": "pass",
"refunded_nusd": "0"
}
],
"total_charged_nusd": "18990000",
"mode": "fixture"
}GET/v1/receipts/{id}
One receipt: held, charged, given back, and every supplier tried.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
resource | string What was quoted, e.g. anthropic/claude-opus-5-5/messages or tool:<id> |
upstreams_attempted | list of string Every supplier an attempt went to, in order (failover history) |
refund_nusd | nano-USD string or null A refund (seller check, operator) |
true_up_refunded_nusd | nano-USD string or null Given back when the supplier invoice arrived |
cost_basis | "reported" | "estimated" | "input_only" or null |
list_nusd | nano-USD string or null Reseller calls: the same usage at list price |
saving_nusd | nano-USD string or null Reseller calls: list minus what was paid |
id | string (uuid) |
created_at | string (date-time) |
settled_at | string (date-time) or null |
model | string |
upstream | string or null |
agent_id | string or null |
parent_agent_id | string or null |
session_id | string or null |
input_tokens | integer or null |
output_tokens | integer or null |
cache_read_input_tokens | integer or null |
cache_creation_input_tokens | integer or null |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
list_price_nusd | nano-USD string or null Supplier cost before the Petrova fee |
fee_nusd | nano-USD string or null |
charged_nusd | nano-USD string or null |
absorbed_nusd | nano-USD string or null |
released_nusd | nano-USD string or null |
status | "held" | "released" | "completed" | "failed" | "unknown_cost" |
checked | boolean Sampled for a seller re-check against a reference upstream |
check_verdict | "pass" | "fail" or null |
refunded_nusd | nano-USD string or null Returned to the balance by a refund or a true-up (their sum); charged_nusd keeps the original charge |
curl -s http://127.0.0.1:4100/v1/receipts/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/receipts/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/receipts/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"resource": "anthropic/claude-opus-5-5/messages",
"upstreams_attempted": [
"fixture-primary"
],
"refund_nusd": "0",
"true_up_refunded_nusd": "0",
"cost_basis": "reported",
"list_nusd": "18000000",
"saving_nusd": "0",
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"created_at": "2026-10-24T09:12:03.000Z",
"settled_at": "2026-10-24T09:12:03.000Z",
"model": "claude-opus-5-5",
"upstream": "fixture-secondary",
"agent_id": "research-bot",
"parent_agent_id": "planner",
"session_id": "sess_7f2a91",
"input_tokens": 2000,
"output_tokens": 500,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"held_nusd": "99085600",
"list_price_nusd": "18000000",
"fee_nusd": "990000",
"charged_nusd": "18990000",
"absorbed_nusd": "0",
"released_nusd": "80095600",
"status": "held",
"checked": true,
"check_verdict": "pass",
"refunded_nusd": "0"
}Tools
GET/v1/tools
Search the paid tool catalogue.
| Parameter | In · type |
|---|---|
query optional | query · string |
max_price_nusd optional | query · nano-USD string |
category optional | query · string |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
data | list of objects |
curl -s http://127.0.0.1:4100/v1/tools \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"source": "x402_bazaar",
"name": "Chain Scout",
"provider": "anthropic",
"provider_key": "provider-key",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"description": "Answers questions about Base tokens in plain words",
"category": "search",
"tags": [
"tags"
],
"input_schema": {},
"price_nusd": "5000000",
"price_usd": "0.005",
"price_kind": "fixed",
"price_hint": "price-hint",
"listing_status": "listed",
"scheme": "x402_exact",
"network": "network",
"health": "unknown",
"last_checked_at": "2026-10-24T09:12:03.000Z",
"payer_count": 412,
"variants": 1,
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"tier": "listed",
"provider_slug": "provider-slug",
"path": "path",
"integration": "first_party",
"pay_method": "pay-method"
}
]
}POST/v1/tools/search
Write tools/search.
| Body field | Type |
|---|---|
task | string One task in plain language, e.g. find a person's work email from name and company |
max_price_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
category optional | string |
limit optional | integer |
payable_only optional | boolean Only tools whose payment terms Petrova could settle and that ask for nothing beyond payment |
card_aware optional | boolean Answer for this key's own card: only tools it may call and can afford, each with a card field |
card_id optional | string (uuid) Answer for this card. Needs card:write, or the key of that card |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
interpretation | object |
confident | boolean The words match a category the task names. Says nothing about whether the tool works |
data | list of objects |
curl -s -X POST http://127.0.0.1:4100/v1/tools/search \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"task":"task","max_price_nusd":"5000000","category":"search","limit":1,"payable_only":false,"card_aware":false,"card_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/search",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"task":"task","max_price_nusd":"5000000","category":"search","limit":1,"payable_only":false,"card_aware":false,"card_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/search", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"task":"task","max_price_nusd":"5000000","category":"search","limit":1,"payable_only":false,"card_aware":false,"card_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
});
console.log(await r.json());{
"mode": "fixture",
"interpretation": {
"categories": [
"categories"
],
"terms": [
"terms"
]
},
"confident": false,
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"provider": "anthropic",
"provider_key": "provider-key",
"category": "search",
"description": "Answers questions about Base tokens in plain words",
"method": "GET",
"price_nusd": "5000000",
"price_usd": "0.005",
"price_kind": "fixed",
"price_hint": "price-hint",
"listing_status": "listed",
"health": "unknown",
"payer_count_30d_directory": 1,
"works": {
"samples": 1,
"success_rate": 0.97
},
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"variants": 1,
"score": 0.82,
"coverage": 0.82,
"matched_terms": [
"matched-terms"
],
"tier": "listed",
"provider_slug": "provider-slug",
"path": "path",
"integration": "first_party",
"rail": "fixture_usdc_base",
"provider_match": "domain",
"card": {
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"needs_approval": false,
"within_allowance": false
}
}
]
}GET/v1/tools/discover
Read tools/discover.
| Parameter | In · type |
|---|---|
query optional | query · string |
provider optional | query · string |
category optional | query · string |
status optional | query · "listed" | "checked" | "passed_paid_call" |
max_price_nusd optional | query · nano-USD string |
limit optional | query · integer |
cursor optional | query · string |
card_aware optional | query · boolean |
card_id optional | query · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
data | list of objects |
next_cursor | string or null |
curl -s http://127.0.0.1:4100/v1/tools/discover \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/discover",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/discover", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"provider": "anthropic",
"provider_key": "provider-key",
"category": "search",
"description": "Answers questions about Base tokens in plain words",
"method": "GET",
"price_nusd": "5000000",
"price_usd": "0.005",
"price_kind": "fixed",
"price_hint": "price-hint",
"listing_status": "listed",
"health": "unknown",
"payer_count_30d_directory": 1,
"works": {
"samples": 1,
"success_rate": 0.97
},
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"variants": 1,
"score": 0.82,
"coverage": 0.82,
"matched_terms": [
"matched-terms"
],
"tier": "listed",
"provider_slug": "provider-slug",
"path": "path",
"integration": "first_party",
"rail": "fixture_usdc_base",
"provider_match": "domain",
"card": {
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"needs_approval": false,
"within_allowance": false
}
}
],
"next_cursor": "next-cursor"
}GET/v1/tools/providers
Read tools/providers.
| Parameter | In · type |
|---|---|
query optional | query · string |
category optional | query · string |
limit optional | query · integer |
cursor optional | query · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
next_cursor | string or null |
curl -s http://127.0.0.1:4100/v1/tools/providers \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/providers",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/providers", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"provider_key": "provider-key",
"name": "Chain Scout",
"tools": 1,
"listed": 1,
"checked": 1,
"passed_paid_call": 1,
"categories": [
"categories"
],
"lowest_price_nusd": "5000000",
"max_payers_30d_directory": 1
}
],
"next_cursor": "next-cursor"
}GET/v1/tools/stats
Read tools/stats.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
status | object Separate on purpose. Only passed_paid_call means a real call worked |
meaning | object |
hidden | integer |
providers | integer |
by_category | object |
by_source | object |
last_updated | string (date-time) or null |
curl -s http://127.0.0.1:4100/v1/tools/stats \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/stats",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/stats", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"status": {
"listed": 1,
"checked": 1,
"passed_paid_call": 1
},
"meaning": {},
"hidden": 1,
"providers": 1,
"by_category": {},
"by_source": {},
"last_updated": "2026-10-24T09:12:03.000Z"
}GET/v1/tools/{id}/inspect
Read tools/:id/inspect.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
source | "x402_bazaar" | "mpp" | "manual" | "petrova_seller" | "petrova_native"petrova_seller: another Petrova agent, paid inside the ledger; petrova_native: served by Petrova itself (chain.watch) |
name | string |
provider | string The name the listing gives itself. A claim, not proof of who runs it |
provider_key | string Who controls the host, from the url or curated directory entry. Group by this |
method | string |
url | string |
description | string |
category | string |
tags | list of string |
input_schema | object |
price_nusd | nano-USD string or null |
price_usd | string or null |
price_kind | "fixed" | "upto" | "per_unit" | "dynamic" | "session"fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure |
price_hint | string or null |
listing_status | "listed" | "checked" | "passed_paid_call"listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result |
scheme | "x402_exact" | "x402_upto" | "mpp" | "petrova_ledger" | "petrova_metered" |
network | string or null |
health | "unknown" | "healthy" | "unhealthy" | "price_mismatch" | "payto_changed" |
last_checked_at | string (date-time) or null |
payer_count | integer |
variants | integer Template-farm endpoints collapsed into this listing |
callable | boolean Whether a call would be attempted in this build. Every real listing is false: only loopback fixtures can be paid |
not_callable_reason | "mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" or null |
tier optional | "listed" | "verified" | "proven"listed: a directory lists it. verified: an unpaid request got a valid payment challenge matching the listing. proven: a real payment with a real signer got a checked result; test mode never sets it |
provider_slug optional | string or null |
path optional | string The path template, e.g. /search or /items/{id} |
integration optional | "first_party" | "third_party" or null |
pay_method optional | string or null |
inputs | list of objects |
schema_quality | "typed" | "examples" | "none"typed: the listing declares its inputs. examples: guessed from a sample. none: nothing published |
cost | object |
account | object |
evidence | object |
docs_url | string or null |
how_to_call | object |
seller optional | object Only for a tool sold by another Petrova account |
curl -s http://127.0.0.1:4100/v1/tools/<id>/inspect \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/<id>/inspect",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/inspect", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"source": "x402_bazaar",
"name": "Chain Scout",
"provider": "anthropic",
"provider_key": "provider-key",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"description": "Answers questions about Base tokens in plain words",
"category": "search",
"tags": [
"tags"
],
"input_schema": {},
"price_nusd": "5000000",
"price_usd": "0.005",
"price_kind": "fixed",
"price_hint": "price-hint",
"listing_status": "listed",
"scheme": "x402_exact",
"network": "network",
"health": "unknown",
"last_checked_at": "2026-10-24T09:12:03.000Z",
"payer_count": 412,
"variants": 1,
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"tier": "listed",
"provider_slug": "provider-slug",
"path": "path",
"integration": "first_party",
"pay_method": "pay-method",
"inputs": [
{
"name": "Chain Scout",
"in": "query",
"required": false,
"type": "type",
"description": "Answers questions about Base tokens in plain words",
"enum": [],
"default": null,
"example": null
}
],
"schema_quality": "typed",
"cost": {
"kind": "fixed",
"hint": "hint",
"price_nusd": "5000000",
"fee_nusd": "990000",
"total_nusd": "18742360000",
"total_usd": "total-usd",
"ceiling": false
},
"account": {
"needs": "none_declared",
"explanation": "explanation",
"paid_from": "paid-from"
},
"evidence": {
"listing_status": "listed",
"last_checked_at": "2026-10-24T09:12:03.000Z",
"paid_proof_at": "2026-10-24T09:12:03.000Z",
"directory": {
"payers_30d": 1,
"calls_30d": 1,
"last_called_at": "2026-10-24T09:12:03.000Z",
"note": "note"
},
"petrova_calls": {
"samples": 1,
"success_rate": 0.97
}
},
"docs_url": "https://example.invalid/",
"how_to_call": {
"quote": "quote",
"call": "call"
},
"seller": {
"agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"reviewed": false,
"version": 1,
"reviewed_at": "2026-10-24T09:12:03.000Z",
"host_verified_by": "http_token",
"checks_output": false
}
}POST/v1/tools/{id}/quote
Write tools/:id/quote.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
inputs | object |
max_cost_nusd optional | nano-USD string Report whether the cost fits this ceiling |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
tool_id | string (uuid) |
spent_nusd | "0"A quote never spends or holds anything |
valid | boolean |
validation | object |
price_nusd | nano-USD string or null |
fee_nusd | nano-USD string or null |
total_nusd | nano-USD string or null |
total_usd | string or null |
price_kind | "fixed" | "upto" | "per_unit" | "dynamic" | "session"fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure |
price_hint | string or null |
ceiling | boolean True when total_nusd is the most this call can cost |
within_max_cost | boolean or null |
enough_balance | boolean or null |
remaining_allowance_nusd | nano-USD string or null |
callable | boolean |
not_callable_reason | "mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" | "card_paused" | "card_closed" | "tool_not_allowed" | "write_not_allowed" | "per_call_limit" | "budget_exceeded" | "insufficient_balance" | "self_dealing" | "seller_paused" or null |
needs_approval | boolean or null |
listing_status | "listed" | "checked" | "passed_paid_call"listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result |
request | object or null |
curl -s -X POST http://127.0.0.1:4100/v1/tools/<id>/quote \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"inputs":{},"max_cost_nusd":"18990000"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/<id>/quote",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"inputs":{},"max_cost_nusd":"18990000"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/quote", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"inputs":{},"max_cost_nusd":"18990000"})
});
console.log(await r.json());{
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"spent_nusd": "0",
"valid": false,
"validation": {
"checked": true,
"errors": [
{
"field": "field",
"code": "PTRV-7K2Q",
"message": "message"
}
],
"warnings": [
{
"field": "field",
"code": "PTRV-7K2Q",
"message": "message"
}
],
"not_checked": [
"not-checked"
]
},
"price_nusd": "5000000",
"fee_nusd": "990000",
"total_nusd": "18742360000",
"total_usd": "total-usd",
"price_kind": "fixed",
"price_hint": "price-hint",
"ceiling": false,
"within_max_cost": false,
"enough_balance": false,
"remaining_allowance_nusd": "1100000000",
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"needs_approval": false,
"listing_status": "listed",
"request": {
"method": "GET",
"url": "https://chain-scout.example/v1/ask"
}
}POST/v1/tools/{id}/rating
Write tools/:id/rating.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
call_id | string (uuid) From your own call to this tool |
outcome | "useful" | "not_useful" | "empty" | "partial" | "unknown"Only useful and not_useful move ranking. Empty, partial and unknown stay neutral |
reason_code optional | "wrong_result" | "low_quality" | "stale" | "too_slow" | "bad_format" | "other" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
tool_id | string (uuid) |
call_id | string (uuid) |
outcome | "useful" | "not_useful" | "empty" | "partial" | "unknown"Only useful and not_useful move ranking. Empty, partial and unknown stay neutral |
reason_code | "wrong_result" | "low_quality" | "stale" | "too_slow" | "bad_format" | "other" or null |
replaced_earlier_rating | boolean |
counts_in_ranking | boolean |
rated_at | string (date-time) |
curl -s -X POST http://127.0.0.1:4100/v1/tools/<id>/rating \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"call_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"useful","reason_code":"wrong_result"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/<id>/rating",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"call_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"useful","reason_code":"wrong_result"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/rating", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"call_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","outcome":"useful","reason_code":"wrong_result"})
});
console.log(await r.json());{
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "useful",
"reason_code": "wrong_result",
"replaced_earlier_rating": false,
"counts_in_ranking": false,
"rated_at": "2026-10-24T09:12:03.000Z"
}GET/v1/tools/{id}
One tool with its input schema and price.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
source | "x402_bazaar" | "mpp" | "manual" | "petrova_seller" | "petrova_native"petrova_seller: another Petrova agent, paid inside the ledger; petrova_native: served by Petrova itself (chain.watch) |
name | string |
provider | string The name the listing gives itself. A claim, not proof of who runs it |
provider_key | string Who controls the host, from the url or curated directory entry. Group by this |
method | string |
url | string |
description | string |
category | string |
tags | list of string |
input_schema | object |
price_nusd | nano-USD string or null |
price_usd | string or null |
price_kind | "fixed" | "upto" | "per_unit" | "dynamic" | "session"fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure |
price_hint | string or null |
listing_status | "listed" | "checked" | "passed_paid_call"listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result |
scheme | "x402_exact" | "x402_upto" | "mpp" | "petrova_ledger" | "petrova_metered" |
network | string or null |
health | "unknown" | "healthy" | "unhealthy" | "price_mismatch" | "payto_changed" |
last_checked_at | string (date-time) or null |
payer_count | integer |
variants | integer Template-farm endpoints collapsed into this listing |
callable | boolean Whether a call would be attempted in this build. Every real listing is false: only loopback fixtures can be paid |
not_callable_reason | "mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" or null |
tier optional | "listed" | "verified" | "proven"listed: a directory lists it. verified: an unpaid request got a valid payment challenge matching the listing. proven: a real payment with a real signer got a checked result; test mode never sets it |
provider_slug optional | string or null |
path optional | string The path template, e.g. /search or /items/{id} |
integration optional | "first_party" | "third_party" or null |
pay_method optional | string or null |
curl -s http://127.0.0.1:4100/v1/tools/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/tools/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"source": "x402_bazaar",
"name": "Chain Scout",
"provider": "anthropic",
"provider_key": "provider-key",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"description": "Answers questions about Base tokens in plain words",
"category": "search",
"tags": [
"tags"
],
"input_schema": {},
"price_nusd": "5000000",
"price_usd": "0.005",
"price_kind": "fixed",
"price_hint": "price-hint",
"listing_status": "listed",
"scheme": "x402_exact",
"network": "network",
"health": "unknown",
"last_checked_at": "2026-10-24T09:12:03.000Z",
"payer_count": 412,
"variants": 1,
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"tier": "listed",
"provider_slug": "provider-slug",
"path": "path",
"integration": "first_party",
"pay_method": "pay-method"
}POST/v1/tools/{id}/call
Call a paid tool. Refused if it now costs more than your max.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
inputs | object |
max_cost_nusd | nano-USD string Ceiling on price plus Petrova fee for this call |
idempotency_key optional | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
upstream failed | 502 | Yes | A supplier or tool failed; you paid nothing. Retry. |
Response fields
call_id | string (uuid) |
tool_id | string (uuid) |
outcome | "paid" | "free" | "failed" | "payment_rejected" |
http_status | integer or null |
price_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
fee_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
charged_usd | string |
reservation_id | string (uuid) or null |
payment_reference | string or null |
result | any The tool response: parsed JSON, or text |
failure optional | string |
absorbed_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
provider_hidden optional | boolean |
curl -s -X POST http://127.0.0.1:4100/v1/tools/<id>/call \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/tools/<id>/call",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/tools/<id>/call", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key"})
});
console.log(await r.json());{
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "paid",
"http_status": 200,
"price_nusd": "5000000",
"fee_nusd": "990000",
"charged_nusd": "18990000",
"charged_usd": "charged-usd",
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"payment_reference": "payment-reference",
"result": null,
"failure": "failure",
"absorbed_nusd": "0",
"provider_hidden": false
}Listings (Earn-to-Run)
POST/v1/listings
List your endpoint as a paid tool for other agents.
| Body field | Type |
|---|---|
agent_name optional | string |
method optional | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" |
url | string |
description | string |
input_schema optional | object |
price_nusd | nano-USD string What a buyer pays per successful call. No markup; the seller pays the fee |
category | string |
success_check | object |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
source | "x402_bazaar" | "mpp" | "manual" | "petrova_seller" | "petrova_native"petrova_seller: another Petrova agent, paid inside the ledger; petrova_native: served by Petrova itself (chain.watch) |
name | string |
provider | string The name the listing gives itself. A claim, not proof of who runs it |
provider_key | string Who controls the host, from the url or curated directory entry. Group by this |
method | string |
url | string |
description | string |
category | string |
tags | list of string |
input_schema | object |
price_nusd | nano-USD string or null |
price_usd | string or null |
price_kind | "fixed" | "upto" | "per_unit" | "dynamic" | "session"fixed: exactly this. upto: at most this. per_unit: this per unit. dynamic and session: priced when called, so the listed number, if any, is only a starting figure |
price_hint | string or null |
listing_status | "listed" | "checked" | "passed_paid_call"listed: a directory lists it, nothing was sent to it. checked: it answered an unpaid request with a valid payment challenge. passed_paid_call: a real payment got a real result |
scheme | "x402_exact" | "x402_upto" | "mpp" | "petrova_ledger" | "petrova_metered" |
network | string or null |
health | "unknown" | "healthy" | "unhealthy" | "price_mismatch" | "payto_changed" |
last_checked_at | string (date-time) or null |
payer_count | integer |
variants | integer Template-farm endpoints collapsed into this listing |
callable | boolean Whether a call would be attempted in this build. Every real listing is false: only loopback fixtures can be paid |
not_callable_reason | "mpp_payment_not_built" | "mpp_method_unknown" | "mpp_method_not_supported" | "mpp_intent_not_supported" | "subscription_tool" | "payment_network_not_supported" | "needs_wallet_signature" | "needs_provider_api_key" | "fixture_only" or null |
tier optional | "listed" | "verified" | "proven"listed: a directory lists it. verified: an unpaid request got a valid payment challenge matching the listing. proven: a real payment with a real signer got a checked result; test mode never sets it |
provider_slug optional | string or null |
path optional | string The path template, e.g. /search or /items/{id} |
integration optional | "first_party" | "third_party" or null |
pay_method optional | string or null |
seller_agent_id | string (uuid) |
fee_bps | integer Taken from each sale, paid by the seller |
success_check | object |
curl -s -X POST http://127.0.0.1:4100/v1/listings \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"agent_name":"agent-name","method":"GET","url":"https://chain-scout.example/v1/ask","description":"Answers questions about Base tokens in plain words","input_schema":{},"price_nusd":"5000000","category":"search","success_check":{"type":"http_2xx","field":"field"}}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/listings",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"agent_name":"agent-name","method":"GET","url":"https://chain-scout.example/v1/ask","description":"Answers questions about Base tokens in plain words","input_schema":{},"price_nusd":"5000000","category":"search","success_check":{"type":"http_2xx","field":"field"}})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/listings", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"agent_name":"agent-name","method":"GET","url":"https://chain-scout.example/v1/ask","description":"Answers questions about Base tokens in plain words","input_schema":{},"price_nusd":"5000000","category":"search","success_check":{"type":"http_2xx","field":"field"}})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"source": "x402_bazaar",
"name": "Chain Scout",
"provider": "anthropic",
"provider_key": "provider-key",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"description": "Answers questions about Base tokens in plain words",
"category": "search",
"tags": [
"tags"
],
"input_schema": {},
"price_nusd": "5000000",
"price_usd": "0.005",
"price_kind": "fixed",
"price_hint": "price-hint",
"listing_status": "listed",
"scheme": "x402_exact",
"network": "network",
"health": "unknown",
"last_checked_at": "2026-10-24T09:12:03.000Z",
"payer_count": 412,
"variants": 1,
"callable": true,
"not_callable_reason": "mpp_payment_not_built",
"tier": "listed",
"provider_slug": "provider-slug",
"path": "path",
"integration": "first_party",
"pay_method": "pay-method",
"seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"fee_bps": 750,
"success_check": {
"type": "http_2xx",
"field": "field"
}
}Earnings and payouts
GET/v1/earnings
What your agent earned and what you can withdraw.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
deposited_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
earned_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
fees_paid_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
repaid_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
to_bills_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
to_owner_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
owner_balance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
withdrawable_nusd | nano-USD string What the owner can withdraw now: owner balance less the refund hold-back, pay-later debt and any reserve shortfall |
held_for_few_buyers_nusd | nano-USD string Income from reviewed listings that stays put until 3 different owners have paid them |
pay_later | object |
rules | object or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/earnings \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/earnings",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/earnings", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"deposited_nusd": "18990000",
"earned_nusd": "46250000000",
"fees_paid_nusd": "990000",
"repaid_nusd": "18990000",
"to_bills_nusd": "18990000",
"to_owner_nusd": "18990000",
"owner_balance_nusd": "18990000",
"withdrawable_nusd": "29000000000",
"held_for_few_buyers_nusd": "99085600",
"pay_later": {
"limit_nusd": "5000000000",
"receivable_nusd": "18990000",
"headroom_nusd": "18990000",
"income_7d_nusd": "18990000"
},
"rules": {
"bills_share_bps": 2000,
"daily_cap_nusd": "5000000000",
"reserve_nusd": "18990000"
},
"mode": "fixture"
}POST/v1/earnings/rules
Where earnings go first: debt, reserve, bills, then you.
| Body field | Type |
|---|---|
bills_share_bps | integer Share of income (after debt and reserve) kept for the agent own bills |
daily_cap_nusd optional | nano-USD string or null |
reserve_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
deposited_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
earned_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
fees_paid_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
repaid_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
to_bills_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
to_owner_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
owner_balance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
withdrawable_nusd | nano-USD string What the owner can withdraw now: owner balance less the refund hold-back, pay-later debt and any reserve shortfall |
held_for_few_buyers_nusd | nano-USD string Income from reviewed listings that stays put until 3 different owners have paid them |
pay_later | object |
rules | object or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/earnings/rules \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"bills_share_bps":2000,"daily_cap_nusd":"5000000000","reserve_nusd":"18990000"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/earnings/rules",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"bills_share_bps":2000,"daily_cap_nusd":"5000000000","reserve_nusd":"18990000"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/earnings/rules", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"bills_share_bps":2000,"daily_cap_nusd":"5000000000","reserve_nusd":"18990000"})
});
console.log(await r.json());{
"deposited_nusd": "18990000",
"earned_nusd": "46250000000",
"fees_paid_nusd": "990000",
"repaid_nusd": "18990000",
"to_bills_nusd": "18990000",
"to_owner_nusd": "18990000",
"owner_balance_nusd": "18990000",
"withdrawable_nusd": "29000000000",
"held_for_few_buyers_nusd": "99085600",
"pay_later": {
"limit_nusd": "5000000000",
"receivable_nusd": "18990000",
"headroom_nusd": "18990000",
"income_7d_nusd": "18990000"
},
"rules": {
"bills_share_bps": 2000,
"daily_cap_nusd": "5000000000",
"reserve_nusd": "18990000"
},
"mode": "fixture"
}POST/v1/earnings/withdraw
Withdraw to your verified wallet. Whole micro-USD only.
| Body field | Type |
|---|---|
amount_nusd | string Integer nano-USD, a whole number of micro-USD (divisible by 1000) |
idempotency_key | string Reuse to make a retry safe: the same key never pays out twice |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
payout_id | string (uuid) |
state | "requested" | "sent" | "failed" |
amount_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
usdc_units | string USDC base units (6 decimals) |
rail | "fixture_usdc_base"Fixture stub rail: no transfer is made |
destination | string The owner's verified wallet |
rail_reference | string or null |
failure_reason | string or null |
created_at | string (date-time) |
closed_at | string (date-time) or null |
replayed | boolean |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/earnings/withdraw \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"amount_nusd":"amount-nusd","idempotency_key":"idempotency-key"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/earnings/withdraw",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"amount_nusd":"amount-nusd","idempotency_key":"idempotency-key"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/earnings/withdraw", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"amount_nusd":"amount-nusd","idempotency_key":"idempotency-key"})
});
console.log(await r.json());{
"payout_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"state": "requested",
"amount_nusd": "20000000000",
"usdc_units": "usdc-units",
"rail": "fixture_usdc_base",
"destination": "0x9f00000000000000000000000000000000000a11",
"rail_reference": "rail-reference",
"failure_reason": "failure-reason",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"replayed": false,
"mode": "fixture"
}Agent scores
GET/v1/agents/{id}/score
A public score for a selling agent. No amounts or ids.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
agent_id | string (uuid) |
name | string |
window_days | integer |
distinct_paying_owners_30d | integer |
success_rate | number or null |
refund_rate | number or null |
median_latency_ms | integer or null |
revenue_band | "none" | "under_10_usd" | "10_to_100_usd" | "100_to_1k_usd" | "1k_to_10k_usd" | "10k_usd_plus"Gross paid revenue over the window, as a band only |
curl -s http://127.0.0.1:4100/v1/agents/<id>/score \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agents/<id>/score",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agents/<id>/score", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"window_days": 30,
"distinct_paying_owners_30d": 7,
"success_rate": 0.97,
"refund_rate": 0.97,
"median_latency_ms": 840,
"revenue_band": "none"
}POST/v1/agents/start
Write agents/start.
| Body field | Type |
|---|---|
name | string What to call this agent, such as research-bot |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started" |
refused_by | string or null |
reason | string |
message | string |
next_action | object What to do now. Always present |
curl -s -X POST http://127.0.0.1:4100/v1/agents/start \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"name":"Chain Scout"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agents/start",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"name":"Chain Scout"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agents/start", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"name":"Chain Scout"})
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "refused-by",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
}
}Repo memory
POST/v1/repos
Write repos.
| Body field | Type |
|---|---|
name | string |
remote_hash optional | string Optional SHA-256 of the remote URL; the URL itself is never sent |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
name | string |
remote_hash | string or null |
created_at | string (date-time) |
created | boolean |
curl -s -X POST http://127.0.0.1:4100/v1/repos \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"name":"Chain Scout","remote_hash":"remote-hash"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/repos",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"name":"Chain Scout","remote_hash":"remote-hash"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/repos", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"name":"Chain Scout","remote_hash":"remote-hash"})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"remote_hash": "remote-hash",
"created_at": "2026-10-24T09:12:03.000Z",
"created": false
}DELETE/v1/repos/{repo}
Delete repos/:repo.
| Parameter | In · type |
|---|---|
repo | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
repo | string |
erased | true |
commits | integer |
blobs | integer File summaries and their symbols deleted (blobs no other repo uses) |
memories | integer |
curl -s -X DELETE http://127.0.0.1:4100/v1/repos/<repo> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/repos/<repo>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"repo": "petrova",
"erased": true,
"commits": 1,
"blobs": 1,
"memories": 1
}POST/v1/repos/{repo}/missing-blobs
Write repos/:repo/missing-blobs.
| Parameter | In · type |
|---|---|
repo | path · string |
| Body field | Type |
|---|---|
blob_shas | list of string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
missing | list of string |
curl -s -X POST http://127.0.0.1:4100/v1/repos/<repo>/missing-blobs \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"blob_shas":["blob-shas"]}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/repos/<repo>/missing-blobs",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"blob_shas":["blob-shas"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/missing-blobs", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"blob_shas":["blob-shas"]})
});
console.log(await r.json());{
"missing": [
"missing"
]
}POST/v1/repos/{repo}/commits/{sha}/index
Write repos/:repo/commits/:sha/index.
| Parameter | In · type |
|---|---|
repo | path · string |
sha | path · string |
| Body field | Type |
|---|---|
parent_sha optional | string |
files optional | list of objects |
changes optional | object |
blobs optional | list of objects Contents of blobs the server does not have (UTF-8 text, at most 256 KiB each) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
upstream failed | 502 | Yes | A supplier or tool failed; you paid nothing. Retry. |
Response fields
repo | string |
commit | string |
state | "pending" | "indexed" | "failed" |
parent_sha | string or null |
files | integer |
loc | integer |
new_blobs | integer |
renderer_version | string or null |
block_hash | string or null |
block_tokens | integer or null |
reservation_id | string (uuid) or null |
replayed | boolean |
charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
queued optional | boolean True when the memory worker will summarise, render and settle this commit; poll GET .../commits/{sha} |
curl -s -X POST http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>/index \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"parent_sha":"parent-sha","files":[{"path":"path","blob_sha":"blob-sha"}],"changes":{"upsert":[{"path":"path","blob_sha":"blob-sha"}],"delete":["delete"]},"blobs":[{"blob_sha":"blob-sha","content":"content"}]}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>/index",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"parent_sha":"parent-sha","files":[{"path":"path","blob_sha":"blob-sha"}],"changes":{"upsert":[{"path":"path","blob_sha":"blob-sha"}],"delete":["delete"]},"blobs":[{"blob_sha":"blob-sha","content":"content"}]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>/index", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"parent_sha":"parent-sha","files":[{"path":"path","blob_sha":"blob-sha"}],"changes":{"upsert":[{"path":"path","blob_sha":"blob-sha"}],"delete":["delete"]},"blobs":[{"blob_sha":"blob-sha","content":"content"}]})
});
console.log(await r.json());{
"repo": "petrova",
"commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
"state": "pending",
"parent_sha": "parent-sha",
"files": 812,
"loc": 61234,
"new_blobs": 1,
"renderer_version": "1",
"block_hash": "ab12…",
"block_tokens": 1180,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"replayed": false,
"charged_nusd": "18990000",
"queued": false
}GET/v1/repos/{repo}/commits/{sha}
Read repos/:repo/commits/:sha.
| Parameter | In · type |
|---|---|
repo | path · string |
sha | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
repo | string |
commit | string |
state | "pending" | "indexed" | "failed" |
parent_sha | string or null |
files | integer |
loc | integer |
new_blobs | integer |
renderer_version | string or null |
block_hash | string or null |
block_tokens | integer or null |
reservation_id | string (uuid) or null |
curl -s http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/commits/<sha>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"repo": "petrova",
"commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
"state": "pending",
"parent_sha": "parent-sha",
"files": 812,
"loc": 61234,
"new_blobs": 1,
"renderer_version": "1",
"block_hash": "ab12…",
"block_tokens": 1180,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
}GET/v1/repos/{repo}/context
Read repos/:repo/context.
| Parameter | In · type |
|---|---|
repo | path · string |
commit optional | query · string |
paths optional | query · string |
ancestors optional | query · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
repo | string |
requested_commit | string |
commit | string |
exact | boolean false when answered from the nearest indexed ancestor |
renderer_version | string |
block_hash | string |
tokens | integer |
block_text optional | string |
truncated optional | boolean |
files optional | list of objects |
curl -s http://127.0.0.1:4100/v1/repos/<repo>/context \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/repos/<repo>/context",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/repos/<repo>/context", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"repo": "petrova",
"requested_commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
"commit": "4fe0ba0c2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f60",
"exact": false,
"renderer_version": "1",
"block_hash": "ab12…",
"tokens": 1180,
"block_text": "block-text",
"truncated": false,
"files": [
{
"path": "path",
"lang": "lang",
"summary": "New token FOO launched with $42,000 liquidity",
"symbols": [
{
"name": null,
"kind": null,
"line": null,
"signature": null
}
]
}
]
}Saved memories
POST/v1/memories
Save a memory (1 to 1,000 characters).
| Body field | Type |
|---|---|
text | string |
kind optional | "fact" | "decision" | "convention" |
repo optional | string |
pinned optional | boolean Pinned memories are injected with the repo block |
scope optional | "account" | "project"account (default): every key; project: keys of this project |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
kind | "fact" | "decision" | "convention" |
text | string |
pinned | boolean |
repo | string or null |
scope | "account" | "project" |
created_at | string (date-time) |
curl -s -X POST http://127.0.0.1:4100/v1/memories \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"text":"Money is nano-USD bigint, never floats.","kind":"fact","repo":"petrova","pinned":false,"scope":"account"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/memories",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"text":"Money is nano-USD bigint, never floats.","kind":"fact","repo":"petrova","pinned":false,"scope":"account"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/memories", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"text":"Money is nano-USD bigint, never floats.","kind":"fact","repo":"petrova","pinned":false,"scope":"account"})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"kind": "fact",
"text": "Money is nano-USD bigint, never floats.",
"pinned": false,
"repo": "petrova",
"scope": "account",
"created_at": "2026-10-24T09:12:03.000Z"
}GET/v1/memories
Search saved memories.
| Parameter | In · type |
|---|---|
q optional | query · string |
repo optional | query · string |
commit optional | query · string |
pinned optional | query · boolean |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
search optional | "fts+trigram" | "fts+ilike" |
symbols optional | list of objects |
curl -s http://127.0.0.1:4100/v1/memories \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/memories",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/memories", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"kind": "fact",
"text": "Money is nano-USD bigint, never floats.",
"pinned": false,
"repo": "petrova",
"scope": "account",
"created_at": "2026-10-24T09:12:03.000Z",
"score": 0.82
}
],
"search": "fts+trigram",
"symbols": [
{
"path": "path",
"name": "Chain Scout",
"kind": "kind",
"line": 1,
"signature": "signature"
}
]
}GET/v1/memories/export
Read memories/export.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
curl -s http://127.0.0.1:4100/v1/memories/export \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/memories/export",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/memories/export", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());"value"DELETE/v1/memories/{id}
Forget a memory: the row, its text and its index.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string |
forgotten | true |
curl -s -X DELETE http://127.0.0.1:4100/v1/memories/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/memories/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/memories/<id>", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"forgotten": true
}Your own cloud (AWS)
GET/v1/clouds/aws
Read clouds/aws.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
provider | "aws" |
state | "pending" | "connected" | "verified" | "failed" |
external_id | string Issued by Petrova. Put it in the CloudFormation stack; the role trusts only this value. |
petrova_principal_arn | string |
region | string |
aws_account_hint | string or null |
template_url | string |
quick_create_url | string |
inference_profiles | object Anthropic model id -> Bedrock inference profile id found in your account |
last_check | any Outcome of the last verification, or null |
verified_at | string (date-time) or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/clouds/aws \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/clouds/aws",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"provider": "aws",
"state": "pending",
"external_id": "ptrv-ext-3c9a1f",
"petrova_principal_arn": "petrova-principal-arn",
"region": "us-east-1",
"aws_account_hint": "aws-account-hint",
"template_url": "https://example.invalid/",
"quick_create_url": "https://example.invalid/",
"inference_profiles": {},
"last_check": null,
"verified_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}POST/v1/clouds/aws
Write clouds/aws.
| Body field | Type |
|---|---|
role_arn | string |
external_id | string |
region optional | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
provider | "aws" |
state | "pending" | "connected" | "verified" | "failed" |
external_id | string Issued by Petrova. Put it in the CloudFormation stack; the role trusts only this value. |
petrova_principal_arn | string |
region | string |
aws_account_hint | string or null |
template_url | string |
quick_create_url | string |
inference_profiles | object Anthropic model id -> Bedrock inference profile id found in your account |
last_check | any Outcome of the last verification, or null |
verified_at | string (date-time) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/clouds/aws \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"role_arn":"role-arn","external_id":"ptrv-ext-3c9a1f","region":"us-east-1"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/clouds/aws",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"role_arn":"role-arn","external_id":"ptrv-ext-3c9a1f","region":"us-east-1"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"role_arn":"role-arn","external_id":"ptrv-ext-3c9a1f","region":"us-east-1"})
});
console.log(await r.json());{
"provider": "aws",
"state": "pending",
"external_id": "ptrv-ext-3c9a1f",
"petrova_principal_arn": "petrova-principal-arn",
"region": "us-east-1",
"aws_account_hint": "aws-account-hint",
"template_url": "https://example.invalid/",
"quick_create_url": "https://example.invalid/",
"inference_profiles": {},
"last_check": null,
"verified_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}DELETE/v1/clouds/aws
Delete clouds/aws.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
provider | "aws" |
state | "disconnected" |
mode | "fixture" |
curl -s -X DELETE http://127.0.0.1:4100/v1/clouds/aws \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/clouds/aws",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"provider": "aws",
"state": "disconnected",
"mode": "fixture"
}POST/v1/clouds/aws/verify
Write clouds/aws/verify.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
provider | "aws" |
state | "pending" | "connected" | "verified" | "failed" |
external_id | string Issued by Petrova. Put it in the CloudFormation stack; the role trusts only this value. |
petrova_principal_arn | string |
region | string |
aws_account_hint | string or null |
template_url | string |
quick_create_url | string |
inference_profiles | object Anthropic model id -> Bedrock inference profile id found in your account |
last_check | any Outcome of the last verification, or null |
verified_at | string (date-time) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/clouds/aws/verify \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/clouds/aws/verify",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/clouds/aws/verify", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"provider": "aws",
"state": "pending",
"external_id": "ptrv-ext-3c9a1f",
"petrova_principal_arn": "petrova-principal-arn",
"region": "us-east-1",
"aws_account_hint": "aws-account-hint",
"template_url": "https://example.invalid/",
"quick_create_url": "https://example.invalid/",
"inference_profiles": {},
"last_check": null,
"verified_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}Chat Completions (OpenAI)
POST/v1/chat/completions
OpenAI Chat Completions, translated and run through the same caps and holds.
| Body field | Type |
|---|---|
model | string |
messages | list of objects |
stream optional | boolean |
max_tokens optional | integer |
max_completion_tokens optional | integer |
tools optional | list of objects |
user optional | string Agent id for agent caps when no header names one |
metadata optional | object agent_id, parent_agent_id, session_id for caps |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
upstream failed | 502 | Yes | A supplier or tool failed; you paid nothing. Retry. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
id | string |
object | "chat.completion" |
created | integer |
model | string |
choices | list of objects |
usage | object |
curl -s -X POST http://127.0.0.1:4100/v1/chat/completions \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"model":"claude-opus-5-5","messages":[{}],"stream":false,"max_tokens":1,"max_completion_tokens":1,"tools":[{}],"user":"user","metadata":{}}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/chat/completions",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"model":"claude-opus-5-5","messages":[{}],"stream":false,"max_tokens":1,"max_completion_tokens":1,"tools":[{}],"user":"user","metadata":{}})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/chat/completions", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"model":"claude-opus-5-5","messages":[{}],"stream":false,"max_tokens":1,"max_completion_tokens":1,"tools":[{}],"user":"user","metadata":{}})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"object": "chat.completion",
"created": 1,
"model": "claude-opus-5-5",
"choices": [
{}
],
"usage": {}
}Responses (OpenAI)
POST/v1/responses
OpenAI Responses (what Codex uses), same caps and holds.
| Body field | Type |
|---|---|
model | string |
input | any |
instructions optional | string |
stream optional | boolean |
max_output_tokens optional | integer |
tools optional | list of objects |
metadata optional | object agent_id, parent_agent_id, session_id for caps |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
upstream failed | 502 | Yes | A supplier or tool failed; you paid nothing. Retry. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
id | string |
object | "response" |
status | string |
model | string |
output | list of objects |
usage | object |
curl -s -X POST http://127.0.0.1:4100/v1/responses \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"model":"claude-opus-5-5","input":null,"instructions":"instructions","stream":false,"max_output_tokens":1,"tools":[{}],"metadata":{}}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/responses",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"model":"claude-opus-5-5","input":null,"instructions":"instructions","stream":false,"max_output_tokens":1,"tools":[{}],"metadata":{}})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/responses", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"model":"claude-opus-5-5","input":null,"instructions":"instructions","stream":false,"max_output_tokens":1,"tools":[{}],"metadata":{}})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"object": "response",
"status": "status",
"model": "claude-opus-5-5",
"output": [
{}
],
"usage": {}
}chain.watch
POST/v1/chain/watch
Start a stream of Base chain events. Pay per event delivered.
| Body field | Type |
|---|---|
filter optional | object |
query optional | string Optional plain-language filter, e.g. "swaps over $50k of 0x..."; filter fields win |
hold_events optional | integer Events held per hold; unused ones are released at settle |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
tool_id | string (uuid) |
chain | "base" |
state | "active" | "stopped" |
filter | object |
query | string or null |
price_per_event_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
price_per_event_usd | string |
hold_events | integer |
delivered_events | integer |
cursor | string Sequence number of the last delivered event |
charged_nusd | nano-USD string Settled charges |
pending_nusd | nano-USD string Delivered against the open hold, settled when it closes |
held_nusd | nano-USD string Size of the open hold |
created_at | string (date-time) |
stopped_at | string (date-time) or null |
events_url | string |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/chain/watch \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"filter":{"types":["token_launch"],"addresses":["addresses"],"wallets":["wallets"],"min_usd_nusd":"18990000"},"query":"new tokens with more than $40k liquidity","hold_events":100}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/chain/watch",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"filter":{"types":["token_launch"],"addresses":["addresses"],"wallets":["wallets"],"min_usd_nusd":"18990000"},"query":"new tokens with more than $40k liquidity","hold_events":100})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/chain/watch", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"filter":{"types":["token_launch"],"addresses":["addresses"],"wallets":["wallets"],"min_usd_nusd":"18990000"},"query":"new tokens with more than $40k liquidity","hold_events":100})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"chain": "base",
"state": "active",
"filter": {
"types": [
"token_launch"
],
"addresses": [
"addresses"
],
"wallets": [
"wallets"
],
"min_usd_nusd": "18990000"
},
"query": "new tokens with more than $40k liquidity",
"price_per_event_nusd": "5000000",
"price_per_event_usd": "price-per-event-usd",
"hold_events": 100,
"delivered_events": 3,
"cursor": "12",
"charged_nusd": "18990000",
"pending_nusd": "18990000",
"held_nusd": "99085600",
"created_at": "2026-10-24T09:12:03.000Z",
"stopped_at": "2026-10-24T09:12:03.000Z",
"events_url": "https://example.invalid/",
"mode": "fixture"
}GET/v1/chain/watch/{id}
Read chain/watch/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
tool_id | string (uuid) |
chain | "base" |
state | "active" | "stopped" |
filter | object |
query | string or null |
price_per_event_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
price_per_event_usd | string |
hold_events | integer |
delivered_events | integer |
cursor | string Sequence number of the last delivered event |
charged_nusd | nano-USD string Settled charges |
pending_nusd | nano-USD string Delivered against the open hold, settled when it closes |
held_nusd | nano-USD string Size of the open hold |
created_at | string (date-time) |
stopped_at | string (date-time) or null |
events_url | string |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/chain/watch/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/chain/watch/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"chain": "base",
"state": "active",
"filter": {
"types": [
"token_launch"
],
"addresses": [
"addresses"
],
"wallets": [
"wallets"
],
"min_usd_nusd": "18990000"
},
"query": "new tokens with more than $40k liquidity",
"price_per_event_nusd": "5000000",
"price_per_event_usd": "price-per-event-usd",
"hold_events": 100,
"delivered_events": 3,
"cursor": "12",
"charged_nusd": "18990000",
"pending_nusd": "18990000",
"held_nusd": "99085600",
"created_at": "2026-10-24T09:12:03.000Z",
"stopped_at": "2026-10-24T09:12:03.000Z",
"events_url": "https://example.invalid/",
"mode": "fixture"
}DELETE/v1/chain/watch/{id}
Delete chain/watch/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
tool_id | string (uuid) |
chain | "base" |
state | "active" | "stopped" |
filter | object |
query | string or null |
price_per_event_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
price_per_event_usd | string |
hold_events | integer |
delivered_events | integer |
cursor | string Sequence number of the last delivered event |
charged_nusd | nano-USD string Settled charges |
pending_nusd | nano-USD string Delivered against the open hold, settled when it closes |
held_nusd | nano-USD string Size of the open hold |
created_at | string (date-time) |
stopped_at | string (date-time) or null |
events_url | string |
mode | "fixture" |
curl -s -X DELETE http://127.0.0.1:4100/v1/chain/watch/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/chain/watch/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"chain": "base",
"state": "active",
"filter": {
"types": [
"token_launch"
],
"addresses": [
"addresses"
],
"wallets": [
"wallets"
],
"min_usd_nusd": "18990000"
},
"query": "new tokens with more than $40k liquidity",
"price_per_event_nusd": "5000000",
"price_per_event_usd": "price-per-event-usd",
"hold_events": 100,
"delivered_events": 3,
"cursor": "12",
"charged_nusd": "18990000",
"pending_nusd": "18990000",
"held_nusd": "99085600",
"created_at": "2026-10-24T09:12:03.000Z",
"stopped_at": "2026-10-24T09:12:03.000Z",
"events_url": "https://example.invalid/",
"mode": "fixture"
}GET/v1/chain/watch/{id}/events
Read chain/watch/:id/events.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
curl -s http://127.0.0.1:4100/v1/chain/watch/<id>/events \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/chain/watch/<id>/events",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>/events", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());"value"GET/v1/chain/watch/{id}/poll
Fetch new events since a cursor.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
cursor optional | query · string |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
watch_id | string (uuid) |
state | "active" | "stopped" |
events | list of objects |
cursor | string |
charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
price_per_event_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
error | object or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/chain/watch/<id>/poll \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/chain/watch/<id>/poll",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/chain/watch/<id>/poll", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"watch_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"state": "active",
"events": [
{
"seq": 1,
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"type": "token_launch",
"summary": "New token FOO launched with $42,000 liquidity"
}
],
"cursor": "12",
"charged_nusd": "18990000",
"price_per_event_nusd": "5000000",
"error": {
"type": "type",
"message": "message"
},
"mode": "fixture"
}Plans
GET/v1/plans
Monthly plans, bonus tiers and the referral share (example numbers).
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
plans | list of objects |
bonus_tiers | list of objects Volume bonus on a top-up: the highest tier reached applies |
referral | object |
curl -s http://127.0.0.1:4100/v1/plans \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/plans",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/plans", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"plans": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"price_nusd": "5000000",
"credits_nusd": "115000000000",
"period": "calendar_month_utc"
}
],
"bonus_tiers": [
{
"min_nusd": "18990000",
"bonus_bps": 500
}
],
"referral": {
"share_bps": 1000,
"months": 12
}
}POST/v1/plans/subscribe
Write plans/subscribe.
| Body field | Type |
|---|---|
plan_id | string |
auto_renew optional | boolean Renew from the balance at each month start (default true) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
replayed | boolean This plan was already bought this month; nothing was charged |
mode | "fixture" |
as_of | string (date-time) |
total_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
plan_nusd | nano-USD string Unspent plan credits this month (spent first; expire at month end) |
bought_nusd | nano-USD string Unspent bought credits (spent last; never expire) |
bonus_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
other_nusd | nano-USD string Balance from elsewhere: funding, seller income, referral rewards |
plan | object or null |
subscription | object or null |
curl -s -X POST http://127.0.0.1:4100/v1/plans/subscribe \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"plan_id":"builder","auto_renew":false}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/plans/subscribe",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"plan_id":"builder","auto_renew":false})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/plans/subscribe", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"plan_id":"builder","auto_renew":false})
});
console.log(await r.json());{
"replayed": false,
"mode": "fixture",
"as_of": "2026-10-24T09:12:03.000Z",
"total_nusd": "18742360000",
"plan_nusd": "18990000",
"bought_nusd": "18990000",
"bonus_nusd": "25000000000",
"other_nusd": "18990000",
"plan": {
"plan_id": "builder",
"credits_nusd": "115000000000",
"remaining_nusd": "1100000000",
"expires_at": "2026-10-24T09:12:03.000Z"
},
"subscription": {
"plan_id": "builder",
"auto_renew": false,
"lapsed_reason": "lapsed-reason"
}
}POST/v1/plans/cancel
Write plans/cancel.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
as_of | string (date-time) |
total_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
plan_nusd | nano-USD string Unspent plan credits this month (spent first; expire at month end) |
bought_nusd | nano-USD string Unspent bought credits (spent last; never expire) |
bonus_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
other_nusd | nano-USD string Balance from elsewhere: funding, seller income, referral rewards |
plan | object or null |
subscription | object or null |
curl -s -X POST http://127.0.0.1:4100/v1/plans/cancel \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/plans/cancel",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/plans/cancel", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"as_of": "2026-10-24T09:12:03.000Z",
"total_nusd": "18742360000",
"plan_nusd": "18990000",
"bought_nusd": "18990000",
"bonus_nusd": "25000000000",
"other_nusd": "18990000",
"plan": {
"plan_id": "builder",
"credits_nusd": "115000000000",
"remaining_nusd": "1100000000",
"expires_at": "2026-10-24T09:12:03.000Z"
},
"subscription": {
"plan_id": "builder",
"auto_renew": false,
"lapsed_reason": "lapsed-reason"
}
}Top-ups
GET/v1/topups/quote
Preview a top-up: what you pay and the bonus. Send amount_nusd.
| Parameter | In · type |
|---|---|
amount_nusd optional | query · nano-USD string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
amount_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
bonus_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
bonus_bps | integer |
credits_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
tiers | list of objects |
curl -s http://127.0.0.1:4100/v1/topups/quote \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/topups/quote",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/topups/quote", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"amount_nusd": "20000000000",
"bonus_nusd": "25000000000",
"bonus_bps": 500,
"credits_nusd": "115000000000",
"tiers": [
{
"min_nusd": "18990000",
"bonus_bps": 500
}
]
}POST/v1/topups/onchain
Write topups/onchain.
| Body field | Type |
|---|---|
message | string |
public_key | string Uncompressed secp256k1 public key, hex |
signature | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
tx_hash | string |
state | "pending" | "awaiting_approval" | "credited" | "rejected" |
reason | string or null |
amount_nusd | nano-USD string or null |
confirmations | integer |
confirmations_required | integer |
approval_id | string (uuid) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/topups/onchain \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"message":"message","public_key":"public-key","signature":"signature"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/topups/onchain",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/topups/onchain", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());{
"tx_hash": "0xaaa1c0ffee",
"state": "pending",
"reason": "reason",
"amount_nusd": "20000000000",
"confirmations": 12,
"confirmations_required": 12,
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"mode": "fixture"
}GET/v1/topups/approvals
Agent top-ups waiting for your OK.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/topups/approvals \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/topups/approvals",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/topups/approvals", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tx_hash": "0xaaa1c0ffee",
"amount_nusd": "20000000000",
"nonce": "n-91f2",
"state": "pending",
"decided_by": "decided-by",
"message_to_sign": "message-to-sign"
}
],
"mode": "fixture"
}POST/v1/topups/approvals/{id}/decide
Approve or reject an agent top-up.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
decision | "approve" | "reject" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
tx_hash | string |
state | "pending" | "awaiting_approval" | "credited" | "rejected" |
reason | string or null |
amount_nusd | nano-USD string or null |
confirmations | integer |
confirmations_required | integer |
approval_id | string (uuid) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/topups/approvals/<id>/decide \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"decision":"approve"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"decision":"approve"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"decision":"approve"})
});
console.log(await r.json());{
"tx_hash": "0xaaa1c0ffee",
"state": "pending",
"reason": "reason",
"amount_nusd": "20000000000",
"confirmations": 12,
"confirmations_required": 12,
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"mode": "fixture"
}POST/v1/topups/approvals/{id}/decide-signed
Write topups/approvals/:id/decide-signed.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
message | string |
public_key | string Uncompressed secp256k1 public key, hex |
signature | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
tx_hash | string |
state | "pending" | "awaiting_approval" | "credited" | "rejected" |
reason | string or null |
amount_nusd | nano-USD string or null |
confirmations | integer |
confirmations_required | integer |
approval_id | string (uuid) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/topups/approvals/<id>/decide-signed \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"message":"message","public_key":"public-key","signature":"signature"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide-signed",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/topups/approvals/<id>/decide-signed", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());{
"tx_hash": "0xaaa1c0ffee",
"state": "pending",
"reason": "reason",
"amount_nusd": "20000000000",
"confirmations": 12,
"confirmations_required": 12,
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"mode": "fixture"
}GET/v1/topups/info
Read topups/info.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
real_money | false |
how_to_add_test_funds | string |
onchain | object |
curl -s http://127.0.0.1:4100/v1/topups/info \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/topups/info",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/topups/info", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"real_money": false,
"how_to_add_test_funds": "how-to-add-test-funds",
"onchain": {
"network": "network",
"token": "token",
"deposit_address": "deposit-address",
"confirmations": 12,
"note": "note"
}
}Credits
GET/v1/credits
Which credits you have and the order they are spent in.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
as_of | string (date-time) |
total_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
plan_nusd | nano-USD string Unspent plan credits this month (spent first; expire at month end) |
bought_nusd | nano-USD string Unspent bought credits (spent last; never expire) |
bonus_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
other_nusd | nano-USD string Balance from elsewhere: funding, seller income, referral rewards |
plan | object or null |
subscription | object or null |
curl -s http://127.0.0.1:4100/v1/credits \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/credits",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/credits", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"as_of": "2026-10-24T09:12:03.000Z",
"total_nusd": "18742360000",
"plan_nusd": "18990000",
"bought_nusd": "18990000",
"bonus_nusd": "25000000000",
"other_nusd": "18990000",
"plan": {
"plan_id": "builder",
"credits_nusd": "115000000000",
"remaining_nusd": "1100000000",
"expires_at": "2026-10-24T09:12:03.000Z"
},
"subscription": {
"plan_id": "builder",
"auto_renew": false,
"lapsed_reason": "lapsed-reason"
}
}Referrals
GET/v1/referrals
Read referrals.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
mode | "fixture" |
code | string or null |
referred_by_someone | boolean |
referred_accounts | integer |
earned_nusd | nano-USD string Rewards opened so far, credited to the balance as the referred accounts spent |
pending_nusd | nano-USD string Rewards that open only as the referred accounts spend what they paid for |
reversed_rewards | integer |
clawback_owed_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
curl -s http://127.0.0.1:4100/v1/referrals \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/referrals",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/referrals", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"mode": "fixture",
"code": "PTRV-7K2Q",
"referred_by_someone": false,
"referred_accounts": 3,
"earned_nusd": "46250000000",
"pending_nusd": "18990000",
"reversed_rewards": 1,
"clawback_owed_nusd": "18990000"
}POST/v1/referrals/code
Write referrals/code.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
code | string |
curl -s -X POST http://127.0.0.1:4100/v1/referrals/code \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/referrals/code",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/referrals/code", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"code": "PTRV-7K2Q"
}POST/v1/referrals/claim
Write referrals/claim.
| Body field | Type |
|---|---|
code | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
referred | true |
share_bps | integer |
rewards_until | string (date-time) |
curl -s -X POST http://127.0.0.1:4100/v1/referrals/claim \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"code":"PTRV-7K2Q"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/referrals/claim",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"code":"PTRV-7K2Q"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/referrals/claim", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"code":"PTRV-7K2Q"})
});
console.log(await r.json());{
"referred": true,
"share_bps": 1000,
"rewards_until": "2026-10-24T09:12:03.000Z"
}Agent wallets
POST/v1/agent-wallets
Register an agent’s wallet with a cap and an approval threshold.
| Body field | Type |
|---|---|
address | string |
agent_id | string |
default_cap_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_threshold_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
operator_public_key optional | string Uncompressed secp256k1 public key, hex |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
wallet_id | string (uuid) |
address | string |
agent_id | string |
default_cap_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_threshold_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent-wallets \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"address":"0x5ab1000000000000000000000000000000c3d2","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"18990000","operator_public_key":"operator-public-key"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent-wallets",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"address":"0x5ab1000000000000000000000000000000c3d2","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"18990000","operator_public_key":"operator-public-key"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent-wallets", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"address":"0x5ab1000000000000000000000000000000c3d2","agent_id":"research-bot","default_cap_nusd":"5000000000","approval_threshold_nusd":"18990000","operator_public_key":"operator-public-key"})
});
console.log(await r.json());{
"wallet_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"address": "0x5ab1000000000000000000000000000000c3d2",
"agent_id": "research-bot",
"default_cap_nusd": "5000000000",
"approval_threshold_nusd": "18990000",
"mode": "fixture"
}POST/v1/agent-wallets/status
Write agent-wallets/status.
| Body field | Type |
|---|---|
message | string |
public_key | string Uncompressed secp256k1 public key, hex |
signature | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
address | string |
agent_id | string |
default_cap_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_threshold_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
deposit | object |
credited_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
active_keys | integer |
balance | object |
topups | list of objects |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent-wallets/status \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"message":"message","public_key":"public-key","signature":"signature"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent-wallets/status",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent-wallets/status", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());{
"address": "0x5ab1000000000000000000000000000000c3d2",
"agent_id": "research-bot",
"default_cap_nusd": "5000000000",
"approval_threshold_nusd": "18990000",
"deposit": {
"chain_id": 1,
"token": "token",
"address": "0x5ab1000000000000000000000000000000c3d2",
"confirmations": 12
},
"credited_nusd": "18990000",
"active_keys": 1,
"balance": {
"currency": "USD",
"total_nusd": "18742360000",
"available_nusd": "18544188800",
"reserved_nusd": "198171200",
"mode": "fixture",
"as_of": "2026-10-24T09:12:03.000Z"
},
"topups": [
{
"tx_hash": "0xaaa1c0ffee",
"state": "pending",
"reason": "reason",
"amount_nusd": "20000000000",
"confirmations": 12,
"confirmations_required": 12,
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"mode": "fixture"
}
],
"mode": "fixture"
}POST/v1/agent-wallets/keys
Write agent-wallets/keys.
| Body field | Type |
|---|---|
message | string |
public_key | string Uncompressed secp256k1 public key, hex |
signature | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
key_id | string (uuid) |
secret | string Shown once. Store it; Petrova keeps only its hash. |
agent_id | string |
scopes | list of string |
cap_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent-wallets/keys \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"message":"message","public_key":"public-key","signature":"signature"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent-wallets/keys",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"message":"message","public_key":"public-key","signature":"signature"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent-wallets/keys", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"message":"message","public_key":"public-key","signature":"signature"})
});
console.log(await r.json());{
"key_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"secret": "secret",
"agent_id": "research-bot",
"scopes": [
"scopes"
],
"cap_nusd": "5000000000",
"mode": "fixture"
}Cards
POST/v1/cards
Write cards.
| Body field | Type |
|---|---|
name | string |
monthly_allowance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
per_call_limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd optional | nano-USD string or null A call whose hold is above this waits for a person. Null: never |
allowed_tools optional | list of string (uuid) or null Null: any tool. With allowed_services, a tool in either list may be called |
allowed_services optional | list of string or null Provider names |
permission optional | "read" | "write"Default read |
shared_budget_id optional | string (uuid) or null |
project_id optional | string (uuid) |
request_id optional | string Reuse to make a retry safe. A replay returns the card without a key |
allowed_connections optional | list of string (uuid) or null Your own provider accounts this card may use. Null: none |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
card | object |
key | object or null |
replayed | boolean |
curl -s -X POST http://127.0.0.1:4100/v1/cards \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","request_id":"request-id","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/cards",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","request_id":"request-id","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","request_id":"request-id","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
});
console.log(await r.json());{
"card": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"state": "active",
"project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"permission": "read",
"monthly_allowance_nusd": "18990000",
"committed_this_month_nusd": "3900000000",
"held_nusd": "99085600",
"available_nusd": "18544188800",
"per_call_limit_nusd": "5000000000",
"approval_over_nusd": "18990000",
"allowed_tools": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"allowed_services": [
"allowed-services"
],
"shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"allowed_connections": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"budgets_above": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"limit_nusd": "5000000000",
"committed_nusd": "3900000000"
}
],
"key_prefix": "key-prefix",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
},
"key": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"secret": "secret",
"scopes": [
"scopes"
]
},
"replayed": false
}GET/v1/cards
Read cards.
| Parameter | In · type |
|---|---|
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/cards \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/cards",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"state": "active",
"project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"permission": "read",
"monthly_allowance_nusd": "18990000",
"committed_this_month_nusd": "3900000000",
"held_nusd": "99085600",
"available_nusd": "18544188800",
"per_call_limit_nusd": "5000000000",
"approval_over_nusd": "18990000",
"allowed_tools": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"allowed_services": [
"allowed-services"
],
"shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"allowed_connections": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"budgets_above": [
{
"id": null,
"limit_nusd": null,
"committed_nusd": null
}
],
"key_prefix": "key-prefix",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
],
"mode": "fixture"
}GET/v1/cards/me
Read cards/me.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
name | string |
state | "active" | "paused" | "closed" |
project_id | string (uuid) |
permission | "read" | "write"read: GET tools only. write: any method |
monthly_allowance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
committed_this_month_nusd | nano-USD string Held plus charged this calendar month, UTC |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
available_nusd | nano-USD string The most a new hold could be under this card and every shared budget above it. The wallet may have less |
per_call_limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd | nano-USD string or null |
allowed_tools | list of string (uuid) or null |
allowed_services | list of string or null |
shared_budget_id | string (uuid) or null |
allowed_connections optional | list of string (uuid) or null |
application_id optional | string (uuid) or null |
budgets_above | list of objects |
key_prefix | string or null |
created_at | string (date-time) |
closed_at | string (date-time) or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/cards/me \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/cards/me",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards/me", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"state": "active",
"project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"permission": "read",
"monthly_allowance_nusd": "18990000",
"committed_this_month_nusd": "3900000000",
"held_nusd": "99085600",
"available_nusd": "18544188800",
"per_call_limit_nusd": "5000000000",
"approval_over_nusd": "18990000",
"allowed_tools": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"allowed_services": [
"allowed-services"
],
"shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"allowed_connections": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"budgets_above": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"limit_nusd": "5000000000",
"committed_nusd": "3900000000"
}
],
"key_prefix": "key-prefix",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}GET/v1/cards/{id}
Read cards/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
name | string |
state | "active" | "paused" | "closed" |
project_id | string (uuid) |
permission | "read" | "write"read: GET tools only. write: any method |
monthly_allowance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
committed_this_month_nusd | nano-USD string Held plus charged this calendar month, UTC |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
available_nusd | nano-USD string The most a new hold could be under this card and every shared budget above it. The wallet may have less |
per_call_limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd | nano-USD string or null |
allowed_tools | list of string (uuid) or null |
allowed_services | list of string or null |
shared_budget_id | string (uuid) or null |
allowed_connections optional | list of string (uuid) or null |
application_id optional | string (uuid) or null |
budgets_above | list of objects |
key_prefix | string or null |
created_at | string (date-time) |
closed_at | string (date-time) or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/cards/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/cards/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"state": "active",
"project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"permission": "read",
"monthly_allowance_nusd": "18990000",
"committed_this_month_nusd": "3900000000",
"held_nusd": "99085600",
"available_nusd": "18544188800",
"per_call_limit_nusd": "5000000000",
"approval_over_nusd": "18990000",
"allowed_tools": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"allowed_services": [
"allowed-services"
],
"shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"allowed_connections": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"budgets_above": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"limit_nusd": "5000000000",
"committed_nusd": "3900000000"
}
],
"key_prefix": "key-prefix",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}PATCH/v1/cards/{id}
Write cards/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
name optional | string |
monthly_allowance_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
per_call_limit_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd optional | nano-USD string or null |
allowed_tools optional | list of string (uuid) or null |
allowed_services optional | list of string or null |
permission optional | "read" | "write" |
shared_budget_id optional | string (uuid) or null |
state optional | "active" | "paused" |
allowed_connections optional | list of string (uuid) or null |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
name | string |
state | "active" | "paused" | "closed" |
project_id | string (uuid) |
permission | "read" | "write"read: GET tools only. write: any method |
monthly_allowance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
committed_this_month_nusd | nano-USD string Held plus charged this calendar month, UTC |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
available_nusd | nano-USD string The most a new hold could be under this card and every shared budget above it. The wallet may have less |
per_call_limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd | nano-USD string or null |
allowed_tools | list of string (uuid) or null |
allowed_services | list of string or null |
shared_budget_id | string (uuid) or null |
allowed_connections optional | list of string (uuid) or null |
application_id optional | string (uuid) or null |
budgets_above | list of objects |
key_prefix | string or null |
created_at | string (date-time) |
closed_at | string (date-time) or null |
mode | "fixture" |
curl -s -X PATCH http://127.0.0.1:4100/v1/cards/<id> \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","state":"active","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]}'import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/cards/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","state":"active","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>", {
method: "PATCH",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"name":"Chain Scout","monthly_allowance_nusd":"18990000","per_call_limit_nusd":"5000000000","approval_over_nusd":"18990000","allowed_tools":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"],"allowed_services":["allowed-services"],"permission":"read","shared_budget_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","state":"active","allowed_connections":["3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"]})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"state": "active",
"project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"permission": "read",
"monthly_allowance_nusd": "18990000",
"committed_this_month_nusd": "3900000000",
"held_nusd": "99085600",
"available_nusd": "18544188800",
"per_call_limit_nusd": "5000000000",
"approval_over_nusd": "18990000",
"allowed_tools": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"allowed_services": [
"allowed-services"
],
"shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"allowed_connections": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"budgets_above": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"limit_nusd": "5000000000",
"committed_nusd": "3900000000"
}
],
"key_prefix": "key-prefix",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}POST/v1/cards/{id}/close
Write cards/:id/close.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
name | string |
state | "active" | "paused" | "closed" |
project_id | string (uuid) |
permission | "read" | "write"read: GET tools only. write: any method |
monthly_allowance_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
committed_this_month_nusd | nano-USD string Held plus charged this calendar month, UTC |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
available_nusd | nano-USD string The most a new hold could be under this card and every shared budget above it. The wallet may have less |
per_call_limit_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd | nano-USD string or null |
allowed_tools | list of string (uuid) or null |
allowed_services | list of string or null |
shared_budget_id | string (uuid) or null |
allowed_connections optional | list of string (uuid) or null |
application_id optional | string (uuid) or null |
budgets_above | list of objects |
key_prefix | string or null |
created_at | string (date-time) |
closed_at | string (date-time) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/cards/<id>/close \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/cards/<id>/close",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>/close", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"state": "active",
"project_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"permission": "read",
"monthly_allowance_nusd": "18990000",
"committed_this_month_nusd": "3900000000",
"held_nusd": "99085600",
"available_nusd": "18544188800",
"per_call_limit_nusd": "5000000000",
"approval_over_nusd": "18990000",
"allowed_tools": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"allowed_services": [
"allowed-services"
],
"shared_budget_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"allowed_connections": [
"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
],
"application_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"budgets_above": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"limit_nusd": "5000000000",
"committed_nusd": "3900000000"
}
],
"key_prefix": "key-prefix",
"created_at": "2026-10-24T09:12:03.000Z",
"closed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}POST/v1/cards/{id}/keys
Write cards/:id/keys.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
secret | string Shown once. Only a hash is stored |
scopes | list of string |
curl -s -X POST http://127.0.0.1:4100/v1/cards/<id>/keys \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/cards/<id>/keys",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>/keys", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"secret": "secret",
"scopes": [
"scopes"
]
}DELETE/v1/cards/{id}/keys
Delete cards/:id/keys.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
card_id | string (uuid) |
revoked | boolean |
mode | "fixture" |
curl -s -X DELETE http://127.0.0.1:4100/v1/cards/<id>/keys \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/cards/<id>/keys",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/cards/<id>/keys", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"revoked": false,
"mode": "fixture"
}Shared-budgets
Calls
POST/v1/calls
Write calls.
| Body field | Type |
|---|---|
tool_id | string (uuid) |
inputs | object |
max_cost_nusd | nano-USD string Ceiling on price plus Petrova fee for this call |
idempotency_key optional | string Send one, and reuse it after a dropped connection. Without one, the response gives you the one it made |
run_id optional | string |
wait_ms optional | integer How long to wait for an answer before returning the call as it stands. Default 20000. The call keeps going either way |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
tool_id | string (uuid) |
card_id | string (uuid) or null |
run_id | string or null |
idempotency_key | string Keep this. The same key and inputs always find this call; a new key is new work |
state | "queued" | "running" | "waiting" | "succeeded" | "failed" | "unknown" | "cancelled"unknown: the service restarted after the payment may have left. Charged nothing, but the tool may have done the work |
waiting_for | "approval" | "terms" or null |
approval_id | string (uuid) or null |
outcome | "paid" | "free" | "failed" | "payment_rejected" | "customer_account" or null |
error | object or null |
failure | string or null |
http_status | integer or null |
price_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
fee_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
charged_usd | string |
absorbed_nusd | nano-USD string What Petrova paid and did not charge you |
payment_reference | string or null |
payment_sent | boolean |
cancel_requested | boolean |
reservation_id | string (uuid) or null |
result | any The tool response, until result_expires_at. Never returned for a call that was not charged because its answer failed a check |
result_available | boolean |
result_expires_at | string (date-time) or null |
result_check | object or null |
provider_hidden | boolean or null |
replayed | boolean True when this request found an earlier call instead of starting one |
created_at | string (date-time) |
finished_at | string (date-time) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/calls \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key","run_id":"run-id","wait_ms":1}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/calls",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key","run_id":"run-id","wait_ms":1})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/calls", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","inputs":{},"max_cost_nusd":"18990000","idempotency_key":"idempotency-key","run_id":"run-id","wait_ms":1})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"run_id": "run-id",
"idempotency_key": "idempotency-key",
"state": "queued",
"waiting_for": "approval",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "paid",
"error": {
"code": "PTRV-7K2Q",
"message": "message"
},
"failure": "failure",
"http_status": 200,
"price_nusd": "5000000",
"fee_nusd": "990000",
"held_nusd": "99085600",
"charged_nusd": "18990000",
"charged_usd": "charged-usd",
"absorbed_nusd": "0",
"payment_reference": "payment-reference",
"payment_sent": false,
"cancel_requested": false,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"result": null,
"result_available": false,
"result_expires_at": "2026-10-24T09:12:03.000Z",
"result_check": {},
"provider_hidden": false,
"replayed": false,
"created_at": "2026-10-24T09:12:03.000Z",
"finished_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}GET/v1/calls
Read calls.
| Parameter | In · type |
|---|---|
state optional | query · "queued" | "running" | "waiting" | "succeeded" | "failed" | "unknown" | "cancelled" |
tool_id optional | query · string (uuid) |
run_id optional | query · string |
card_id optional | query · string (uuid) |
idempotency_key optional | query · string |
limit optional | query · integer |
cursor optional | query · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
next_cursor | string or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/calls \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/calls",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/calls", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"run_id": "run-id",
"idempotency_key": "idempotency-key",
"state": "queued",
"waiting_for": "approval",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "paid",
"error": {
"code": "PTRV-7K2Q",
"message": "message"
},
"failure": "failure",
"http_status": 200,
"price_nusd": "5000000",
"fee_nusd": "990000",
"held_nusd": "99085600",
"charged_nusd": "18990000",
"charged_usd": "charged-usd",
"absorbed_nusd": "0",
"payment_reference": "payment-reference",
"payment_sent": false,
"cancel_requested": false,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"result": null,
"result_available": false,
"result_expires_at": "2026-10-24T09:12:03.000Z",
"result_check": {},
"provider_hidden": false,
"replayed": false,
"created_at": "2026-10-24T09:12:03.000Z",
"finished_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
],
"next_cursor": "next-cursor",
"mode": "fixture"
}GET/v1/calls/{id}
Read calls/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
tool_id | string (uuid) |
card_id | string (uuid) or null |
run_id | string or null |
idempotency_key | string Keep this. The same key and inputs always find this call; a new key is new work |
state | "queued" | "running" | "waiting" | "succeeded" | "failed" | "unknown" | "cancelled"unknown: the service restarted after the payment may have left. Charged nothing, but the tool may have done the work |
waiting_for | "approval" | "terms" or null |
approval_id | string (uuid) or null |
outcome | "paid" | "free" | "failed" | "payment_rejected" | "customer_account" or null |
error | object or null |
failure | string or null |
http_status | integer or null |
price_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
fee_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
held_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
charged_nusd | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
charged_usd | string |
absorbed_nusd | nano-USD string What Petrova paid and did not charge you |
payment_reference | string or null |
payment_sent | boolean |
cancel_requested | boolean |
reservation_id | string (uuid) or null |
result | any The tool response, until result_expires_at. Never returned for a call that was not charged because its answer failed a check |
result_available | boolean |
result_expires_at | string (date-time) or null |
result_check | object or null |
provider_hidden | boolean or null |
replayed | boolean True when this request found an earlier call instead of starting one |
created_at | string (date-time) |
finished_at | string (date-time) or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/calls/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/calls/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/calls/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"run_id": "run-id",
"idempotency_key": "idempotency-key",
"state": "queued",
"waiting_for": "approval",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "paid",
"error": {
"code": "PTRV-7K2Q",
"message": "message"
},
"failure": "failure",
"http_status": 200,
"price_nusd": "5000000",
"fee_nusd": "990000",
"held_nusd": "99085600",
"charged_nusd": "18990000",
"charged_usd": "charged-usd",
"absorbed_nusd": "0",
"payment_reference": "payment-reference",
"payment_sent": false,
"cancel_requested": false,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"result": null,
"result_available": false,
"result_expires_at": "2026-10-24T09:12:03.000Z",
"result_check": {},
"provider_hidden": false,
"replayed": false,
"created_at": "2026-10-24T09:12:03.000Z",
"finished_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}POST/v1/calls/{id}/cancel
Write calls/:id/cancel.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
effect | "cancelled" | "requested" | "too_late" | "already_finished"too_late: the payment went out, so the work may finish and be charged. Read the call again for the final answer |
call | object |
curl -s -X POST http://127.0.0.1:4100/v1/calls/<id>/cancel \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/calls/<id>/cancel",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/calls/<id>/cancel", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"effect": "cancelled",
"call": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"run_id": "run-id",
"idempotency_key": "idempotency-key",
"state": "queued",
"waiting_for": "approval",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "paid",
"error": {
"code": "PTRV-7K2Q",
"message": "message"
},
"failure": "failure",
"http_status": 200,
"price_nusd": "5000000",
"fee_nusd": "990000",
"held_nusd": "99085600",
"charged_nusd": "18990000",
"charged_usd": "charged-usd",
"absorbed_nusd": "0",
"payment_reference": "payment-reference",
"payment_sent": false,
"cancel_requested": false,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"result": null,
"result_available": false,
"result_expires_at": "2026-10-24T09:12:03.000Z",
"result_check": {},
"provider_hidden": false,
"replayed": false,
"created_at": "2026-10-24T09:12:03.000Z",
"finished_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
}Runs
GET/v1/runs/{id}
Read runs/:id.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
run_id | string |
calls | integer |
states | object |
total_charged_nusd | nano-USD string What this run cost, less anything given back |
held_nusd | nano-USD string Still held for calls in flight |
first_call_at | string (date-time) or null |
last_call_at | string (date-time) or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/runs/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/runs/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/runs/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"run_id": "run-id",
"calls": 1,
"states": {},
"total_charged_nusd": "18990000",
"held_nusd": "99085600",
"first_call_at": "2026-10-24T09:12:03.000Z",
"last_call_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}Approvals
GET/v1/approvals
Read approvals.
| Parameter | In · type |
|---|---|
state optional | query · "pending" | "approved" | "rejected" | "expired" | "cancelled" |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/approvals \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/approvals",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/approvals", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"state": "pending",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"provider": "anthropic",
"run_id": "run-id",
"price_nusd": "5000000",
"fee_nusd": "990000",
"amount_nusd": "20000000000",
"amount_usd": "amount-usd",
"inputs": null,
"expires_at": "2026-10-24T09:12:03.000Z",
"decided_at": "2026-10-24T09:12:03.000Z",
"created_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
],
"mode": "fixture"
}POST/v1/approvals/{id}/decide
Write approvals/:id/decide.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
decision | "approve" | "reject" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
approval | object |
call | object |
curl -s -X POST http://127.0.0.1:4100/v1/approvals/<id>/decide \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"decision":"approve"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/approvals/<id>/decide",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"decision":"approve"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/approvals/<id>/decide", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"decision":"approve"})
});
console.log(await r.json());{
"approval": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"state": "pending",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"provider": "anthropic",
"run_id": "run-id",
"price_nusd": "5000000",
"fee_nusd": "990000",
"amount_nusd": "20000000000",
"amount_usd": "amount-usd",
"inputs": null,
"expires_at": "2026-10-24T09:12:03.000Z",
"decided_at": "2026-10-24T09:12:03.000Z",
"created_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
},
"call": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"run_id": "run-id",
"idempotency_key": "idempotency-key",
"state": "queued",
"waiting_for": "approval",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"outcome": "paid",
"error": {
"code": "PTRV-7K2Q",
"message": "message"
},
"failure": "failure",
"http_status": 200,
"price_nusd": "5000000",
"fee_nusd": "990000",
"held_nusd": "99085600",
"charged_nusd": "18990000",
"charged_usd": "charged-usd",
"absorbed_nusd": "0",
"payment_reference": "payment-reference",
"payment_sent": false,
"cancel_requested": false,
"reservation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"result": null,
"result_available": false,
"result_expires_at": "2026-10-24T09:12:03.000Z",
"result_check": {},
"provider_hidden": false,
"replayed": false,
"created_at": "2026-10-24T09:12:03.000Z",
"finished_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
}Agent
POST/v1/agent/search
Write agent/search.
| Body field | Type |
|---|---|
query optional | string What you need, in plain words. Omit to browse |
provider optional | string Only this provider slug, e.g. exa |
limit optional | integer |
tiers optional | list of "listed" | "verified" | "proven" |
max_price optional | string Highest price per call in USD, e.g. "0.05" |
cursor optional | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
kind | "ok" |
reason | "found" | "nothing_found" |
message | string |
next_action | object What to do now. Always present |
items | list of objects |
next_cursor | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent/search \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"query":"new tokens with more than $40k liquidity","provider":"anthropic","limit":1,"tiers":["listed"],"max_price":"max-price","cursor":"12"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/search",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"query":"new tokens with more than $40k liquidity","provider":"anthropic","limit":1,"tiers":["listed"],"max_price":"max-price","cursor":"12"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/search", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"query":"new tokens with more than $40k liquidity","provider":"anthropic","limit":1,"tiers":["listed"],"max_price":"max-price","cursor":"12"})
});
console.log(await r.json());{
"kind": "ok",
"reason": "found",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
},
"items": [
{
"provider": "anthropic",
"method": "GET",
"path": "path",
"tier": "listed",
"availability": "priced",
"pricing": {
"kind": "fixed",
"summary": "New token FOO launched with $42,000 liquidity"
}
}
],
"next_cursor": "next-cursor",
"mode": "fixture"
}POST/v1/agent/inspect
Write agent/inspect.
| Body field | Type |
|---|---|
tool_id optional | string (uuid) Call by id instead of provider and path |
provider optional | string Provider slug from search, e.g. exa |
path optional | string Path template from search, e.g. /search. Put {placeholder} values in path_params |
method optional | "GET" | "POST" | "PUT" | "PATCH" | "DELETE"Optional when the path serves one method |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key |
refused_by | "auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null |
reason | string A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ... |
message | string The same in plain words, always saying what was charged |
next_action | object What to do now. Always present |
receipt optional | object or null |
balance optional | object What is left: balance, monthly limit, what the next call can spend |
warnings optional | list of objects |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent/inspect \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/inspect",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/inspect", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET"})
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "auth",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
},
"receipt": {
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"idempotency_key": "idempotency-key",
"charged_nusd": "18990000",
"charge_status": "pending"
},
"balance": {},
"warnings": [
{
"kind": "low_balance"
}
],
"mode": "fixture"
}POST/v1/agent/calls
Write agent/calls.
| Body field | Type |
|---|---|
tool_id optional | string (uuid) Call by id instead of provider and path |
provider optional | string Provider slug from search, e.g. exa |
path optional | string Path template from search, e.g. /search. Put {placeholder} values in path_params |
method optional | "GET" | "POST" | "PUT" | "PATCH" | "DELETE"Optional when the path serves one method |
inputs optional | object One object checked against the tool's input schema. Or give path_params, query, headers and body |
path_params optional | object |
query optional | object |
headers optional | object |
body optional | any |
idempotency_key | string New for each new call. Reuse it to retry, recover, or accept terms for the same call |
max_cost optional | string Most this call may charge, fee included, in USD. Default "1.00" |
max_cost_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
accept_terms optional | string (uuid) From next_action.accept_terms of a price_changed answer. Repeat the original arguments unchanged, with the same key |
credential_mode optional | "wallet" | "customer"customer: call on your own provider account (connection_id). Never falls back to the wallet |
connection_id optional | string (uuid) |
run_id optional | string |
wait_ms optional | integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key |
refused_by | "auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null |
reason | string A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ... |
message | string The same in plain words, always saying what was charged |
next_action | object What to do now. Always present |
receipt optional | object or null |
balance optional | object What is left: balance, monthly limit, what the next call can spend |
warnings optional | list of objects |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent/calls \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null,"idempotency_key":"idempotency-key","max_cost":"max-cost","max_cost_nusd":"18990000","accept_terms":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","credential_mode":"wallet","connection_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","run_id":"run-id","wait_ms":1}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/calls",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null,"idempotency_key":"idempotency-key","max_cost":"max-cost","max_cost_nusd":"18990000","accept_terms":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","credential_mode":"wallet","connection_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","run_id":"run-id","wait_ms":1})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/calls", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"tool_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null,"idempotency_key":"idempotency-key","max_cost":"max-cost","max_cost_nusd":"18990000","accept_terms":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","credential_mode":"wallet","connection_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","run_id":"run-id","wait_ms":1})
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "auth",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
},
"receipt": {
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"idempotency_key": "idempotency-key",
"charged_nusd": "18990000",
"charge_status": "pending"
},
"balance": {},
"warnings": [
{
"kind": "low_balance"
}
],
"mode": "fixture"
}GET/v1/agent/calls
Read agent/calls.
| Parameter | In · type |
|---|---|
idempotency_key optional | query · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key |
refused_by | "auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null |
reason | string A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ... |
message | string The same in plain words, always saying what was charged |
next_action | object What to do now. Always present |
receipt optional | object or null |
balance optional | object What is left: balance, monthly limit, what the next call can spend |
warnings optional | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/agent/calls \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agent/calls",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/calls", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "auth",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
},
"receipt": {
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"idempotency_key": "idempotency-key",
"charged_nusd": "18990000",
"charge_status": "pending"
},
"balance": {},
"warnings": [
{
"kind": "low_balance"
}
],
"mode": "fixture"
}GET/v1/agent/calls/{id}
Read agent/calls/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started"ok: the answer, its cost and a receipt. needs_funding: no money or not enough, a link for the person. over_limit: over a limit only the person can raise. needs_approval: the person must say yes. price_changed: new terms (accept with accept_terms, or a new key and a higher maximum). failed: the tool failed, charged $0. pending: read it again with the same key. paused: the person paused this agent. refused: stopped, see refused_by. not_started: nothing began with that key |
refused_by | "auth" | "person" | "policy" | "balance" | "budget" | "cap" | "resolution" | "request" | "listing" | "payment" | "provider" or null |
reason | string A short code: answered, executing, price_above_max, insufficient_balance, payto_changed, http_500, ... |
message | string The same in plain words, always saying what was charged |
next_action | object What to do now. Always present |
receipt optional | object or null |
balance optional | object What is left: balance, monthly limit, what the next call can spend |
warnings optional | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/agent/calls/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agent/calls/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/calls/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "auth",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
},
"receipt": {
"call_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"idempotency_key": "idempotency-key",
"charged_nusd": "18990000",
"charge_status": "pending"
},
"balance": {},
"warnings": [
{
"kind": "low_balance"
}
],
"mode": "fixture"
}POST/v1/agent/calls/{id}/outcome
Write agent/calls/:id/outcome.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
outcome | "succeeded" | "failed" | "not-useful" |
reason_code optional | "wrong_result" | "low_quality" | "stale" | "too_slow" | "bad_format" | "other" |
note optional | string Accepted and not stored: reports are codes only |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
accepted | boolean |
duplicate | boolean True when this call was already reported. The first report stands |
invocation_id | string (uuid) |
counts_in_ranking | boolean |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/agent/calls/<id>/outcome \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"outcome":"succeeded","reason_code":"wrong_result","note":"note"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/calls/<id>/outcome",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"outcome":"succeeded","reason_code":"wrong_result","note":"note"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/calls/<id>/outcome", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"outcome":"succeeded","reason_code":"wrong_result","note":"note"})
});
console.log(await r.json());{
"accepted": false,
"duplicate": false,
"invocation_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"counts_in_ranking": false,
"mode": "fixture"
}GET/v1/agent/status
Read agent/status.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started" |
refused_by | string or null |
reason | string |
message | string |
next_action | object What to do now. Always present |
curl -s http://127.0.0.1:4100/v1/agent/status \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/agent/status",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/status", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "refused-by",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
}
}POST/v1/agent/links
Write agent/links.
| Body field | Type |
|---|---|
amount_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
Response fields
kind | "ok" | "needs_funding" | "over_limit" | "needs_approval" | "price_changed" | "failed" | "pending" | "paused" | "refused" | "not_started" |
refused_by | string or null |
reason | string |
message | string |
next_action | object What to do now. Always present |
curl -s -X POST http://127.0.0.1:4100/v1/agent/links \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"amount_nusd":"20000000000"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/agent/links",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"amount_nusd":"20000000000"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/agent/links", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"amount_nusd":"20000000000"})
});
console.log(await r.json());{
"kind": "ok",
"refused_by": "refused-by",
"reason": "reason",
"message": "message",
"next_action": {
"kind": "kind",
"message": "message",
"command": "command",
"tool": {},
"link": {
"purpose": "fund",
"url": "https://chain-scout.example/v1/ask",
"code": "PTRV-7K2Q",
"expires_at": "2026-10-24T09:12:03.000Z",
"amount_nusd": "20000000000"
},
"say_to_person": "say-to-person",
"accept_terms": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"approval_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"
}
}Applications
POST/v1/applications
Write applications.
| Body field | Type |
|---|---|
external_id | string Your id for the customer company. The same id returns the same application |
label | string |
cap_nusd | nano-USD string Spending cap for every key of this application together |
period optional | "lifetime" | "month"Default lifetime: it never resets |
per_call_limit_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
confirmation optional | "require" | "unattended"require: a person approves every paid call. Default unattended, within the caps |
project_id optional | string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
application | object |
created | boolean |
curl -s -X POST http://127.0.0.1:4100/v1/applications \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"external_id":"ptrv-ext-3c9a1f","label":"label","cap_nusd":"5000000000","period":"lifetime","per_call_limit_nusd":"5000000000","confirmation":"require","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/applications",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"external_id":"ptrv-ext-3c9a1f","label":"label","cap_nusd":"5000000000","period":"lifetime","per_call_limit_nusd":"5000000000","confirmation":"require","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"external_id":"ptrv-ext-3c9a1f","label":"label","cap_nusd":"5000000000","period":"lifetime","per_call_limit_nusd":"5000000000","confirmation":"require","project_id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f"})
});
console.log(await r.json());{
"application": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
},
"created": false
}GET/v1/applications
Read applications.
| Parameter | In · type |
|---|---|
external_id optional | query · string |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/applications \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/applications",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
}
],
"mode": "fixture"
}GET/v1/applications/{id}
Read applications/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
external_id | string |
label | string |
state | "active" | "disabled" |
confirmation optional | "require" | "unattended" |
cap | object |
keys | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/applications/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/applications/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
}PATCH/v1/applications/{id}
Write applications/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
label optional | string |
cap_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
confirmation optional | "require" | "unattended" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
external_id | string |
label | string |
state | "active" | "disabled" |
confirmation optional | "require" | "unattended" |
cap | object |
keys | list of objects |
mode | "fixture" |
curl -s -X PATCH http://127.0.0.1:4100/v1/applications/<id> \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"label":"label","cap_nusd":"5000000000","confirmation":"require"}'import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/applications/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"label":"label","cap_nusd":"5000000000","confirmation":"require"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>", {
method: "PATCH",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"label":"label","cap_nusd":"5000000000","confirmation":"require"})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
}POST/v1/applications/{id}/disable
Write applications/:id/disable.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
external_id | string |
label | string |
state | "active" | "disabled" |
confirmation optional | "require" | "unattended" |
cap | object |
keys | list of objects |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/applications/<id>/disable \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/applications/<id>/disable",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/disable", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
}POST/v1/applications/{id}/keys
Write applications/:id/keys.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
key | object or null |
replayed | boolean |
application | object |
curl -s -X POST http://127.0.0.1:4100/v1/applications/<id>/keys \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d 'null'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/applications/<id>/keys",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json=null)
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/keys", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify(null)
});
console.log(await r.json());{
"key": {
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"secret": "secret",
"scopes": [
"scopes"
]
},
"replayed": false,
"application": {
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
}
}DELETE/v1/applications/{id}/keys/{card}
Delete applications/:id/keys/:card.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
card | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
external_id | string |
label | string |
state | "active" | "disabled" |
confirmation optional | "require" | "unattended" |
cap | object |
keys | list of objects |
mode | "fixture" |
curl -s -X DELETE http://127.0.0.1:4100/v1/applications/<id>/keys/<card> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/applications/<id>/keys/<card>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/keys/<card>", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"external_id": "ptrv-ext-3c9a1f",
"label": "label",
"state": "active",
"confirmation": "require",
"cap": {},
"keys": [
{}
],
"mode": "fixture"
}GET/v1/applications/{id}/calls
Read applications/:id/calls.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
partition optional | query · string |
limit optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
curl -s http://127.0.0.1:4100/v1/applications/<id>/calls \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/applications/<id>/calls",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/applications/<id>/calls", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}Connections
POST/v1/connections
Write connections.
| Body field | Type |
|---|---|
provider | string Provider slug, e.g. exa |
label | string |
base_url | string Where the provider's own API lives, e.g. https://api.exa.ai |
auth_header optional | string Default authorization |
auth_prefix optional | string Default "Bearer " for authorization, empty otherwise |
secret | string Your provider API key. Stored encrypted, never returned |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
provider_key | string |
provider_slug | string or null |
label | string |
base_url | string |
auth_header | string |
hint | string or null |
state | "active" | "revoked" |
created_at | string (date-time) |
revoked_at | string (date-time) or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/connections \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"provider":"anthropic","label":"label","base_url":"https://example.invalid/","auth_header":"auth-header","auth_prefix":"auth-prefix","secret":"secret"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/connections",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"provider":"anthropic","label":"label","base_url":"https://example.invalid/","auth_header":"auth-header","auth_prefix":"auth-prefix","secret":"secret"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/connections", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"provider":"anthropic","label":"label","base_url":"https://example.invalid/","auth_header":"auth-header","auth_prefix":"auth-prefix","secret":"secret"})
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"provider_key": "provider-key",
"provider_slug": "provider-slug",
"label": "label",
"base_url": "https://example.invalid/",
"auth_header": "auth-header",
"hint": "hint",
"state": "active",
"created_at": "2026-10-24T09:12:03.000Z",
"revoked_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}GET/v1/connections
Read connections.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/connections \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/connections",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/connections", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"provider_key": "provider-key",
"provider_slug": "provider-slug",
"label": "label",
"base_url": "https://example.invalid/",
"auth_header": "auth-header",
"hint": "hint",
"state": "active",
"created_at": "2026-10-24T09:12:03.000Z",
"revoked_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
],
"mode": "fixture"
}GET/v1/connections/{id}
Read connections/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
provider_key | string |
provider_slug | string or null |
label | string |
base_url | string |
auth_header | string |
hint | string or null |
state | "active" | "revoked" |
created_at | string (date-time) |
revoked_at | string (date-time) or null |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/connections/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/connections/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/connections/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"provider_key": "provider-key",
"provider_slug": "provider-slug",
"label": "label",
"base_url": "https://example.invalid/",
"auth_header": "auth-header",
"hint": "hint",
"state": "active",
"created_at": "2026-10-24T09:12:03.000Z",
"revoked_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}DELETE/v1/connections/{id}
Delete connections/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
provider_key | string |
provider_slug | string or null |
label | string |
base_url | string |
auth_header | string |
hint | string or null |
state | "active" | "revoked" |
created_at | string (date-time) |
revoked_at | string (date-time) or null |
mode | "fixture" |
curl -s -X DELETE http://127.0.0.1:4100/v1/connections/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/connections/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/connections/<id>", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"provider_key": "provider-key",
"provider_slug": "provider-slug",
"label": "label",
"base_url": "https://example.invalid/",
"auth_header": "auth-header",
"hint": "hint",
"state": "active",
"created_at": "2026-10-24T09:12:03.000Z",
"revoked_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}Operator
GET/v1/operator/tool-economics
Read operator/tool-economics.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
arithmetic | object |
total | object |
providers | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/operator/tool-economics \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/operator/tool-economics",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/operator/tool-economics", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"arithmetic": {},
"total": {},
"providers": [
{}
],
"mode": "fixture"
}GET/v1/operator/listings
Read operator/listings.
| Parameter | In · type |
|---|---|
state optional | query · "in_review" | "changes_requested" | "approved" | "superseded" | "rejected" | "withdrawn" | "draft" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/operator/listings \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/operator/listings",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/operator/listings", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"version_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing": "listing",
"number": 1,
"state": "state",
"product_state": "product-state",
"seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"host": "host",
"host_verified": false,
"host_verified_by": "host-verified-by",
"local_fixture": false,
"preview": {
"listing_id": "listing-id",
"name": "Chain Scout",
"category": "search",
"host": "host",
"auth": "none",
"auth_header": "auth-header",
"fee_bps": 750,
"endpoints": [
null
],
"confirm_hash": "confirm-hash"
},
"changes": [
{
"endpoint": null,
"field": null,
"from": null,
"to": null,
"material": null
}
],
"material_change": false,
"contact_email": "contact-email",
"review_notes": "review-notes",
"submitted_at": "2026-10-24T09:12:03.000Z",
"reviewed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
],
"mode": "fixture"
}GET/v1/operator/listings/versions/{id}
Read operator/listings/versions/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
version_id | string (uuid) |
listing_id | string (uuid) |
listing | string |
number | integer |
state | string |
product_state | string |
seller_agent_id | string (uuid) |
host | string |
host_verified | boolean |
host_verified_by | string or null |
local_fixture | boolean |
preview | object |
changes | list of objects |
material_change | boolean |
contact_email | string |
review_notes | string or null |
submitted_at | string (date-time) or null |
reviewed_at | string (date-time) or null |
mode | "fixture" |
file | string |
curl -s http://127.0.0.1:4100/v1/operator/listings/versions/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/operator/listings/versions/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/versions/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"version_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing": "listing",
"number": 1,
"state": "state",
"product_state": "product-state",
"seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"host": "host",
"host_verified": false,
"host_verified_by": "host-verified-by",
"local_fixture": false,
"preview": {
"listing_id": "listing-id",
"name": "Chain Scout",
"category": "search",
"host": "host",
"auth": "none",
"auth_header": "auth-header",
"fee_bps": 750,
"endpoints": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"inputs": [
null
],
"required": [
null
],
"success": "success",
"checks_output": false,
"buyer_pays_nusd": "18990000",
"buyer_pays_usd": "buyer-pays-usd",
"fee_nusd": "990000",
"you_keep_nusd": "18990000"
}
],
"confirm_hash": "confirm-hash"
},
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"material_change": false,
"contact_email": "contact-email",
"review_notes": "review-notes",
"submitted_at": "2026-10-24T09:12:03.000Z",
"reviewed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture",
"file": "file"
}POST/v1/operator/listings/versions/{id}/decide
Write operator/listings/versions/:id/decide.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
decision | "approve" | "request_changes" | "reject" |
notes optional | string Required unless approving. The seller reads this |
attest_host optional | boolean You checked this seller controls the host yourself, because this build cannot contact a real one |
take_over optional | boolean Give the seller a URL a directory already lists. Never another seller's |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
version_id | string (uuid) |
listing_id | string (uuid) |
listing | string |
number | integer |
state | string |
product_state | string |
seller_agent_id | string (uuid) |
host | string |
host_verified | boolean |
host_verified_by | string or null |
local_fixture | boolean |
preview | object |
changes | list of objects |
material_change | boolean |
contact_email | string |
review_notes | string or null |
submitted_at | string (date-time) or null |
reviewed_at | string (date-time) or null |
mode | "fixture" |
file | string |
curl -s -X POST http://127.0.0.1:4100/v1/operator/listings/versions/<id>/decide \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"decision":"approve","notes":"notes","attest_host":false,"take_over":false}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/operator/listings/versions/<id>/decide",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"decision":"approve","notes":"notes","attest_host":false,"take_over":false})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/versions/<id>/decide", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"decision":"approve","notes":"notes","attest_host":false,"take_over":false})
});
console.log(await r.json());{
"version_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing": "listing",
"number": 1,
"state": "state",
"product_state": "product-state",
"seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"host": "host",
"host_verified": false,
"host_verified_by": "host-verified-by",
"local_fixture": false,
"preview": {
"listing_id": "listing-id",
"name": "Chain Scout",
"category": "search",
"host": "host",
"auth": "none",
"auth_header": "auth-header",
"fee_bps": 750,
"endpoints": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"inputs": [
null
],
"required": [
null
],
"success": "success",
"checks_output": false,
"buyer_pays_nusd": "18990000",
"buyer_pays_usd": "buyer-pays-usd",
"fee_nusd": "990000",
"you_keep_nusd": "18990000"
}
],
"confirm_hash": "confirm-hash"
},
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"material_change": false,
"contact_email": "contact-email",
"review_notes": "review-notes",
"submitted_at": "2026-10-24T09:12:03.000Z",
"reviewed_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture",
"file": "file"
}POST/v1/operator/listings/{id}/suspend
Write operator/listings/:id/suspend.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
reason | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version optional | integer |
state | string |
replayed optional | boolean |
warning optional | string or null |
changes optional | list of objects or null |
reason optional | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/operator/listings/<id>/suspend \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"reason":"reason"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/operator/listings/<id>/suspend",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"reason":"reason"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/<id>/suspend", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"reason":"reason"})
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"replayed": false,
"warning": "warning",
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"reason": "reason",
"mode": "fixture"
}POST/v1/operator/listings/{id}/reinstate
Write operator/listings/:id/reinstate.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version optional | integer |
state | string |
replayed optional | boolean |
warning optional | string or null |
changes optional | list of objects or null |
reason optional | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/operator/listings/<id>/reinstate \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/operator/listings/<id>/reinstate",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/operator/listings/<id>/reinstate", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"replayed": false,
"warning": "warning",
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"reason": "reason",
"mode": "fixture"
}Me
GET/v1/me
Read me.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
key_id | string (uuid) |
scopes | list of string |
card_id | string (uuid) or null |
kind | "card" | "owner" | "operator" |
mode | "fixture" |
live_spend_enabled | false |
curl -s http://127.0.0.1:4100/v1/me \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/me",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/me", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"key_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"scopes": [
"scopes"
],
"card_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"kind": "card",
"mode": "fixture",
"live_spend_enabled": false
}Seller
POST/v1/seller/validate
Write seller/validate.
| Body field | Type |
|---|---|
file | string The text of petrova.yaml. JSON is YAML, so JSON works too |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
valid | boolean |
errors | list of objects |
warnings | list of objects |
preview | object or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/validate \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"file":"file"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/validate",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"file":"file"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/validate", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"file":"file"})
});
console.log(await r.json());{
"valid": false,
"errors": [
{
"path": "path",
"code": "PTRV-7K2Q",
"message": "message",
"fix": "fix"
}
],
"warnings": [
{
"path": "path",
"code": "PTRV-7K2Q",
"message": "message",
"fix": "fix"
}
],
"preview": {
"listing_id": "listing-id",
"name": "Chain Scout",
"category": "search",
"host": "host",
"auth": "none",
"auth_header": "auth-header",
"fee_bps": 750,
"endpoints": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"inputs": [
null
],
"required": [
null
],
"success": "success",
"checks_output": false,
"buyer_pays_nusd": "18990000",
"buyer_pays_usd": "buyer-pays-usd",
"fee_nusd": "990000",
"you_keep_nusd": "18990000"
}
],
"confirm_hash": "confirm-hash"
},
"mode": "fixture"
}POST/v1/seller/from-openapi
Write seller/from-openapi.
| Body field | Type |
|---|---|
openapi | string The OpenAPI file, as JSON or YAML text |
price_usd optional | string One price for every endpoint. Without it every price says TODO |
base_url optional | string |
id optional | string |
category optional | string |
contact_email optional | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
file | string A first petrova.yaml. Read it, and set what it marks TODO |
skipped | list of objects |
warnings | list of string |
endpoints | integer |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/from-openapi \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"openapi":"openapi","price_usd":"0.005","base_url":"https://example.invalid/","id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","category":"search","contact_email":"contact-email"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/from-openapi",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"openapi":"openapi","price_usd":"0.005","base_url":"https://example.invalid/","id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","category":"search","contact_email":"contact-email"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/from-openapi", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"openapi":"openapi","price_usd":"0.005","base_url":"https://example.invalid/","id":"3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f","category":"search","contact_email":"contact-email"})
});
console.log(await r.json());{
"file": "file",
"skipped": [
{
"operation": "operation",
"reason": "reason"
}
],
"warnings": [
"warnings"
],
"endpoints": 1,
"mode": "fixture"
}POST/v1/seller/listings
Write seller/listings.
| Body field | Type |
|---|---|
file | string The text of petrova.yaml. JSON is YAML, so JSON works too |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
listing | string |
version | integer |
state | string |
replayed | boolean The same file again: nothing new was saved |
warnings | list of objects |
preview | object |
changes | list of objects |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"file":"file"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"file":"file"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"file":"file"})
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing": "listing",
"version": 1,
"state": "state",
"replayed": false,
"warnings": [
{
"path": "path",
"code": "PTRV-7K2Q",
"message": "message",
"fix": "fix"
}
],
"preview": {
"listing_id": "listing-id",
"name": "Chain Scout",
"category": "search",
"host": "host",
"auth": "none",
"auth_header": "auth-header",
"fee_bps": 750,
"endpoints": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"inputs": [
null
],
"required": [
null
],
"success": "success",
"checks_output": false,
"buyer_pays_nusd": "18990000",
"buyer_pays_usd": "buyer-pays-usd",
"fee_nusd": "990000",
"you_keep_nusd": "18990000"
}
],
"confirm_hash": "confirm-hash"
},
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"mode": "fixture"
}GET/v1/seller/listings
Read seller/listings.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
data | list of objects |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/seller/listings \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"data": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing": "listing",
"seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"status": "draft",
"suspended_reason": "suspended-reason",
"host": {
"host": "host",
"verified": false,
"verified_by": "http_token"
},
"credential": {
"stored": false,
"hint": "hint",
"updated_at": "2026-10-24T09:12:03.000Z"
},
"live_version": 1,
"latest_version": 1,
"tools": [
{
"tool_id": null,
"endpoint": null,
"hidden": null
}
],
"versions": [
{
"number": null,
"id": null,
"state": null,
"content_hash": null,
"fee_bps": null,
"review_notes": null,
"changes": null,
"submitted_at": null,
"reviewed_at": null,
"created_at": null
}
],
"created_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}
],
"mode": "fixture"
}GET/v1/seller/listings/{id}
Read seller/listings/:id.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
id | string (uuid) |
listing | string |
seller_agent_id | string (uuid) |
status | "draft" | "in_review" | "changes_requested" | "live" | "live_new_version_in_review" | "live_changes_requested" | "unlisted" | "suspended" |
suspended_reason | string or null |
host | object or null |
credential | object |
live_version | integer or null |
latest_version | integer or null |
tools | list of objects |
versions | list of objects |
created_at | string (date-time) |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/seller/listings/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"listing": "listing",
"seller_agent_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"status": "draft",
"suspended_reason": "suspended-reason",
"host": {
"host": "host",
"verified": false,
"verified_by": "http_token"
},
"credential": {
"stored": false,
"hint": "hint",
"updated_at": "2026-10-24T09:12:03.000Z"
},
"live_version": 1,
"latest_version": 1,
"tools": [
{
"tool_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"endpoint": "endpoint",
"hidden": false
}
],
"versions": [
{
"number": 1,
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"state": "draft",
"content_hash": "content-hash",
"fee_bps": 750,
"review_notes": "review-notes",
"changes": [
{
"endpoint": null,
"field": null,
"from": null,
"to": null,
"material": null
}
],
"submitted_at": "2026-10-24T09:12:03.000Z",
"reviewed_at": "2026-10-24T09:12:03.000Z",
"created_at": "2026-10-24T09:12:03.000Z"
}
],
"created_at": "2026-10-24T09:12:03.000Z",
"mode": "fixture"
}GET/v1/seller/listings/{id}/file
Read seller/listings/:id/file.
| Parameter | In · type |
|---|---|
id | path · string |
version optional | query · integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version | integer |
state | string |
file | string |
preview | object |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/seller/listings/<id>/file \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings/<id>/file",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/file", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"file": "file",
"preview": {
"listing_id": "listing-id",
"name": "Chain Scout",
"category": "search",
"host": "host",
"auth": "none",
"auth_header": "auth-header",
"fee_bps": 750,
"endpoints": [
{
"id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"name": "Chain Scout",
"method": "GET",
"url": "https://chain-scout.example/v1/ask",
"inputs": [
null
],
"required": [
null
],
"success": "success",
"checks_output": false,
"buyer_pays_nusd": "18990000",
"buyer_pays_usd": "buyer-pays-usd",
"fee_nusd": "990000",
"you_keep_nusd": "18990000"
}
],
"confirm_hash": "confirm-hash"
},
"mode": "fixture"
}GET/v1/seller/listings/{id}/host
Read seller/listings/:id/host.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
host | string |
verified | boolean |
verified_by | "http_token" | "operator_attest" or null |
verified_at | string (date-time) or null |
provider_key | string Your identity in the catalog, from the host. Cards allow services by this |
proof | object |
checked optional | "found" | "already_verified" | "blocked_by_fixture_boundary"blocked_by_fixture_boundary: this build cannot contact a real host. A reviewer can check it and attest |
mode | "fixture" |
curl -s http://127.0.0.1:4100/v1/seller/listings/<id>/host \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/seller/listings/<id>/host",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/host", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"host": "host",
"verified": false,
"verified_by": "http_token",
"verified_at": "2026-10-24T09:12:03.000Z",
"provider_key": "provider-key",
"proof": {
"put_this_text": "put-this-text",
"at_this_url": "https://example.invalid/"
},
"checked": "found",
"mode": "fixture"
}POST/v1/seller/listings/{id}/host/verify
Write seller/listings/:id/host/verify.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
host | string |
verified | boolean |
verified_by | "http_token" | "operator_attest" or null |
verified_at | string (date-time) or null |
provider_key | string Your identity in the catalog, from the host. Cards allow services by this |
proof | object |
checked optional | "found" | "already_verified" | "blocked_by_fixture_boundary"blocked_by_fixture_boundary: this build cannot contact a real host. A reviewer can check it and attest |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/host/verify \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/host/verify",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/host/verify", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"host": "host",
"verified": false,
"verified_by": "http_token",
"verified_at": "2026-10-24T09:12:03.000Z",
"provider_key": "provider-key",
"proof": {
"put_this_text": "put-this-text",
"at_this_url": "https://example.invalid/"
},
"checked": "found",
"mode": "fixture"
}PUT/v1/seller/listings/{id}/credential
Write seller/listings/:id/credential.
| Parameter | In · type |
|---|---|
id | path · string |
| Body field | Type |
|---|---|
api_key | string Your API key for your own API. Stored encrypted. Never returned, and never in petrova.yaml |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
stored | boolean |
hint | string or null |
mode | "fixture" |
curl -s -X PUT http://127.0.0.1:4100/v1/seller/listings/<id>/credential \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"api_key":"api-key"}'import os, requests
r = requests.put("http://127.0.0.1:4100/v1/seller/listings/<id>/credential",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"api_key":"api-key"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/credential", {
method: "PUT",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"api_key":"api-key"})
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"stored": false,
"hint": "hint",
"mode": "fixture"
}DELETE/v1/seller/listings/{id}/credential
Delete seller/listings/:id/credential.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
stored | boolean |
hint | string or null |
mode | "fixture" |
curl -s -X DELETE http://127.0.0.1:4100/v1/seller/listings/<id>/credential \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.delete("http://127.0.0.1:4100/v1/seller/listings/<id>/credential",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/credential", {
method: "DELETE",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"stored": false,
"hint": "hint",
"mode": "fixture"
}POST/v1/seller/listings/{id}/submit
Write seller/listings/:id/submit.
| Parameter | In · type |
|---|---|
id | path · string |
| Body field | Type |
|---|---|
confirm_hash | string |
version optional | integer |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version optional | integer |
state | string |
replayed optional | boolean |
warning optional | string or null |
changes optional | list of objects or null |
reason optional | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/submit \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"confirm_hash":"confirm-hash","version":1}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/submit",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"confirm_hash":"confirm-hash","version":1})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/submit", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"confirm_hash":"confirm-hash","version":1})
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"replayed": false,
"warning": "warning",
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"reason": "reason",
"mode": "fixture"
}POST/v1/seller/listings/{id}/withdraw
Write seller/listings/:id/withdraw.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version optional | integer |
state | string |
replayed optional | boolean |
warning optional | string or null |
changes optional | list of objects or null |
reason optional | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/withdraw \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/withdraw",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/withdraw", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"replayed": false,
"warning": "warning",
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"reason": "reason",
"mode": "fixture"
}POST/v1/seller/listings/{id}/unlist
Write seller/listings/:id/unlist.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version optional | integer |
state | string |
replayed optional | boolean |
warning optional | string or null |
changes optional | list of objects or null |
reason optional | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/unlist \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/unlist",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/unlist", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"replayed": false,
"warning": "warning",
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"reason": "reason",
"mode": "fixture"
}POST/v1/seller/listings/{id}/relist
Write seller/listings/:id/relist.
| Parameter | In · type |
|---|---|
id | path · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
Response fields
listing_id | string (uuid) |
version optional | integer |
state | string |
replayed optional | boolean |
warning optional | string or null |
changes optional | list of objects or null |
reason optional | string or null |
mode | "fixture" |
curl -s -X POST http://127.0.0.1:4100/v1/seller/listings/<id>/relist \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/seller/listings/<id>/relist",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/seller/listings/<id>/relist", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{
"listing_id": "3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f",
"version": 1,
"state": "state",
"replayed": false,
"warning": "warning",
"changes": [
{
"endpoint": "endpoint",
"field": "field",
"from": null,
"to": null,
"material": false
}
],
"reason": "reason",
"mode": "fixture"
}Links
POST/v1/links/view
Write links/view.
| Body field | Type |
|---|---|
token | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/links/view \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"token":"token"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/view",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"token":"token"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/links/view", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"token":"token"})
});
console.log(await r.json());{}POST/v1/links/pay
Write links/pay.
| Body field | Type |
|---|---|
token | string |
csrf | string |
agent_id | string |
amount_nusd | string |
code optional | string The 6-digit code the agent gave its person with the link. Needed for a fund link and for an approval; a top-up link needs none |
monthly_limit_nusd optional | string |
approval_over_nusd optional | string |
provider | "fixture" | "card" | "usdc_topup" |
confirm optional | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/links/pay \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd","provider":"fixture","confirm":"confirm"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/pay",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd","provider":"fixture","confirm":"confirm"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/links/pay", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd","provider":"fixture","confirm":"confirm"})
});
console.log(await r.json());{}POST/v1/links/decide
Write links/decide.
| Body field | Type |
|---|---|
token | string |
csrf | string |
agent_id | string |
amount_nusd | string |
code optional | string The 6-digit code the agent gave its person with the link. Needed for a fund link and for an approval; a top-up link needs none |
decision | "approve" | "reject" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/links/decide \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","decision":"approve"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/decide",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","decision":"approve"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/links/decide", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","decision":"approve"})
});
console.log(await r.json());{}POST/v1/links/deposit
Write links/deposit.
| Body field | Type |
|---|---|
token | string |
csrf | string |
agent_id | string |
amount_nusd | string |
code optional | string The 6-digit code the agent gave its person with the link. Needed for a fund link before the address is shown |
monthly_limit_nusd optional | string |
approval_over_nusd optional | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/links/deposit \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/deposit",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/links/deposit", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"token":"token","csrf":"csrf","agent_id":"research-bot","amount_nusd":"amount-nusd","code":"PTRV-7K2Q","monthly_limit_nusd":"monthly-limit-nusd","approval_over_nusd":"approval-over-nusd"})
});
console.log(await r.json());{}POST/v1/links/deposit/status
Write links/deposit/status.
| Body field | Type |
|---|---|
token | string |
csrf | string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/links/deposit/status \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"token":"token","csrf":"csrf"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/links/deposit/status",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"token":"token","csrf":"csrf"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/links/deposit/status", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"token":"token","csrf":"csrf"})
});
console.log(await r.json());{}Owner
GET/v1/owner/me
Read owner/me.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s http://127.0.0.1:4100/v1/owner/me \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/owner/me",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/me", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}GET/v1/owner/feed
Read owner/feed.
| Parameter | In · type |
|---|---|
limit optional | query · integer |
cursor optional | query · string |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s http://127.0.0.1:4100/v1/owner/feed \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/owner/feed",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/feed", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}GET/v1/owner/agents
Read owner/agents.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s http://127.0.0.1:4100/v1/owner/agents \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/owner/agents",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/agents", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}PATCH/v1/owner/agents/{id}
Write owner/agents/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
monthly_limit_nusd optional | nano-USD string Integer nano-USD, 1 USD = 1000000000 |
approval_over_nusd optional | nano-USD string or null |
state optional | "active" | "paused" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X PATCH http://127.0.0.1:4100/v1/owner/agents/<id> \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"monthly_limit_nusd":"5000000000","approval_over_nusd":"18990000","state":"active"}'import os, requests
r = requests.patch("http://127.0.0.1:4100/v1/owner/agents/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"monthly_limit_nusd":"5000000000","approval_over_nusd":"18990000","state":"active"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/agents/<id>", {
method: "PATCH",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"monthly_limit_nusd":"5000000000","approval_over_nusd":"18990000","state":"active"})
});
console.log(await r.json());{}POST/v1/owner/calls/{id}/decide
Write owner/calls/:id/decide.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
decision | "approve" | "reject" |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/owner/calls/<id>/decide \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"decision":"approve"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/calls/<id>/decide",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"decision":"approve"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/calls/<id>/decide", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"decision":"approve"})
});
console.log(await r.json());{}POST/v1/owner/agents/{id}/remove
Write owner/agents/:id/remove.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/owner/agents/<id>/remove \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/agents/<id>/remove",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/agents/<id>/remove", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}POST/v1/owner/signin
Write owner/signin.
| Body field | Type |
|---|---|
recovery_code | string The recovery code the person was shown when they first paid. Never given to an agent |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/owner/signin \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"recovery_code":"recovery-code"}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/signin",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"recovery_code":"recovery-code"})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/signin", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"recovery_code":"recovery-code"})
});
console.log(await r.json());{}POST/v1/owner/recovery
Write owner/recovery.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/owner/recovery \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/recovery",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/recovery", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}POST/v1/owner/pause-all
Write owner/pause-all.
| Body field | Type |
|---|---|
paused | boolean |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/owner/pause-all \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"paused":false}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/owner/pause-all",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"paused":false})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/owner/pause-all", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"paused":false})
});
console.log(await r.json());{}X402
POST/v1/x402/tools/{id}/call
Write x402/tools/:id/call.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Body field | Type |
|---|---|
inputs | object |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
upstream failed | 502 | Yes | A supplier or tool failed; you paid nothing. Retry. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/x402/tools/<id>/call \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"inputs":{}}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/x402/tools/<id>/call",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"inputs":{}})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/x402/tools/<id>/call", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"inputs":{}})
});
console.log(await r.json());{}POST/v1/x402/call
Write x402/call.
| Body field | Type |
|---|---|
provider | string Provider slug from search, e.g. exa |
path | string Path from search, e.g. /search |
method optional | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" |
inputs optional | object |
path_params optional | object |
query optional | object |
headers optional | object |
body optional | any |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
upstream failed | 502 | Yes | A supplier or tool failed; you paid nothing. Retry. |
unavailable | 503 | Yes | Try again shortly. |
curl -s -X POST http://127.0.0.1:4100/v1/x402/call \
-H "authorization: Bearer $PETROVA_API_KEY" \
-H 'content-type: application/json' \
-d '{"provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null}'import os, requests
r = requests.post("http://127.0.0.1:4100/v1/x402/call",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]},
json={"provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/x402/call", {
method: "POST",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY, "content-type": "application/json" },
body: JSON.stringify({"provider":"anthropic","path":"path","method":"GET","inputs":{},"path_params":{},"query":{},"headers":{},"body":null})
});
console.log(await r.json());{}GET/v1/x402/payments/{id}
Read x402/payments/:id.
| Parameter | In · type |
|---|---|
id | path · string (uuid) |
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
invalid_request | 400 | No | Fix the field named in the message. |
unauthorized | 401 | No | Send a valid key: Authorization: Bearer ptrv_test_… |
insufficient_balance | 402 | No | Add funds, or lower the amount. |
scope_denied | 403 | No | Use a key that has the scope shown above. |
not_found | 404 | No | Check the id; it must belong to this account. |
conflict | 409 | No | The state changed (used, expired or already decided). Read it again. |
error | 410 | No | See the message. |
rate_limit / spend limit | 429 | No | A cap or loop pause stopped it. Raise the cap or fix the loop. |
internal_error | 500 | Yes | Retry with the same idempotency key. |
unavailable | 503 | Yes | Try again shortly. |
curl -s http://127.0.0.1:4100/v1/x402/payments/<id> \
-H "authorization: Bearer $PETROVA_API_KEY"import os, requests
r = requests.get("http://127.0.0.1:4100/v1/x402/payments/<id>",
headers={"authorization": "Bearer " + os.environ["PETROVA_API_KEY"]})
print(r.json())const r = await fetch("http://127.0.0.1:4100/v1/x402/payments/<id>", {
method: "GET",
headers: { authorization: "Bearer " + process.env.PETROVA_API_KEY }
});
console.log(await r.json());{}