# Quickstart — five minutes from key to first ledger entry

Veritally keeps audit-grade books for what your AI agents spend. This gets you
from an API key to a verified ledger entry.

Base URL: `https://api.veritally.ai` · Auth: `Authorization: Bearer <your key>`

Get an ingest key for your tenant from the Veritally owner and set `VT_KEY` in your environment. Account and key provisioning are currently manual. Public demo reads work without a key; writes require one. Use an admin key separately for closes and adjustments.

The JavaScript SDK takes `apiKey`; the Python SDK takes `api_key`. Both send a Bearer header to `/ingest` and surface failed delivery. [SDK examples and retry behavior](./integrations.md#veritally-sdks).

## 1. Record a token-usage event

Give a model with token counts and Veritally prices it from the per-model price
book; or pass an explicit `cost_usd`.

```bash
curl --fail-with-body -sS https://api.veritally.ai/v1/events \
  -H "Authorization: Bearer $VT_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input_tokens": 120000,
    "output_tokens": 40000,
    "agent": "research-agent",
    "principal": "you@company.com",
    "project": "research",
    "event_key": "run-2026-07-03-001"
  }'
```

Response includes the booked cost, GL account, ledger seq, and hash. Re-POST the
same `event_key` and it returns `duplicate: true` — never double-booked.

## 2. Record a payment (card / wallet / merchant)

```bash
curl --fail-with-body -sS https://api.veritally.ai/v1/payments \
  -H "Authorization: Bearer $VT_KEY" -H "Content-Type: application/json" \
  -d '{ "amount_usd": 42.50, "merchant": "Anthropic", "agent": "ops-agent", "event_key": "pay-001" }'
```

## 3. Check a budget before spending

```bash
curl -s "https://api.veritally.ai/v1/budgets/check?scope=agent&name=research-agent" \
  -H "Authorization: Bearer $VT_KEY"
# → { "scope":"agent","name":"research-agent","limit_usd":100,"spent":63.2,"remaining":36.8,"over_budget":false }
```

## 4. See the books

```bash
curl -s "https://api.veritally.ai/v1/summary?period=2026-07" -H "Authorization: Bearer $VT_KEY"
curl -s "https://api.veritally.ai/v1/ledger?limit=20"        -H "Authorization: Bearer $VT_KEY"
```

## 5. Verify the ledger's tamper evidence

```bash
curl -s https://api.veritally.ai/v1/verify -H "Authorization: Bearer $VT_KEY"
# → { "valid": true, "entries_checked": 41, "first_broken_seq": null }
```

## 6. Close the month (admin key)

```bash
curl -s "https://api.veritally.ai/v1/reports/close?period=2026-07" -H "Authorization: Bearer $VT_ADMIN"  # dry run
curl -s https://api.veritally.ai/v1/close -H "Authorization: Bearer $VT_ADMIN" \
  -H "Content-Type: application/json" -d '{ "period": "2026-07" }'                                        # locks it
```

Once a period is closed, events dated inside it are refused (`409 period_locked`).
Corrections go through `POST /v1/adjustments`, which posts a new hash-chained
reclass entry — the original is never edited.

A successful verification checks the stored chain against its hashes. It does not validate an upstream invoice or rule out a complete rewrite by the operator. See [signing and anchoring](./signing-and-anchoring.md) for publishing independent chain-head commitments.

## Roles

- **ingest** — may record events and payments (REST, MCP or SDK); administrative closes and adjustments require an admin key.
- **admin** — everything, including `/v1/close` and `/v1/adjustments`.

Keys are stored only as SHA-256 hashes; your raw key is shown once at creation.
Rate limit: best-effort 120 requests/minute per key, per Worker isolate.

Next: [MCP connection](./mcp-connection.md) · [Integration snippets](./integrations.md) · [Hash-chain spec](./hash-chain.md)