Treasury

Treasury brings ledger holdings, custody observations, obligations, conditional receipts, and cash-flow scenarios into one workspace. Use it to review where capital is recorded, inspect the evidence behind a balance, and explore how declared future activity changes a historical snapshot.

The current cash-flow workflow produces an issuer-declared planning scenario. Its saved records explicitly retain spendability: "NOT_ESTABLISHED", verifiedExpenseCoverage: "UNKNOWN", and financialAuthority: false. Creating or acknowledging these records does not transfer assets or authorize payment.

Find your way around#

Open Treasury in the app. Its sections are:

Ledger summaries use quote atomic amounts. Dated assumptions and cash-flow scenarios use the exact token and decimal scale derived from their custody sources. A quote valuation cannot be treated as a spendable token balance. Keep amounts as decimal strings in integrations and use the saved unit when formatting them.

Build a cash-flow scenario#

1. Review holdings and admit custody evidence#

Start with active ledger holdings. Open the ledger and custody mapping workspace from Accounts. A signed custody observation binds an organization, saved project, custody account, token, chain and genesis, finalized block, balance, observation time, and source authority.

Use Import signed custody evidence to select the signed JSON supplied by your configured custody provider. The app accepts a file under 64 KB and shows its unverified contents before submission. Verify and save custody evidence sends the signed observation to the server, which checks the signature, accepted project-control relationship, provider authority, and configured finalized-chain quorum.

Custody admission requires an interactive organization owner or treasury administrator with recent authentication. It also requires configured verification providers and accepted control relationships in the deployment; uploading an arbitrary wallet balance or valuation signature cannot establish them. A finalized balance proves an observation at a block, not legal ownership, unrestricted funds, or complete expense coverage.

2. Save and acknowledge an exact mapping#

Choose a ledger generation and its admitted custody-evidence generation, then select Add mapping. Repeat for the physical balances you want to review and select Save mapping draft.

The server loads the complete active ledger at its selected cutoff and checks exact amounts, units, conservation, current source authority, and repeated use of a physical balance. Future commitments and signed obligations cannot be mapped as cash. Review omitted entries and any unallocated custody surplus in the returned draft.

Select the saved draft, inspect its source generations, and acknowledge the mapping only after reviewing the exact result. Acknowledgment creates an attributed immutable version; it remains an assertion connecting the ledger to custody evidence. A ledger change can make an older candidate unsuitable for current admission. Refresh saved sources before preparing a new write after a conflict.

3. Create dated assumptions#

An acknowledged mapping can seed a saved assumption schedule. Select the ledger entries covered by the schedule and enter:

• Obligations with total amounts and dated installments. Installments must sum exactly to each obligation total.
• Conditional inflows with expected UTC dates and explicit conditions.
• Proposed allocations with their amounts and UTC dates.
• The relationship between ledger obligations and scheduled obligations.
• Expense coverage as declared complete, declared partial, or unknown, with omitted categories and a note.

Economic keys and row identifiers must be unique. A schedule permits at most 256 dated entries across installments, conditional inflows, and allocations. These identifiers help preserve the declared identity across revisions; they do not independently prove real-world economic identity.

Revisions append immutable versions and preserve the selected reconciliation and ledger-entry set. Create a separate document for a different selection. Documents represent alternative or successive plans, so adding their opening balances together would double count funds. Even a DECLARED_COMPLETE expense declaration retains verified coverage UNKNOWN.

4. Save the projection#

In Cash flow, select New projection, choose an exact saved assumption generation, and enter the through date in UTC. Declare a restriction amount and reason for every selected ledger entry; enter zero explicitly when no independent restriction applies. Confirm that scheduled obligations remain unpaid and that restrictions exclude those obligations.

The server requires one exact token unit and one common block number, hash, and timestamp across selected accounts. Only mapped AVAILABLE amounts contribute to opening scenario cash. Other capital states and unallocated custody surplus are excluded. Restricted amounts are deducted separately.

The model starts at the observed block timestamp and includes unpaid obligations and allocations on its UTC day. It does not infer an end-of-day opening balance. Earlier dates, unresolved ledger obligations, or obligations declared already deducted require reconciliation before this model can proceed. The horizon contains at most 365 daily buckets.

5. Compare the result#

Inspect the baseline first: it deducts scheduled obligations and proposed allocations without assuming conditional funding arrives. The conditional scenario adds expected inflows separately. Passing an expected date never turns an inflow into a settled receipt; this declared model reports actual inflows as zero.

Use monthly or source-row views, inspect exact amounts in the timeline, and review the minimum baseline balance and first shortfall date. Monthly presentation summarizes the saved daily rows. Chart labels can be approximate for large balances; saved amounts remain exact. Daily buckets do not establish intraday solvency.

Compare in research opens the saved snapshot comparison. Create Decision Pack starts a review record bound to the exact persisted projection. These actions preserve the scenario's historical scope and do not grant funding or execution authority. See simulation mechanics for model and replay boundaries.

Integrate with Treasury#

The following paths are relative to /api/liquidity-studio/v2. These are authenticated workspace endpoints; public documentation does not make private Treasury records public. Send the authorized x-klineo-organization-id with each request.

Custody admission accepts signed evidence, never a caller-generated verification receipt. Reconciliation requests accept immutable references, never caller-supplied balances or conservation results. Projection requests accept the saved assumption reference, horizon, restriction declarations, and confirmation; the server computes opening amounts and timeline results.

Use an Idempotency-Key for saved reconciliations, assumption writes, and projection creation. Keep the same key and exact request when retrying an unconfirmed attempt. Acknowledgment and assumption revisions also require a strong If-Match for the exact reviewed resource version. Treasury planning writes require interactive owner or treasury-administrator authentication; service credentials cannot bypass that requirement. Reads remain subject to current workspace access.

Saved evidence and scenarios remain historical when sources expire or a new ledger generation appears. The server reconstructs saved projection results from immutable inputs on reads. Treasury evidence and planning endpoints return Cache-Control: private, no-store; preserve that boundary in your integration.

Stress-test the ledger#

Treasury stress tests apply seven modeled shocks: a 50% token-price fall, stablecoin depeg, major-holder selling, LP withdrawal, exchange delisting, runway deterioration, and simultaneous unlocks. The workflow needs a complete conserved ledger, a launch plan with a non-empty unique unlock schedule, the exact completed unlock-impact generation for that plan, and the current server-side vault autonomy policy.

Enter Monthly operating cost as monthlyOperatingCostQuote: a strictly positive integer string in quote atomic units per month. Zero, decimal points, signs and scientific notation are rejected. For a 6-decimal quote token, a monthly cost of 1,000 quote units is "1000000000"; use the actual quote denomination and decimals of the ledger.

Results include modeled loss, stressed value, runway, reserve sufficiency, bucket breaches, and mitigation suggestions. Runway uses the supplied monthly cost and a 30-day model month, rounding down the stressed operating and emergency reserve coverage to whole days. Shock magnitudes are model assumptions; the simultaneous-unlock shock uses the saved unlock-impact tail estimate. The saved study records executionAuthorityGranted: false.

Use stress results alongside the dated scenario and its assumptions. A stress-test ledger completeness check does not establish that all real-world expenses are known or that the historical scenario is verified current cash.