The Record
The shared, event-sourced set of posted facts about one VIN — read identically by a person and an agent. The record, then the deal.
The record is the shared, event-sourced set of posted facts about one VIN, read identically by both sides of the market. It is the front door: free, keyless, and legible before any identity is established. The record, then the deal.
Evidence objects
Nothing on the record is a bare number. Every fact is an evidence object:
{
"value": "24990.00",
"source": "the attesting authority, named at the estate's level of abstraction",
"timestamp": "2026-08-09T00:00:00Z",
"verification": "posted"
}value— the fact, money as a decimal string.source— the attesting authority. Never a sub-processor, vendor, or data-book brand: the provider behind a fact is walled off on the integration layer, never leaked onto the record.timestamp— when it was posted.verification—posted(verified against the record) orreported(not yet verified). The two states never blend.
Act-minted facts additionally carry a dereferenceable pointer to the event that minted them — so a claim can always be walked back to the act that made it true.
The twin invariant
The same VIN, read on any two doors, returns byte-identical shared evidence. The human face and the machine face are not two products — they are two representations of one record, negotiated by content type, never rewritten. The HTML a person reads and the Markdown-plus-JSON an agent reads are the same statement in different clothes. The agent reads the same record you do.
Scaled up from the record to the whole product, this is why every face — this documentation, the SDK, the CLI, the doors — is generated from the one catalog and cannot drift.
Content negotiation
GET /{vin} serves three faces, negotiated on Accept (with Vary: Accept),
or forced by extension:
| Reader | How | Face |
|---|---|---|
an agent with curl | default | application/json |
| an assistant reading prose | Accept: text/markdown or /{vin}.md | Markdown |
| a person in a browser | Accept: text/html or /{vin}.html | HTML |
Same bytes underneath. The JSON keeps worth and ask apart: a valuation block and,
when a listing stands, a listing block carrying the same asking price the
listings door posts — the record face and the listings door can never disagree
about whether a VIN is listed or at what ask.
The precision ladder
Access deepens by rung, over one package (apis.vin) and one key. The rung a
reader stands on is posted as data — never enforced as a lockout:
| Rung | Auth | What it grants |
|---|---|---|
| anonymous | none | every free data face — decode, recalls, taxes math, the record composition — and POST /keys mints a key |
| keyed | Bearer vk_… | account context on top of every keyless surface, metered under a posted usd-per-day ceiling |
| paid | per act | entered per act, not per seat: a priced act returns a 402 OFFER with a durable intent that settles by x402 or checkout |
No account wall stands between a reader and the record. Precision is a meter, not a gate: a runaway agent hits a posted ceiling, never a surprise invoice.
Provenance and the sandbox
Every record-derived payload names its source and environment. Where a real
counterparty integration is not yet connected, the backend simulates it —
behind the same wire shapes the real one uses — and every simulated payload is
labeled in the body: { "environment": "sandbox", "simulated": true }.
simulated: true stays true when it is true. Sandbox is an environment, never a
frontend mock; its responses are deterministic and replayable.
Next
- The catalog — every capability that reads or writes the record.
- Subjects & events — how the record changes, and how to follow it.
- The act — the gate law that guards every write.