Klineo separates the interface, API authorization, deterministic calculation, evidence storage, and onchain custody. Each layer has a defined responsibility so that a screen, model output, or developer token cannot become a financial authorization by itself.
Read Platform overview for the user journey and Data lineage for the records carried between these layers.
Component responsibilities#
| Component | Responsibility | Authority boundary |
|---|---|---|
| Web application | Project inspection, workspace navigation, studies, review, monitoring, and report presentation | Presents the API's records and permitted actions. It holds no issuer signing key. |
| Versioned HTTP API | Authentication, organization and role checks, schema validation, workflow transitions, and source binding | A request must satisfy its endpoint's authorization and evidence requirements. |
| Deterministic core | Fixed-point amounts, strategy calculations, policy checks, simulation, and modeled comparisons | Calculates within explicit inputs and engine versions. A calculation does not grant custody authority. |
| Evidence store | Organization records, immutable versions, studies, reports, receipts, and audit history | Preserves the captured source and decision history. Private records remain organization-scoped. |
| Background tasks | Admitted studies, investigations, projections, reconciliation, and report materialization | Task completion establishes the stated artifact, not approval or execution. |
| Issuer Safe | Issuer-owned signatures and authorization for the relevant onchain action | Workspace roles and developer credentials do not replace its threshold. |
| Liquidity contracts | Vault custody, typed actions, policy limits, price-source checks, and issuer exit | Onchain enforcement remains required even after offchain review. |
HTTP contracts and SDKs#
The application uses three API areas with different purposes:
| API base | Purpose |
|---|---|
/api/auth/v1 |
Backend-owned email authentication and browser sessions |
/api/liquidity-studio/v1 |
Existing organization, vault, Safe review, reporting, and operational workflows |
/api/liquidity-studio/v2 |
Additive operating-system resources, studies, strategies, proposals, proof, and developer integrations |
The TypeScript and Python operating-system SDKs are generated from the v2 OpenAPI contract. Use the API base supplied for your environment; a hostname in an example is not evidence of a deployed or enabled service.
Browser sessions use backend-managed cookies. Supported v2 service operations can use scoped API-key or OAuth bearer credentials bound to an organization. A method in a generated SDK may require an interactive session rather than a service credential; consult that operation's authentication and scope requirements.
The current service scope families include study reading and writing, score reading, strategy validation, policy compilation and checks, proposal reading and preparation, and vault, receipt, proof, alert, and webhook access. Scope names describe permitted API work. For example, proposal preparation does not authorize approval, Safe signing, or execution.
Two distinct entry paths#
The public project path starts with a supported identifier and reads supported market evidence. It does not load a private organization's records or create a vault. Provider configuration determines whether a public observation is available; an unavailable provider produces an explicit unavailable result.
The private issuer path starts with authenticated organization membership. Members can save observations, create analysis records, and use the workflows allowed by their roles. Safe verification, asset and venue qualification, policy state, release state, and finality add separate requirements before a custody action can become eligible.
Keep these paths separate in an integration. A public project result is useful evidence about the stated market; it is not permission to operate a vault for that project.
From study to transaction#
The deterministic study layer captures source generations, assumptions, calculation versions, and artifact commitments. A policy or proposal must refer to the exact eligible evidence required by its workflow. Updating a current source does not rewrite the study that was already run.
The review layer adds actor decisions and the current policy and proposal generation. Sensitive actions may require recent authentication. A prepared Safe packet binds the expected chain, target, action, limits, and relevant evidence. Required preflight checks evaluate that exact packet rather than an approximate UI summary.
The issuer then signs through its Safe. Klineo records submission evidence and independently observes inclusion, finality, and the resulting state. Reconciliation compares the expected transaction and economic changes with the observed records. Attribution and finalized reports consume the reconciled outcome, retaining applicable failures and costs.
Contract model#
The existing contract system uses dedicated components for each issuer vault:
| Component | What it enforces |
|---|---|
| Vault factory | Deterministic deployment and commitments to the configured component code |
| Private vault | Custody of supported assets and positions, with issuer-controlled withdrawal and exit |
| Venue module | Enumerated supported position and swap operations with bounded pool, recipient, deadline, and asset constraints |
| Policy manager | Active policy identity, timing, recipients, budgets, reserve and loss limits, and daily counters |
| Oracle guard | Required price-source freshness and agreement, plus venue-specific pool-health checks |
| Execution controller and risk engine | Exact action authorization, nonce and deadline checks, risk validation, and post-action constraints |
The SDK does not expose an arbitrary target-and-calldata path that bypasses this model. Adding an observation for an external venue does not enable a write adapter for that venue.
These are responsibilities of the implemented contract model. Whether a particular environment has accepted deployments, enabled adapters, or live admission is determined by its verified release state.
AI and durable research#
AI can explain captured evidence, assist with question-led research planning, and produce validated analysis reports. Agent Tasks preserve admission, progress, source cutoff, clarification, cancellation, and report state.
The financial calculation remains in the deterministic engines. Model hypotheses and unknown inputs require the review specified by the workflow. AI output cannot supply Safe authority, create executable calldata, approve a proposal, activate policy, or clear a release gate. Cancelling an investigation task does not pause a vault.
If an AI provider is unavailable, its task or explanation can be unavailable without turning other evidence into a fabricated response. Inspect report availability separately from task terminal status.
Environment and release boundaries#
The design demo, disposable testnet sandbox, and connected workspace have different evidence and authority. A demo is synthetic. A sandbox can contain deployed test contracts and test assets. A connected workspace uses its configured backend and sources. None of these descriptions alone establishes live financial admission.
The current canonical v2 release configuration is shadow-only with Level 0 observation authority, live activation disabled, and external EVM write adapters disabled. Mainnet acceptance requires the applicable deployment, provider, audit, approval, and operational evidence. The /status page separates runtime availability, automated execution, and new-vault funding.
For an integration, handle each returned state explicitly. Preserve paused, stale, unavailable, expired, superseded, failed, and reconciliation-mismatch conditions; do not replace them with a demo value or a successful status.