kestrel.markets
Version:
A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.
60 lines • 3.5 kB
TypeScript
/**
* # fair/spot — `@fair` for a spot instrument (equity/crypto), ADR-0017
*
* ExecutionFair-B76 (`./index.ts`) is underlying-anchored Black-76 backed out of an option
* chain, floored at intrinsic — meaningless for a plain equity or coin: there is no chain to
* read a vol out of and no strike to take an intrinsic of. For a **spot instrument** the honest
* fill-reference is simply its own **two-sided quote mid**: `(bid + ask) / 2`, carrying a receipt
* under the distinct model tag {@link EXEC_FAIR_QUOTE_MODEL} (EVs across tags do not compare).
*
* Note the deliberate contrast with the options doctrine, where *mid is never a fair-value source*
* (ARCHITECTURE §4): there, the observed option mid is a health signal off a possibly-fictional
* book. For a spot instrument there is no chain and no maker model between the quote and the fill —
* the NBBO mid **is** the honest reference, and it is receipt-gated (the bid/ask it was built from
* ride the receipt) exactly so a downstream consumer can see what it rested on.
*
* Fail-closed (RUNTIME §4/§8): a **one-sided or dark** quote (`bid`/`ask` `null`), a non-finite
* side, or a crossed book (`ask < bid`) is **not** a fair — the function returns `null` and the
* price resolver falls back to an explicit `@bid`/`@ask`/`@mid`/`@last` (a silent mid is
* forbidden). This module is **pure** — no I/O, no clock, no RNG (RUNTIME §0); the caller injects
* `asof` and any staleness gate is applied downstream (the receipt only makes `asof` observable).
*/
/** The versioned model tag stamped on every spot-fair receipt — distinct from the options
* `exec-fair-b76-v1`, so a grade never compares a quote-mid fair against a Black-76 fair. */
export declare const EXEC_FAIR_QUOTE_MODEL: "exec-fair-quote-v1";
/** The trust envelope carried alongside a spot-fair value — the two-sided quote it was built
* from, plus the injected observation time. */
export interface SpotFairReceipt {
readonly model: typeof EXEC_FAIR_QUOTE_MODEL;
/** The bid the mid was built from. */
readonly bid: number;
/** The ask the mid was built from. */
readonly ask: number;
/** The injected observation timestamp (epoch ms), carried verbatim; absent when none was
* supplied. Never gated here — freshness is the engine's job downstream. */
readonly asof?: number;
}
/** A resolved spot-fair value with its receipt. */
export interface SpotFairResult {
readonly value: number;
readonly receipt: SpotFairReceipt;
}
/** The inputs to a single spot-fair valuation — the instrument's own two-sided quote. */
export interface SpotFairInput {
/** The bid; `null` ⇒ that side is dark. */
readonly bid: number | null;
/** The ask; `null` ⇒ that side is dark. */
readonly ask: number | null;
/** Optional injected observation timestamp (epoch ms) of the quote; carried onto the receipt. */
readonly asof?: number;
}
/**
* Resolve `@fair` for one spot instrument.
*
* Returns `{ value, receipt }` with `value = (bid + ask) / 2` when the quote is genuinely
* two-sided; returns **`null`** — the fail-closed "unbuildable fair" signal the caller handles
* with an annotated `@bid`/`@ask`/`@mid` fallback — when either side is dark (`null`), a side is
* non-finite, or the book is crossed (`ask < bid`). Never Black-76, never a silent mid.
*/
export declare function executionFairSpot(input: SpotFairInput): SpotFairResult | null;
//# sourceMappingURL=spot.d.ts.map