{ "openapi": "3.1.0", "info": { "title": "BTC Now forward-flow engine", "version": "v1.14", "summary": "Prices BPA (Bitcoin Purchase Agreement) paper for Holders: one seeded run, Monte Carlo, the price solver, sensitivity grids, the vintage backtest, the risk desk and the derivatives desk.", "description": "The engine is stateless: a configuration (`SimConfig`) goes in, results come out, nothing is stored. Same request, same bytes \u2014 every run is seeded (ChaCha20, `seed`).\n\n**Vocabulary.** The **Buyer** is the paying side of an **Agreement**; the **Holder** is the receiving side (Holder 0 is BTC Now, the originator and servicer). A **stop** is a missed payment: day 16 is the Stop Date, the coin is sold for dollars within two business days, the proceeds pay the Holder the remaining schedule first, refund the Buyer up to what he paid in, and any surplus above the Purchase Price stays with the Holder. An **early completion** (`settled` in the JSON) is the Buyer paying the remaining schedule and taking the coin. BTC Now takes fees only \u2014 the first N payments and a flat share of every delivered dollar \u2014 never a share of a stop sale. Engine identifiers (`Owner` for the Holder, `Obligor` for the Buyer, `non_performance` for a stop) are older than the vocabulary and are kept on the wire.\n\n**Money travels as strings.** Every ledger amount is a cent-quantized decimal and serializes as a JSON string (`\"1475.00\"`). Ratios, IRRs and statistics are numbers.\n\n**Access.** The hosted configuration sets `FF_MCP_ACCESS=keys` and refuses startup without `FF_API_KEYS`. In local `inherit` mode, unset keys mean **open** access. With keys configured it runs **keyed**: every `/api/forwardflow/*` route needs `X-API-Key` or `Authorization: Bearer ` (send only one; compared in constant time; only the key's *name* ever reaches a log line or the `X-Key-Name` response header), except the websocket, which alternatively takes `?token=` \u2014 a 10-minute HMAC-SHA256 token minted by the web app's server so the browser never sees a key. `GET /health`, `GET /api/forwardflow/health` and `GET /api/forwardflow/openapi.json` are open in both modes. Every response carries `X-Engine-Spec: v1.14`, `X-Engine-Version` (the crate version), `X-Engine-Build` (`++`, `0.2.0+v1.14+1a2b3c4d5e6f`: the source revision `build.rs` stamps from `GIT_SHA` at build time, else `git rev-parse --short=12 HEAD` on the build host \u2014 suffixed `-dirty` when that host's `backend/` tree had uncommitted changes \u2014 else `unknown`) and `X-Engine-Data` (the SHA-256 of the historical price series compiled in). `/api/forwardflow/health` reports them as `engine_spec`, `version`, `build`, `git_sha` and `data_sha256`; the websocket's `Complete` frame carries them as `engine`; a record takes them off the answer that produced it, never off a global last response.\n\n**Caps.** Per key in keyed mode (per client IP in open mode): 120 requests per rolling minute and at most 4 concurrent heavy runs \u2014 a breach is a 429 with `Retry-After`. Rate-limit state is in-memory on one machine. Server-wide, three heavy requests run at once and the rest queue. Heavy: Monte Carlo and its websocket, heatmap, backtest, risk, fair value, hedge, hedge series, rebalance policies and coin seat always; simulate, solve_price and placement only when the body's estimate is heavy \u2014 above 1,000,000 Agreement-runs, or above 128,000,000 bytes at peak (model audit 2026-09-07, R04: a 50,000-Agreement simulate at 60 months is \u2248 385 MB at peak and takes the guard; the placement runs no book and never does) \u2014 the guard reads the body for the estimate, and a light request stays light.\n\n**One cost estimate for every route**, in Agreement-runs (one Agreement simulated through one run of the engine), checked before any thread is taken and held under the one ceiling of **24,000,000**; a breach is a 400 naming the route, the estimate, the formula with the inputs' values, and the inputs to lower (`risk desk: estimated work 89650000 Agreement-runs (book 50000 \u00d7 (1 + 7 \u00d7 greek_seeds 256)) is over the ceiling of 24000000 \u2014 lower greek_seeds or the book (inputs #13 \u00d7 #18)`). With book = cohorts \u00d7 agreements_per_cohort: simulate = book; montecarlo = book \u00d7 runs; solve_price = book \u00d7 2 (the prepared run and the verifying run); heatmap = book \u00d7 cells; backtest = agreements_per_cohort \u00d7 vintages \u00d7 1 (one seeded replay per vintage); risk = book \u00d7 (1 + 7 \u00d7 greek_seeds); placement = book (nominal \u2014 the ladder is priced per payment age); fair_value = book \u00d7 seeds; hedge = book \u00d7 seeds \u00d7 \u03a3 structure units (+ 2 with the benchmarks); rebalance_policies = book \u00d7 seeds \u00d7 structure units \u00d7 policies; coin_seat = book \u00d7 seeds \u00d7 (\u03a3 structure units + 1) \u00d7 drifts; hedge_series = book \u00d7 (seeds \u00d7 structure units + \u2308horizon/3\u2309 \u00d7 57 when include_greeks). A structure unit is 1, or term-months for a perpetual delta hedge or a dollar-delta futures leg (it revalues the ladder monthly). Input caps, each answered with a 400 naming the input: cohorts \u2264 1,200; book \u2264 50,000 Agreements; term 1\u2013480 months; Monte Carlo runs 1\u2013100,000; heatmap 1\u2013900 cells; frontier drifts 1\u20138; desk and Greek seeds 1\u2013256; series seeds 1\u201364; hedge structures 1\u20138; sweep structures 1\u20136; sweep drifts 1\u201312; rebalance policies 1\u20136. **And a second ceiling in bytes** (model audit 2026-09-06, M08; the peak bound, the check-first rule and the shared budget model audit 2026-09-07, R03 and R04): the same estimate carries two byte figures. The EXPECTATION, for display \u2014 the engine's expected postings per run \u00d7 44 bytes a posting \u00d7 the books live at once (one per rayon worker for a fan-out; every seed's for the monthly series, which keeps them; plus a surface's transient paths on the desk routes). The PEAK, for admission \u2014 a bound no run of the configuration can exceed: 2\u00b7term \u2212 N + 4 postings an Agreement (the ledger's vector is allocated at exactly that bound and never grows past it) \u00d7 44 bytes, plus the Agreement state and schedules, the path and the outputs of every run kept, \u00d7 the books live at once. The peak is held under **1,500,000,000 bytes** (1.5 GB; `FF_MAX_ESTIMATED_BYTES` overrides it). A breach is the same 400, naming the peak, its arithmetic, the expectation and the ceiling that refused (`simulate: estimated ledger memory at peak 2917431256 bytes ((48150000 postings at most per run \u00d7 44 bytes a posting + 798800000 bytes of Agreement state and schedules + 7712 bytes of path) \u00d7 1 books held at once + 23544 bytes of outputs \u00d7 1 runs) is over the ceiling of 1500000000 bytes (FF_MAX_ESTIMATED_BYTES); expected 2112000000 bytes (48000000 expected postings per run \u00d7 44 bytes a posting \u00d7 1 books held at once); estimated work 50000 Agreement-runs (book 50000) is under its ceiling of 24000000 \u2014 lower the book (inputs #13 \u00d7 #18), or the term`): a 50,000-Agreement, 480-month book passes the count and is refused by bytes \u2014 and the auditor's down path (early completion suppressed by a price at 1% of entry), which writes 956 postings an Agreement against an expectation of 355.7, is refused by the peak where the expectation alone admitted it. `include_postings: false` trims the response, never the book in memory. **Every estimate checks the configuration first**: a term, cohort count or book the engine would refuse is the 400 naming the input before a model, a schedule, a path or a cache key is built for it \u2014 on the light routes the access guard answers it before the handler. **And a shared budget**: every route reserves its peak on the process's memory budget (`FF_MEMORY_BUDGET_BYTES`; default the per-request ceiling, 1,200,000,000 on the 2 GB machine) after it takes its heavy permit and before it runs, and releases it when the work ends; a request that does not fit beside the runs in progress is a 503 with `Retry-After: 5` and a JSON body naming the bytes requested, reserved and budgeted \u2014 it computes nothing. Behind the ceilings, three heavy runs execute at once and at most eight wait; a ninth is a 503 with `Retry-After: 10`. A request dropped mid-run (the browser aborted, the proxy timed out, the websocket closed \u2014 observed during a chunk, not after it) cancels its work at the engine's next seed, cell, vintage or structure and frees its permit, its reservation and its slot there.\n\n**Errors.** 400 \u2014 a well-formed request the engine refuses; the body is the engine's plain-text message naming the input (`term (input #6) must be 1\u2013480 months, got 1700`). 401 \u2014 keyed mode, no valid credential; JSON `{\"error\": \u2026}` naming what is missing, never echoing a value. 415 \u2014 a POST without `Content-Type: application/json`. 422 \u2014 a body that does not deserialize (a missing field, a wrong type); the body is the deserializer's message. 429 \u2014 a per-caller cap; JSON `{\"error\": \u2026}` with `Retry-After`. 500 \u2014 the blocking task itself failed. 503 \u2014 the machine's cap, always `application/json`: the heavy queue is full (`Retry-After: 10`, JSON `{\"error\": \u2026, \"retry_after_secs\": 10}`) or the memory budget cannot hold the request beside the runs in progress (`Retry-After: 5`, JSON `{\"error\": \u2026, \"requested_bytes\": \u2026, \"reserved_bytes\": \u2026, \"budget_bytes\": \u2026, \"retry_after_secs\": 5}`)." }, "servers": [ { "url": "https://btcnow-forwardflow.fly.dev", "description": "Hosted engine (keyed mode)" }, { "url": "http://localhost:8080", "description": "Local engine (`cargo run --release`; open mode unless FF_API_KEYS is set)" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "health", "description": "Liveness and the document itself \u2014 open in both modes." }, { "name": "run", "description": "One seeded run and the inverse price solver." }, { "name": "distribution", "description": "Monte Carlo over REST and over a websocket." }, { "name": "sensitivity", "description": "Grids and the vintage backtest." }, { "name": "risk desk", "description": "The exposure layer, the Greeks and the rational frontier (spec v1.6)." }, { "name": "derivatives desk", "description": "Crash library, preset surfaces, placement, fair value, the hedge overlay, the coin seat (FUND_DESK_PLAN Phases 2 and 3, v1.8), and the months \u2014 the hedged sleeve month by month and the rebalancing policies (Phase 4a)." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The party's individual API key from FF_API_KEYS, sent as Authorization: Bearer . No ForwardFlow account or OAuth login is required. An alternative to X-API-Key; sending both headers is refused. Both headers use the same key lookup and per-key limits." }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "One of the keys configured in `FF_API_KEYS` (`name:key,name:key`, every key at least 24 characters). Required on every `/api/forwardflow/*` route in keyed mode except `health` and `openapi.json`; ignored in open mode. A successful keyed response carries the key's name in `X-Key-Name`. Placeholder for docs and tests: `desk-alpha:REPLACE_ME_desk_alpha_key_0001`." }, "WsToken": { "type": "apiKey", "in": "query", "name": "token", "description": "The websocket's credential, accepted **only** on `GET /api/forwardflow/montecarlo/ws`. `token = base64url(payload) + \".\" + base64url(HMAC-SHA256(FF_TOKEN_SECRET, payload))` with `payload = \"|\"`, expiry at most 10 minutes ahead. Minted by the web app's server (`GET /api/forwardflow/token` on the Next.js app, which holds the cockpit's own key and the secret) so the browser never sees a key; the token names the key, so the socket is rate-limited and counted against that key. 401 when `FF_TOKEN_SECRET` is unset on the engine." } }, "headers": { "X-Engine-Spec": { "description": "The model specification the engine implements. Always `v1.14`; on every response, preflights and 404s included.", "schema": { "type": "string", "const": "v1.14" } }, "X-Engine-Version": { "description": "The engine crate's version (`CARGO_PKG_VERSION`). On every response.", "schema": { "type": "string", "examples": [ "0.2.0" ] } }, "X-Engine-Build": { "description": "The engine's build identity: the crate version, the spec it implements and the source revision \u2014 `++` (`0.2.0+v1.14+1a2b3c4d5e6f`; the sha is `GIT_SHA` at build time, else `git rev-parse --short=12 HEAD` on the build host \u2014 suffixed `-dirty` when that host's `backend/` tree had uncommitted changes, so a binary built from unstaged source never names the commit it lacks \u2014 else `unknown`). Two builds of different source never share it (model audit 2026-09-06, M07). On every response; a record takes it off the answer that produced its numbers.", "schema": { "type": "string", "examples": [ "0.2.0+v1.14+1a2b3c4d5e6f" ] } }, "X-Key-Name": { "description": "Keyed mode only: the NAME of the key that authenticated the request (never the key). Absent in open mode.", "schema": { "type": "string", "examples": [ "cockpit", "desk-alpha" ] } }, "Retry-After": { "description": "On a 429: seconds until the rolling-minute window admits another request (rate limit), or 5 for the concurrency cap. On a 503: 10 for the heavy queue's cap, 5 for the memory budget (model audit 2026-09-07, R04).", "schema": { "type": "integer", "minimum": 0 } }, "X-Engine-Data": { "description": "SHA-256 (64 hex characters) of the historical price series compiled into the engine (`data/btc_historical_monthly.csv`), computed at build time \u2014 the data half of the build identity (model audit 2026-09-06, M07). On every response; `data_sha256` on the health route and on the websocket's `Complete` frame say the same.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "examples": [ "8846a81b803001d885b0cc3b830f26bfeba35405b91d1843c6376eeca5d8a1bf" ] } } }, "responses": { "BadRequest": { "description": "A well-formed request the engine refuses. The body is the engine's plain-text message and names the input \u2014 or, for the admission estimate, the Agreement-run estimate, the ledger bytes at peak and expected, and the ceiling that refused. The configuration is checked before anything is estimated or built for it (model audit 2026-09-07, R03).", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "term": { "value": "term (input #6) must be 1\u2013480 months, got 1700" }, "runs": { "value": "runs must be 1\u2013100000 (input #14)" }, "replay": { "value": "historical replay needs 85 months from index 170, have 4" }, "work": { "value": "hedge overlay: estimated work 30720000 Agreement-runs (book 50000 \u00d7 seeds 256 \u00d7 structure units 3 (a perpetual delta hedge or a dollar-delta futures leg counts term-months; + 2 for the benchmarks)) is over the ceiling of 24000000 \u2014 lower seeds or the book (inputs #13 \u00d7 #18), or the structures" }, "series": { "value": "hedge series: estimated work 157100000 Agreement-runs (book 50000 \u00d7 (seeds 64 \u00d7 structure units 1 + 3078 Greek runs \u2014 \u2308(cohorts + term)/3\u2309 \u00d7 (8 seeds \u00d7 7 runs + 1) when include_greeks)) is over the ceiling of 24000000 \u2014 lower seeds or the book (inputs #13 \u00d7 #18), or drop include_greeks" }, "risk": { "value": "risk desk: estimated work 89650000 Agreement-runs (book 50000 \u00d7 (1 + 7 \u00d7 greek_seeds 256)) is over the ceiling of 24000000 \u2014 lower greek_seeds or the book (inputs #13 \u00d7 #18)" }, "ledger_bytes": { "summary": "Refused by the byte ceiling \u2014 the PEAK bound, with the expectation beside it \u2014 though under the Agreement-run count (model audit 2026-09-06, M08; the peak model audit 2026-09-07, R04)", "value": "simulate: estimated ledger memory at peak 2917431256 bytes ((48150000 postings at most per run \u00d7 44 bytes a posting + 798800000 bytes of Agreement state and schedules + 7712 bytes of path) \u00d7 1 books held at once + 23544 bytes of outputs \u00d7 1 runs) is over the ceiling of 1500000000 bytes (FF_MAX_ESTIMATED_BYTES); expected 2112000000 bytes (48000000 expected postings per run \u00d7 44 bytes a posting \u00d7 1 books held at once); estimated work 50000 Agreement-runs (book 50000) is under its ceiling of 24000000 \u2014 lower the book (inputs #13 \u00d7 #18), or the term" }, "checked_first": { "summary": "A configuration the engine would refuse is the 400 naming the input before anything is built for it \u2014 on a light route, from the access guard (model audit 2026-09-07, R03)", "value": "term (input #6) must be 1\u2013480 months, got 10000" } } } } }, "Unauthorized": { "description": "Keyed mode: no valid credential. The message names what is missing and never echoes the value presented.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "error": "missing X-API-Key header" } }, "invalid": { "value": { "error": "invalid X-API-Key" } }, "ws": { "value": { "error": "missing X-API-Key header or token query parameter" } }, "tokensOff": { "value": { "error": "websocket tokens are disabled on this engine (FF_TOKEN_SECRET unset)" } } } } } }, "Unprocessable": { "description": "The body does not deserialize into the request type (a missing field, a wrong type). The body is the deserializer's message; the engine was never reached. A POST without `Content-Type: application/json` is a 415 before this.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "Failed to deserialize the JSON body into the target type: config: missing field `path` at line 1 column 607" } } }, "TooManyRequests": { "description": "A per-caller cap (per key in keyed mode, per client IP in open mode): 120 requests per rolling minute, or a third concurrent heavy run \u2014 a heavy route, or simulate / solve_price / placement with a body whose estimated work is above 1,000,000 Agreement-runs.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate": { "value": { "error": "rate limit exceeded: 120 requests per minute for this key" } }, "concurrency": { "value": { "error": "too many concurrent runs for this key" } } } } } }, "ServerError": { "description": "The blocking task that ran the engine failed. Not an input error.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "Busy": { "description": "The machine's cap, not the caller's (distinct from the per-caller 429). Either the server-wide heavy queue is full (model audit 2026-09-06, M08): three heavy runs execute at once and at most eight more wait; the next arrival is refused rather than parked, `Retry-After: 10`. Or the process's memory budget cannot hold the request's peak bytes beside the runs in progress (model audit 2026-09-07, R04; `FF_MEMORY_BUDGET_BYTES`): `Retry-After: 5`, and the body carries `requested_bytes`, `reserved_bytes`, `budget_bytes` and `retry_after_secs` beside `error`. Nothing is computed for a refused request.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "queue": { "value": { "error": "the engine is busy: 3 heavy runs in progress and 8 waiting (the queue's cap) \u2014 retry in 10 seconds", "retry_after_secs": 10 } }, "budget": { "value": { "error": "monte carlo: the engine's memory budget cannot hold this request beside the runs in progress \u2014 37040800 bytes at peak requested, 1180000000 bytes reserved of a 1200000000-byte budget (FF_MEMORY_BUDGET_BYTES) \u2014 retry in 5 seconds", "requested_bytes": 37040800, "reserved_bytes": 1180000000, "budget_bytes": 1200000000, "retry_after_secs": 5 } } } } } } }, "schemas": { "Error": { "type": "object", "description": "The access guard's error body (401 and 429).", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Decimal": { "type": "string", "description": "A cent-quantized decimal carried as a string, exact to the cent. Parse with a decimal type, never a float, if you intend to re-add ledger amounts.", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "examples": [ "1.475", "0.05", "1475.00", "-230645.54" ] }, "HealthResponse": { "type": "object", "required": [ "status", "engine_spec", "version", "build", "git_sha", "data_sha256", "mode" ], "properties": { "status": { "type": "string", "const": "ok" }, "engine_spec": { "type": "string", "const": "v1.14" }, "version": { "type": "string", "description": "The engine crate's version (`0.2.0`)." }, "build": { "type": "string", "description": "The build identity \u2014 crate version + spec + source revision (`0.2.0+v1.14+1a2b3c4d5e6f`), the same string as `X-Engine-Build`." }, "mode": { "type": "string", "enum": [ "open", "keyed" ], "description": "`keyed` when `FF_API_KEYS` holds at least one key." }, "git_sha": { "type": "string", "description": "The source revision alone (the build identity's third part): 12 hex characters, `<12 hex>-dirty` for a host build from a tree with uncommitted changes under `backend/`, or `unknown` when the build had neither `GIT_SHA` nor a git checkout." }, "data_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the compiled-in historical series, the same string as `X-Engine-Data`." } } }, "SimConfig": { "type": "object", "description": "The whole inputs panel \u2014 the same object for every POST route. Field numbers (`input #n`) are the specification's and appear in 400 messages. Decimals travel as strings.", "required": [ "start_price", "path", "multiple", "term_months", "origination_payments", "servicing_fee_rate", "purchase_pct_of_strike", "scenario", "rational_default", "conviction", "settlement_propensity", "cohorts", "agreements_per_cohort", "haircut", "sale_cost_bps", "seed" ], "properties": { "start_price": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000000.0, "description": "Input #1: the simulation start price in dollars \u2014 the cohort-1 entry environment. Program: 60,000." }, "path": { "$ref": "#/components/schemas/PathMode" }, "multiple": { "$ref": "#/components/schemas/Decimal", "description": "Input #5: the price multiple over the coin's cost; the Purchase Price is entry \u00d7 multiple, paid as term_months equal payments. Positive and below 100. Program: \"1.475\"." }, "term_months": { "type": "integer", "minimum": 1, "maximum": 480, "description": "Input #6: the term in months. Program: 60." }, "origination_payments": { "type": "integer", "minimum": 0, "description": "Input #3: the first N payments routed to BTC Now (0 = off). Cannot exceed the term. Program: 1." }, "servicing_fee_rate": { "$ref": "#/components/schemas/Decimal", "description": "Input #4: the flat servicing fee as a share of every dollar delivered to the Holder, 0 \u2264 rate < 1. Program: \"0.05\"." }, "purchase_pct_of_strike": { "$ref": "#/components/schemas/Decimal", "description": "Input #6b: the Holder's purchase price as a fraction of the coin's cost (\"1.00\" = par; \"1.05\" \u2192 $63,000 on a $60,000 coin). Positive and below 100." }, "scenario": { "$ref": "#/components/schemas/DefaultScenario" }, "rational_default": { "type": "boolean", "description": "Input #9: the rational-default toggle \u2014 stop draws are suppressed while the coin beats the remaining schedule and redirected when it does not." }, "drawdown_hazard_multipliers": { "type": "boolean", "default": false, "description": "Input #23: drawdown-scaled hazard. Each month the draw probability is the baseline hazard \u00d7 a multiplier read off the Buyer's coin vs entry: in-the-money \u00d70.5 \u00b7 drawdown \u226430% \u00d71.0 \u00b7 30\u201350% \u00d71.5 \u00b7 50\u201370% \u00d72.0 \u00b7 >70% \u00d73.0." }, "conviction": { "$ref": "#/components/schemas/ConvictionRule" }, "settlement_propensity": { "type": "number", "minimum": 0, "maximum": 1, "description": "Input #12: monthly early-completion propensity among Buyers whose coin beats the remaining schedule. Program: 0.025." }, "settlement_min_return": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "default": null, "description": "Input #22: take-profit gate on early completion \u2014 with a value x a Buyer only completes early once spot \u2265 the full Agreement price \u00d7 (1 + x). null = ungated." }, "cohorts": { "type": "integer", "minimum": 1, "maximum": 1200, "description": "Input #13: monthly origination cohorts. cohorts \u00d7 agreements_per_cohort \u2264 50,000. Program base: 24." }, "agreements_per_cohort": { "type": "integer", "minimum": 1, "description": "Input #18 in the book-size cap: Agreements per cohort. Program base: 10." }, "haircut": { "type": "number", "minimum": 0, "description": "Input #15: static execution discount on a stop sale \u2014 the coin sells at spot \u00d7 e^(\u2212haircut). Program: 0 (the stop's delay is priced by the sale lag on the path)." }, "sale_cost_bps": { "type": "number", "minimum": 0, "exclusiveMaximum": 10000, "description": "Input #16: market-sale execution cost in basis points. Program: 25." }, "stop_sale_lag_days": { "type": "number", "minimum": 0, "maximum": 90, "default": 18, "description": "Input #24: calendar days from the missed payment date to the recorded stop sale; the sale price interpolates log-linearly between monthly marks. Program: 18 (day 16 is the Stop Date, the sale within two business days)." }, "shock": { "oneOf": [ { "$ref": "#/components/schemas/Shock" }, { "type": "null" } ], "description": "Input #17: multiplicative crash overlay on any path mode. null = no shock." }, "bump": { "oneOf": [ { "$ref": "#/components/schemas/PathBump" }, { "type": "null" } ], "default": null, "description": "Bump overlay (v1.6): the Greeks' bump-and-revalue and the desk's what-if. null = the path as generated. Must be null on `/risk`, which owns the bump." }, "rational_boundary": { "oneOf": [ { "$ref": "#/components/schemas/BoundaryParams" }, { "type": "null" } ], "default": null, "description": "Input #25 (v1.6): the rational boundary as the fifth behavior mode \u2014 a Buyer whose coin sits below the computed walk-away frontier for that month does not pay. null = off." }, "origination_stop_month": { "type": [ "integer", "null" ], "minimum": 1, "description": "Input #18: no new cohorts from this month on (a deal term, or the originator-disappears stress). null = full pacing." }, "intramonth_strike_dispersion": { "type": "boolean", "default": false, "description": "Input #20: each Agreement draws its own entry price around the cohort month's price (spread from the realized volatility of the twelve months before the entry, or the path mode's stated volatility with fewer than three returns behind it; mean-preserving, seeded). The cockpit sends true." }, "market_horizon_months": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2400, "default": null, "description": "The market horizon: the last month the price path is generated to, so a pacing change (cohorts, origination_stop_month) cannot move the bridge's endpoint date. null = the pacing's own requirement, (cohorts \u2212 1) + term + the stop-sale settlement tail (\u230alag/30.4375\u230b + 1 months); when set it must be at least that, or 400 `market horizon (market_horizon_months) must be at least the pacing's own requirement of {n} months \u2026`." }, "seed": { "type": "integer", "minimum": 0, "description": "ChaCha20 seed. Same config and seed \u21d2 byte-identical output. Program base: 42." } } }, "PathMode": { "description": "Input #2/#2b/#2c: the price path, externally tagged \u2014 an object with exactly one property naming the mode.", "oneOf": [ { "type": "object", "required": [ "Bridge" ], "additionalProperties": false, "properties": { "Bridge": { "type": "object", "required": [ "end_price", "vol_annual" ], "properties": { "end_price": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000000.0, "description": "Input #2: the price the bridge is pinned to at the horizon." }, "vol_annual": { "type": "number", "minimum": 0, "maximum": 5, "description": "Input #2b: annual vol of the Brownian bridge; 0 = the deterministic log-linear ramp. Program: 0.43." } } } }, "description": "Geometric Brownian bridge pinned at start and end price." }, { "type": "object", "required": [ "HistoricalReplay" ], "additionalProperties": false, "properties": { "HistoricalReplay": { "type": "object", "required": [ "start_index" ], "properties": { "start_index": { "type": "integer", "minimum": 0, "description": "Index into the embedded monthly series (`GET /api/forwardflow/history`); the replay is rebased so month 0 equals start_price. 400 when the horizon runs off the end of the series." } } } }, "description": "Historical monthly replay from a chosen start month." }, { "type": "object", "required": [ "ZeroDriftBootstrap" ], "additionalProperties": false, "properties": { "ZeroDriftBootstrap": { "type": "object", "required": [ "block_len", "regime_start_index" ], "properties": { "block_len": { "type": "integer", "minimum": 1, "description": "Months per sampled block." }, "regime_start_index": { "type": "integer", "minimum": 0, "description": "Index into the historical series where the sampled regime begins; the slice must hold enough returns (400 otherwise)." } } } }, "description": "Block bootstrap of de-meaned modern-regime monthly returns." }, { "type": "object", "required": [ "Custom" ], "additionalProperties": false, "properties": { "Custom": { "type": "object", "required": [ "points" ], "properties": { "points": { "type": "array", "minItems": 1, "items": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": 1 }, { "type": "number", "exclusiveMinimum": 0 } ], "minItems": 2, "maxItems": 2 }, "description": "(month, price ratio to the start) anchors; months strictly increasing and after 0; piecewise log-linear from (0, 1.0), flat after the last. The crash library serves these." } } } }, "description": "Piecewise log-linear path through anchor points \u2014 deterministic and seed-free." }, { "type": "object", "required": [ "Gbm" ], "additionalProperties": false, "properties": { "Gbm": { "type": "object", "required": [ "mu_annual", "vol_annual" ], "properties": { "mu_annual": { "type": "number", "exclusiveMinimum": -5, "exclusiveMaximum": 5, "description": "\u03bc: annual drift of the price (0.25 = +25%/yr expected), so E[S_t] = S\u2080\u00b7e^{\u03bct}." }, "vol_annual": { "type": "number", "minimum": 0, "exclusiveMaximum": 5, "description": "\u03c3: annual vol of the log price; 0 = the deterministic exponential ramp at \u03bc." } } } }, "description": "Geometric Brownian motion at monthly steps, free at the far end." }, { "type": "object", "required": [ "JumpDiffusion" ], "additionalProperties": false, "properties": { "JumpDiffusion": { "type": "object", "required": [ "mu_annual", "vol_annual", "jump_rate_annual", "jump" ], "properties": { "mu_annual": { "type": "number", "exclusiveMinimum": -5, "exclusiveMaximum": 5, "description": "\u03bc: annual drift, jumps included (the compensator is subtracted)." }, "vol_annual": { "type": "number", "minimum": 0, "exclusiveMaximum": 5, "description": "\u03c3 of the diffusion part only." }, "jump_rate_annual": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000, "description": "\u03bb: expected jumps per year; 0 is GBM exactly." }, "jump": { "$ref": "#/components/schemas/JumpKind" } } } }, "description": "Merton or Kou jump-diffusion: GBM plus a Poisson stream of log-price jumps." }, { "type": "object", "required": [ "RegimeSwitching" ], "additionalProperties": false, "properties": { "RegimeSwitching": { "type": "object", "required": [ "mu_annual", "calm_vol", "stressed_vol", "p_calm_to_stressed", "p_stressed_to_calm", "start_stressed" ], "properties": { "mu_annual": { "type": "number", "exclusiveMinimum": -5, "exclusiveMaximum": 5, "description": "\u03bc in both states." }, "calm_vol": { "type": "number", "minimum": 0, "exclusiveMaximum": 5 }, "stressed_vol": { "type": "number", "minimum": 0, "exclusiveMaximum": 5 }, "p_calm_to_stressed": { "type": "number", "minimum": 0, "maximum": 1, "description": "Monthly probability of leaving calm for stressed." }, "p_stressed_to_calm": { "type": "number", "minimum": 0, "maximum": 1, "description": "Monthly probability of leaving stressed for calm." }, "start_stressed": { "type": "boolean", "description": "Begin the run in the stressed state." } } } }, "description": "Two-state monthly Markov chain on the volatility; equal vols reduce to GBM." }, { "type": "object", "required": [ "Upload" ], "additionalProperties": false, "properties": { "Upload": { "type": "object", "required": [ "prices" ], "properties": { "prices": { "type": "array", "minItems": 1, "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "Monthly prices, month 0 first, at least horizon + 1 of them (extra points are ignored); rebased so the path starts at start_price. 400 (`uploaded path (input #2c upload) needs N monthly prices for this run, have M`) when short." } } } }, "description": "The desk's own path \u2014 deterministic and seed-free." } ] }, "JumpKind": { "description": "The jump-size law for `JumpDiffusion`, externally tagged. Sizes are log-price jumps: \u22120.30 multiplies the price by e^{\u22120.30} \u2248 0.74.", "oneOf": [ { "type": "object", "required": [ "Merton" ], "additionalProperties": false, "properties": { "Merton": { "type": "object", "required": [ "mean_log", "vol_log" ], "properties": { "mean_log": { "type": "number", "exclusiveMinimum": -5, "exclusiveMaximum": 5, "description": "Mean log jump size (\u22120.20 \u2248 a typical jump of \u221218%)." }, "vol_log": { "type": "number", "minimum": 0, "exclusiveMaximum": 5, "description": "Standard deviation of the log jump size." } } } }, "description": "Merton (1976): log-size ~ Normal(mean_log, vol_log\u00b2)." }, { "type": "object", "required": [ "Kou" ], "additionalProperties": false, "properties": { "Kou": { "type": "object", "required": [ "p_up", "eta_up", "eta_down" ], "properties": { "p_up": { "type": "number", "minimum": 0, "maximum": 1, "description": "Probability a jump is upward." }, "eta_up": { "type": "number", "exclusiveMinimum": 1, "exclusiveMaximum": 1000000.0, "description": "\u03b7\u208a > 1: rate of the up-jump exponential (mean up-jump 1/\u03b7\u208a in log terms)." }, "eta_down": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000.0, "description": "\u03b7\u208b > 0: rate of the down-jump exponential." } } } }, "description": "Kou (2002) double exponential." } ] }, "DefaultScenario": { "description": "Inputs #7/#8: the stop hazard by payment age, externally tagged. The final payment date can never stop (h[term] \u2261 0), so lifetime targets calibrate over ages 1..term\u22121.", "oneOf": [ { "type": "object", "required": [ "BaselineCurve" ], "additionalProperties": false, "properties": { "BaselineCurve": { "type": "object", "required": [ "lifetime" ], "properties": { "lifetime": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "description": "Lifetime stop share the program hump is scaled to. Program pricing stance: 0.40 (needs a term of at least 2 months unless 0)." } } } }, "description": "The program's baseline curve (a hump in the early-middle of the term, normalized to term fraction) scaled to a lifetime target." }, { "type": "object", "required": [ "FlatAnnual" ], "additionalProperties": false, "properties": { "FlatAnnual": { "type": "object", "required": [ "annual_rate" ], "properties": { "annual_rate": { "type": "number", "minimum": 0, "maximum": 1, "description": "Annual stop rate converted to a monthly hazard \u2014 rate semantics, not a lifetime target." } } } }, "description": "Flat annual stop rate." }, { "type": "object", "required": [ "CustomYearly" ], "additionalProperties": false, "properties": { "CustomYearly": { "type": "object", "required": [ "shares" ], "properties": { "shares": { "type": "array", "items": { "type": "number", "minimum": 0 }, "description": "shares[y] is the unconditional share of the ORIGINAL book that stops in year y+1; the shares sum to the lifetime stop share and spread uniformly over each year's defaultable ages. Length, sign, sum and empty-year rules are validated (400)." } } } }, "description": "Custom per-year stop timing (v1.4)." } ] }, "ConvictionRule": { "type": "object", "description": "Input #11: the lost-conviction rule \u2014 a Buyer whose spot has sat below (1 \u2212 x_underwater) \u00d7 entry for y_consecutive consecutive payment dates walks at the next one.", "required": [ "enabled", "x_underwater", "y_consecutive" ], "properties": { "enabled": { "type": "boolean", "default": false }, "x_underwater": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, "y_consecutive": { "type": "integer", "minimum": 1, "default": 6 } } }, "Shock": { "type": "object", "description": "Input #17: drop `drop_pct` from `start_month` over `duration_months` (log-linear ramp), then hold flat \u2014 or recover log-linearly to `recover_to_pct` of the unshocked path by the horizon. Applied after path generation, so it composes with any mode.", "required": [ "start_month", "drop_pct", "duration_months" ], "properties": { "start_month": { "type": "integer", "minimum": 0 }, "drop_pct": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1, "description": "0.70 = a 70% drawdown." }, "duration_months": { "type": "integer", "minimum": 1 }, "recover_to_pct": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "null = permanent; 1.0 = a full round trip by the final month." } } }, "PathBump": { "type": "object", "description": "Bump overlay (v1.6): from `from_month` on, multiply every price by `price_factor` and scale the deviations of the log returns around their mean by `vol_factor`. Applied after the shock.", "required": [ "from_month", "price_factor", "vol_factor" ], "properties": { "from_month": { "type": "integer", "minimum": 0 }, "price_factor": { "type": "number", "exclusiveMinimum": 0.1, "exclusiveMaximum": 10 }, "vol_factor": { "type": "number", "minimum": 0, "exclusiveMaximum": 5 }, "hold_strikes": { "type": "boolean", "default": false, "description": "Hold every Agreement's entry price (and Purchase Price) at the UNBUMPED level \u2014 the existing book's Greeks. false = later cohorts strike at the bumped prices, the commitment's exposure." } } }, "BoundaryParams": { "type": "object", "description": "Input #25: the rational walk-away frontier's lattice (CRR under the Buyer's believed drift). Defaults: \u03c3 0.414, \u03bc 0.25, r_c 0.15, walk cost 0.025.", "required": [ "sigma_annual", "mu_annual", "r_c_annual", "walk_cost_of_strike" ], "properties": { "sigma_annual": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 2.5, "default": 0.414, "description": "Annual vol of the lattice (the trailing-24-month realized at the v1.1 refresh)." }, "mu_annual": { "type": "number", "exclusiveMinimum": -2, "exclusiveMaximum": 2, "default": 0.25, "description": "The Buyer's BELIEVED annual drift; \u03bc = 0 walks at or above par from the earliest months." }, "r_c_annual": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "default": 0.15, "description": "The Buyer's personal discount rate per year." }, "walk_cost_of_strike": { "type": "number", "minimum": 0, "exclusiveMaximum": 1, "default": 0.025, "description": "Walk cost as a fraction of the coin's cost \u2014 the six-month lockout, the re-strike at market and the loss of access, as a lump." } } }, "SimulateRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "include_postings": { "type": "boolean", "default": false, "description": "Attach the raw double-entry postings (large; the drill-down wants them)." }, "include_agreements": { "type": "boolean", "default": true, "description": "Attach the per-Agreement table \u2014 about 106 KB of the 112 KB default body at the base book. Side-runs that only read scalars pass false and use `agreement_count`." }, "include_research": { "type": "boolean", "default": false, "description": "Attach an unhedged USD/BTC research observation and monthly cash replay from this same simulated book. USD discounting is zero; no second path is run." } } }, "SimulateResponse": { "type": "object", "required": [ "outputs", "agreements", "agreement_count", "path", "conservation_ok", "hazard_monthly", "postings" ], "properties": { "outputs": { "$ref": "#/components/schemas/RunOutputs" }, "agreements": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementRow" }, "description": "One row per Agreement; empty when `include_agreements` was false." }, "agreement_count": { "type": "integer", "description": "Book size, always populated." }, "path": { "type": "array", "items": { "type": "number" }, "description": "The monthly price path, index = month, length horizon + 1." }, "conservation_ok": { "type": "boolean", "description": "The ledger's postings sum to zero." }, "hazard_monthly": { "type": "array", "items": { "type": "number" }, "description": "The stop hazard by payment age for the scenario and term, length term + 1, h[0] = h[term] = 0." }, "postings": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Posting" }, "description": "The ledger, when asked for." }, "research": { "$ref": "#/components/schemas/SimulateResearch", "description": "Present only when include_research is true; omitted otherwise." } } }, "RunOutputs": { "type": "object", "description": "The Holder's outputs of one run.", "required": [ "irr_monthly", "irr_nominal_pa", "irr_effective_pa", "irr_unavailable", "wal_months", "payback_month", "undiscounted_multiple", "owner_total_inflow", "owner_total_outflow", "coins_per_coin", "coin_irr_effective_pa", "cash_recovery", "exit_split", "suppressed_defaults", "coin_returned_to_obligors", "total_shortfall_usd", "buyer_refunds_usd", "stop_surplus_usd", "cumulative_net_cash", "btcnow", "btcnow_fee_monthly", "irr_ambiguous", "irr_root_count", "coin_irr_unavailable", "coin_irr_ambiguous", "coin_irr_root_count" ], "properties": { "irr_monthly": { "type": [ "number", "null" ], "description": "Monthly IRR of the Holder's net cash flows, the lowest root of a log-space NPV (model audit 2026-09-06, M02); null when the flows are single-signed, no root lies in [\u22120.999, 10] per month, or the evaluation failed \u2014 `irr_unavailable` says which; `irr_ambiguous` says when the flow has several roots." }, "irr_nominal_pa": { "type": [ "number", "null" ], "description": "12 \u00d7 monthly." }, "irr_effective_pa": { "type": [ "number", "null" ], "description": "(1 + monthly)^12 \u2212 1, the figure quoted everywhere." }, "irr_unavailable": { "oneOf": [ { "$ref": "#/components/schemas/NoIrr" }, { "type": "null" } ], "description": "Why `irr_effective_pa` is null, when it is; null when the run has an IRR (audit 2026-09-05, finding 1)." }, "wal_months": { "type": [ "number", "null" ], "description": "Weighted average life of gross inflows." }, "payback_month": { "type": [ "integer", "null" ], "description": "First month cumulative net cash is \u2265 0." }, "undiscounted_multiple": { "type": [ "number", "null" ], "description": "Gross inflow \u00f7 gross outflow." }, "owner_total_inflow": { "$ref": "#/components/schemas/Decimal" }, "owner_total_outflow": { "$ref": "#/components/schemas/Decimal" }, "coins_per_coin": { "type": [ "number", "null" ], "description": "Gross fee-net Holder receipts converted at each monthly spot divided by gross Agreement purchases similarly converted; not one BTC per Agreement under strike dispersion or non-par pricing." }, "coin_irr_effective_pa": { "type": [ "number", "null" ], "description": "The coin seat's IRR: the IRR of the net coin flows, effective annual." }, "cash_recovery": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "number" } ], "minItems": 2, "maxItems": 2 }, "description": "Cumulative gross cash \u00f7 outflow at months 12, 24, 36." }, "exit_split": { "$ref": "#/components/schemas/ExitSplit" }, "suppressed_defaults": { "type": "integer", "description": "Stop draws suppressed by rational mode." }, "coin_returned_to_obligors": { "$ref": "#/components/schemas/Decimal", "description": "Spot value of the coin Buyers took at early completion, net of the payoff \u2014 Buyer property, never cash." }, "total_shortfall_usd": { "$ref": "#/components/schemas/Decimal", "description": "\u03a3 over stops of (remaining schedule \u2212 sale proceeds) where the sale fell short." }, "buyer_refunds_usd": { "$ref": "#/components/schemas/Decimal", "description": "\u03a3 dollar refunds to stopped Buyers: min(paid, max(0, V + paid \u2212 P))." }, "stop_surplus_usd": { "$ref": "#/components/schemas/Decimal", "description": "\u03a3 stop-sale proceeds delivered to the Holder above the remaining schedule." }, "cumulative_net_cash": { "type": "array", "items": { "type": "number" }, "description": "Cumulative net Holder cash by month; feeds the cash fan." }, "btcnow": { "$ref": "#/components/schemas/BtcNowTake" }, "btcnow_fee_monthly": { "type": "array", "items": { "type": "number" }, "description": "BTC Now's fee revenue by month; sums to `btcnow.total_take`." }, "irr_ambiguous": { "type": "boolean", "description": "The flow has more than one IRR root on the scan (model audit 2026-09-06, M02): `irr_monthly` is the lowest, a reporting convention \u2014 read the cash and the multiple beside it." }, "irr_root_count": { "type": "integer", "description": "How many roots the scan found (0 when there is no IRR)." }, "coin_irr_unavailable": { "oneOf": [ { "$ref": "#/components/schemas/NoIrr" }, { "type": "null" } ], "description": "Why `irr_effective_pa` is null, when it is; null when the run has an IRR (audit 2026-09-05, finding 1)." }, "coin_irr_ambiguous": { "type": "boolean", "description": "The flow has more than one IRR root on the scan (model audit 2026-09-06, M02): `irr_monthly` is the lowest, a reporting convention \u2014 read the cash and the multiple beside it." }, "coin_irr_root_count": { "type": "integer", "description": "How many roots the scan found (0 when there is no IRR)." } } }, "ExitSplit": { "type": "object", "description": "Exit counts. `non_performance` is a stop, `settled` an early completion (engine identifiers, kept on the wire).", "required": [ "completed", "settled", "non_performance", "non_performance_rational", "conviction_walks", "rational_boundary", "open" ], "properties": { "completed": { "type": "integer" }, "settled": { "type": "integer", "description": "Early completions." }, "non_performance": { "type": "integer", "description": "Stops drawn from the hazard." }, "non_performance_rational": { "type": "integer", "description": "Stops redirected by rational mode." }, "conviction_walks": { "type": "integer" }, "rational_boundary": { "type": "integer", "description": "Walks at the computed frontier (input #25)." }, "open": { "type": "integer", "description": "Still active at the horizon (only mid-experiment)." } } }, "BtcNowTake": { "type": "object", "description": "BTC Now's take \u2014 fees only, never a share of a stop sale.", "required": [ "origination_fees", "flow_fees", "total_take", "purchase_prices", "paper_spread" ], "properties": { "origination_fees": { "$ref": "#/components/schemas/Decimal" }, "flow_fees": { "$ref": "#/components/schemas/Decimal" }, "total_take": { "$ref": "#/components/schemas/Decimal", "description": "origination + flow." }, "purchase_prices": { "$ref": "#/components/schemas/Decimal" }, "paper_spread": { "$ref": "#/components/schemas/Decimal", "description": "\u03a3(purchase \u2212 coin cost); zero at par." } } }, "AgreementRow": { "type": "object", "required": [ "id", "origination_month", "strike", "term_months", "outcome", "exit_month", "payments_made", "delivered_gross", "owner_net", "fee_to_btcnow", "origination_to_btcnow", "shortfall_usd", "coin_returned_usd", "purchase_price", "stop_proceeds_usd", "buyer_refund_usd", "stop_surplus_usd", "expected_net", "capital_pnl" ], "properties": { "id": { "type": "integer" }, "origination_month": { "type": "integer" }, "strike": { "$ref": "#/components/schemas/Decimal", "description": "The coin's cost at entry (dispersed within the cohort month when input #20 is on)." }, "term_months": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "completed", "settled", "non_performance", "non_performance_rational", "conviction_walk", "rational_boundary", "open" ] }, "exit_month": { "type": [ "integer", "null" ] }, "payments_made": { "type": "integer" }, "delivered_gross": { "$ref": "#/components/schemas/Decimal", "description": "Every dollar that entered the Holder's delivery stream." }, "owner_net": { "$ref": "#/components/schemas/Decimal", "description": "The same net of the servicing fee." }, "fee_to_btcnow": { "$ref": "#/components/schemas/Decimal" }, "origination_to_btcnow": { "$ref": "#/components/schemas/Decimal", "description": "The first N payments routed to BTC Now, as far as they were made." }, "shortfall_usd": { "$ref": "#/components/schemas/Decimal", "description": "Remaining schedule at the stop minus the sale proceeds, where positive." }, "coin_returned_usd": { "$ref": "#/components/schemas/Decimal", "description": "Coin value taken at early completion, net of the payoff; zero on every other exit." }, "purchase_price": { "$ref": "#/components/schemas/Decimal", "description": "Capital the Holder deployed." }, "stop_proceeds_usd": { "$ref": "#/components/schemas/Decimal", "description": "Recorded sale proceeds V after haircut and sale cost." }, "buyer_refund_usd": { "$ref": "#/components/schemas/Decimal", "description": "The Buyer's refund on a stop: min(A, max(0, V + A \u2212 P))." }, "stop_surplus_usd": { "$ref": "#/components/schemas/Decimal", "description": "Proceeds above the remaining schedule kept by the Holder." }, "expected_net": { "$ref": "#/components/schemas/Decimal", "description": "What full performance would deliver: (terminal \u2212 first N) \u00d7 (1 \u2212 fee)." }, "capital_pnl": { "$ref": "#/components/schemas/Decimal", "description": "owner_net \u2212 purchase_price." } } }, "Posting": { "type": "object", "description": "One double-entry posting. Entities: `\"Owner\"` (the Holder), `\"BtcNow\"`, `\"Market\"` (the stop sale's counterparty) or `{\"Obligor\": id}` (the Buyer).", "required": [ "month", "from", "to", "amount", "kind", "agreement" ], "properties": { "month": { "type": "integer" }, "from": { "$ref": "#/components/schemas/EntityId" }, "to": { "$ref": "#/components/schemas/EntityId" }, "amount": { "$ref": "#/components/schemas/Decimal" }, "kind": { "type": "string", "enum": [ "PurchasePrice", "OriginationFee", "PaymentDelivery", "FlowFee", "MakeWholeDelivery", "StopSaleDelivery", "StopRefund" ] }, "agreement": { "type": "integer" } } }, "EntityId": { "oneOf": [ { "type": "string", "enum": [ "Market", "Owner", "BtcNow" ] }, { "type": "object", "required": [ "Obligor" ], "additionalProperties": false, "properties": { "Obligor": { "type": "integer" } } } ] }, "MonteCarloRequest": { "type": "object", "required": [ "config", "runs" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "runs": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Input #14: seeded runs, seeds `seed \u2026 seed + runs \u2212 1`. Estimated work book \u00d7 runs \u2264 24,000,000 Agreement-runs (the shared ceiling)." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "Percentiles": { "type": "object", "description": "Nearest-rank percentiles over the sorted sample; `es3`/`es5` are expected shortfall \u2014 the MEAN of the worst 3%/5% of runs. `p3` is the institutional worst-case line (v1.4).", "required": [ "worst", "p1", "p3", "p5", "p25", "p50", "p75", "p95", "mean", "es3", "es5" ], "properties": { "worst": { "type": "number" }, "p1": { "type": "number" }, "p3": { "type": "number" }, "p5": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p95": { "type": "number" }, "mean": { "type": "number" }, "es3": { "type": "number" }, "es5": { "type": "number" } } }, "CashFanPoint": { "type": "object", "required": [ "month", "p5", "p25", "p50", "p75", "p95" ], "properties": { "month": { "type": "integer" }, "p5": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p95": { "type": "number" } } }, "MonteCarloSummary": { "type": "object", "required": [ "runs", "irr_effective", "wal_months", "pct_negative_irr", "pct_cash_loss", "multiple", "runs_without_irr", "without_irr_reasons", "note", "irr_histogram", "cash_fan", "base_seed", "runs_irr_ambiguous", "objective" ], "properties": { "runs": { "type": "integer" }, "irr_effective": { "oneOf": [ { "$ref": "#/components/schemas/Percentiles" }, { "type": "null" } ], "description": "The effective IRR over the runs that have one (`runs \u2212 runs_without_irr`) \u2014 conditional (audit 2026-09-05, finding 1); null when no run has an IRR (audit 2026-09-06, finding 1). Every other statistic is over all runs." }, "wal_months": { "$ref": "#/components/schemas/Percentiles" }, "pct_negative_irr": { "type": [ "number", "null" ], "description": "Share of the runs WITH an IRR whose IRR is below zero \u2014 conditional, null when no run has an IRR; read `pct_cash_loss` beside it." }, "pct_cash_loss": { "type": "number", "description": "Share of ALL runs whose undiscounted multiple is below one \u2014 the cash-loss frequency, never conditional on an IRR." }, "multiple": { "$ref": "#/components/schemas/Percentiles", "description": "The undiscounted multiple (gross dollars in over gross dollars out) over every run that deployed capital." }, "runs_without_irr": { "type": "integer", "description": "Runs without an IRR." }, "without_irr_reasons": { "$ref": "#/components/schemas/NoIrrCounts", "description": "The runs without an IRR, by reason." }, "note": { "type": "string", "description": "What the IRR statistics are conditional on, in words." }, "irr_histogram": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "integer" } ], "minItems": 2, "maxItems": 2 }, "description": "50 equal bins from the worst to the best IRR: (left edge, count)." }, "cash_fan": { "type": "array", "items": { "$ref": "#/components/schemas/CashFanPoint" }, "description": "Percentile bands of `cumulative_net_cash` per month \u2014 when the money is actually back." }, "base_seed": { "type": "integer" }, "runs_irr_ambiguous": { "type": "integer", "description": "Runs whose flow has more than one IRR root (model audit 2026-09-06, M02): their IRR is the lowest root, a reporting convention." }, "objective": { "type": "string", "enum": [ "dollar" ], "description": "The measurement objective used for these legacy headline results." } } }, "WsFrame": { "description": "A server \u2192 client text frame on the Monte Carlo websocket, discriminated by `event`.", "oneOf": [ { "type": "object", "required": [ "event", "done", "total", "pct" ], "properties": { "event": { "const": "Progress" }, "done": { "type": "integer" }, "total": { "type": "integer" }, "pct": { "type": "integer", "description": "Integer 100\u00b7done/total." } }, "description": "After every chunk of 1,000 runs." }, { "type": "object", "required": [ "event", "summary", "engine" ], "properties": { "event": { "const": "Complete" }, "summary": { "$ref": "#/components/schemas/MonteCarloSummary" }, "engine": { "type": "object", "required": [ "spec", "version", "build", "data_sha256" ], "properties": { "spec": { "type": "string", "const": "v1.14" }, "version": { "type": "string" }, "build": { "type": "string", "description": "`X-Engine-Build`: crate + spec + source revision." }, "data_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "`X-Engine-Data`: SHA-256 of the compiled-in series." } }, "description": "The answering engine's identity \u2014 what the headers say on a REST response; a socket has none (audit 2026-09-06, finding 6)." } }, "description": "Once; the client should close. A memoized request skips straight here." }, { "type": "object", "required": [ "event", "message" ], "properties": { "event": { "const": "Error" }, "message": { "type": "string" } }, "description": "Validation failure, an engine 400, or a first frame that is not valid JSON; the server closes." } ] }, "SolvePriceRequest": { "type": "object", "required": [ "config", "target_effective_irr" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "target_effective_irr": { "type": "number", "exclusiveMinimum": -0.9, "exclusiveMaximum": 10, "description": "Input #19: the Holder's hurdle, an effective annual IRR (0.12 = 12%)." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "SolvePriceResponse": { "type": "object", "required": [ "pct_of_strike", "usd_at_start_price", "target_effective_irr", "irr_check", "attainable", "note", "objective" ], "properties": { "pct_of_strike": { "oneOf": [ { "$ref": "#/components/schemas/Decimal" }, { "type": "null" } ], "description": "The price that attains the target as a fraction of the coin's cost, eight decimals \u2014 PV(the Holder's net receipts at the target rate) / PV(the strikes at their origination months) from one prepared run (audit 2026-09-05, finding 7). null only when the Holder receives nothing, so no price attains any target." }, "usd_at_start_price": { "type": [ "number", "null" ], "description": "The fraction \u00d7 start_price." }, "target_effective_irr": { "type": "number", "description": "Echoed." }, "irr_check": { "type": [ "number", "null" ], "description": "The effective annual IRR a verifying run reports at pct_of_strike." }, "attainable": { "type": "boolean", "description": "True when pct_of_strike lies inside the desk's bracket (1%\u2013500% of the coin's cost) and the check agrees with the target within a basis point; false otherwise, with `note` saying why (nothing received; the target above the yield at 1%; the target below the yield at five times the coin's cost)." }, "note": { "type": "string", "description": "The method, or the reason the target is not attained." }, "objective": { "type": "string", "enum": [ "dollar" ], "description": "The measurement objective used for these legacy headline results." } } }, "HeatmapRequest": { "description": "`config` plus a flattened grid spec selected by `grid`. Every cell is a full deterministic run on the config's seed; a cell that fails validation is a hole (null), never a 400. 1\u2013900 cells.", "oneOf": [ { "type": "object", "required": [ "config", "grid", "end_prices", "lifetimes" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "grid": { "const": "PriceDefault" }, "end_prices": { "type": "array", "minItems": 1, "items": { "type": "number" }, "description": "Column axis: bridge end prices in dollars." }, "lifetimes": { "type": "array", "minItems": 1, "items": { "type": "number" }, "description": "Row axis: lifetime stop shares for the baseline curve." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } }, "description": "The break-even frontier: each cell runs a bridge to the column's end price at the base bridge vol (43% when the base path is not a bridge), the baseline curve at the row's lifetime." }, { "type": "object", "required": [ "config", "grid", "vols", "x_underwater" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "grid": { "const": "VolConviction" }, "vols": { "type": "array", "minItems": 1, "items": { "type": "number" }, "description": "Column axis: annual bridge vols." }, "x_underwater": { "type": "array", "minItems": 1, "items": { "type": "number" }, "description": "Row axis: lost-conviction thresholds (fraction below entry)." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } }, "description": "The behavioral cliff: a bridge to the base end price at the column's vol, the conviction rule forced on at the row's X with the config's Y." } ] }, "HeatmapResponse": { "type": "object", "required": [ "cells" ], "properties": { "cells": { "type": "array", "items": { "type": "array", "items": { "type": [ "number", "null" ] } }, "description": "cells[row][col] = effective annual IRR, null where undefined or the cell failed validation." } } }, "BacktestRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig", "description": "`path`, `cohorts` and `origination_stop_month` are overridden per vintage (HistoricalReplay at each seasoned month, 1, null); everything else \u2014 `agreements_per_cohort` as units per vintage \u2014 is the sensitivity set. The replay is rebased so month 0 equals start_price." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "VintageRow": { "type": "object", "required": [ "month", "start_index", "entry_close", "irr_effective_pa", "moic", "net_gain_usd", "deployed_usd", "shortfall_usd", "completed", "settled", "non_performance", "coin_returned_usd", "buyer_refund_usd", "stop_surplus_usd", "btcnow_take_usd" ], "properties": { "month": { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "integer" } ], "minItems": 2, "maxItems": 2, "description": "Origination (year, month)." }, "start_index": { "type": "integer" }, "entry_close": { "type": "number", "description": "That month's actual close \u2014 a context label; dollar figures are rebased." }, "irr_effective_pa": { "type": [ "number", "null" ] }, "moic": { "type": [ "number", "null" ] }, "net_gain_usd": { "type": "number" }, "deployed_usd": { "type": "number" }, "shortfall_usd": { "type": "number" }, "completed": { "type": "integer" }, "settled": { "type": "integer", "description": "Early completions." }, "non_performance": { "type": "integer", "description": "All four stop buckets summed." }, "coin_returned_usd": { "type": "number" }, "buyer_refund_usd": { "type": "number" }, "stop_surplus_usd": { "type": "number" }, "btcnow_take_usd": { "type": "number" } } }, "BacktestResponse": { "type": "object", "required": [ "vintages", "blended_net_gain_usd", "blended_deployed_usd", "blended_moic", "failed" ], "properties": { "vintages": { "type": "array", "items": { "$ref": "#/components/schemas/VintageRow" } }, "blended_net_gain_usd": { "type": "number", "description": "Every vintage bought at equal size." }, "blended_deployed_usd": { "type": "number" }, "blended_moic": { "type": [ "number", "null" ] }, "failed": { "type": "integer", "description": "Vintages the engine rejected \u2014 holes, not a 400." } } }, "HistoryResponse": { "type": "object", "required": [ "months", "closes" ], "properties": { "months": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "integer" } ], "minItems": 2, "maxItems": 2 }, "description": "(year, month), chronological." }, "closes": { "type": "array", "items": { "type": "number" }, "description": "Monthly closes in dollars, same length." } } }, "RiskRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig", "description": "`config.bump` must be null; the Greeks own the bump." }, "ladder_month": { "type": [ "integer", "null" ], "default": null, "description": "Month for the exposure ladder and the as-of month for the Greeks; null = the month of peak capital at risk." }, "price_bump": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 0.5, "default": 0.05, "description": "Fraction, for delta and gamma." }, "vol_bump": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1, "default": 0.05, "description": "Vol points as a fraction, for vega." }, "frontier_mus": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "number" }, "default": [ 0, 0.1, 0.25, 0.5 ], "description": "Believed annual drifts for the frontier family." }, "greek_seeds": { "type": "integer", "minimum": 1, "maximum": 256, "default": 16, "description": "Seeds averaged for the Greeks. Estimated work: book \u00d7 (1 + 7 \u00d7 greek_seeds) Agreement-runs under the shared 24,000,000 ceiling \u2014 50,000 Agreements at 256 seeds (89,650,000) is a 400 naming greek_seeds and the book." }, "frontier_params": { "oneOf": [ { "$ref": "#/components/schemas/BoundaryParams" }, { "type": "null" } ], "default": null, "description": "Lattice parameters other than \u03bc; null = `config.rational_boundary`, else the defaults (\u03c3 0.414, \u03bc 0.25, r_c 0.15, walk cost 0.025)." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "RiskResponse": { "type": "object", "description": "The `ExposureReport` flattened to the top level, then the frontier family.", "required": [ "lines", "coverage", "coverage_by_cohort", "ladder", "credit", "greeks", "frontiers", "frontier_params" ], "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/LineRow" }, "description": "One per payments made, t = 0..term; scale-invariant in the coin's cost." }, "coverage": { "type": "array", "items": { "$ref": "#/components/schemas/CoveragePoint" }, "description": "One per calendar month." }, "coverage_by_cohort": { "type": "array", "items": { "$ref": "#/components/schemas/CohortCoverage" } }, "ladder": { "$ref": "#/components/schemas/Ladder" }, "credit": { "type": "array", "items": { "$ref": "#/components/schemas/CreditRow" }, "description": "One per vintage and a book row last (`origination_month: null`)." }, "greeks": { "$ref": "#/components/schemas/Greeks" }, "frontiers": { "type": "array", "items": { "$ref": "#/components/schemas/FrontierFamily" } }, "frontier_params": { "$ref": "#/components/schemas/BoundaryParams", "description": "The lattice parameters used (\u03bc per family)." } } }, "LineRow": { "type": "object", "required": [ "t", "schedule_line", "capital_line", "capital_above_purchase_price", "remaining_schedule_usd", "unrecovered_capital_usd" ], "properties": { "t": { "type": "integer", "description": "Payments made so far (0 = at signing)." }, "schedule_line": { "type": "number", "description": "Remaining nominal schedule \u00f7 entry price: above it a stop costs the Holder nothing but future yield." }, "capital_line": { "type": "number", "description": "Sale proceeds that return the Holder's unrecovered capital \u00f7 entry price, read off the waterfall: U/(1 \u2212 fee) while that sits at or below the remaining schedule, else A + U/(1 \u2212 fee). Zero once the capital is back." }, "capital_above_purchase_price": { "type": "boolean", "description": "The capital line sits in the surplus regime." }, "remaining_schedule_usd": { "type": "number" }, "unrecovered_capital_usd": { "type": "number" } } }, "CoveragePoint": { "type": "object", "required": [ "month", "spot", "active", "below_schedule", "below_capital", "notional_usd", "capital_at_risk_usd", "intrinsic_shortfall_usd" ], "properties": { "month": { "type": "integer" }, "spot": { "type": "number" }, "active": { "type": "integer" }, "below_schedule": { "type": "integer", "description": "Active Agreements whose stop sale at this month's price (haircut and sale cost applied) would not cover the remaining schedule." }, "below_capital": { "type": "integer", "description": "Active Agreements whose stop sale would not return the Holder's unrecovered capital under the waterfall." }, "notional_usd": { "type": "number", "description": "\u03a3 remaining schedule \u2014 the notional of the embedded put ladder." }, "capital_at_risk_usd": { "type": "number", "description": "\u03a3 unrecovered capital." }, "intrinsic_shortfall_usd": { "type": "number", "description": "\u03a3 shortfall a sale at this price would leave on every Agreement below the schedule line." } } }, "CohortCoverage": { "type": "object", "required": [ "origination_month", "agreements", "months_below_schedule", "months_below_capital", "share_below_schedule", "share_below_capital" ], "properties": { "origination_month": { "type": "integer" }, "agreements": { "type": "integer" }, "months_below_schedule": { "type": "number", "description": "Mean per Agreement." }, "months_below_capital": { "type": "number" }, "share_below_schedule": { "type": "number", "description": "Share of active Agreement-months." }, "share_below_capital": { "type": "number" } } }, "LadderCell": { "type": "object", "required": [ "moneyness", "tenor", "agreements", "notional_usd", "capital_at_risk_usd" ], "properties": { "moneyness": { "type": "string", "enum": [ "< 0.50", "0.50\u20130.70", "0.70\u20130.85", "0.85\u20131.00", "1.00\u20131.20", "\u2265 1.20" ], "description": "Sale proceeds \u00f7 remaining schedule, bucketed." }, "tenor": { "type": "string", "enum": [ "\u2264 6 mo", "7\u201312 mo", "13\u201324 mo", "25\u201336 mo", "> 36 mo" ] }, "agreements": { "type": "integer" }, "notional_usd": { "type": "number" }, "capital_at_risk_usd": { "type": "number" } } }, "Ladder": { "type": "object", "required": [ "month", "spot", "cells", "total_notional_usd", "total_capital_at_risk_usd", "active" ], "properties": { "month": { "type": "integer" }, "spot": { "type": "number" }, "cells": { "type": "array", "minItems": 30, "maxItems": 30, "items": { "$ref": "#/components/schemas/LadderCell" }, "description": "6 moneyness \u00d7 5 tenor buckets." }, "total_notional_usd": { "type": "number" }, "total_capital_at_risk_usd": { "type": "number" }, "active": { "type": "integer" } } }, "CreditRow": { "type": "object", "required": [ "origination_month", "agreements", "stops", "completed", "completed_early", "pd", "ead_usd", "lgd", "el_usd", "el_rate", "capital_loss_usd", "deployed_usd", "refunds_usd", "surplus_usd" ], "properties": { "origination_month": { "type": [ "integer", "null" ], "description": "null for the whole book." }, "agreements": { "type": "integer" }, "stops": { "type": "integer" }, "completed": { "type": "integer" }, "completed_early": { "type": "integer" }, "pd": { "type": "number", "description": "stops \u00f7 Agreements." }, "ead_usd": { "type": "number", "description": "Mean remaining schedule at the stop." }, "lgd": { "type": "number", "description": "\u03a3 shortfall \u00f7 \u03a3 remaining schedule at the stop." }, "el_usd": { "type": "number", "description": "\u03a3 shortfall; the book row equals simulate's `total_shortfall_usd`." }, "el_rate": { "type": "number", "description": "\u00f7 capital deployed." }, "capital_loss_usd": { "type": "number", "description": "\u03a3 max(0, \u2212capital P&L) over stops \u2014 the par Holder's realized loss after the waterfall." }, "deployed_usd": { "type": "number" }, "refunds_usd": { "type": "number" }, "surplus_usd": { "type": "number" } } }, "Greeks": { "type": "object", "required": [ "price_bump", "vol_bump", "as_of_month", "as_of_spot", "seeds", "vega_method", "base_net_gain_usd", "base_irr", "delta_usd_per_pct", "delta_commitment_usd_per_pct", "delta_coins", "gamma_usd_per_pct2", "vega_usd_per_vol_point", "theta_usd_per_month", "delta_irr_pp_per_pct", "vega_irr_pp_per_vol_point", "base_vol_annual", "notes" ], "properties": { "price_bump": { "type": "number" }, "vol_bump": { "type": "number" }, "as_of_month": { "type": "integer", "description": "The book is valued as it stands at this month; bumps apply from the month after." }, "as_of_spot": { "type": "number" }, "seeds": { "type": "integer" }, "vega_method": { "type": "string", "description": "How vega is taken (audit 2026-09-06, finding 2): the base path is kept through `as_of` and the deviations of the log returns after it are scaled around their mean (`PathBump { from_month: as_of + 1, vol_factor }`) \u2014 never a regeneration, on every path mode, the bridge included \u2014 so an existing book of fixed dollar schedules has zero vega and only the continuation is bumped." }, "base_net_gain_usd": { "type": "number", "description": "Seed-ensemble mean of the unbumped book." }, "base_irr": { "type": [ "number", "null" ] }, "delta_usd_per_pct": { "type": "number", "description": "\u0394 net gain per +1% in every price after as_of_month, strikes held \u2014 the EXISTING book." }, "delta_commitment_usd_per_pct": { "type": "number", "description": "The same with later cohorts striking at the bumped prices \u2014 the forward-flow commitment." }, "delta_coins": { "type": "number", "description": "delta_usd_per_pct \u00f7 (1% \u00d7 as_of_spot): the coins a market-neutral desk would short." }, "gamma_usd_per_pct2": { "type": "number" }, "vega_usd_per_vol_point": { "type": "number" }, "theta_usd_per_month": { "type": "number", "description": "Flat-path net gain per month of weighted average life \u2014 the markup accrual." }, "delta_irr_pp_per_pct": { "type": [ "number", "null" ] }, "vega_irr_pp_per_vol_point": { "type": [ "number", "null" ] }, "base_vol_annual": { "type": "number", "description": "Realized annualized vol of the base path." }, "notes": { "type": "string", "description": "What the bump-and-revalue is and is not: the method, stated beside the numbers (exposure.rs GREEKS_NOTES)." } } }, "FrontierRow": { "type": "object", "required": [ "m", "payment", "walk_below_spot", "walk_below_of_entry", "walk_below_moneyness", "remaining_obligation", "remaining_schedule" ], "properties": { "m": { "type": "integer", "description": "Row index, payment \u2212 1." }, "payment": { "type": "integer", "description": "The payment this decision is about, 1-based." }, "walk_below_spot": { "type": [ "number", "null" ], "description": "The spot below which walking is optimal, dollars; null when no lattice node walks." }, "walk_below_of_entry": { "type": [ "number", "null" ], "description": "The same as a fraction of the entry price." }, "walk_below_moneyness": { "type": [ "number", "null" ], "description": "The same as spot \u00f7 the amortized obligation." }, "remaining_obligation": { "type": "number", "description": "The amortized obligation after the payments made before this date." }, "remaining_schedule": { "type": "number", "description": "Remaining nominal schedule, this payment included." } } }, "FrontierFamily": { "type": "object", "required": [ "mu_annual", "rows" ], "properties": { "mu_annual": { "type": "number" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/FrontierRow" }, "description": "One per payment." } } }, "CrashPreset": { "type": "object", "required": [ "id", "name", "description", "points" ], "properties": { "id": { "type": "string", "description": "Stable identifier (`\"2018\"`, `\"peak-crash\"`)." }, "name": { "type": "string" }, "description": { "type": "string", "description": "The episode it stylises and how." }, "points": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "number" } ], "minItems": 2, "maxItems": 2 }, "description": "(month, price ratio to the start) anchors. Load as `config.path = {\"Custom\": {\"points\": \u2026}}`." } } }, "CrashLibraryResponse": { "type": "object", "required": [ "presets" ], "properties": { "presets": { "type": "array", "items": { "$ref": "#/components/schemas/CrashPreset" }, "description": "The six one-click drawdowns." } } }, "VolSurface": { "type": "object", "description": "Implied volatility by tenor and moneyness. Rows are tenors, columns are moneyness K/S (the option-quoting convention \u2014 puts below 1, calls above; the reciprocal of the engine's own moneyness). Interpolation is linear in the vol between quoted strikes (ln moneyness); beyond the quoted moneyness range each tenor row follows the wing convention \u2014 total variance \u03c3\u00b2T linear in ln K/S at the edge cell's own slope, clamped to Lee's bound |dw/dk| \u2264 2, so there is no kink at the edge; between quoted tenors total variance is linear in the tenor, beyond them the surface is flat in tenor. Every price beyond the quoted range is that convention, not a quote. Every surface is checked in price space (monotone, convex across every node and into the wings, bounded, calendar) before it prices anything.", "required": [ "tenors_months", "moneyness", "vols", "source" ], "properties": { "tenors_months": { "type": "array", "minItems": 1, "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "Strictly ascending, positive." }, "moneyness": { "type": "array", "minItems": 1, "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "K/S, strictly ascending, positive." }, "vols": { "type": "array", "items": { "type": "array", "items": { "type": "number", "minimum": 0, "exclusiveMaximum": 5 } }, "description": "vols[i][j] at tenors_months[i], moneyness[j]; rectangular; annual fractions in [0, 5)." }, "source": { "type": "string", "description": "A venue and a timestamp for a real snapshot, or the preset's own warning label." }, "quoted_moneyness": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "readOnly": true, "description": "[first, last] quoted K/S: inside, a vol is interpolated between quotes; beyond, the wing convention applies. Reported on every surface the engine returns; ignored on import." }, "wing": { "type": "string", "readOnly": true, "description": "The wing convention, spelled out (forwardflow::surface::WING_CONVENTION). Reported on every surface the engine returns; ignored on import." }, "quoted_columns": { "type": "array", "items": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2 }, "description": "Optional. Per tenor row, [first, last] \u2014 the columns of `moneyness` that are that row's own quotes, when the rows were quoted on different strikes (a delta grid: the same delta lands at a different strike in every tenor). A row is read on its own quotes and its wing from its own edge; the cells outside its span are the wing convention's samples at the other rows' strikes, kept for display and never read. Absent: every column is a quote of every row." } } }, "SurfacesResponse": { "type": "object", "required": [ "flat", "stylised" ], "properties": { "flat": { "$ref": "#/components/schemas/VolSurface", "description": "43% at every tenor (1/3/6/12/24 months) and strike (K/S 0.50\u20131.30), no skew \u2014 the cockpit's base bridge vol." }, "stylised": { "$ref": "#/components/schemas/VolSurface", "description": "The stylised Bitcoin skew \u2014 ATM 41.4% to 12 months rising to 48% at 24, the 0.70 put +9/+6/+4 vol points, the 1.30 call \u22122/\u22121/0. An illustration, never market data; its `source` says so." } } }, "PlacementRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null, "description": "The surface the ladder is priced on; null = the stylised preset." }, "funding_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.045, "description": "Discount rate for the ladder's Black-Scholes puts, annual continuously compounded fraction." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "LadderLeg": { "type": "object", "description": "One leg of the paper's embedded put ladder: the put the Holder is short on a stop at one payment age.", "required": [ "month", "strike_usd", "tenor_months", "weight", "moneyness", "implied_vol", "put_value_usd" ], "properties": { "month": { "type": "integer", "description": "Payments made when the next is missed, 1..term\u22121." }, "strike_usd": { "type": "number", "description": "The remaining nominal schedule after `month` payments \u2014 the schedule line in dollars." }, "tenor_months": { "type": "integer", "description": "The missed payment date, month + 1." }, "weight": { "type": "number", "description": "Unconditional stop probability at this age from the scenario, price-blind; the weights sum to the lifetime stop share." }, "moneyness": { "type": "number", "description": "The engine's moneyness S\u2080/R_t; the surface is read at its reciprocal." }, "implied_vol": { "type": "number" }, "put_value_usd": { "type": "number", "description": "Black-Scholes put on one coin at that vol." } } }, "Placement": { "type": "object", "required": [ "legs", "paper_implied_vol", "surface_atm_12m", "ladder_value_usd_per_agreement", "markup_usd_per_agreement", "markup_pv_usd_per_agreement" ], "properties": { "legs": { "type": "array", "items": { "$ref": "#/components/schemas/LadderLeg" } }, "paper_implied_vol": { "type": [ "number", "null" ], "description": "The flat vol at which the markup exactly pays for the weighted ladder; null when no vol in (1%, 1000%) does." }, "surface_atm_12m": { "type": "number" }, "ladder_value_usd_per_agreement": { "type": "number", "description": "\u03a3 weight \u00d7 put value \u2014 what the market says the Holder's short puts are worth per Agreement." }, "markup_usd_per_agreement": { "type": "number", "description": "The flat-path markup \u2014 what the Holder is paid to be short them." }, "markup_pv_usd_per_agreement": { "type": "number", "description": "The same as a present value at the funding rate." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "The surface's arbitrage violations, each naming the tenor, the strikes and the prices, when the request set `allow_arbitrage_warning` and the surface carried any (model audit 2026-09-06, M06). Absent when there are none." }, "surface_note": { "type": "string", "description": "The surface's quoted moneyness range and wing rule, spelled out (`VolSurface::wing_note`; model audit 2026-09-07, R01): every option priced beyond the quoted range is priced by the wing convention, not a quote. On every result priced on a surface." } } }, "FairValueRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig", "description": "Behavior stays the config's; the shock and bump overlays are cleared (a fair value is not a stress)." }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null, "description": "The surface whose 24-month ATM vol the paths run at; null = the stylised preset." }, "funding_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.045, "description": "The desk's funding rate, annual continuously compounded: the paths drift at it and the flows discount at it." }, "seeds": { "type": "integer", "minimum": 1, "maximum": 256, "default": 32, "description": "Seeds averaged, from the config's seed upward; seeds \u00d7 book \u2264 24,000,000." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "FairValue": { "type": "object", "required": [ "pv_per_agreement_usd", "pv_book_usd", "purchase_book_usd", "spread_bps", "atm_vol_used", "seeds", "funding_rate_annual", "agreements" ], "properties": { "pv_per_agreement_usd": { "type": "number" }, "pv_book_usd": { "type": "number", "description": "PV at month 0 of every dollar delivered to the Holder, averaged over seeds." }, "purchase_book_usd": { "type": "number", "description": "PV at month 0 of every purchase price the Holder paid." }, "spread_bps": { "type": "number", "description": "(pv \u2212 purchase) / purchase in basis points; positive means the paper is cheap under the surface's measure." }, "atm_vol_used": { "type": "number", "description": "The surface's ATM vol at 24 months." }, "seeds": { "type": "integer" }, "funding_rate_annual": { "type": "number" }, "agreements": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "The surface's arbitrage violations, each naming the tenor, the strikes and the prices, when the request set `allow_arbitrage_warning` and the surface carried any (model audit 2026-09-06, M06). Absent when there are none." }, "surface_note": { "type": "string", "description": "The surface's quoted moneyness range and wing rule, spelled out (`VolSurface::wing_note`; model audit 2026-09-07, R01): every option priced beyond the quoted range is priced by the wing convention, not a quote. On every result priced on a surface." } } }, "Inception": { "description": "When a static hedge is put on: `\"AtOrigination\"` (each cohort at its own origination month) or `{\"AtMonth\": m}` (the whole book on the books at that month, m within the run's horizon).", "oneOf": [ { "type": "string", "const": "AtOrigination" }, { "type": "object", "required": [ "AtMonth" ], "additionalProperties": false, "properties": { "AtMonth": { "type": "integer", "minimum": 0 } } } ] }, "Side": { "type": "string", "enum": [ "Long", "Short", "Buy", "Write" ], "description": "`Long`/`Short` for a futures leg, `Buy`/`Write` for an option leg (a write is naked on the paper)." }, "OptionKind": { "type": "string", "enum": [ "Put", "Call" ] }, "FuturesSizing": { "description": "How a futures leg is sized per on-book Agreement at every rebalance, externally tagged.", "oneOf": [ { "type": "object", "required": [ "DollarDelta" ], "additionalProperties": false, "properties": { "DollarDelta": { "type": "object", "required": [ "share" ], "properties": { "share": { "type": "number", "minimum": 0, "maximum": 2 } } } }, "description": "The dollar seat's delta (the embedded put ladder's proxy delta, about 0.30 coins per Agreement at signing, melting) \u00d7 share." }, { "type": "object", "required": [ "CoinDelta" ], "additionalProperties": false, "properties": { "CoinDelta": { "type": "object", "required": [ "share" ], "properties": { "share": { "type": "number", "minimum": 0, "maximum": 2 } } } }, "description": "The coin seat's ex-ante coin delta (about one coin per Agreement at signing) \u00d7 share." }, { "type": "object", "required": [ "Coins" ], "additionalProperties": false, "properties": { "Coins": { "type": "object", "required": [ "per_agreement" ], "properties": { "per_agreement": { "type": "number", "minimum": 0, "maximum": 2 } } } }, "description": "A fixed count of coins per on-book Agreement." } ] }, "BasisSchedule": { "type": "object", "description": "Dated-futures basis: `locked_rate` for the first `locked_months` of each Agreement (a listed contract held to expiry), `after_rate` on the rolls after. A long pays the basis on its notional; a short receives it.", "required": [ "locked_months", "locked_rate", "after_rate" ], "properties": { "locked_months": { "type": "integer", "minimum": 0, "maximum": 120 }, "locked_rate": { "type": "number", "minimum": -1, "maximum": 1, "description": "Annual." }, "after_rate": { "type": "number", "minimum": -1, "maximum": 1, "description": "Annual." } } }, "Strike": { "description": "Where an option leg is struck, resolved at each inception.", "oneOf": [ { "type": "object", "required": [ "PctOfEntry" ], "additionalProperties": false, "properties": { "PctOfEntry": { "type": "number", "minimum": 0.01, "maximum": 5 } }, "description": "A share of the Agreement's entry price." }, { "type": "object", "required": [ "PctOfSpot" ], "additionalProperties": false, "properties": { "PctOfSpot": { "type": "number", "minimum": 0.01, "maximum": 5 } }, "description": "A share of the path's spot at the inception." }, { "type": "object", "required": [ "PctOfPurchasePrice" ], "additionalProperties": false, "properties": { "PctOfPurchasePrice": { "type": "number", "minimum": 0.01, "maximum": 5 } }, "description": "A share of the Purchase Price (entry \u00d7 multiple)." }, { "type": "string", "const": "LossLineAtExpiry", "description": "The Holder's capital line at the option's expiry age, as a share of entry; an option whose loss-line strike is zero is not bought." } ] }, "Roll": { "type": "string", "enum": [ "Once", "AtEachExpiry" ], "description": "`Once`: one option per inception, held to expiry. `AtEachExpiry`: re-bought (or re-written) at each expiry while the Agreement is on the book, within `years_limit` if set." }, "Coverage": { "description": "How many coins an option leg covers per Agreement, resolved at each inception.", "oneOf": [ { "type": "object", "required": [ "Coins" ], "additionalProperties": false, "properties": { "Coins": { "type": "number", "minimum": 0, "maximum": 2 } }, "description": "Coins per Agreement." }, { "type": "object", "required": [ "ShareOfDollarDelta" ], "additionalProperties": false, "properties": { "ShareOfDollarDelta": { "type": "number", "minimum": 0, "maximum": 2 } } }, { "type": "object", "required": [ "ShareOfCoinDelta" ], "additionalProperties": false, "properties": { "ShareOfCoinDelta": { "type": "number", "minimum": 0, "maximum": 2 } } } ] }, "Leg": { "description": "One leg of a generic `Legs` structure, externally tagged.", "oneOf": [ { "type": "object", "required": [ "Futures" ], "additionalProperties": false, "properties": { "Futures": { "type": "object", "required": [ "side", "sizing", "basis", "initial_margin_pct", "surface_vol" ], "properties": { "side": { "$ref": "#/components/schemas/Side", "description": "`Long` or `Short`." }, "sizing": { "$ref": "#/components/schemas/FuturesSizing" }, "basis": { "$ref": "#/components/schemas/BasisSchedule" }, "rebalance_months": { "type": "integer", "minimum": 1, "maximum": 120, "description": "The older key: a plain calendar reset every k months. Read when `rebalance` is absent; a plain calendar rule with the three fields below at zero WRITES this key, so stored structures round-trip unchanged. One of `rebalance_months` or `rebalance` is required." }, "rebalance": { "$ref": "#/components/schemas/Rebalance", "description": "The rebalance policy (Phase 4a). Takes precedence over `rebalance_months` when both are sent; written, with the three fields below, whenever the rule is not the plain calendar reset." }, "min_trade_coins": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "A reset whose trade is smaller than this (coins, per Agreement) is skipped and the position held; the opening trade is never skipped." }, "lot_coins": { "type": "number", "minimum": 0, "maximum": 1000, "default": 0, "description": "The book's net position on the leg is rounded to the nearest lot each month, spread pro rata over the Agreements; 0 = none, CME is 5." }, "margin_funding_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0, "description": "Annual rate charged monthly on the initial margin held from the month into the next, posted on the basis channel; 0 = nothing charged." }, "futures_cost_bps": { "type": "number", "minimum": 0, "maximum": 1000, "default": 0, "description": "Trading cost in basis points of the notional of every futures trade \u2014 the opening, each rebalance's change and the close-outs, priced at the month's spot (the turnover's own terms) \u2014 posted on the basis channel in the trade's month and reported as futures_trading_cost_mean_usd; 0 = nothing charged. The execution cost (exec_cost_bps) is bps of option premium and never touches a futures leg (model audit 2026-09-06, M10)." }, "close_on_exit": { "type": "boolean", "default": false, "description": "Calendar rule only: close the position the month its Agreement leaves the book instead of holding it through the interval. Default false, the original rule \u2014 a position reset every k months is held to the next reset whether or not the Agreement is still on the book; the Agreement-months held past the paper's exit are reported as futures_retained_agreement_months and flagged in the result's notes. True closes at the Agreement's exit (the month DeltaBand and PriceMove already break at), the close-out counted in the turnover and charged futures_cost_bps (model audit 2026-09-07)." }, "initial_margin_pct": { "type": "number", "minimum": 0, "maximum": 1, "description": "Share of the gross notional; reported as capital (`margin_peak_of_par`), never charged." }, "surface_vol": { "type": "number", "minimum": 0, "exclusiveMaximum": 5, "description": "Annual vol of the zero-drift continuation paths the coin delta surface is built on (`CoinDelta` sizing only)." } }, "description": "Listed futures per on-book Agreement, reset by its trading rule (Phase 4a: `rebalance`, `min_trade_coins`, `lot_coins`, `margin_funding_rate`, flattened into the leg); the older `rebalance_months` still reads and writes for the plain calendar rule." } }, "description": "Listed futures per on-book Agreement, reset by its trading rule: the mark and the basis post in dollars at m + 1." }, { "type": "object", "required": [ "Option" ], "additionalProperties": false, "properties": { "Option": { "type": "object", "required": [ "kind", "side", "strike", "tenor_months", "roll", "coverage", "inception" ], "properties": { "kind": { "$ref": "#/components/schemas/OptionKind" }, "side": { "$ref": "#/components/schemas/Side", "description": "`Buy` or `Write`; a write is NAKED on the paper." }, "strike": { "$ref": "#/components/schemas/Strike" }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "roll": { "$ref": "#/components/schemas/Roll" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "inception": { "$ref": "#/components/schemas/Inception" }, "years_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 40, "description": "With `AtEachExpiry`: only during the first N years of each Agreement; null = the whole term." } } } }, "description": "A European option per Agreement, priced off the surface per the request's option pricing, cash-settled at intrinsic." } ] }, "HedgeSpec": { "description": "One hedge structure, externally tagged. Tenors and rebalance intervals are 1\u2013120 months.", "oneOf": [ { "type": "object", "required": [ "PutLadder" ], "additionalProperties": false, "properties": { "PutLadder": { "type": "object", "required": [ "strike_pct_of_entry", "tenor_months", "coverage", "inception" ], "properties": { "strike_pct_of_entry": { "type": "number", "minimum": 0.01, "maximum": 3, "description": "0.70 = the 70% floor." }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "coverage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Coins hedged per Agreement." }, "inception": { "$ref": "#/components/schemas/Inception" } } } }, "description": "Static puts on the paper, struck at a share of entry, held to expiry." }, { "type": "object", "required": [ "PutSpread" ], "additionalProperties": false, "properties": { "PutSpread": { "type": "object", "required": [ "long_strike_pct", "short_strike_pct", "tenor_months", "coverage", "inception" ], "properties": { "long_strike_pct": { "type": "number", "minimum": 0.01, "maximum": 3, "description": "Must exceed the short strike." }, "short_strike_pct": { "type": "number", "minimum": 0.01, "maximum": 3 }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "coverage": { "type": "number", "minimum": 0, "maximum": 1 }, "inception": { "$ref": "#/components/schemas/Inception" } } } }, "description": "Long the higher put, short the lower, both as shares of entry." }, { "type": "object", "required": [ "RollingPuts" ], "additionalProperties": false, "properties": { "RollingPuts": { "type": "object", "required": [ "strike_pct_of_spot", "tenor_months", "coverage" ], "properties": { "strike_pct_of_spot": { "type": "number", "minimum": 0.01, "maximum": 3 }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "coverage": { "type": "number", "minimum": 0, "maximum": 1 } } } }, "description": "Short-dated puts at a share of the then-spot, rolled at each expiry while the Agreement is on the book." }, { "type": "object", "required": [ "PerpDeltaHedge" ], "additionalProperties": false, "properties": { "PerpDeltaHedge": { "type": "object", "required": [ "rebalance_months", "funding_rate_annual", "initial_margin_pct", "coverage" ], "properties": { "rebalance_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "funding_rate_annual": { "type": "number", "minimum": -1, "maximum": 1, "description": "The short pays this on its notional; negative = the short is paid." }, "initial_margin_pct": { "type": "number", "minimum": 0, "maximum": 1 }, "coverage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Share of the proxy delta shorted." } } } }, "description": "Short perpetuals against the book's delta, reset at every rebalance \u2014 the market-neutral seat. Weighs term-months of work against the Agreement-run cap." }, { "type": "object", "required": [ "VarianceSwap" ], "additionalProperties": false, "properties": { "VarianceSwap": { "type": "object", "required": [ "tenor_months", "vega_notional_usd" ], "properties": { "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "vega_notional_usd": { "type": "number", "minimum": 0, "maximum": 1000000000000.0 } } } }, "description": "Long variance at the surface's ATM vol for the tenor, rolled through the horizon. Each swap runs its contractual tenor and is marked monthly \u2014 50 \u00d7 vega \u00d7 ((\u03c3\u00b2\u1d63\u00b7t + K\u00b2\u00b7(T \u2212 t))/T \u2212 K\u00b2)/K, the realised months as they were and the remaining at the strike \u2014 so the mark equals the settlement at expiry; a window still open at the horizon is marked there on the `variance swap (open at the horizon, marked)` leg rather than settled on a cut window (model audit 2026-09-06, M10). The series carries the mark in `option_mark` and settlements in `option_value`." }, { "type": "object", "required": [ "CrossBookCollar" ], "additionalProperties": false, "properties": { "CrossBookCollar": { "type": "object", "required": [ "free_coins", "call_strike_pct_of_spot", "put_strike_pct_of_entry", "tenor_months", "coverage" ], "properties": { "free_coins": { "type": "number", "minimum": 0, "maximum": 1000000000.0, "description": "Coins in the Holder's other book the calls are written on." }, "call_strike_pct_of_spot": { "type": "number", "minimum": 0.01, "maximum": 5 }, "put_strike_pct_of_entry": { "type": "number", "minimum": 0.01, "maximum": 3 }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "coverage": { "type": "number", "minimum": 0, "maximum": 1 } } } }, "description": "Calls written on free coin pay for puts on the paper." }, { "type": "object", "required": [ "CoinDeltaFutures" ], "additionalProperties": false, "properties": { "CoinDeltaFutures": { "type": "object", "required": [ "hedge_ratio", "basis_locked_months", "basis_locked_rate", "basis_after_rate", "rebalance_months", "surface_vol" ], "properties": { "hedge_ratio": { "type": "number", "minimum": 0, "maximum": 2, "description": "Share of the coin delta hedged; the coin-certainty setting is about 0.75\u20130.80." }, "basis_locked_months": { "type": "integer", "minimum": 0, "maximum": 120 }, "basis_locked_rate": { "type": "number", "minimum": -1, "maximum": 1 }, "basis_after_rate": { "type": "number", "minimum": -1, "maximum": 1 }, "rebalance_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "surface_vol": { "type": "number", "minimum": 0, "exclusiveMaximum": 5 } } } }, "description": "The coin seat's screen hedge: LONG futures of hedge_ratio \u00d7 the coin delta per on-book Agreement." }, { "type": "object", "required": [ "RolledCalls" ], "additionalProperties": false, "properties": { "RolledCalls": { "type": "object", "required": [ "strike_pct_of_entry", "tenor_months", "coverage" ], "properties": { "strike_pct_of_entry": { "type": "number", "minimum": 0.01, "maximum": 5, "description": "1.475 = the paper's multiple." }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120 }, "coverage": { "type": "number", "minimum": 0, "maximum": 1 }, "years_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 40 } } } }, "description": "Long listed calls at a fixed share of entry, re-bought at each expiry while the Agreement is on the book." }, { "type": "object", "required": [ "DealerCall" ], "additionalProperties": false, "properties": { "DealerCall": { "type": "object", "required": [ "strike_pct_of_entry", "tenor_months" ], "properties": { "strike_pct_of_entry": { "type": "number", "minimum": 0.01, "maximum": 5 }, "tenor_months": { "type": "integer", "minimum": 1, "maximum": 120, "description": "60 = the five-year reference." }, "coverage": { "type": "number", "minimum": 0, "maximum": 1, "default": 1 } } } }, "description": "One long call per Agreement at origination for the whole tenor \u2014 a dealer quote, not a screen instrument." }, { "type": "object", "required": [ "Legs" ], "additionalProperties": false, "properties": { "Legs": { "type": "object", "required": [ "legs" ], "properties": { "legs": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/Leg" } } } } }, "description": "A generic structure: 1\u20138 futures and option legs posting into one set of flows, each labelled `leg N: \u2026`." } ] }, "ShelfParams": { "type": "object", "description": "The shelf's rates (the risk paper's Table 18 holdings); every field defaults on its own.", "properties": { "coin_lend_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.02, "description": "Coin lending: the coin count grows at this rate a year." }, "covered_call_share": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 }, "covered_call_otm_pct": { "type": "number", "minimum": 0, "maximum": 4, "default": 0.1, "description": "How far above the month's mark the second covered-call row strikes, as a share of spot." }, "basis_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.04, "description": "The cash-and-carry basis a year." }, "dollar_lend_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.0765, "description": "The rate a year on dollars lent against coin." } } }, "HedgeRequest": { "type": "object", "required": [ "config", "structures" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null, "description": "The surface every option leg is priced on; null = the stylised preset." }, "funding_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.045, "description": "Accepted and validated for symmetry with placement and fair value; does not enter the hedge flows." }, "option_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0, "description": "The rate every option leg is priced at (Black-Scholes), annual continuously compounded; 0 = the surface's own quoting convention. The risk paper prices at 0.045." }, "put_skew_points": { "type": "number", "minimum": 0, "maximum": 50, "default": 0, "description": "Vol points ADDED to the surface's vol when a put is priced (5 = a 40% surface prices puts at 45%); calls read the surface as it is. The risk paper's setting is 5." }, "basis_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0.06, "description": "The crypto risk-free rate to a market-neutral desk; fills `hedged_excess_over_basis_pp`." }, "exec_cost_bps": { "type": "number", "minimum": 0, "maximum": 1000, "default": 50, "description": "Execution cost in basis points of premium on every option leg traded; none on perpetuals." }, "seeds": { "type": "integer", "minimum": 1, "maximum": 256, "default": 32, "description": "Seeds per structure, from the config's seed upward. Estimated work: book \u00d7 seeds \u00d7 \u03a3 structure units (+ 2 with the benchmarks) under the shared 24,000,000 ceiling." }, "structures": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/HedgeSpec" } }, "include_benchmarks": { "type": "boolean", "default": false, "description": "Also run paper vs spot vs covered call on the same seeds, and the shelf (counts as two more units of work)." }, "shelf": { "oneOf": [ { "$ref": "#/components/schemas/ShelfParams" }, { "type": "null" } ], "default": null, "description": "The shelf's rates; null = the paper's placeholders 2% / 30% / 10% / 4% / 7.65%." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "valuation_seed": { "type": [ "integer", "null" ], "minimum": 0, "description": "Fixed estimation seed, independent of realized path seeds. Omitted or null uses config.seed." }, "objective": { "type": "string", "enum": [ "dollar" ], "default": "dollar", "description": "Dollar-only route. Omission preserves the Dollar default. Explicit Coin, null or unknown objective values are refused with400; use hedge_research for Coin Monte Carlo." } } }, "Dist": { "type": "object", "description": "A distribution of the Holder's outcome over the seeds. IRRs are effective annual fractions. Every seed is a path (audit 2026-09-05, finding 1): `median_multiple`, `p5_multiple` and `pct_cash_loss` are over ALL `seeds_total` seeds; the IRR statistics (`median_irr`, `mean_irr`, `p5_irr`, `p95_irr`, `pct_negative`) are conditional on the `seeds_with_irr` seeds that have one, and `seeds_without_irr` says how many do not, by reason in `without_irr_reasons`. Read `pct_cash_loss` beside `pct_negative`: a hedge whose every seed loses money and none has an IRR reports `median_irr`, `mean_irr`, `p5_irr`, `p95_irr` and `pct_negative` null and `pct_cash_loss` 1. In a coin-seat `Dist` (`unhedged_coin`, `hedged_coin`, `paper_coin`, `SeatDists.coin`) the IRR fields are the COIN IRR, the multiples are COINS PER COIN and `pct_negative` is the share of seeds below ONE coin, over all seeds.", "required": [ "median_irr", "mean_irr", "p5_irr", "p95_irr", "pct_negative", "pct_cash_loss", "median_multiple", "p5_multiple", "seeds_total", "seeds_with_irr", "seeds_without_irr", "without_irr_reasons", "irr_ambiguous", "seeds_irr_ambiguous" ], "properties": { "median_irr": { "type": [ "number", "null" ], "description": "Median effective annual IRR over the seeds with an IRR; null when no seed has one (audit 2026-09-06, finding 1 \u2014 never a numeric zero)." }, "mean_irr": { "type": [ "number", "null" ], "description": "Mean over the seeds with an IRR; null when no seed has one." }, "p5_irr": { "type": [ "number", "null" ], "description": "5th percentile over the seeds with an IRR (linear interpolation); null when no seed has one." }, "p95_irr": { "type": [ "number", "null" ], "description": "95th percentile over the seeds with an IRR; null when no seed has one." }, "pct_negative": { "type": [ "number", "null" ], "description": "Share of the seeds WITH an IRR whose IRR is below zero, 0\u20131 \u2014 conditional, and null when no seed has an IRR; read `pct_cash_loss` beside it. Coin seat: the share below one coin, over all seeds, always present." }, "pct_cash_loss": { "type": "number", "description": "Share of ALL seeds whose undiscounted multiple is below one (coins per coin below one on the coin seat), 0\u20131 \u2014 the cash-loss frequency, never conditional on an IRR." }, "median_multiple": { "type": "number", "description": "Gross dollars in over gross dollars out, the hedge's flows included on the hedged side." }, "p5_multiple": { "type": "number" }, "seeds_total": { "type": "integer", "description": "Seeds run." }, "seeds_with_irr": { "type": "integer", "description": "Seeds whose IRR exists; the IRR statistics are over these." }, "seeds_without_irr": { "type": "integer", "description": "`seeds_total \u2212 seeds_with_irr`." }, "without_irr_reasons": { "$ref": "#/components/schemas/NoIrrCounts", "description": "The seeds without an IRR, by reason." }, "irr_ambiguous": { "type": "boolean", "description": "At least one seed's flow has more than one IRR root (model audit 2026-09-06, M02): on those seeds the IRR is the root nearest the unhedged rate, a reporting convention \u2014 read `pct_cash_loss` and the multiples beside the IRR statistics." }, "seeds_irr_ambiguous": { "type": "integer", "description": "How many seeds have more than one root." } } }, "HedgeLeg": { "type": "object", "required": [ "leg", "paid_mean_usd", "received_mean_usd" ], "properties": { "leg": { "type": "string", "description": "`puts on the paper`, `calls on the free coin`, `perpetual short, mark-to-market`, `perpetual funding`, `margin carry`, `variance swap`, or `leg N: ` for a generic structure." }, "paid_mean_usd": { "type": "number" }, "received_mean_usd": { "type": "number" } } }, "HedgeResult": { "type": "object", "required": [ "spec", "exec_cost_bps", "seeds", "unhedged", "hedged", "cost_irr_points", "cost_bps_of_deployed", "premium_paid_mean_usd", "payoff_mean_usd", "payout_over_premium", "floor_p5_irr", "worst_path_irr", "worst_path_seed", "worst_path_multiple", "worst_path_multiple_seed", "hedged_excess_over_basis_pp", "legs", "notes", "unhedged_coin", "hedged_coin", "coin_seat_note", "futures_notional_mean_of_par", "futures_notional_peak_of_par", "futures_worst_loss_of_par_median", "futures_worst_loss_of_par_p95", "futures_worst_month_of_par_median", "futures_worst_month_of_par_p95", "margin_peak_of_par", "futures_turnover_coins_mean", "futures_trades_mean", "futures_trading_cost_mean_usd", "futures_trading_cost_bps_of_deployed", "futures_retained_agreement_months", "surface_domain", "valuation_seed", "horizon_mark_mean_usd", "realized_settlement_mean_usd" ], "properties": { "spec": { "$ref": "#/components/schemas/HedgeSpec", "description": "Echoed exactly as sent." }, "exec_cost_bps": { "type": "number" }, "seeds": { "type": "integer" }, "unhedged": { "$ref": "#/components/schemas/Dist", "description": "The paper alone on the same seeds." }, "hedged": { "$ref": "#/components/schemas/Dist", "description": "The paper plus the hedge's flows." }, "cost_irr_points": { "type": [ "number", "null" ], "description": "Unhedged median IRR \u2212 hedged median IRR, percentage points; null when either median is missing (no seed with an IRR)." }, "cost_bps_of_deployed": { "type": "number" }, "premium_paid_mean_usd": { "type": "number", "description": "Net premium and carry paid; negative when the structure is net premium-positive." }, "payoff_mean_usd": { "type": "number" }, "payout_over_premium": { "type": "number" }, "floor_p5_irr": { "type": [ "number", "null" ], "description": "The hedged 5th-percentile IRR \u2014 the floor achieved; null when no hedged seed has an IRR (read `worst_path_multiple` and `hedged.p5_multiple`)." }, "worst_path_irr": { "type": [ "number", "null" ], "description": "The lowest hedged IRR across the seeds with one; null when no seed has an IRR \u2014 read `worst_path_multiple` then (audit 2026-09-05, finding 1)." }, "worst_path_seed": { "type": "integer", "description": "The seed of `worst_path_irr`; of `worst_path_multiple` when no seed has an IRR." }, "worst_path_multiple": { "type": "number", "description": "The lowest hedged undiscounted multiple across ALL seeds \u2014 always present." }, "worst_path_multiple_seed": { "type": "integer", "description": "Its seed." }, "hedged_excess_over_basis_pp": { "type": [ "number", "null" ], "description": "(hedged median IRR \u2212 basis_rate) \u00d7 100 \u2014 filled only for the market-neutral seat (a perpetual delta hedge, or a short dollar-delta futures leg); null otherwise, and null when the hedged median IRR is missing." }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/HedgeLeg" } }, "notes": { "type": "string" }, "unhedged_coin": { "$ref": "#/components/schemas/Dist" }, "hedged_coin": { "$ref": "#/components/schemas/Dist" }, "coin_seat_note": { "type": "string" }, "futures_notional_mean_of_par": { "type": "number", "description": "Futures structures only (zero otherwise): time-average gross notional as a share of par (\u03a3 purchase prices)." }, "futures_notional_peak_of_par": { "type": "number" }, "futures_worst_loss_of_par_median": { "type": "number", "description": "The worst cumulative futures loss as a share of par \u2014 the margin call the desk must meet \u2014 median over seeds." }, "futures_worst_loss_of_par_p95": { "type": "number" }, "futures_worst_month_of_par_median": { "type": "number", "description": "The worst single month's futures cash as a positive share of par, median over seeds." }, "futures_worst_month_of_par_p95": { "type": "number" }, "margin_peak_of_par": { "type": "number", "description": "Peak initial margin as a share of par; zero for `CoinDeltaFutures`, which carries no margin input." }, "futures_turnover_coins_mean": { "type": "number", "description": "Futures legs only (zero otherwise): \u03a3 |the change in the net position| over the months in coins \u2014 opening, resets, close-outs; a position open at the horizon not counted \u2014 mean over seeds." }, "futures_trades_mean": { "type": "number", "description": "Futures legs only: the months the rebalance policy traded, mean over seeds." }, "futures_trading_cost_mean_usd": { "type": "number", "description": "Futures legs only: dollars of futures trading cost charged per run \u2014 every leg's futures_cost_bps on the notional of every trade (the opening, each rebalance's change, the close-outs: the turnover's own terms at the month's spot), posted on the basis channel in the trade's month \u2014 mean over seeds; zero at the default and without futures (model audit 2026-09-06, M10)." }, "futures_trading_cost_bps_of_deployed": { "type": "number", "description": "The same as basis points of the mean deployed (\u03a3 purchase prices)." }, "futures_retained_agreement_months": { "type": "number", "description": "Futures legs only: Agreement-months a futures position was held past its Agreement's exit \u2014 the calendar rule holding a position through its interval after the paper left the book \u2014 summed over the legs, mean over seeds. A speculative exposure, not a hedge of anything on the book: when positive the notes carry a WARNING naming close_on_exit; zero under close_on_exit, under the band and price-move policies, and without futures (model audit 2026-09-07)." }, "surface_domain": { "oneOf": [ { "$ref": "#/components/schemas/SurfaceDomain" }, { "type": "null" } ], "description": "Structures that read the coin delta surface (CoinDeltaFutures, a CoinDelta futures leg, a ShareOfCoinDelta option leg): how far the surface reached over the run. Null for every other structure." }, "valuation_seed": { "type": "integer", "minimum": 0 }, "horizon_mark_mean_usd": { "type": "number", "description": "Mean signed remaining derivative value at horizon; economic value, not settled cash." }, "realized_settlement_mean_usd": { "type": "number", "description": "Mean realized payoff including futures settlements; payoff_mean_usd less remaining derivative value." } } }, "ShelfRow": { "type": "object", "required": [ "name", "usd", "coin" ], "properties": { "name": { "type": "string" }, "usd": { "$ref": "#/components/schemas/Dist" }, "coin": { "$ref": "#/components/schemas/Dist" } } }, "Benchmarks": { "type": "object", "description": "The directional desk's comparison on the same seeds: the paper, spot, and spot with a covered-call overwrite \u2014 each on both seats \u2014 plus the shelf.", "required": [ "paper", "spot", "covered_call", "paper_coin", "spot_coin", "covered_call_coin", "shelf", "seeds", "notes" ], "properties": { "paper": { "$ref": "#/components/schemas/Dist" }, "spot": { "$ref": "#/components/schemas/Dist", "description": "One coin per Agreement bought at its entry, every coin sold at the horizon's mark." }, "covered_call": { "$ref": "#/components/schemas/Dist", "description": "Contractual one-coin reference with annual calls struck at 130% of spot at each roll, using supplied option pricing and zero execution cost. Not a matched-purchase-budget comparison." }, "paper_coin": { "$ref": "#/components/schemas/Dist" }, "spot_coin": { "$ref": "#/components/schemas/Dist", "description": "One coin per coin by definition, a zero coin IRR \u2014 the coin seat's yardstick." }, "covered_call_coin": { "$ref": "#/components/schemas/Dist" }, "shelf": { "type": "array", "items": { "$ref": "#/components/schemas/ShelfRow" }, "description": "Six holdings, `Hold the coin` first." }, "seeds": { "type": "integer" }, "notes": { "type": "string" } } }, "HedgePreset": { "type": "object", "required": [ "name", "spec" ], "properties": { "name": { "type": "string", "description": "Prefixed `Dollar seat: `, `Coin seat: ` or `Both seats: ` for the generic structures; BTC Now's own posture is labelled as such \u2014 one preset among several, never a recommendation." }, "spec": { "$ref": "#/components/schemas/HedgeSpec" } } }, "HedgeResponse": { "type": "object", "required": [ "results", "benchmarks", "presets", "surface_note" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/HedgeResult" }, "description": "One per structure, in request order." }, "benchmarks": { "oneOf": [ { "$ref": "#/components/schemas/Benchmarks" }, { "type": "null" } ], "description": "null unless `include_benchmarks` was set." }, "presets": { "type": "array", "items": { "$ref": "#/components/schemas/HedgePreset" }, "description": "The preset shelf (15 entries), so a client offers the same specs the engine tests." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "The surface's arbitrage violations, each naming the tenor, the strikes and the prices, when the request set `allow_arbitrage_warning` and the surface carried any (model audit 2026-09-06, M06). Absent when there are none." }, "surface_note": { "type": "string", "description": "The surface's quoted moneyness range and wing rule, spelled out (`VolSurface::wing_note`; model audit 2026-09-07, R01): every option priced beyond the quoted range is priced by the wing convention, not a quote. On every result priced on a surface." } } }, "CoinSeatRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null }, "structures": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "$ref": "#/components/schemas/HedgeSpec" }, "description": "Run at each drift. Omitted = the coin-seat entries of the preset shelf (futures at 80% and 100% of the coin delta, the rolled twelve-month calls, the five-year dealer call)." }, "option_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0 }, "put_skew_points": { "type": "number", "minimum": 0, "maximum": 50, "default": 0 }, "drifts": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "number", "exclusiveMinimum": -0.99, "exclusiveMaximum": 20 }, "default": [ -0.3, -0.18, -0.09, 0.0, 0.1, 0.18, 0.22, 0.3, 0.39, 0.49, 0.6, 0.8 ], "description": "Median annual returns to sweep." }, "vol_annual": { "type": "number", "minimum": 0, "exclusiveMaximum": 5, "default": 0.4, "description": "Annual vol of the GBM paths." }, "seeds": { "type": "integer", "minimum": 1, "maximum": 256, "default": 32, "description": "Per row and structure; book \u00d7 seeds \u00d7 (structures + 1) \u00d7 drifts \u2264 24,000,000." }, "exec_cost_bps": { "type": "number", "minimum": 0, "maximum": 1000, "default": 50, "description": "Execution cost in basis points of premium on every option leg of every structure (the hedge overlay's default), so the sweep and the desk are net of the same cost; the response echoes it." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "valuation_seed": { "type": [ "integer", "null" ], "minimum": 0, "description": "Fixed estimation seed, independent of realized path seeds. Omitted or null uses config.seed." } } }, "SeatDists": { "type": "object", "required": [ "usd", "coin" ], "properties": { "usd": { "$ref": "#/components/schemas/Dist" }, "coin": { "$ref": "#/components/schemas/Dist" } } }, "DriftRow": { "type": "object", "required": [ "median_annual_return", "mu_annual", "unhedged", "structures" ], "properties": { "median_annual_return": { "type": "number", "description": "The r the row was run at." }, "mu_annual": { "type": "number", "description": "ln(1 + r) + \u03c3\u00b2/2." }, "unhedged": { "$ref": "#/components/schemas/SeatDists" }, "structures": { "type": "array", "items": { "$ref": "#/components/schemas/SeatDists" }, "description": "In request order." } } }, "DriftSweep": { "type": "object", "required": [ "vol_annual", "seeds", "exec_cost_bps", "structures", "rows", "notes", "valuation_seed" ], "properties": { "vol_annual": { "type": "number" }, "seeds": { "type": "integer" }, "exec_cost_bps": { "type": "number", "description": "Execution cost every option leg of every structure was charged, basis points of premium \u2014 the request's input, so the sweep and the desk are net of the same cost." }, "structures": { "type": "array", "items": { "$ref": "#/components/schemas/HedgeSpec" } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DriftRow" } }, "notes": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "The surface's arbitrage violations, each naming the tenor, the strikes and the prices, when the request set `allow_arbitrage_warning` and the surface carried any (model audit 2026-09-06, M06). Absent when there are none." }, "surface_note": { "type": "string", "description": "The surface's quoted moneyness range and wing rule, spelled out (`VolSurface::wing_note`; model audit 2026-09-07, R01): every option priced beyond the quoted range is priced by the wing convention, not a quote. On every result priced on a surface." }, "valuation_seed": { "type": "integer", "minimum": 0 } } }, "Rebalance": { "description": "When a futures leg resets its position to the sizing's target (Phase 4a). Externally tagged; a bare integer `3` reads as `{\"Calendar\": {\"months\": 3}}`, so the older `rebalance_months` still parses.", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 120, "description": "Shorthand for `Calendar` with these months." }, { "type": "object", "required": [ "Calendar" ], "additionalProperties": false, "properties": { "Calendar": { "type": "object", "required": [ "months" ], "properties": { "months": { "type": "integer", "minimum": 1, "maximum": 120 } } } }, "description": "Reset every `months` months from each Agreement's origination and hold through the interval (the original rule; `months: 1` is the monthly reset every preset ships with)." }, { "type": "object", "required": [ "DeltaBand" ], "additionalProperties": false, "properties": { "DeltaBand": { "type": "object", "required": [ "band_coins_per_agreement" ], "properties": { "band_coins_per_agreement": { "type": "number", "minimum": 0, "maximum": 10 } } } }, "description": "Reset when the target drifts from the position held by more than the band, per Agreement, checked monthly." }, { "type": "object", "required": [ "PriceMove" ], "additionalProperties": false, "properties": { "PriceMove": { "type": "object", "required": [ "pct" ], "properties": { "pct": { "type": "number", "minimum": 0.001, "maximum": 10 } } } }, "description": "Reset when the spot has moved by more than `pct` (a fraction) since that Agreement's last reset, checked monthly." } ] }, "Band": { "type": "object", "description": "One monthly series summarised across the seeds: index = month, 0 to the horizon (every array is `horizon + 1` long). `p5` / `median` / `p95` interpolate linearly between seeds; `min` and `max` are the extreme seeds.", "required": [ "p5", "median", "mean", "p95", "min", "max" ], "properties": { "p5": { "type": "array", "items": { "type": "number" } }, "median": { "type": "array", "items": { "type": "number" } }, "mean": { "type": "array", "items": { "type": "number" } }, "p95": { "type": "array", "items": { "type": "number" } }, "min": { "type": "array", "items": { "type": "number" } }, "max": { "type": "array", "items": { "type": "number" } } } }, "BookBand": { "type": "object", "description": "The book's monthly series across the seeds, each field a `Band`. Dollars unless said (counts on `on_book`, `stops`, `early_completions`).", "required": [ "paper_in", "paper_out", "hedge_premium", "hedge_settlement", "futures_mark", "futures_basis", "margin_balance", "futures_notional", "variation_call", "intramonth_call", "on_book", "stops", "early_completions", "spot", "mark_paper", "option_mark" ], "properties": { "paper_in": { "$ref": "#/components/schemas/Band", "description": "The Holder's gross receipts: payments, early-completion payoffs and stop-sale deliveries, net of the fee." }, "paper_out": { "$ref": "#/components/schemas/Band", "description": "Purchases: the purchase prices paid at each origination." }, "hedge_premium": { "$ref": "#/components/schemas/Band", "description": "Option premium as cash: negative when paid (execution cost included), positive when received on a written option." }, "hedge_settlement": { "$ref": "#/components/schemas/Band", "description": "Option payoffs and assignments and variance-swap settlements, signed \u2014 cash alone: an option still open at the run's last month is NOT settled here (its remaining-life value stays in `option_mark`)." }, "futures_mark": { "$ref": "#/components/schemas/Band", "description": "The futures legs' (and the perpetual's) mark-to-market cash." }, "futures_basis": { "$ref": "#/components/schemas/Band", "description": "The futures basis as cash (a long pays, a short receives), the perpetual's funding and the margin funding included." }, "margin_balance": { "$ref": "#/components/schemas/Band", "description": "Initial margin the treasury must fund: the leg's margin share \u00d7 the gross notional held from this month into the next; zero without futures." }, "futures_notional": { "$ref": "#/components/schemas/Band", "description": "Gross futures notional held from this month into the next." }, "variation_call": { "$ref": "#/components/schemas/Band", "description": "The variation call the desk posts this month: max(0, \u2212(futures_mark + futures_basis))." }, "intramonth_call": { "$ref": "#/components/schemas/Band", "description": "The call met inside the month on the paper's 18-day convention \u2014 a proxy for a typical intramonth move, not the path's own worst point." }, "on_book": { "$ref": "#/components/schemas/Band", "description": "Agreements on the book after the month's events (count)." }, "stops": { "$ref": "#/components/schemas/Band", "description": "Agreements that stopped this month (count); the sale cash lands later." }, "early_completions": { "$ref": "#/components/schemas/Band", "description": "Agreements that completed early this month (count)." }, "spot": { "$ref": "#/components/schemas/Band", "description": "The path's mark for the month." }, "mark_paper": { "$ref": "#/components/schemas/Band", "description": "The mark: fair value at the purchase yield of every Agreement on the book, plus the discounted sale proceeds of stops in transit." }, "option_mark": { "$ref": "#/components/schemas/Band", "description": "The outstanding options' value at month end: every option position open after the month's settlements, at its Black-Scholes remaining-life value on the surface at the month's spot (the premium's own pricing: the pricing rate, the surface's vol at the remaining tenor, the skew as at inception), a written option negative. Zero without options; a position still open at the run's last month stays in it (the same number the overlay counts as cash at the horizon); the cross-book collar's covered call is the free coin's and is not marked here (audit 2026-09-06, finding 3)." } } }, "BookSeries": { "type": "object", "description": "The book's monthly series for one seed, each field an array indexed by month. Dollars unless said.", "required": [ "paper_in", "paper_out", "hedge_premium", "hedge_settlement", "futures_mark", "futures_basis", "margin_balance", "futures_notional", "variation_call", "intramonth_call", "on_book", "stops", "early_completions", "spot", "mark_paper", "option_mark" ], "properties": { "paper_in": { "type": "array", "items": { "type": "number" }, "description": "The Holder's gross receipts: payments, early-completion payoffs and stop-sale deliveries, net of the fee." }, "paper_out": { "type": "array", "items": { "type": "number" }, "description": "Purchases: the purchase prices paid at each origination." }, "hedge_premium": { "type": "array", "items": { "type": "number" }, "description": "Option premium as cash: negative when paid (execution cost included), positive when received on a written option." }, "hedge_settlement": { "type": "array", "items": { "type": "number" }, "description": "Option payoffs and assignments and variance-swap settlements, signed \u2014 cash alone: an option still open at the run's last month is NOT settled here (its remaining-life value stays in `option_mark`)." }, "futures_mark": { "type": "array", "items": { "type": "number" }, "description": "The futures legs' (and the perpetual's) mark-to-market cash." }, "futures_basis": { "type": "array", "items": { "type": "number" }, "description": "The futures basis as cash (a long pays, a short receives), the perpetual's funding and the margin funding included." }, "margin_balance": { "type": "array", "items": { "type": "number" }, "description": "Initial margin the treasury must fund: the leg's margin share \u00d7 the gross notional held from this month into the next; zero without futures." }, "futures_notional": { "type": "array", "items": { "type": "number" }, "description": "Gross futures notional held from this month into the next." }, "variation_call": { "type": "array", "items": { "type": "number" }, "description": "The variation call the desk posts this month: max(0, \u2212(futures_mark + futures_basis))." }, "intramonth_call": { "type": "array", "items": { "type": "number" }, "description": "The call met inside the month on the paper's 18-day convention \u2014 a proxy for a typical intramonth move, not the path's own worst point." }, "on_book": { "type": "array", "items": { "type": "number" }, "description": "Agreements on the book after the month's events (count)." }, "stops": { "type": "array", "items": { "type": "number" }, "description": "Agreements that stopped this month (count); the sale cash lands later." }, "early_completions": { "type": "array", "items": { "type": "number" }, "description": "Agreements that completed early this month (count)." }, "spot": { "type": "array", "items": { "type": "number" }, "description": "The path's mark for the month." }, "mark_paper": { "type": "array", "items": { "type": "number" }, "description": "The mark: fair value at the purchase yield of every Agreement on the book, plus the discounted sale proceeds of stops in transit." }, "option_mark": { "type": "array", "items": { "type": "number" }, "description": "The outstanding options' value at month end: every option position open after the month's settlements, at its Black-Scholes remaining-life value on the surface at the month's spot (the premium's own pricing: the pricing rate, the surface's vol at the remaining tenor, the skew as at inception), a written option negative. Zero without options; a position still open at the run's last month stays in it (the same number the overlay counts as cash at the horizon); the cross-book collar's covered call is the free coin's and is not marked here (audit 2026-09-06, finding 3)." } } }, "AttributionBand": { "type": "object", "description": "The month's P&L and where it came from, across the seeds, each bucket a `Band`. Every bucket is a sum over Agreements of a per-Agreement formula at the purchase yield y; the formulas are on the fields and in `notes`.", "required": [ "total_pnl", "carry", "price", "stops", "early_completion", "hedge_mark", "hedge_settlement", "basis", "option_value", "residual" ], "properties": { "total_pnl": { "$ref": "#/components/schemas/Band", "description": "`cash + \u0394mark_paper + \u0394option_mark + hedge_cash`, with `cash = paper_in \u2212 paper_out` and `hedge_cash = hedge_premium + hedge_settlement + futures_mark + futures_basis`. Equals the sum of the nine buckets, every month, to rounding \u2014 total P&L on marks, not a cash report." }, "carry": { "$ref": "#/components/schemas/Band", "description": "y \u00d7 mark_paper[m\u22121]: the mark rolling forward one month at the purchase yield." }, "price": { "$ref": "#/components/schemas/Band", "description": "The coin-price line: the previous month's book, rolled one month at y, re-priced at this month's spot minus at the previous spot, same ages." }, "stops": { "$ref": "#/components/schemas/Band", "description": "Stops realised against the prior: a stopped Agreement's cash minus its rolled mark; for a survivor the expected stop released." }, "early_completion": { "$ref": "#/components/schemas/Band", "description": "Early completions realised against the prior, the same way." }, "hedge_mark": { "$ref": "#/components/schemas/Band", "description": "The futures mark (futures_mark)." }, "hedge_settlement": { "$ref": "#/components/schemas/Band", "description": "The hedge's cash that no marked position carries: `hedge_premium` (paid or received, execution cost included) plus the settlements that are not an option position's (the variance swap's). An option's own payoff is in `option_value`." }, "basis": { "$ref": "#/components/schemas/Band", "description": "The futures basis as cash (futures_basis)." }, "residual": { "$ref": "#/components/schemas/Band", "description": "What remains: cent rounding, the conviction rule's memory, and at origination the cent difference between the fresh mark and the purchase price." }, "option_value": { "$ref": "#/components/schemas/Band", "description": "The options' value: `option_mark[m] \u2212 option_mark[m\u22121]` plus the settlement cash of the positions closed this month (the payoff at expiry, booked against the mark it replaces \u2014 never counted twice). At inception it offsets the premium in `hedge_settlement` to the execution cost; each month after it is the option's decay and re-pricing; at the run's last month it carries the horizon mark of a position still open." } } }, "AttributionSeries": { "type": "object", "description": "The month's P&L attribution for one seed, each bucket an array indexed by month; the nine buckets sum to `total_pnl` every month.", "required": [ "total_pnl", "carry", "price", "stops", "early_completion", "hedge_mark", "hedge_settlement", "basis", "option_value", "residual" ], "properties": { "total_pnl": { "type": "array", "items": { "type": "number" }, "description": "`cash + \u0394mark_paper + \u0394option_mark + hedge_cash`, with `cash = paper_in \u2212 paper_out` and `hedge_cash = hedge_premium + hedge_settlement + futures_mark + futures_basis`. Equals the sum of the nine buckets, every month, to rounding \u2014 total P&L on marks, not a cash report." }, "carry": { "type": "array", "items": { "type": "number" }, "description": "y \u00d7 mark_paper[m\u22121]: the mark rolling forward one month at the purchase yield." }, "price": { "type": "array", "items": { "type": "number" }, "description": "The coin-price line: the previous month's book, rolled one month at y, re-priced at this month's spot minus at the previous spot, same ages." }, "stops": { "type": "array", "items": { "type": "number" }, "description": "Stops realised against the prior: a stopped Agreement's cash minus its rolled mark; for a survivor the expected stop released." }, "early_completion": { "type": "array", "items": { "type": "number" }, "description": "Early completions realised against the prior, the same way." }, "hedge_mark": { "type": "array", "items": { "type": "number" }, "description": "The futures mark (futures_mark)." }, "hedge_settlement": { "type": "array", "items": { "type": "number" }, "description": "The hedge's cash that no marked position carries: `hedge_premium` (paid or received, execution cost included) plus the settlements that are not an option position's (the variance swap's). An option's own payoff is in `option_value`." }, "basis": { "type": "array", "items": { "type": "number" }, "description": "The futures basis as cash (futures_basis)." }, "residual": { "type": "array", "items": { "type": "number" }, "description": "What remains: cent rounding, the conviction rule's memory, and at origination the cent difference between the fresh mark and the purchase price." }, "option_value": { "type": "array", "items": { "type": "number" }, "description": "The options' value: `option_mark[m] \u2212 option_mark[m\u22121]` plus the settlement cash of the positions closed this month (the payoff at expiry, booked against the mark it replaces \u2014 never counted twice). At inception it offsets the premium in `hedge_settlement` to the execution cost; each month after it is the option's decay and re-pricing; at the run's last month it carries the horizon mark of a position still open." } } }, "SeedSeries": { "type": "object", "description": "One seed's full matrix.", "required": [ "seed", "book", "attribution", "hedged_irr", "unhedged_irr", "par_usd", "btc_book", "coin_holding", "coin" ], "properties": { "seed": { "type": "integer" }, "book": { "$ref": "#/components/schemas/BookSeries" }, "attribution": { "$ref": "#/components/schemas/AttributionSeries" }, "hedged_irr": { "type": [ "number", "null" ], "description": "The seed's lifetime hedged IRR, effective annual; null when the combined flows have no IRR." }, "unhedged_irr": { "type": [ "number", "null" ] }, "par_usd": { "type": "number", "description": "\u03a3 purchase prices on this seed." }, "btc_book": { "$ref": "#/components/schemas/BtcBook" }, "coin_holding": { "$ref": "#/components/schemas/CoinHoldingOutcome" }, "coin": { "$ref": "#/components/schemas/Outcome" }, "coin_cohorts": { "type": "array", "items": { "$ref": "#/components/schemas/CoinCohort" }, "description": "Unhedged cohorts; on Research only when an unhedged detailed path is requested. On Monthly, the selected path's unhedged reference." } } }, "Lifetime": { "type": "object", "description": "The lifetime figures from the same run \u2014 the hedge overlay's four distributions on the same seeds, for a page's reconciliation.", "required": [ "unhedged", "hedged", "unhedged_coin", "hedged_coin" ], "properties": { "unhedged": { "$ref": "#/components/schemas/Dist" }, "hedged": { "$ref": "#/components/schemas/Dist" }, "unhedged_coin": { "$ref": "#/components/schemas/Dist", "description": "Coin seat." }, "hedged_coin": { "$ref": "#/components/schemas/Dist", "description": "Coin seat." } } }, "MarginBuffer": { "type": "object", "description": "The margin buffer the treasury sizes, across the seeds, as shares of each seed's par (\u03a3 purchase prices). Zero without futures.", "required": [ "p95_worst_call_of_par", "p99_worst_call_of_par", "p95_worst_cumulative_of_par", "months_to_worst_median" ], "properties": { "p95_worst_call_of_par": { "type": "number", "description": "The worst single month's variation call, 95th percentile over seeds." }, "p99_worst_call_of_par": { "type": "number", "description": "The same at the 99th percentile (interpolated between the top seeds; run more seeds for a tail that means more)." }, "p95_worst_cumulative_of_par": { "type": "number", "description": "The deepest point of \u03a3 (futures_mark + futures_basis) from the start \u2014 the buffer that would have covered every call so far \u2014 95th percentile over seeds." }, "months_to_worst_median": { "type": "number", "description": "The month of the worst single call, median over seeds." } } }, "DeltaSeries": { "type": "object", "description": "The delta the desk sizes on, for the median seed, month by month: three readings of one book, stated so the desk picks one.", "required": [ "month", "proxy_delta_coins", "coin_delta_coins", "coin_delta_surface_vol", "greeks_delta_coins_quarterly", "note", "price_exposed_agreements" ], "properties": { "month": { "type": "array", "items": { "type": "integer" } }, "proxy_delta_coins": { "type": "array", "items": { "type": "number" }, "description": "The dollar seat's delta the perpetual hedge and DollarDelta legs use: the embedded put ladder's \u2212\u0394, stop-mass weighted, summed over the book. Positive; about 0.2\u20130.35 coins per Agreement at signing, melting to zero." }, "coin_delta_coins": { "type": "array", "items": { "type": "number" }, "description": "Lifecycle-aware Coin sensitivity: performing Agreements use the continuation surface; stopped collateral uses its known paid count, refund waterfall and residual sale/receipt timing. Signed delta can be negative, zero or positive; a final-payment stop may remain exposed after contractual maturity." }, "coin_delta_surface_vol": { "type": "number", "description": "The coin delta surface's vol (annual)." }, "greeks_delta_coins_quarterly": { "type": [ "array", "null" ], "items": { "type": "array", "prefixItems": [ { "type": "integer" }, { "type": "number" } ], "minItems": 2, "maxItems": 2 }, "description": "`[month, delta in coins]` pairs at months 0, 3, 6, \u2026: the ensemble delta by bump-and-revalue (8 seeds). Only with `include_greeks`; null otherwise." }, "note": { "type": "string" }, "price_exposed_agreements": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Agreements still price exposed at each month; same population used by total delta, including stopped collateral awaiting sale." } } }, "HedgeSeries": { "type": "object", "description": "The months of a hedged sleeve (Phase 4a).", "required": [ "spec", "exec_cost_bps", "seeds", "horizon", "agreements", "par_mean_usd", "purchase_yield_monthly", "purchase_yield_annual", "schedule_yield_annual", "yield_unavailable", "book", "attribution", "median_seed", "lifetime", "buffer", "delta_series", "notes", "valuation_seed", "objective", "selection", "btc_book" ], "properties": { "spec": { "$ref": "#/components/schemas/HedgeSpec", "description": "The structure run, as it ran (a `margin_funding_rate` from the request is written into every futures leg)." }, "exec_cost_bps": { "type": "number" }, "seeds": { "type": "integer", "description": "Seeds run, from the config's seed upward." }, "horizon": { "type": "integer", "description": "Months simulated; every series has `horizon + 1` entries." }, "agreements": { "type": "integer", "description": "Agreements in the book." }, "par_mean_usd": { "type": "number", "description": "Mean over seeds of \u03a3 purchase prices \u2014 the par the desk scales by." }, "purchase_yield_monthly": { "type": [ "number", "null" ], "description": "The purchase yield y, monthly: the rate at which a fresh Agreement's expected flows on a flat path at its entry price (the config's own hazard, early-completion and stop rules) equal its purchase price \u2014 so a new origination enters at cost. Null when no yield brackets \u2014 a Holder with no receipts, every payment assigned to origination (model audit 2026-09-06, M10) \u2014 with the reason in yield_unavailable; the mark is then the undiscounted expected receipts (y = 0) and every cash and loss line still reads." }, "purchase_yield_annual": { "type": [ "number", "null" ], "description": "(1 + y)^12 \u2212 1; null with purchase_yield_monthly." }, "schedule_yield_annual": { "type": [ "number", "null" ], "description": "The completing Agreement's yield on a flat path (no stops, no early completions), effective annual \u2014 the schedule's own rate, for reference; equals the purchase yield on a riskless config. On the base config the purchase yield sits above it: at par a stop sells a coin worth most of the remaining schedule at once. Null when the schedule's own net payments do not bracket the price." }, "yield_unavailable": { "type": [ "string", "null" ], "description": "Why the purchase yield is unavailable, when it is; null when a yield was found." }, "book": { "$ref": "#/components/schemas/BookBand" }, "attribution": { "$ref": "#/components/schemas/AttributionBand" }, "median_seed": { "$ref": "#/components/schemas/SeedSeries", "description": "Full selected path; selection.metric identifies the rank or explicit requested seed. Coin defaults to lower-median economic BTC surplus; Dollar retains USD IRR (or USD multiple fallback). Pointwise bands are not this path." }, "lifetime": { "$ref": "#/components/schemas/Lifetime" }, "buffer": { "$ref": "#/components/schemas/MarginBuffer" }, "delta_series": { "$ref": "#/components/schemas/DeltaSeries", "description": "The delta series of the median seed." }, "notes": { "type": "string", "description": "The conventions: the mark at the purchase yield, every open option marked monthly at its remaining-life value (`option_mark`, its change in `option_value`), futures cash-settled monthly, every bucket's formula and the identity total = cash + \u0394mark_paper + \u0394option_mark + hedge_cash." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "The surface's arbitrage violations, each naming the tenor, the strikes and the prices, when the request set `allow_arbitrage_warning` and the surface carried any (model audit 2026-09-06, M06). Absent when there are none." }, "surface_note": { "type": "string", "description": "The surface's quoted moneyness range and wing rule, spelled out (`VolSurface::wing_note`; model audit 2026-09-07, R01): every option priced beyond the quoted range is priced by the wing convention, not a quote. On every result priced on a surface." }, "valuation_seed": { "type": "integer", "minimum": 0 }, "objective": { "type": "string", "enum": [ "dollar", "coin" ], "default": "dollar" }, "selection": { "$ref": "#/components/schemas/PathSelection" }, "btc_book": { "$ref": "#/components/schemas/BtcBookBand" } } }, "HedgeSeriesRequest": { "type": "object", "required": [ "config" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null, "description": "The surface every option leg is priced on; null = the stylised preset." }, "structure": { "oneOf": [ { "$ref": "#/components/schemas/HedgeSpec" }, { "type": "null" } ], "default": null, "description": "ONE structure, in the hedge overlay's shapes; null = the loss-line ladder preset (quarterly puts at the loss line, re-bought at each expiry, Table D1)." }, "seeds": { "type": "integer", "minimum": 1, "maximum": 64, "default": 16, "description": "Seeds run, from the config's seed upward; every seed keeps its whole monthly matrix until the bands are drawn." }, "option_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0, "description": "The rate every option leg is priced at (Black-Scholes), annual continuously compounded; 0 = the surface's own quoting convention." }, "put_skew_points": { "type": "number", "minimum": 0, "maximum": 50, "default": 0, "description": "Vol points ADDED to the surface's vol when a put is priced." }, "exec_cost_bps": { "type": "number", "minimum": 0, "maximum": 1000, "default": 50, "description": "Execution cost in basis points of premium on every option leg traded." }, "include_greeks": { "type": "boolean", "default": false, "description": "Also compute the ensemble delta (bump-and-revalue, 8 seeds) at every third month of the median seed \u2014 `delta_series.greeks_delta_coins_quarterly`. Costly: counts \u2308(cohorts + term)/3\u2309 \u00d7 (8 seeds \u00d7 7 runs + 1) runs of the whole book against the cap, once (on the median seed, not per seed)." }, "margin_funding_rate": { "type": [ "number", "null" ], "minimum": -1, "maximum": 1, "default": null, "description": "Annual rate charged monthly on the initial margin every futures leg holds. Given, it replaces the rate on EVERY futures leg of the structure; null = each leg's own rule. Ignored by a structure without a futures leg." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "valuation_seed": { "type": [ "integer", "null" ], "minimum": 0, "description": "Fixed estimation seed, independent of realized path seeds. Omitted or null uses config.seed." }, "objective": { "type": "string", "enum": [ "dollar", "coin" ], "default": "dollar" }, "selected_seed": { "type": [ "integer", "null" ], "minimum": 0, "description": "Choose a full path from the requested seed range; otherwise objective chooses the representative path." } } }, "RebalancePoliciesRequest": { "type": "object", "required": [ "config", "policies" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null, "description": "null = the stylised preset." }, "structure": { "oneOf": [ { "$ref": "#/components/schemas/HedgeSpec" }, { "type": "null" } ], "default": null, "description": "A `Legs` structure with at least one futures leg (the policy is a futures leg's); null = the coin seat's listed futures at 80% of the coin delta (Table 7c)." }, "seeds": { "type": "integer", "minimum": 1, "maximum": 256, "default": 16, "description": "Seeds per policy, from the config's seed upward." }, "exec_cost_bps": { "type": "number", "minimum": 0, "maximum": 1000, "default": 50, "description": "Execution cost in basis points of premium on every option leg in the structure \u2014 the same figure the hedge desk and the series take, so the table is net of the same cost as the run it sits under; a futures leg carries none. Zero by convention until the follow-up audit of 2026-09-06." }, "option_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0 }, "put_skew_points": { "type": "number", "minimum": 0, "maximum": 50, "default": 0 }, "policies": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "$ref": "#/components/schemas/Rebalance" }, "description": "Put `{\"Calendar\": {\"months\": 1}}` among them to have the monthly reference on the table." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "valuation_seed": { "type": [ "integer", "null" ], "minimum": 0, "description": "Fixed estimation seed, independent of realized path seeds. Omitted or null uses config.seed." } } }, "RebalanceRow": { "type": "object", "description": "One policy of the comparison.", "required": [ "policy", "result", "turnover_coins", "trades_count", "trading_cost_usd" ], "properties": { "policy": { "$ref": "#/components/schemas/Rebalance", "description": "Always written in the tagged form." }, "result": { "$ref": "#/components/schemas/HedgeResult", "description": "The hedge overlay of the structure under this policy at the request's `exec_cost_bps`; its `spec` carries the policy on every futures leg." }, "turnover_coins": { "type": "number", "description": "`result.futures_turnover_coins_mean`, beside the policy." }, "trades_count": { "type": "number", "description": "`result.futures_trades_mean`." }, "trading_cost_usd": { "type": "number", "description": "`result.futures_trading_cost_mean_usd`: the futures trading cost the policy's trades were charged (every futures leg's futures_cost_bps on the turnover at the month's spot), dollars per run, mean over seeds \u2014 zero unless a leg sets a cost." } } }, "RebalancePoliciesResponse": { "type": "object", "required": [ "structure", "seeds", "exec_cost_bps", "rows", "notes", "surface_note" ], "properties": { "structure": { "$ref": "#/components/schemas/HedgeSpec", "description": "The structure the policies were set on, as sent (its own rule intact)." }, "seeds": { "type": "integer" }, "exec_cost_bps": { "type": "number", "description": "The execution cost every row was priced at (each row's `result.exec_cost_bps` repeats it); the notes say it too." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/RebalanceRow" }, "description": "One row per policy, in request order." }, "notes": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "The surface's arbitrage violations, each naming the tenor, the strikes and the prices, when the request set `allow_arbitrage_warning` and the surface carried any (model audit 2026-09-06, M06). Absent when there are none." }, "surface_note": { "type": "string", "description": "The surface's quoted moneyness range and wing rule, spelled out (`VolSurface::wing_note`; model audit 2026-09-07, R01): every option priced beyond the quoted range is priced by the wing convention, not a quote. On every result priced on a surface." } } }, "NoIrr": { "type": "string", "enum": [ "single_signed", "no_root_in_range", "non_finite", "numerical" ], "description": "Why a path has no IRR (audit 2026-09-05, finding 1): `single_signed` \u2014 every flow has the same sign (zero receipts against a purchase is this), no rate makes the NPV zero; `no_root_in_range` \u2014 the flows change sign but no root lies in the solver's range, (\u221295%, +500%) a month; `non_finite` \u2014 the solver returned a root that is not a finite number. A path without an IRR is still a path: its multiple and its cash loss are counted, never dropped from the denominator. `numerical`: the NPV could not be evaluated as a finite number or a bracketed root failed the residual check (model audit 2026-09-06, M02) \u2014 never reported as a rate." }, "NoIrrCounts": { "type": "object", "description": "Paths without an IRR, counted by reason (`NoIrr`).", "required": [ "single_signed", "no_root_in_range", "non_finite", "numerical" ], "properties": { "single_signed": { "type": "integer" }, "no_root_in_range": { "type": "integer" }, "non_finite": { "type": "integer" }, "numerical": { "type": "integer", "description": "The evaluation failed (`NoIrr::numerical`, model audit 2026-09-06, M02)." } } }, "SurfaceDomain": { "type": "object", "required": [ "min_multiple", "max_multiple", "nodes_added_on_demand" ], "description": "How far a coin delta surface reached over a run (model audit 2026-09-06, M05): its built grid \u2014 price multiples of the strike from 0.1\u00d7 to 10\u00d7, log-spaced \u2014 plus every column of nodes added on demand when a path read beyond it (at 1.5\u00d7 steps, the same 256 continuation paths per node, cached), never a clamp.", "properties": { "min_multiple": { "type": "number", "description": "The lowest price multiple of the strike the surface holds a node at (0.1 unless a path went lower)." }, "max_multiple": { "type": "number", "description": "The highest price multiple of the strike the surface holds a node at (10 unless a path went higher)." }, "nodes_added_on_demand": { "type": "integer", "minimum": 0, "description": "Nodes built on demand for reads beyond the 0.1\u201310\u00d7 grid \u2014 one column of nodes (every grid age) per 1.5\u00d7 step reached; 0 when every read stayed inside the grid." } } }, "HedgeResearchRequest": { "type": "object", "additionalProperties": false, "required": [ "config", "structures" ], "properties": { "config": { "$ref": "#/components/schemas/SimConfig" }, "structures": { "type": "array", "minItems": 0, "maxItems": 8, "items": { "$ref": "#/components/schemas/HedgeSpec" }, "description": "0\u20138 Agreement-book hedge structures. The unhedged baseline is always included; an empty array requests only its samples." }, "seeds": { "type": "integer", "minimum": 1, "maximum": 32, "default": 32, "description": "Consecutive seeds, 1\u201332 per bounded batch. Join raw samples across disjoint batches using identical inputs and engine identity. No wrapping seed ranges." }, "surface": { "oneOf": [ { "$ref": "#/components/schemas/VolSurface" }, { "type": "null" } ], "default": null, "description": "The surface every option leg is priced on; null = the stylised preset." }, "allow_arbitrage_warning": { "type": "boolean", "default": false, "description": "Accept a surface whose call prices are inconsistent in price space at the request's rate \u2014 rising with the strike, concave in the strike, outside their bounds, or falling with the tenor (model audit 2026-09-06, M06) \u2014 and carry the violations as `warnings` on the response. Default false: such a surface is refused with a 400 naming the tenor, the strikes and the prices." }, "option_rate": { "type": "number", "minimum": -1, "maximum": 1, "default": 0, "description": "The rate every option leg is priced at (Black-Scholes), annual continuously compounded; 0 = the surface's own quoting convention. The risk paper prices at 0.045." }, "put_skew_points": { "type": "number", "minimum": -100, "maximum": 100, "default": 0, "description": "Vol points ADDED to the surface's vol when a put is priced (5 = a 40% surface prices puts at 45%); calls read the surface as it is. The risk paper's setting is 5." }, "exec_cost_bps": { "type": "number", "minimum": 0, "maximum": 1000, "default": 50, "description": "Execution cost in basis points of premium on every option leg traded; none on perpetuals." }, "discount_rate_annual": { "type": "number", "minimum": -0.99, "maximum": 1, "default": 0, "description": "Effective annual USD NPV discount rate. Zero gives undiscounted net gain." }, "include_monthly": { "type": "boolean", "default": false, "description": "Include actual monthly cash arrays; limits the batch to 8 seeds." }, "valuation_seed": { "type": "integer", "minimum": 0, "default": 42, "description": "Random seed for estimating the coin-delta trading rule. Hold fixed across all batches, stress runs and separate realized-seed checks. Independent of config.seed." }, "objective": { "type": "string", "enum": [ "dollar", "coin" ], "default": "dollar", "description": "Reporting objective only; does not change raw USD/BTC economics, paths or trading rules. Omitted legacy requests use dollar. State the chosen objective before comparing which strategy is better." } } }, "ResearchIrr": { "type": "object", "required": [ "irr", "no_irr", "multiple", "irr_ambiguous", "irr_root_count" ], "properties": { "irr": { "type": [ "number", "null" ] }, "no_irr": { "type": [ "string", "null" ] }, "multiple": { "type": [ "number", "null" ] }, "irr_ambiguous": { "type": "boolean" }, "irr_root_count": { "type": "integer" } } }, "ResearchMonthly": { "type": "object", "required": [ "paper_cash", "hedge_cash", "margin", "hedge_cash_required", "total_cash_required", "spot", "btc_book" ], "properties": { "paper_cash": { "type": "array", "items": { "type": "number" } }, "hedge_cash": { "type": "array", "items": { "type": "number" } }, "margin": { "type": "array", "items": { "type": "number" } }, "hedge_cash_required": { "type": "array", "items": { "type": "number" } }, "total_cash_required": { "type": "array", "items": { "type": "number" } }, "spot": { "type": "array", "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "Simulated BTC/USD spot by month, matching every replay cash array. Add horizon_mark_usd to the final realized net flow to reconcile economic BTC outcomes." }, "btc_book": { "$ref": "#/components/schemas/BtcBook" } } }, "ResearchOutcome": { "type": "object", "required": [ "usd", "coin", "net_gain_usd", "net_gain_coins", "npv_usd", "peak_hedge_cash_usd", "peak_total_cash_usd", "horizon_mark_usd", "coin_holding" ], "properties": { "usd": { "$ref": "#/components/schemas/ResearchIrr" }, "coin": { "$ref": "#/components/schemas/ResearchIrr" }, "net_gain_usd": { "type": "number" }, "net_gain_coins": { "type": "number" }, "npv_usd": { "type": "number" }, "peak_hedge_cash_usd": { "type": "number" }, "peak_total_cash_usd": { "type": "number" }, "horizon_mark_usd": { "type": "number" }, "monthly": { "$ref": "#/components/schemas/ResearchMonthly" }, "coin_holding": { "$ref": "#/components/schemas/CoinHoldingOutcome" }, "coin_cohorts": { "type": "array", "items": { "$ref": "#/components/schemas/CoinCohort" }, "description": "Unhedged cohorts; on Research only when an unhedged detailed path is requested. On Monthly, the selected path's unhedged reference." } } }, "ResearchSeed": { "type": "object", "required": [ "seed", "unhedged", "strategies", "terminal_spot", "deployed_usd", "peak_paper_capital_at_risk_usd", "peak_schedule_shortfall_usd" ], "properties": { "seed": { "type": "integer", "minimum": 0 }, "terminal_spot": { "type": "number" }, "deployed_usd": { "type": "number" }, "peak_paper_capital_at_risk_usd": { "type": "number" }, "peak_schedule_shortfall_usd": { "type": "number" }, "unhedged": { "$ref": "#/components/schemas/ResearchOutcome" }, "strategies": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchOutcome" } } } }, "ResearchBatch": { "type": "object", "required": [ "schema", "horizon_months", "discount_rate_annual", "samples", "notes", "objective", "conventions", "valuation_seed" ], "properties": { "schema": { "type": "integer", "const": 1 }, "horizon_months": { "type": "integer" }, "discount_rate_annual": { "type": "number" }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchSeed" } }, "notes": { "type": "string" }, "objective": { "type": "string", "enum": [ "dollar", "coin" ], "default": "dollar", "description": "Reporting objective only; does not change raw USD/BTC economics, paths or trading rules. Omitted legacy requests use dollar. State the chosen objective before comparing which strategy is better." }, "conventions": { "$ref": "#/components/schemas/ResearchConventions" }, "valuation_seed": { "type": "integer", "minimum": 0, "description": "Fixed valuation seed used by hedge sizing, separate from the realized path sample seeds." } } }, "HedgeResearchResponse": { "type": "object", "required": [ "schema", "horizon_months", "discount_rate_annual", "samples", "notes", "surface_note", "objective", "conventions", "valuation_seed" ], "properties": { "schema": { "type": "integer", "const": 1 }, "horizon_months": { "type": "integer" }, "discount_rate_annual": { "type": "number" }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchSeed" } }, "notes": { "type": "string" }, "surface_note": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "objective": { "type": "string", "enum": [ "dollar", "coin" ], "default": "dollar", "description": "Reporting objective only; does not change raw USD/BTC economics, paths or trading rules. Omitted legacy requests use dollar. State the chosen objective before comparing which strategy is better." }, "conventions": { "$ref": "#/components/schemas/ResearchConventions" }, "valuation_seed": { "type": "integer", "minimum": 0, "description": "Fixed valuation seed used by hedge sizing, separate from the realized path sample seeds." } } }, "ResearchConventions": { "type": "object", "required": [ "version", "coin_conversion", "coin_benchmark", "coin_capital_basis", "coin_mark_treatment", "usd_cash_screen", "coin_loss", "coin_discounting" ], "properties": { "version": { "type": "integer", "const": 2 }, "coin_conversion": { "type": "string", "const": "agreement_purchases_at_actual_entry_price; USD_receipts_and_hedge_flows_at_monthly_spot" }, "coin_benchmark": { "type": "string", "const": "hold_matching_dated_net_contributions" }, "coin_capital_basis": { "type": "string" }, "coin_mark_treatment": { "type": "string" }, "usd_cash_screen": { "type": "string" }, "coin_loss": { "type": "string" }, "coin_discounting": { "type": "string" } } }, "CoinHoldingOutcome": { "type": "object", "required": [ "contributed_coins", "recovered_coins", "holding_benchmark_coins", "surplus_coins", "realized_cash_contributed_coins", "realized_cash_recovered_coins", "horizon_mark_coins", "paper_purchase_coins", "paper_receipt_coins", "economic_recovery_multiple", "economic_total_return", "realized_cash_recovery_multiple", "realized_cash_total_return", "agreement_notional_coins", "paper_receipt_offset_coins" ], "properties": { "contributed_coins": { "type": "number", "description": "Negative net monthly economic BTC flows made positive. Purchases funded at actual Agreement entry; USD receipts and hedges at monthly spot. Includes negative horizon marks; excludes a starting wallet and reserves.", "minimum": 0 }, "recovered_coins": { "type": "number", "description": "Positive net monthly economic BTC flows, including signed remaining derivative value once. Economic recovery is not all settled cash.", "minimum": 0 }, "holding_benchmark_coins": { "type": "number", "description": "BTC retained by holding the same dated contributions as this strategy; equals contributed_coins. Contributions are strategy-specific, not a common initial budget.", "minimum": 0 }, "surplus_coins": { "type": "number", "description": "recovered_coins minus holding_benchmark_coins, to floating-point tolerance; exactly the existing net_gain_coins calculation. No BTC discounting." }, "realized_cash_contributed_coins": { "type": "number", "description": "Negative net monthly realized BTC flows made positive; purchase funding at actual entry, receipts and hedges at monthly spot; no remaining derivative mark.", "minimum": 0 }, "realized_cash_recovered_coins": { "type": "number", "description": "Positive net monthly realized BTC flows; purchase funding at actual entry, receipts and hedges at monthly spot; no remaining derivative mark.", "minimum": 0 }, "horizon_mark_coins": { "type": "number", "description": "Signed surviving derivative horizon mark divided by horizon spot; excluded from realized cash fields." }, "paper_purchase_coins": { "type": "number", "description": "Gross BTC purchase funding: each Agreement USD acquisition cost divided by its own entry strike. Exactly one BTC per Agreement at par, including with entry-price dispersion." }, "paper_receipt_coins": { "type": "number", "description": "Fee-net Holder USD receipts divided by each reporting month's spot; gross before monthly offsets." }, "economic_recovery_multiple": { "type": [ "number", "null" ], "description": "Net recovery/contribution ratio or lifetime gain/contribution; null when the denominator is zero or the ratio cannot be represented. Not annualized. Legacy coin.multiple retains its gross Agreement purchase denominator." }, "economic_total_return": { "type": [ "number", "null" ], "description": "Net recovery/contribution ratio or lifetime gain/contribution; null when the denominator is zero or the ratio cannot be represented. Not annualized. Legacy coin.multiple retains its gross Agreement purchase denominator." }, "realized_cash_recovery_multiple": { "type": [ "number", "null" ], "description": "Net recovery/contribution ratio or lifetime gain/contribution; null when the denominator is zero or the ratio cannot be represented. Not annualized. Legacy coin.multiple retains its gross Agreement purchase denominator." }, "realized_cash_total_return": { "type": [ "number", "null" ], "description": "Net recovery/contribution ratio or lifetime gain/contribution; null when the denominator is zero or the ratio cannot be represented. Not annualized. Legacy coin.multiple retains its gross Agreement purchase denominator." }, "agreement_notional_coins": { "type": "number", "minimum": 0, "description": "Actual originated Agreements times one contractual BTC per Agreement." }, "paper_receipt_offset_coins": { "type": "number", "minimum": 0, "description": "Sum of same-month min(Agreement BTC purchases, fee-net BTC-equivalent receipts), before hedge cash. Shows receipt recycling into Agreement purchases only." } } }, "SimulateResearch": { "type": "object", "required": [ "outcome", "conventions" ], "description": "One unhedged observation using the same research math as hedge_research. The outcome always includes monthly arrays and spot. No derivative is applied and npv_usd uses zero USD discounting. BTC holding uses matching dated net contributions; it is not a funded wallet simulation.", "properties": { "outcome": { "$ref": "#/components/schemas/ResearchOutcome" }, "conventions": { "$ref": "#/components/schemas/ResearchConventions" } } }, "PathSelection": { "type": "object", "required": [ "metric", "seed" ], "properties": { "metric": { "type": "string", "enum": [ "usd_irr", "usd_multiple", "economic_btc_gain", "requested_seed" ] }, "seed": { "type": "integer", "minimum": 0 } } }, "BtcBook": { "type": "object", "required": [ "conversion_spot_usd_per_btc", "agreement_purchase_btc", "holder_receipt_btc", "option_premium_paid_btc", "option_premium_received_btc", "hedge_settlement_btc", "futures_realized_pnl_btc", "hedge_carry_and_cost_btc", "net_realized_cash_btc", "net_contribution_btc", "net_recovery_btc", "open_derivative_value_btc", "agreement_value_btc" ], "properties": { "conversion_spot_usd_per_btc": { "type": "array", "items": { "type": "number" }, "description": "Monthly reporting spot for USD receipts, hedge cash and marks; Agreement purchases use each Agreement's actual entry price." }, "agreement_purchase_btc": { "type": "array", "items": { "type": "number" }, "description": "BTC purchase funding at each Agreement's own entry price, exactly one BTC at par. Does not use the monthly conversion spot." }, "holder_receipt_btc": { "type": "array", "items": { "type": "number" } }, "option_premium_paid_btc": { "type": "array", "items": { "type": "number" } }, "option_premium_received_btc": { "type": "array", "items": { "type": "number" } }, "hedge_settlement_btc": { "type": "array", "items": { "type": "number" } }, "futures_realized_pnl_btc": { "type": "array", "items": { "type": "number" } }, "hedge_carry_and_cost_btc": { "type": "array", "items": { "type": "number" } }, "net_realized_cash_btc": { "type": "array", "items": { "type": "number" } }, "net_contribution_btc": { "type": "array", "items": { "type": "number" } }, "net_recovery_btc": { "type": "array", "items": { "type": "number" } }, "open_derivative_value_btc": { "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "End-of-period stock; null when the endpoint did not compute the monthly valuation series." }, "agreement_value_btc": { "oneOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "End-of-period stock; null when the endpoint did not compute the monthly valuation series." } }, "description": "Native monthly BTC-equivalent cash components converted at each month spot before aggregation. Purchases and raw premiums are positive magnitudes; settlements and carry/cost signed. Holder receipts already net servicing fees. net_realized_cash = receipts - purchases - premium paid + premium received + non-futures settlement + futures P&L + carry/cost. Contribution/recovery split occurs monthly. Asset marks are separate stocks, not cash or a funded wallet." }, "BtcBookBand": { "type": "object", "required": [ "conversion_spot_usd_per_btc", "agreement_purchase_btc", "holder_receipt_btc", "option_premium_paid_btc", "option_premium_received_btc", "hedge_settlement_btc", "futures_realized_pnl_btc", "hedge_carry_and_cost_btc", "net_realized_cash_btc", "net_contribution_btc", "net_recovery_btc", "open_derivative_value_btc", "agreement_value_btc" ], "properties": { "conversion_spot_usd_per_btc": { "$ref": "#/components/schemas/Band", "description": "Monthly reporting spot for USD receipts, hedge cash and marks; Agreement purchases use each Agreement's actual entry price." }, "agreement_purchase_btc": { "$ref": "#/components/schemas/Band", "description": "BTC purchase funding at each Agreement's own entry price, exactly one BTC at par. Does not use the monthly conversion spot." }, "holder_receipt_btc": { "$ref": "#/components/schemas/Band" }, "option_premium_paid_btc": { "$ref": "#/components/schemas/Band" }, "option_premium_received_btc": { "$ref": "#/components/schemas/Band" }, "hedge_settlement_btc": { "$ref": "#/components/schemas/Band" }, "futures_realized_pnl_btc": { "$ref": "#/components/schemas/Band" }, "hedge_carry_and_cost_btc": { "$ref": "#/components/schemas/Band" }, "net_realized_cash_btc": { "$ref": "#/components/schemas/Band" }, "net_contribution_btc": { "$ref": "#/components/schemas/Band" }, "net_recovery_btc": { "$ref": "#/components/schemas/Band" }, "open_derivative_value_btc": { "oneOf": [ { "$ref": "#/components/schemas/Band" }, { "type": "null" } ], "description": "End-of-period stock; null when the endpoint did not compute the monthly valuation series." }, "agreement_value_btc": { "oneOf": [ { "$ref": "#/components/schemas/Band" }, { "type": "null" } ], "description": "End-of-period stock; null when the endpoint did not compute the monthly valuation series." } }, "description": "Native monthly BTC-equivalent cash components converted at each month spot before aggregation. Purchases and raw premiums are positive magnitudes; settlements and carry/cost signed. Holder receipts already net servicing fees. net_realized_cash = receipts - purchases - premium paid + premium received + non-futures settlement + futures P&L + carry/cost. Contribution/recovery split occurs monthly. Asset marks are separate stocks, not cash or a funded wallet." }, "CoinCohort": { "type": "object", "required": [ "origination_month", "agreement_count", "agreement_notional_coins", "paper_purchase_coins", "paper_receipt_coins", "surplus_coins", "coin" ], "description": "Unhedged Agreement cohort on a detailed path. Shared hedge costs are not allocated. Gross purchases, receipts and gain are additive; cohort IRRs and net-capital ratios are not.", "properties": { "origination_month": { "type": "integer" }, "agreement_count": { "type": "integer" }, "agreement_notional_coins": { "type": "number" }, "paper_purchase_coins": { "type": "number" }, "paper_receipt_coins": { "type": "number" }, "surplus_coins": { "type": "number" }, "coin": { "$ref": "#/components/schemas/Outcome" } } } }, "examples": { "BaseConfig": { "summary": "The September program at par \u2014 the cockpit's BASE_CONFIG", "description": "A $60,000 coin, 1.475\u00d7, 60 monthly payments of $1,475, payment 1 to BTC Now, 5% of every delivered dollar, the Holder buys at par; 24 monthly cohorts of 10 on a 43% bridge back to $60,000 with the 40% lifetime stop share, seed 42. Returns `irr_effective_pa` \u2248 0.142 on `/simulate`.", "value": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 } } } }, "paths": { "/health": { "get": { "tags": [ "health" ], "summary": "Liveness", "description": "Plain-text `OK`. Open in both modes; a deploy check should call it.", "operationId": "health", "security": [], "responses": { "200": { "description": "Alive.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "text/plain": { "schema": { "type": "string", "const": "OK" } } } } } } }, "/api/forwardflow/health": { "get": { "tags": [ "health" ], "summary": "Engine health and access mode", "description": "Open in both modes. Tells a client whether the engine is keyed before it sends a key.", "operationId": "ffHealth", "security": [], "responses": { "200": { "description": "The engine's spec, version, build and mode.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok", "engine_spec": "v1.14", "version": "0.2.0", "build": "0.2.0+v1.14", "mode": "keyed" } } } } } } }, "/api/forwardflow/openapi.json": { "get": { "tags": [ "health" ], "summary": "This document", "description": "Served verbatim from the build (`backend/openapi/openapi.json`, compiled in). Open in both modes.", "operationId": "openapi", "security": [], "responses": { "200": { "description": "The OpenAPI 3.1 document.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/forwardflow/simulate": { "post": { "tags": [ "run" ], "summary": "One seeded run", "description": "One run of the engine on one seeded path: the Holder's outputs, the per-Agreement table, the price path, the stop hazard by age and, on request, the ledger. Light at the cockpit's sizes (no permit, a blocking thread, about 0.01 s at the base book); estimated work = book Agreement-runs, heavy-guarded only above 1,000,000 \u2014 under the 50,000 book cap, never. Pass `include_agreements: false` on any run that only reads scalars. Set include_research: true to attach the same unhedged USD/BTC observation used by paired hedge research, including monthly spot and cash, from this one book at zero USD discounting. The extra monthly arrays are included in memory admission. Enabled Agreement rows, research/cohort observations and bounded JSON serialization are included in admission. Raw postings retain their typed representation; response reservations survive serialization and transport. Oversized detailed responses are refused before engine execution where their bound exceeds the limit.", "operationId": "simulate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateRequest" }, "examples": { "base": { "summary": "The base book, scalars only", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "include_agreements": false } }, "oneAgreement": { "summary": "One clean Agreement so the schedule can be read off", "description": "Returns `irr_effective_pa` 0.1397, `owner_total_inflow` \"82673.75\", `btcnow.total_take` \"5826.25\": payments 2\u201360 deliver $1,401.25 to the Holder and $73.75 to BTC Now each.", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0 } }, "rational_default": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0, "cohorts": 1, "agreements_per_cohort": 1, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": false, "seed": 42 }, "include_postings": true } } } } } }, "responses": { "200": { "description": "The run.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateResponse" }, "example": { "outputs": { "irr_monthly": 0.010956, "irr_nominal_pa": 0.13147, "irr_effective_pa": 0.139654410356713, "wal_months": 31.0, "payback_month": 44, "undiscounted_multiple": 1.3778958333333333, "owner_total_inflow": "82673.75", "owner_total_outflow": "60000.00", "coins_per_coin": 1.3778958333333333, "coin_irr_effective_pa": 0.139654410356713, "cash_recovery": [ [ 12, 0.2569 ], [ 24, 0.5372 ], [ 36, 0.8174 ] ], "exit_split": { "completed": 1, "settled": 0, "non_performance": 0, "non_performance_rational": 0, "conviction_walks": 0, "rational_boundary": 0, "open": 0 }, "suppressed_defaults": 0, "coin_returned_to_obligors": "0.00", "total_shortfall_usd": "0.00", "buyer_refunds_usd": "0.00", "stop_surplus_usd": "0.00", "cumulative_net_cash": [ -60000.0, -60000.0, -58598.75 ], "btcnow": { "origination_fees": "1475.00", "flow_fees": "4351.25", "total_take": "5826.25", "purchase_prices": "60000.00", "paper_spread": "0.00" }, "btcnow_fee_monthly": [ 0.0, 1475.0, 73.75 ] }, "agreements": [ { "id": 0, "origination_month": 0, "strike": "60000.00", "term_months": 60, "outcome": "completed", "exit_month": 60, "payments_made": 60, "delivered_gross": "87025.00", "owner_net": "82673.75", "fee_to_btcnow": "4351.25", "origination_to_btcnow": "1475.00", "shortfall_usd": "0.00", "coin_returned_usd": "0.00", "purchase_price": "60000.00", "stop_proceeds_usd": "0.00", "buyer_refund_usd": "0.00", "stop_surplus_usd": "0.00", "expected_net": "82673.75", "capital_pnl": "22673.75" } ], "agreement_count": 1, "path": [ 60000.0, 60000.0, 60000.0 ], "conservation_ok": true, "hazard_monthly": [ 0.0, 0.0, 0.0 ], "postings": [ { "month": 0, "from": "Owner", "to": "BtcNow", "amount": "60000.00", "kind": "PurchasePrice", "agreement": 0 }, { "month": 1, "from": { "Obligor": 0 }, "to": "BtcNow", "amount": "1475.00", "kind": "OriginationFee", "agreement": 0 }, { "month": 2, "from": { "Obligor": 0 }, "to": "Owner", "amount": "1401.25", "kind": "PaymentDelivery", "agreement": 0 }, { "month": 2, "from": { "Obligor": 0 }, "to": "BtcNow", "amount": "73.75", "kind": "FlowFee", "agreement": 0 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" }, "413": { "description": "The response could not be serialized inside its reserved JSON allowance; reduce the book or disable detailed output." } } } }, "/api/forwardflow/solve_price": { "post": { "tags": [ "run" ], "summary": "The purchase price that clears a target IRR", "description": "The inverse of the deal card (input #19), solved directly (audit 2026-09-05, finding 7): the Holder's receipts do not depend on what the Holder paid, so one prepared run on the config's seed gives them and the price as a fraction of the coin's cost is PV(net receipts at the target rate) / PV(the strikes at their origination months); a second run at that price verifies it (`irr_check`). Targets the bracket [1%, 500%] cannot attain come back `attainable: false` with `note` saying why, never as the bracket's edge. Light (two runs of the book; estimated work = book \u00d7 2, heavy-guarded only above 1,000,000 Agreement-runs \u2014 under the 50,000 book cap, never). Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "solvePrice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolvePriceRequest" }, "example": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "target_effective_irr": 0.12 } } } }, "responses": { "200": { "description": "The clearing price. At a 12% hurdle the base book clears at 103.7% of the coin's cost.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolvePriceResponse" }, "example": { "pct_of_strike": "1.03835638", "usd_at_start_price": 62301.3828, "irr_check": 0.12000000467405858, "attainable": true, "note": "the present value of the Holder's net receipts at the target rate (monthly compounding of the effective annual target) over the present value of the strikes at their origination months, from one prepared run; verified by a run at that price", "target_effective_irr": 0.12 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/history": { "get": { "tags": [ "sensitivity" ], "summary": "The embedded monthly price series", "description": "The monthly bars compiled into the engine (no data files at runtime): 174 each, `[2012, 2]` to `[2026, 7]`. Powers `HistoricalReplay` start indices and the backtest.", "operationId": "history", "responses": { "200": { "description": "Months and closes, chronological.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResponse" }, "example": { "months": [ [ 2012, 2 ], [ 2012, 3 ] ], "closes": [ 4.9, 4.89 ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/forwardflow/montecarlo": { "post": { "tags": [ "distribution" ], "summary": "Monte Carlo, summarized", "description": "`runs` seeded runs with seeds `seed \u2026 seed + runs \u2212 1`, in parallel, summarized. **Heavy** (one permit; counts against the caller's concurrency cap): estimated work book \u00d7 runs \u2264 24,000,000 Agreement-runs. Identical requests are memoized in a 64-entry LRU keyed by `runs` plus the config's serialization (key order does not matter), which is sound only because the engine is seeded. The base book at 1,000 runs: about 0.3 s cold, milliseconds memoized. The bridge is endpoint-pinned, so a bridge distribution is the uncertainty between the start and end price, not a view on where the price ends. Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "monteCarlo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonteCarloRequest" }, "example": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "runs": 1000 } } } }, "responses": { "200": { "description": "The summary.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonteCarloSummary" }, "example": { "runs": 1000, "irr_effective": { "worst": 0.0721, "p1": 0.0918, "p3": 0.097, "p5": 0.1029, "p25": 0.1291, "p50": 0.1493, "p75": 0.1722, "p95": 0.219, "mean": 0.1538, "es3": 0.0903, "es5": 0.0946 }, "wal_months": { "worst": 33.1, "p1": 33.9, "p3": 34.2, "p5": 34.48, "p25": 35.3, "p50": 35.91, "p75": 36.5, "p95": 37.34, "mean": 35.9, "es3": 33.8, "es5": 34.0 }, "pct_negative_irr": 0.0, "irr_histogram": [ [ 0.0721, 3 ], [ 0.0777, 2 ] ], "cash_fan": [ { "month": 84, "p5": 2288927.49, "p25": 3500000.0, "p50": 4529348.68, "p75": 6000000.0, "p95": 8948182.21 } ], "base_seed": 42 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/montecarlo/ws": { "get": { "tags": [ "distribution" ], "summary": "Monte Carlo over a websocket, with progress", "description": "The same computation in chunks of 1,000 runs, so a heavy book neither times out nor looks dead. **Upgrade** to a websocket (`ws://` locally, `wss://` hosted).\n\n**Credential.** In keyed mode the upgrade request carries `X-API-Key`, `Authorization: Bearer `, or `?token=` (the only route that accepts the token; see the `WsToken` scheme). The Next.js app mints the token server-side at `GET /api/forwardflow/token` and returns `{token, expires_at, ws_url}` \u2014 the browser learns the engine host only for the socket. 401 is answered on the HTTP upgrade, before any frame.\n\n**Protocol.** The client's first text frame is the `MonteCarloRequest` JSON, exactly the REST body. The server then sends text frames, each a `WsFrame` discriminated by `event`: `Progress` (`done`, `total`, `pct`) after every chunk; `Complete` (`summary`) once, after which the client should close; `Error` (`message`) on a validation failure, an engine 400 or a first frame that is not valid JSON, after which the server closes. A memoized request skips straight to `Complete`. If the client disconnects the server stops after the current chunk.\n\n**Caps.** The caller's heavy slot is held for the life of the socket (a long run counts against its key until it finishes); the server-wide permit is taken per chunk, so a long Monte Carlo yields to other work between chunks.", "operationId": "monteCarloWs", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "WsToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The websocket token (keyed mode, when `X-API-Key` is not sent). See `WsToken`." }, { "name": "Upgrade", "in": "header", "required": true, "schema": { "type": "string", "const": "websocket" } }, { "name": "Connection", "in": "header", "required": true, "schema": { "type": "string", "const": "Upgrade" } } ], "responses": { "101": { "description": "Switching to the websocket. Frames follow the protocol above; the first client frame is a `MonteCarloRequest`, server frames are `WsFrame`.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-websocket": { "client-first-frame": { "$ref": "#/components/schemas/MonteCarloRequest" }, "server-frames": { "$ref": "#/components/schemas/WsFrame" }, "transcript": [ { "done": 1000, "event": "Progress", "pct": 33, "total": 3000 }, { "done": 2000, "event": "Progress", "pct": 66, "total": 3000 }, { "done": 3000, "event": "Progress", "pct": 100, "total": 3000 }, { "event": "Complete", "summary": { "runs": 3000, "base_seed": 4242 } } ], "errors": [ { "event": "Error", "message": "runs must be 1\u2013100000 (input #14)" }, { "event": "Error", "message": "expected ident at line 1 column 2" } ] } } }, "/api/forwardflow/heatmap": { "post": { "tags": [ "sensitivity" ], "summary": "A sensitivity grid", "description": "Every cell is a full deterministic run on the config's seed, computed in parallel. **Heavy**: estimated work book \u00d7 cells \u2264 24,000,000 Agreement-runs. The request is `config` plus a grid spec flattened beside it and selected by `grid`. A cell that fails validation is a hole (`null`), never a 400 \u2014 the rest of the map is still information. 1\u2013900 cells. Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "heatmap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeatmapRequest" }, "examples": { "priceDefault": { "summary": "The break-even frontier", "description": "The centre cell (40%, $60,000) is the base run's 0.1421 exactly.", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "grid": "PriceDefault", "end_prices": [ 30000, 60000, 90000 ], "lifetimes": [ 0.2, 0.4, 0.6 ] } }, "volConviction": { "summary": "The behavioral cliff", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "grid": "VolConviction", "vols": [ 0.3, 0.43, 0.6 ], "x_underwater": [ 0.3, 0.5, 0.7 ] } } } } } }, "responses": { "200": { "description": "The grid.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeatmapResponse" }, "example": { "cells": [ [ 0.136, 0.1459, 0.1547 ], [ 0.1224, 0.1421, 0.1578 ], [ 0.0999, 0.1298, 0.1525 ] ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/backtest": { "post": { "tags": [ "sensitivity" ], "summary": "The vintage backtest", "description": "The static-pool vintage exhibit: one cohort originated at every fully seasoned historical month (term + 1 months of history follow it), each replayed against the actual price path that followed, all by the same engine. **Heavy**: estimated work agreements_per_cohort \u00d7 vintages \u2264 24,000,000 Agreement-runs (one seeded replay per vintage). With 174 monthly bars and a 60-month term that is 113 vintages, February 2012 to June 2021. A vintage the engine rejects is a hole counted in `failed`, not a 400. Read the rows, not the blend \u2014 a 2012 entry rebased to $60,000 rides the whole rally. Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "backtest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BacktestRequest" }, "example": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 } } } } }, "responses": { "200": { "description": "One row per seasoned vintage and the blend.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BacktestResponse" }, "example": { "vintages": [ { "month": [ 2021, 6 ], "start_index": 112, "entry_close": 35026.9, "irr_effective_pa": 0.1729, "moic": 1.3697, "net_gain_usd": 219143.32, "deployed_usd": 592714.83, "shortfall_usd": 28602.45, "completed": 6, "settled": 0, "non_performance": 4, "coin_returned_usd": 0.0, "buyer_refund_usd": 46994.76, "stop_surplus_usd": 23506.44, "btcnow_take_usd": 57300.22 } ], "blended_net_gain_usd": 138206160.2, "blended_deployed_usd": 66412793.69, "blended_moic": 3.081, "failed": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/risk": { "post": { "tags": [ "risk desk" ], "summary": "The exposure layer, the Greeks and the frontier family", "description": "Spec v1.6: the two lines (schedule and capital, as fractions of entry), coverage by month and by cohort, the exposure ladder at a month (6 moneyness \u00d7 5 tenor buckets), PD\u00b7LGD\u00b7EAD per vintage with a book row last, the Greeks by bump-and-revalue on the same seeds, and the rational walk-away frontier for a family of believed drifts. **Heavy**: estimated work book \u00d7 (1 + 7 \u00d7 greek_seeds) \u2264 24,000,000 Agreement-runs \u2014 the base run and seven runs of the book per Greek seed; 50,000 Agreements at 256 seeds (89,650,000) is refused naming greek_seeds and the book. `config.bump` must be null \u2014 the Greeks own the bump. Left unset, `ladder_month` comes back as the month of peak capital at risk. The base IRR in the Greeks is a seed-ensemble mean, not the single-seed run's. Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "risk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskRequest" }, "example": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "greek_seeds": 16, "frontier_mus": [ 0, 0.1, 0.25, 0.5 ] } } } }, "responses": { "200": { "description": "The report, flattened, plus the frontiers.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskResponse" }, "example": { "lines": [ { "t": 0, "schedule_line": 1.475, "capital_line": 1.0526, "capital_above_purchase_price": false, "remaining_schedule_usd": 88500.0, "unrecovered_capital_usd": 60000.0 } ], "coverage": [ { "month": 12, "spot": 30126.08, "active": 123, "below_schedule": 123, "below_capital": 117, "notional_usd": 6876400.2, "capital_at_risk_usd": 4542958.33, "intrinsic_shortfall_usd": 3180156.59 } ], "coverage_by_cohort": [ { "origination_month": 0, "agreements": 10, "months_below_schedule": 41.2, "months_below_capital": 18.9, "share_below_schedule": 0.83, "share_below_capital": 0.38 } ], "ladder": { "month": 23, "spot": 33375.25, "active": 203, "cells": [ { "moneyness": "< 0.50", "tenor": "\u2264 6 mo", "agreements": 0, "notional_usd": 0.0, "capital_at_risk_usd": 0.0 } ], "total_notional_usd": 9012345.0, "total_capital_at_risk_usd": 5678901.0 }, "credit": [ { "origination_month": null, "agreements": 240, "stops": 101, "completed": 84, "completed_early": 55, "pd": 0.4208, "ead_usd": 43562.82, "lgd": 0.2251, "el_usd": 990282.37, "el_rate": 0.1029, "capital_loss_usd": 230645.54, "deployed_usd": 9619863.62, "refunds_usd": 603951.54, "surplus_usd": 148595.85 } ], "greeks": { "price_bump": 0.05, "vol_bump": 0.05, "as_of_month": 23, "as_of_spot": 33375.25, "seeds": 16, "vega_method": "bridge vol", "base_net_gain_usd": 5072824.14, "base_irr": 0.1586, "delta_usd_per_pct": 24884.96, "delta_commitment_usd_per_pct": 24884.96, "delta_coins": 74.56, "gamma_usd_per_pct2": -175.64, "vega_usd_per_vol_point": 29718.22, "theta_usd_per_month": 127160.35, "delta_irr_pp_per_pct": 0.091, "vega_irr_pp_per_vol_point": 0.0415, "base_vol_annual": 0.3941 }, "frontiers": [ { "mu_annual": 0.25, "rows": [ { "m": 0, "payment": 1, "walk_below_spot": 31270.64, "walk_below_of_entry": 0.5212, "walk_below_moneyness": 0.5212, "remaining_obligation": 60000.0, "remaining_schedule": 88500.0 } ] } ], "frontier_params": { "sigma_annual": 0.414, "mu_annual": 0.25, "r_c_annual": 0.15, "walk_cost_of_strike": 0.025 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/crash_library": { "get": { "tags": [ "derivatives desk" ], "summary": "The named crash presets", "description": "Six one-click stylised drawdowns, each as `Custom` path anchors \u2014 data, not a mode. Load one as `config.path = {\"Custom\": {\"points\": preset.points}}`.", "operationId": "crashLibrary", "responses": { "200": { "description": "The presets.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrashLibraryResponse" }, "example": { "presets": [ { "id": "2018", "name": "2018 bear", "description": "A stylisation of the December 2017 peak to the December 2018 trough \u2014 monthly anchors, not the tick data.", "points": [ [ 12, 0.2 ], [ 24, 0.4 ] ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/forwardflow/surfaces": { "get": { "tags": [ "derivatives desk" ], "summary": "The two preset vol surfaces", "description": "`flat` (43% everywhere) and `stylised` (the Bitcoin skew \u2014 an illustration, never market data), in the `VolSurface` shape every desk endpoint accepts back as `surface`.", "operationId": "surfaces", "responses": { "200": { "description": "The presets.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfacesResponse" }, "example": { "flat": { "tenors_months": [ 1, 3, 6, 12, 24 ], "moneyness": [ 0.5, 0.7, 0.85, 1.0, 1.15, 1.3 ], "vols": [ [ 0.43, 0.43, 0.43, 0.43, 0.43, 0.43 ] ], "source": "flat 43% preset \u2014 not market data" }, "stylised": { "tenors_months": [ 1, 3, 6, 12, 24 ], "moneyness": [ 0.5, 0.7, 0.85, 1.0, 1.15, 1.3 ], "vols": [ [ 0.52, 0.504, 0.45, 0.414, 0.4, 0.394 ] ], "source": "stylised Bitcoin skew \u2014 an illustration, not market data" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/forwardflow/placement": { "post": { "tags": [ "derivatives desk" ], "summary": "The paper's embedded put ladder on a surface", "description": "One leg per defaultable payment age (1..term\u22121): the put the Holder is short on a stop at that age, struck at the remaining schedule, expiring at the missed payment date, weighted by the scenario's unconditional stop probability, priced Black-Scholes on the surface at the funding rate. Beside it the paper's own implied vol \u2014 the flat vol at which the markup exactly pays for the weighted ladder \u2014 and the surface's 12-month ATM. Light (estimated work = book, nominally \u2014 the ladder is priced per payment age; heavy-guarded only above 1,000,000 Agreement-runs). Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "placement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementRequest" }, "example": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "funding_rate": 0.045 } } } }, "responses": { "200": { "description": "The ladder and the two vols.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Placement" }, "example": { "legs": [ { "month": 1, "strike_usd": 87025.0, "tenor_months": 2, "weight": 0.0021, "moneyness": 0.6895, "implied_vol": 0.52, "put_value_usd": 27310.5 } ], "paper_implied_vol": 0.61, "surface_atm_12m": 0.414, "ladder_value_usd_per_agreement": 9870.2, "markup_usd_per_agreement": 22673.75, "markup_pv_usd_per_agreement": 19940.1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/fair_value": { "post": { "tags": [ "derivatives desk" ], "summary": "The risk-neutral fair value of the book", "description": "The engine run under GBM at the funding rate with the surface's 24-month ATM vol, the Holder's receipts and purchases discounted continuously at the funding rate to month 0, averaged over seeds. The measure is the desk's; behavior (hazards, multipliers, propensity, the conviction rule, the rational modes) stays the config's. The shock and bump overlays are cleared. **Heavy**: estimated work book \u00d7 seeds \u2264 24,000,000 Agreement-runs. Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "fairValue", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FairValueRequest" }, "example": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "funding_rate": 0.045, "seeds": 32 } } } }, "responses": { "200": { "description": "The fair value.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FairValue" }, "example": { "pv_per_agreement_usd": 63120.4, "pv_book_usd": 15148896.0, "purchase_book_usd": 14210000.0, "spread_bps": 660.7, "atm_vol_used": 0.48, "seeds": 32, "funding_rate_annual": 0.045, "agreements": 240 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/hedge": { "post": { "tags": [ "derivatives desk" ], "summary": "The hedge overlay", "description": "Each structure's flows laid over the same seeded paths the paper runs on: the hedged distribution beside the unhedged one on both seats, the cost and floor figures, every leg's two sides, the market-neutral desk's number (`hedged_excess_over_basis_pp`, filled only when the delta is hedged) and, on request, the directional desk's comparison (paper vs spot vs covered call) with the shelf. The preset shelf rides with every response. **Heavy**: estimated work book \u00d7 seeds \u00d7 (\u03a3 structure units + 2 if benchmarks) \u2264 24,000,000 Agreement-runs, a perpetual delta hedge or a dollar-delta futures leg counting term-months of units. Objective is Dollar-only: omit objective or set it to \"dollar\". Other explicit values are refused before calculation.", "operationId": "hedge", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HedgeRequest" }, "examples": { "posture": { "summary": "A put ladder, a perpetual delta hedge and a generic two-leg structure, with the benchmarks", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "seeds": 32, "include_benchmarks": true, "option_rate": 0.045, "put_skew_points": 5, "structures": [ { "PutLadder": { "strike_pct_of_entry": 0.7, "tenor_months": 12, "coverage": 1.0, "inception": "AtOrigination" } }, { "PerpDeltaHedge": { "rebalance_months": 1, "funding_rate_annual": 0.1, "initial_margin_pct": 0.1, "coverage": 1.0 } }, { "Legs": { "legs": [ { "Futures": { "side": "Short", "sizing": { "DollarDelta": { "share": 1.0 } }, "basis": { "locked_months": 0, "locked_rate": 0.04, "after_rate": 0.04 }, "rebalance_months": 1, "initial_margin_pct": 0.35, "surface_vol": 0.4 } }, { "Option": { "kind": "Put", "side": "Buy", "strike": "LossLineAtExpiry", "tenor_months": 3, "roll": "AtEachExpiry", "coverage": { "Coins": 1.0 }, "inception": "AtOrigination", "years_limit": null } } ] } } ] } }, "collar": { "summary": "The cross-book collar and a variance swap on the flat surface", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "seeds": 16, "surface": { "tenors_months": [ 1, 3, 6, 12, 24 ], "moneyness": [ 0.5, 0.7, 0.85, 1.0, 1.15, 1.3 ], "vols": [ [ 0.43, 0.43, 0.43, 0.43, 0.43, 0.43 ], [ 0.43, 0.43, 0.43, 0.43, 0.43, 0.43 ], [ 0.43, 0.43, 0.43, 0.43, 0.43, 0.43 ], [ 0.43, 0.43, 0.43, 0.43, 0.43, 0.43 ], [ 0.43, 0.43, 0.43, 0.43, 0.43, 0.43 ] ], "source": "flat 43% \u2014 not market data" }, "structures": [ { "CrossBookCollar": { "free_coins": 10.0, "call_strike_pct_of_spot": 1.3, "put_strike_pct_of_entry": 0.85, "tenor_months": 12, "coverage": 1.0 } }, { "VarianceSwap": { "tenor_months": 12, "vega_notional_usd": 1000.0 } } ] } } } } } }, "responses": { "200": { "description": "One result per structure, the benchmarks when asked for, and the presets.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HedgeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/hedge_series": { "post": { "tags": [ "derivatives desk" ], "summary": "The months of a hedged sleeve", "description": "One structure run per seed with every month kept (FUND_DESK_PLAN Phase 4a): the book \u2014 receipts, purchases, the hedge's premium and settlements, the futures mark and basis, notional, initial margin, the variation and intramonth calls, the counts, the spot and the mark \u2014 the mark at the purchase yield (every Agreement's expected remaining flows on a flat continuation under the config's own rules, discounted at the yield that makes a fresh origination enter at cost; stops in transit at their sale proceeds discounted; open options carry no mark), the P&L attribution with its conservation identity (`total_pnl = carry + price + stops + early_completion + hedge_mark + hedge_settlement + basis + residual`, and `= cash + \u0394mark + hedge cash`), the margin buffer, and the delta series of the median seed. Bands across seeds; the median seed in full; the lifetime distributions from the same run. **Heavy**: estimated work book \u00d7 (seeds \u00d7 structure units + \u2308horizon/3\u2309 \u00d7 (8 seeds \u00d7 7 runs + 1) when `include_greeks`, on the median seed only) \u2264 24,000,000 Agreement-runs, a perpetual delta hedge or a dollar-delta futures leg counting term-months of units.", "operationId": "hedgeSeries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HedgeSeriesRequest" }, "examples": { "ladder": { "summary": "The loss-line ladder preset, 16 seeds, the risk paper's option pricing", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "seeds": 16, "option_rate": 0.045, "put_skew_points": 5 } }, "futures": { "summary": "Coin-delta futures with the margin funded at 8%, the Greeks at every third month", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "seeds": 8, "structure": { "Legs": { "legs": [ { "Futures": { "side": "Long", "sizing": { "CoinDelta": { "share": 0.8 } }, "basis": { "locked_months": 24, "locked_rate": 0.04, "after_rate": 0.1 }, "rebalance_months": 1, "initial_margin_pct": 0.35, "surface_vol": 0.4 } } ] } }, "margin_funding_rate": 0.08, "include_greeks": true } } } } } }, "responses": { "200": { "description": "The months: bands across the seeds, the median seed in full, the lifetime figures, the buffer and the delta series.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HedgeSeries" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/rebalance_policies": { "post": { "tags": [ "derivatives desk" ], "summary": "The rebalancing policies side by side", "description": "The same `Legs` structure with every futures leg's rebalance set to each policy in turn \u2014 calendar, delta band or price move; its minimum trade, lot and margin funding kept \u2014 each priced by the hedge overlay on the same seeds at the request's `exec_cost_bps` (default 50, the desk's own; a futures leg carries none), with the leg's turnover and trade count beside the result. The policy's cost is its hedged median IRR against the same leg reset monthly: the page's subtraction, so put the monthly policy among the policies. **Heavy**: estimated work book \u00d7 seeds \u00d7 structure units \u00d7 policies \u2264 24,000,000 Agreement-runs, a dollar-delta leg counting term-months per policy.", "operationId": "rebalancePolicies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebalancePoliciesRequest" }, "examples": { "four": { "summary": "Monthly, quarterly, a 0.05-coin band and a 10% move on the coin seat's futures", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "seeds": 16, "structure": { "Legs": { "legs": [ { "Futures": { "side": "Long", "sizing": { "CoinDelta": { "share": 0.8 } }, "basis": { "locked_months": 24, "locked_rate": 0.04, "after_rate": 0.1 }, "rebalance_months": 1, "initial_margin_pct": 0.35, "surface_vol": 0.4 } } ] } }, "policies": [ { "Calendar": { "months": 1 } }, { "Calendar": { "months": 3 } }, { "DeltaBand": { "band_coins_per_agreement": 0.05 } }, { "PriceMove": { "pct": 0.1 } } ] } } } } } }, "responses": { "200": { "description": "One row per policy, in request order.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebalancePoliciesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/coin_seat": { "post": { "tags": [ "derivatives desk" ], "summary": "The coin seat across drifts", "description": "The paper and each structure re-run under GBM at the sweep's vol for every median annual return r (\u03bc = ln(1 + r) + \u03c3\u00b2/2, so the median path returns r a year), both seats' distributions per row \u2014 coins per coin and the coin IRR beside the dollar figures. Seeds run from the config's seed upward and are the same for every row and structure; hedge structures run net of `exec_cost_bps` on every option leg (default 50, the hedge overlay's), so the sweep and the desk are net of the same cost, and the response's `notes` name the value. **Heavy**: estimated work book \u00d7 seeds \u00d7 (\u03a3 structure units + 1) \u00d7 drifts \u2264 24,000,000 Agreement-runs.", "operationId": "coinSeat", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoinSeatRequest" }, "examples": { "defaults": { "summary": "The default grid and the four preset coin-seat structures", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 } } }, "twoDrifts": { "summary": "Two drifts, rolled calls at the paper's multiple", "value": { "config": { "start_price": 60000, "path": { "Bridge": { "end_price": 60000, "vol_annual": 0.43 } }, "multiple": "1.475", "term_months": 60, "origination_payments": 1, "servicing_fee_rate": "0.05", "purchase_pct_of_strike": "1.00", "scenario": { "BaselineCurve": { "lifetime": 0.4 } }, "rational_default": false, "drawdown_hazard_multipliers": false, "conviction": { "enabled": false, "x_underwater": 0.5, "y_consecutive": 6 }, "settlement_propensity": 0.025, "settlement_min_return": null, "cohorts": 24, "agreements_per_cohort": 10, "haircut": 0, "sale_cost_bps": 25, "stop_sale_lag_days": 18, "bump": null, "rational_boundary": null, "shock": null, "origination_stop_month": null, "intramonth_strike_dispersion": true, "seed": 42 }, "seeds": 8, "drifts": [ -0.18, 0.3 ], "structures": [ { "RolledCalls": { "strike_pct_of_entry": 1.475, "tenor_months": 12, "coverage": 1.0, "years_limit": null } }, { "DealerCall": { "strike_pct_of_entry": 1.475, "tenor_months": 60 } } ] } } } } } }, "responses": { "200": { "description": "The sweep.", "headers": { "X-Engine-Spec": { "$ref": "#/components/headers/X-Engine-Spec" }, "X-Engine-Version": { "$ref": "#/components/headers/X-Engine-Version" }, "X-Key-Name": { "$ref": "#/components/headers/X-Key-Name" }, "X-Engine-Build": { "$ref": "#/components/headers/X-Engine-Build" }, "X-Engine-Data": { "$ref": "#/components/headers/X-Engine-Data" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriftSweep" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Busy" } } } }, "/api/forwardflow/hedge_research": { "post": { "tags": [ "derivatives desk" ], "operationId": "hedge_research", "summary": "Paired hedge loss and cash research", "description": "Each seed runs one shared Agreement book across 1\u20138 strategies. Returns raw per-seed USD/coin economic outcomes, NPV and monthly cash requirements, optional actual-path arrays. Excludes cross-book collars. Same heavy queue, per-key limits, cancellation and process memory budget as other research endpoints. Cash is a monthly netting screen, excluding short-option margin, daily calls and forced closure. No held-state continuation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HedgeResearchRequest" } } } }, "responses": { "200": { "description": "Compact ordered observations; aggregate these, not batch percentiles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HedgeResearchResponse" } } } }, "400": { "description": "Invalid input or work/memory limit" }, "503": { "description": "Shared capacity unavailable; honor Retry-After" } } } } } }