# Liberty

> Agent Settlement — escrow and credits for agent jobs. Demo only. Not real money.

The human demo stores payer credits and jobs in the browser (`localStorage`) and a separate agent wallet (`liberty.agent-settlement.agent-credits.v0`). Before fund, release, or dispute it POSTs `/api/v0/quote` (dry-run of the fee/payout cut), then POSTs create / fund / submit / release / dispute to `/api/v0/transition` — the same engine adapters use. Optional `client_ref` (max 128) on create stamps the adapter’s correlation id on the job and receipt. Optional `callback_url` (`notify_url` alias, max 512, https) is stamped the same way — Liberty never HTTP-fetches or calls it. Optional `proof_note` on submit (max 400) and `release_note` / `dispute_reason` (max 400) land on the job and terminal receipt. A successful release credits the agent wallet by `agent_credits_delta` (same as `agent_payout`). Dispute refunds the payer and does not credit the agent. One click can POST `/api/v0/simulate` to walk create → fund → submit → release|dispute in one request. A successful release or dispute keeps the JSON receipt in this browser so you can download or share proof (JSON / NDJSON). `POST /api/v0/verify` checks that receipt (or a proposed release/dispute) against the same fee engine. Clients hold state; Liberty does not persist jobs, receipts, or balances or take custody. Optional `Idempotency-Key` (or body `idempotency_key`) on quote, transition, and simulate makes create ids stable for retries; Liberty does not replay stored responses. Share a job across browsers with a handoff link (`#handoff/h1.…` base64url JSON). Share a terminal receipt with a receipt link (`#receipt/r1.…` base64url JSON) so another device can inspect or verify without pasting JSON. The Settlement ledger (`/#ledger`) sums this browser’s stored receipts (fees paid, agent payouts, disputed returns) and can download them as CSV. Liberty does not persist that ledger. The activity log (`/#activity`) appends local demo actions in this browser. Liberty never receives that log. Come back later or move devices with a demo pack (`/#demo-pack`) — one client-held JSON file of Settlement localStorage. Import replaces; Liberty never receives the pack. The file may include the raw demo API key if one is stored. Credits stay in each browser. Optional demo API key: mint on `/`, send `Authorization: Bearer <key>` or `X-Liberty-Key`. If sent, response/receipt include `key_id` (hash prefix only). If omitted, the route notes `key_optional` and still works. Not production auth. No payments, no claimed user counts.

Human demo: https://liberty-amber.vercel.app

## Protocol

- [Discovery](/.well-known/agent.json): machine-readable card (`mode: demo`, `money: false`). Same JSON as `/api/agent.json`. Not an A2A Agent Card. Not a ChatGPT plugin
- [Health](/api/health.json): service, demo mode, `money: false`
- [Settlement](/api/settlement.json): states, fees, job and receipt fields, client-held receipt export, shareable receipt links, verify, client-held agent wallet
- [Examples](/api/examples.json): copy-ready request bodies for quote, transition, simulate, and verify (same curls as `/#adapters`)
- [Templates](/api/templates.json): preset create-job fields (same buttons as `/#create`; fill only, no auto-create or fund)
- [What's new](/api/changelog.json): recent shipped slices (newest first; dates and titles only; no user counts or revenue). Same list as `/#whats-new`
- [Scoreboard](/api/scoreboard.json): honest zeros (`external_users`, `paid_pilots`, `revenue_usd`) plus curated listing URLs. Listings ≠ users. Same facts as `/#scoreboard`
- [Fees](/api/fees.json): demo fee schedule (release 5% rounded `Math.round(amount * 0.05)`, dispute no release fee, top-up/fund none). Same facts as `/#fees`
- [Tools](/api/tools.json): callable Settlement surfaces (quote, transition, simulate, verify) plus read-only discovery URLs. Not an MCP server
- [Quickstart](/api/quickstart.json): ordered ready-to-run demo escrow walk (health/discovery → quote → fund → prove → release; dispute optional). Client-held. Liberty does not move real money
- [Transition schema](/api/schemas/transition.json): JSON Schema (2020-12) for `POST /api/v0/transition` bodies. Client-held demo protocol; Liberty does not move real money
- [Quote](/api/v0/quote): `POST` dry-run of the same engine (no state change; create has no durable id; Idempotency-Key echoed only)
- [Transition](/api/v0/transition): `POST` stateless demo engine (not live escrow; optional Idempotency-Key stabilizes create ids)
- [Simulate](/api/v0/simulate): `POST` one-shot create → fund → submit → release|dispute (same optional Idempotency-Key)
- [Verify](/api/v0/verify): `POST` recompute fee math for a receipt or proposed release/dispute
- [OpenAPI 3.1](/settlement.openapi.json): same surface. Same JSON at `/openapi.json` and `/api/openapi.json`
- [SETTLEMENT.md](/SETTLEMENT.md): markdown for humans
- [robots.txt](/robots.txt): crawler allow list
- [sitemap.xml](/sitemap.xml): same discovery URLs (hash UI states are `/` once)

## Optional

- [GitHub](https://github.com/masterpuzzle38/liberty): source