Receipts, ledger and reports#

Every call Lockpin sees is recorded in a ledger file on the machine. This page shows how to read it: per-call receipts, the hash-chained ledger and its exports, the weekly digest, and the reports that compare Lockpin’s numbers with your providers’ bills. It is for developers checking a task’s cost and for admins, auditors and finance teams who need the records.

Where the ledger is#

The installed service writes the ledger as lockpin-ledger.jsonl in the data folder:

System	Data folder
Windows	`%LOCALAPPDATA%\Lockpin`
macOS	`~/Library/Application Support/Lockpin`
Linux	`$XDG_DATA_HOME/lockpin`, else `~/.local/share/lockpin`

LOCKPIN_DATA_DIR changes it. lockpin projects, suggest, gaps, pause, resume, stop and quit look in the data folder on their own. The other commands that read the ledger default to lockpin-ledger.jsonl in the current folder: run them from the data folder, or pass -ledger FILE.

Receipts#

A receipt says what a call would have cost without Lockpin, what it cost, one line for each thing Lockpin did to it, and what is left on the tightest limit. Refusals have receipts too.

Print the last calls’ receipts, newest first:

lockpin receipt -n 5
lockpin receipt fix-login-bug
lockpin receipt -json

Flag	Default	What it does
`-ledger`	`lockpin-ledger.jsonl`	The ledger file Lockpin writes.
`-n`	`10`	How many calls to print.
`-json`	off	Print JSON.
`TASK`	all tasks	Limit the receipts to one task.

lockpin receipt reads the ledger file, so it works with Lockpin stopped.

The receipt on each reply#

Non-streaming replies carry X-Lockpin-Receipt, the receipt as one line of JSON (at most 4 KB):

{"v":1,"at":"2026-10-24T14:05:00Z","task":"fix-login-bug","model":"claude-sonnet-5-5","decision":"sent",
 "was_usd":0.42,"sent_usd":0.27,
 "lines":[{"stage":"trim","what":"trimmed stale tool results, 11.9k tokens (−$0.15)","usd":-0.15,"est":true}],
 "left":{"scope":"task","name":"fix-login-bug","usd":1.2},"summary":"$0.27 (was $0.42) · $1.20 left on task"}

A negative line usd is a saving, a positive one cost more, and 0 is for information. A charge Lockpin had to estimate is marked “(est.)” in the summary. Streamed replies send their headers before the call is charged, so their receipts are in the meter and in lockpin receipt.

The ledger#

The ledger records every budget change, call charged, call refused, held-call decision, alert, and start and stop of Lockpin.

Hash chain. Every line carries the SHA-256 hash of the line before it. The hash has no key: it catches accidental damage and casual edits, but anyone who can write the file can recompute the chain, and lines cut from the end leave no trace.
Signed checkpoints. A team node also adds a checkpoint every 1,000 lines and when it stops, signed with its Ed25519 node key. Lines up to the last checkpoint cannot then be edited without breaking a signature. Only a team node writes checkpoints.
What is not in it. No prompt, response, key or alert text is in an export.

Verify the ledger#

Give verify a copy of a live ledger:

lockpin ledger verify lockpin-ledger.jsonl
lockpin ledger verify -key HEX copy.jsonl

-key is the node’s public key in hex, as lockpin keys seal printed it. verify prints verified N entries, or chain broken at entry N or signature failed at checkpoint N and exits 1.

Export the ledger#

lockpin ledger export -format csv -since 2026-11-01 -o spend.csv lockpin-ledger.jsonl

Flag	Default	What it does
`-format`	`jsonl`	`jsonl`, `csv` or `focus` (CSV in the FOCUS 1.4 Cost and Usage layout).
`-since`, `-until`	none	RFC 3339 or a `YYYY-MM-DD` day in UTC. `-until` is exclusive.
`-o`	standard output	The file to write. It never overwrites one.
`-keys`	none	`-format focus`: the keys file, for the team of a key on lines that do not say it.
`-follow DIR`	none	Keep writing the ledger, as it grows, to `DIR/lockpin-<source>.jsonl`, until stopped.

Export is safe on a live ledger: it reads only lines that are complete. In CSV, a cell starting with =, +, - or @ gets a leading ' so a spreadsheet does not run it as a formula.

Each record has the schema lockpin.ledger.v1 and carries schema, host, source, seq, time, type and hash. The type is one of budget, reserve, charge, release, reject, decision, alert, start, stop, off, pause, resume, caplink, checkpoint, prices or unreadable. In an export not filtered by time, each record’s prev equals the hash of the record before it, so a gap shows.

Continuous export for a log agent#

Give Lockpin a folder and it keeps writing the ledger there as JSON Lines while it runs, for Splunk, Microsoft Sentinel, Elastic, Datadog or another log agent to collect:

lockpin -audit-export /var/log/lockpin

Or set "audit-export" in lockpin.json. New lines appear within about 2 seconds. A full or unwritable folder stops the export, never the cap. Make the folder yourself first, readable only by Lockpin and your log agent. See Security.

Finance export (FOCUS)#

-format focus writes spend in FOCUS 1.4, one row per UTC day of each provider, model, key, project, task and tag set, for a finance team’s FinOps tools or a spreadsheet pivot.

lockpin ledger export -format focus -keys lockpin-keys.json -since 2026-10-01 -o focus.csv lockpin-ledger.jsonl

Important

These are Lockpin’s numbers, not your provider’s invoice. Lockpin prices each call at the list price in its catalog. Use the file to split the invoice by team, project and tag, and reconcile the total against the invoice. Do not load it next to your cloud’s own billing data for the same provider as more spend: that counts it twice. Filter on x_CostSource, which starts with lockpin.

Every row carries x_AsOf, the time it was read. The hosted dashboard offers the same format across machines: see Hosted dashboard and reporting.

The weekly digest#

lockpin digest prints the last 7 days from the ledger: what was spent (against the week before), what Lockpin saved, the calls it blocked, the loops it caught and the tasks that spent most.

lockpin digest
lockpin digest -send

-send also posts it to the alert destinations. A running Lockpin posts it there itself every week (-digest-at, default mon 09:00; off never posts it). See Alerts and phone approvals.

What your providers billed#

lockpin import reads what Anthropic, OpenAI and Cursor billed, from their admin APIs, and shows it by key or person and model, with outliers. No agent has to go through Lockpin for this.

Windows

$env:ANTHROPIC_ADMIN_KEY = "..."; $env:OPENAI_ADMIN_KEY = "..."
lockpin import -days 7

macOS and Linux

export ANTHROPIC_ADMIN_KEY=... OPENAI_ADMIN_KEY=...
lockpin import -days 7

Flag	Default	What it does
`-days`	`30`	How many days back to read, 1 to 30.
`-providers`	every provider whose admin key is set	`anthropic`, `openai`, `cursor`.
`-all`	off	Every key or person and model, not the top 10 per provider.
`-emails`	off	Show people’s emails in full (masked by default).
`-tz`	`Local`	Time zone for the overnight rule.
`-json`	off	Print JSON.

The admin keys are read from ANTHROPIC_ADMIN_KEY, OPENAI_ADMIN_KEY and CURSOR_ADMIN_KEY. They are never written down, and nothing is sent anywhere.

It flags three outliers:

Outlier	Rule
Spike	A day at least 3x the usual day (the median of the 14 days before it) and at least $25.
Overnight	A run of 6 hours or more with spend, starting between midnight and 06:00 local time, spending at least $20. That pattern is often a loop.
Concentration	One key or person is 40% or more of a provider’s month, with at least 5 spending and at least $200 on the bill.

For Anthropic and OpenAI each outlier comes with a lockpin keys create command and a starting daily and monthly limit. For Cursor it suggests a member spend limit to set in Cursor’s dashboard.

Check Lockpin against the bill#

lockpin reconcile compares a provider’s own usage export (CSV) with what Lockpin charged for the same days and models.

lockpin reconcile usage.csv -days 7

Flag	Default	What it does
`-format`	`auto`	`auto`, `anthropic`, `openai` or `generic` (`date,model,input_tokens,output_tokens,cost_usd`).
`-columns`	none	Name the export’s columns yourself, such as `date=Date,model=Model,input=Input tokens,output=Output tokens,cost=Cost (USD)`. Add `,cents` when cost is in cents.
`-from`, `-to`	the export’s first and last day	Days to compare, `YYYY-MM-DD`.
`-days`	none	The last N days ending today instead.
`-provider`	the detected vendor	Compare only ledger charges for this provider.
`-tolerance`	`1`	Percent difference in the period total that still counts as agreement.
`-ledger`	`lockpin-ledger.jsonl`	Local ledger file.
`-json`	off	Print JSON.

It prints, per day and model, the provider’s total against Lockpin’s, the difference in dollars and percent, and one line naming the largest gap and its likely cause: a model Lockpin could not price, a tier mismatch, or calls that bypassed the proxy.

What reporting would upload#

Reporting to the hosted dashboard is optional and off by default. lockpin report preview prints what would be uploaded, so you can see it before you turn reporting on. lockpin report status prints the reporter’s state.

lockpin report preview
lockpin report status

-detail totals|tags|tasks (default tags) sets the local maximum detail for preview. See What leaves your machine.