GET /api/wallet/ledger
Session
Returns account-scoped transfer and note history with private actor context, rollups, cursors, and proof bundles.
Receiz/Ledger Contract
Account ledger contract
The ledger is the durable settlement record. This page defines route behavior, event schema, proof payload shape, and privacy boundaries.
Settlement Ledger Unit (SLU): Settlement Ledger Unit (SLU) is the canonical non-USD settlement custody unit used to keep online ledger replay and offline note settlement deterministic. For protocol compatibility, SLU micro-values are persisted in `phi*` field names (for example `amountPhiMicro` and `balancePhiMicro`).
Institutional core: one deterministic custody unit across ledger posting, replay, and offline note settlement. Approachable edge: USD-first account UX with explicit field-level SLU compatibility for integrators.
GET /api/wallet/ledger/public
No Auth
Returns public attestation stream with pseudonymous actor identities and exact value/proof fields.
Normative Requirements
L-001
Ledger routes SHALL return append-only settlement events with stable event identifiers.
L-002
Private and public routes SHALL preserve identical value/proof semantics while differing in identity visibility.
L-003
Each event SHALL include `amountUsdCents`, `amountPhiMicro`, and `usdPerPhiMicrocents` for deterministic replay.
L-004
Proof bundle payload SHALL include capsule and bundle hashes with verification version identifiers.
L-005
Pagination controls SHALL be bounded and deterministic (`limit`, `cursor`, `since`).
L-006
Public outputs SHALL pseudonymize actor identity while preserving attestation continuity.
L-007
For note claims, authoritative ordering SHALL be server acceptance order; first accepted claim for a token wins globally.
L-008
Recipient-locked claims SHALL enforce `claimRecipientUserId` and reject non-matching claimants with explicit restricted status.
L-009
Offline claim-batch execution on `/ledger` SHALL require authenticated wallet context so credits post to the signed-in account.
Claim-To-Code Traceability
| Req | Source Route / Function | Verification Method |
|---|---|---|
| L-001 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Both ledger routes return durable event IDs and created-at ordering for append-only replay. |
| L-002 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Public response removes private identity fields while preserving value and proof payload semantics. |
| L-003 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Each event includes USD amount, SLU amount, and posting rate tuple for deterministic conversion replay. |
| L-004 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Proof bundle payload includes capsule hash, bundle hash, and versioned verification coordinates. |
| L-005 | app/api/wallet/ledger/route.ts, app/api/wallet/ledger/public/route.ts | Route handlers clamp `limit` and apply cursor/since windows for deterministic pagination behavior. |
| L-006 | app/api/wallet/ledger/public/route.ts | Public actor identifiers are pseudonymized yet stable for continuity tracking. |
| L-007 | app/api/wallet/notes/claim/route.ts | Claim route applies first accepted server-write semantics and reports `wallet_note_already_claimed` on later attempts. |
| L-008 | app/api/wallet/notes/mint/route.ts, app/api/wallet/notes/claim/route.ts | Recipient lock is persisted at mint and enforced at claim with `wallet_note_claim_restricted` on mismatch. |
| L-009 | app/ledger/LedgerClient.tsx, app/api/wallet/me/route.ts | Claim-batch imports are sign-in gated; ledger proof-bundle imports can still rehydrate public ledger snapshots. |
Event Kinds
chat_transfer
Account-to-account value movement event.
note_mint
Withdrawal note creation event.
note_claim
Withdrawal note claim event.
Query Rules
- `limit` is clamped to [1, 100].
- `cursor` accepts ISO timestamp for descending pagination.
- `since` accepts ISO timestamp for incremental sync windows.
- Responses include `nextCursor`, rollup summary, and response `ETag`.
Value Fields
`amountUsdCents``amountPhiMicro``usdPerPhiMicrocents`
Proof Bundle Shape
{
"proofCapsule": {
"v": "KPV-1",
"pulse": 0,
"chakraDay": "...",
"kaiSignature": "...",
"phiKey": "...",
"verifierSlug": "..."
},
"capsuleHash": "...",
"bundleHash": "...",
"verificationVersion": "wallet-ledger-v1",
"proofHints": {
"source": "wallet_ledger_v1",
"eventId": "...",
"eventKind": "chat_transfer | note_mint | note_claim",
"createdAt": "ISO-8601"
}
}Privacy and Attestation Model
- Public route omits private account identity fields.
- Public actor identity is transformed into stable pseudonymous keys.
- Value/proof fields remain exact across private and public outputs.
- External verifiers can validate continuity from proof bundle data.
Claim authority model
- Claim posting authority is server-side only; offline claim creation time does not override server acceptance order.
- First accepted claim for a note token wins globally and posts settlement credit.
- Recipient-locked notes can only be claimed by the locked account identity.
- On `/ledger`, claim-batch imports require sign-in; proof-bundle ledger imports remain publicly available.