# Capital planning

Capital planning translates an issuer's liquidity goals into a reproducible study. It estimates a minimum capital requirement, reserve requirement, range width, fee-income bounds, inventory exposure, and five plan variants. Use the study to compare declared constraints and prepare linked planning records before moving into simulation or execution review.

A completed study is a completed calculation. Its result does not prove funding, select a live pool automatically, or authorize deployment.

## Define the issuer intent

Start with the market behavior you want to support and the capital constraints you can accept. An issuer intent records:

| Input | Meaning |
| --- | --- |
| Target trade size | The quote notional of a trade the plan should support. |
| Maximum slippage | Permitted modeled price movement for that trade. |
| Executable depth and depth band | Target quote depth and the price band it should cover. |
| Treasury reserve | The fraction of capital to preserve as a stable reserve. |
| Capital ceiling | The upper bound on the declared capital budget. |
| Maximum daily turnover | The turnover limit used by the planning model. |
| Acceptable volatility | A declared tolerance used in the modeled range width. |
| Duration | A rolling period or an explicit end time. |
| Prohibited behaviors | Restrictions carried into the intent and study. |

Amounts are quote atomic decimal strings. Rates use **pips**, where `1_000_000` equals 100%, `100_000` equals 10%, and `10_000` equals 1%. They are not conventional market basis points. Keep atomic amounts as strings or `bigint` in your code to preserve precision.

## Calculate locally with liquidity-core

The core package exposes the same deterministic capital calculation used by the backend:

```ts
import { calculateCapitalRequirement } from '@klineo/liquidity-core';

const study = calculateCapitalRequirement({
  name: 'Initial liquidity plan',
  quoteSymbol: 'USDC',
  targetTradeSizeQuote: '1000000000',
  maximumSlippagePips: 10_000,
  executableDepthQuote: '100000000000',
  executableDepthBandPips: 50_000,
  treasuryReservePips: 250_000,
  capitalCeilingQuote: '200000000000',
  maximumDailyTurnoverPips: 1_000_000,
  acceptableVolatilityPips: 100_000,
  duration: { kind: 'ROLLING', days: 30 },
  prohibitedBehaviors: ['Do not deploy the stable reserve'],
});

console.log(study.calculationVersion); // capital-requirement-v2
console.log(study.minimumCapitalQuote);
console.table(study.variants.map(variant => ({
  kind: variant.kind,
  capital: variant.requiredCapitalQuote,
  deployable: variant.deployableCapitalQuote,
  satisfiesIntent: variant.satisfiesIntent,
  reasons: variant.reasons.join('; '),
})));
```

Local calculation creates a value in your process. Saving a workspace record requires the authenticated API and its admission checks. Quote atomic amounts in the example need the intended quote asset's decimal scale to display as asset units; `quoteSymbol` alone does not authenticate that scale or a price source.

## Understand the calculation

The `capital-requirement-v2` model takes the larger of two requirements, rounding up:

```text
slippage requirement = ceil(target trade size × 1,000,000 / maximum slippage pips)
depth requirement = ceil(executable depth × (1,000,000 + depth band pips) / 1,000,000)
minimum capital = max(slippage requirement, depth requirement)
stable reserve = ceil(minimum capital × reserve pips / 1,000,000)
```

The initial range width is the larger of twice the depth band and three times the volatility tolerance, clamped to the model's range limits. The calculation uses explicit integer rounding and a versioned local-depth approximation before venue-specific replay.

Fee-income bounds come from declared turnover and fixed model ratios. Inventory exposure and `confidencePips` are model heuristics; confidence is not a statistical probability. Neither an income bound nor a model confidence value promises a realized outcome.

## Compare the five variants

The study returns `CURRENT`, `RECOMMENDED`, `CONSERVATIVE`, `CAPITAL_EFFICIENT`, and `EMERGENCY` variants. Each applies versioned multipliers to capital, reserves, range width, and turnover, then returns its deployable capital, modeled slippage, fee bounds, exposure, and findings.

`CURRENT` is the name of a generated model variant. It does not establish the current configuration of a deployed market.

A variant satisfies the intent only when it has positive deployable capital, stays within the capital ceiling, meets the modeled slippage limit, and retains sufficient stable reserve. Read `satisfiesIntent` and `reasons` for each result. A `RECOMMENDED` label alone does not mean those conditions pass.

## Use the app workflow

Open Capital requirements in the workspace and select a saved completed study. Review its source ID, resource version, and artifact hash before preparing a linked action.

The view includes Capital requirements, Pool configuration, Market data, Risk analysis, and Launch readiness. Pool configuration shows returned venue records; a study does not automatically choose one. Risk analysis displays the selected intent constraints, model assumptions, heuristic confidence, exposure, and variant findings. Launch readiness shows saved launch plans and their recorded evidence.

The **Use this capital study** panel supports three actions:

1. **Seed linked intent** creates a validated intent from the completed study's exact intent. When updating an existing intent, the server requires its exact expected version.
2. **Seed launch draft** uses the study's recommended variant, or its first variant if no recommended one is present, as the liquidity budget for a new draft. Supply token supply, treasury allocation, valuation, initial demand, initial price, unlock schedule, review owner, launch time, and a reason. Inspect the resulting draft before further review.
3. **Reserve capital** records either the study's stable reserve or minimum capital requirement as a Treasury future commitment. It requires a signed obligation and the relevant source, valuation, reconciliation, and custody references. The backend validates admission evidence before recording it.

Review the exact request in the confirmation dialog and submit it. The returned receipt must match the organization, record type, expected state, and study artifact. Reserving requires an organization owner, treasury administrator, or KlineO operator with the relevant planning access. Recording a reservation does not move funds.

## Integrate with saved studies

The following paths are relative to `/api/liquidity-studio/v2`. Use the authenticated organization context and the endpoint's required mutation headers.

| Operation | Method and path |
| --- | --- |
| Save an intent and its initial study | `POST /intents` |
| Calculate another study from a saved intent | `POST /capital-requirements` |
| List saved studies | `GET /capital-requirements` |
| Read one saved study | `GET /capital-requirements/{id}` |
| Seed a source-linked intent | `POST /capital-requirements/{id}/seed-intent` |
| Seed a source-linked launch draft | `POST /capital-requirements/{id}/seed-launch-plan` |
| Record a future Treasury commitment | `POST /capital-requirements/{id}/reservations` |

Saved study records carry the exact payload, calculation version, artifact hash, evidence hashes, resource version, author, and reason. Study-derived actions bind their resulting record to the study artifact. Send the reviewed strong `If-Match` when selecting a source generation; updates to an existing target require that target's expected version. Reuse the same idempotency key and exact body after an unconfirmed mutation instead of creating another request.

A reservation has ledger state `FUTURE_COMMITTED` and source kind `SIGNED_OBLIGATION`. Its quoted amount is derived from the study. It cannot be mapped as current custody cash or treated as an independently observed spendable token balance. See [Treasury](/guides/treasury/) for the evidence and dated-planning workflow.

## Continue into simulation and review

Use a capital study as planning evidence for a simulation, launch draft, or Treasury review. Review the exact source generation together with venue assumptions, reserves, prohibited behaviors, and the variants' constraint findings. See [simulation mechanics](/mechanics/simulation/) for how scenarios and replay evidence affect interpretation.

Capital arithmetic alone does not authenticate market prices or test a venue's execution behavior. A seeded launch draft remains a draft, and a recorded commitment remains a commitment. Deployment and funding require the separate proposal, authority, and finalized-evidence workflows available in the configured workspace.