Skip to content
TotalFinance

Portfolio · @insiderfinance/totalfinance

@insiderfinance/totalfinance/portfolio

import { … } from '@insiderfinance/totalfinance/portfolio'
stable-by-law (pre-1.0; not a 1.0 stability guarantee)iface 159type 60const 12fn 30JSON ↗
type

ResolvedTargetSource

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { ResolvedTargetSource } from '@insiderfinance/totalfinance/portfolio';

// ---------------------------------------------------------------------------------------------------
// Public types — resolution
// ---------------------------------------------------------------------------------------------------
export type ResolvedTargetSource = 'inline' | 'strategic' | 'tactical' | 'glide-path';

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ResolvedTargets

#

The targets effective at one instant, with where they came from.

Signature
import type { ResolvedTargets } from '@insiderfinance/totalfinance/portfolio';

/** The targets effective at one instant, with where they came from. */
export interface ResolvedTargets {
    targets: AllocationTarget[];
    source: ResolvedTargetSource;
    /** The effective-from instant of the winning set (`null` for inline targets). */
    effectiveFrom: EpochMs | null;
    /** Present when a linear glide path interpolated between two points. */
    interpolation?: {
        from: EpochMs;
        to: EpochMs;
        fraction: number;
    };
}
Fields, parameters and returned members (7)
Name · typeMeaning · unitRequired · default
effectiveFromnumber | null

The effective-from instant of the winning set (null for inline targets).

unitless by name
RequiredNo @default declared
interpolation{ fraction: number; from: EpochMs; to: EpochMs; }

Present when a linear glide path interpolated between two points.

unitless by name
OptionalNo @default declared
interpolation.fractionnumber—unitless by nameRequiredNo @default declared
interpolation.fromnumber—unitless by nameRequiredNo @default declared
interpolation.tonumber—unitless by nameRequiredNo @default declared
sourceResolvedTargetSource—unitless by nameRequiredNo @default declared
targetsAllocationTarget[]—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ReturnOfCapitalEvent

#

A return of capital: cash received reduces basis (never income); excess over basis is realized.

Signature
import type { ReturnOfCapitalEvent } from '@insiderfinance/totalfinance/portfolio';

/** A return of capital: cash received reduces basis (never income); excess over basis is realized. */
export interface ReturnOfCapitalEvent {
    eventType: 'corporate.return-of-capital';
    instrumentId: string;
    amountPerShare: number;
    currency: string;
    settleTimestampMs?: EpochMs;
}
Fields, parameters and returned members (5)
Name · typeMeaning · unitRequired · default
amountPerSharenumber—decimal fraction / multipleRequiredNo @default declared
currencystring—unitless by nameRequiredNo @default declared
eventType'corporate.return-of-capital'—unitless by nameRequiredNo @default declared
instrumentIdstring—unitless by nameRequiredNo @default declared
settleTimestampMsnumber—epoch milliseconds (UTC instant)OptionalNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

ScheduledSettlement

#

One dated cash leg: amount (signed) becomes settled once asOf ≥ settleTimestampMs.

Signature
import type { ScheduledSettlement } from '@insiderfinance/totalfinance/portfolio';

/** One dated cash leg: `amount` (signed) becomes settled once `asOf ≥ settleTimestampMs`. */
export interface ScheduledSettlement {
    /** The envelope `eventId` that booked this leg. */
    eventId: string;
    /** Signed cash effect: positive = incoming (receivable until settled), negative = payable. */
    amount: number;
    settleTimestampMs: EpochMs;
}
Fields, parameters and returned members (3)
Name · typeMeaning · unitRequired · default
amountnumber

Signed cash effect: positive = incoming (receivable until settled), negative = payable.

unitless by name
RequiredNo @default declared
eventIdstring

The envelope eventId that booked this leg.

unitless by name
RequiredNo @default declared
settleTimestampMsnumber—epoch milliseconds (UTC instant)RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

SettlementStyle

#

How a position's cash settles: at the fill, or through variation margin.

Signature
import type { SettlementStyle } from '@insiderfinance/totalfinance/portfolio';

// ---------------------------------------------------------------------------------------------------
// Instrument profile and lifecycle families (slice 5, 2026-08-29; agent-native "Derivative
// lifecycle" and "Corporate actions" families; FC7 mandatory state)
// ---------------------------------------------------------------------------------------------------
/** How a position's cash settles: at the fill, or through variation margin. */
export type SettlementStyle = 'cash-on-trade' | 'variation-margin';

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SleeveMember

#

A sleeve member: an instrument and its weight WITHIN the sleeve (members sum to 1).

Signature
import type { SleeveMember } from '@insiderfinance/totalfinance/portfolio';

/** A sleeve member: an instrument and its weight WITHIN the sleeve (members sum to 1). */
export interface SleeveMember {
    instrumentId: string;
    weight: number;
}
Fields, parameters and returned members (2)
Name · typeMeaning · unitRequired · default
instrumentIdstring—unitless by nameRequiredNo @default declared
weightnumber—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SpinOffEvent

#

A spin-off: child shares per parent share with an EXPLICIT basis allocation fraction.

Signature
import type { SpinOffEvent } from '@insiderfinance/totalfinance/portfolio';

/** A spin-off: child shares per parent share with an EXPLICIT basis allocation fraction. */
export interface SpinOffEvent {
    eventType: 'corporate.spin-off';
    parentInstrumentId: string;
    childInstrumentId: string;
    sharesPerParentShare: number;
    /** Fraction of the parent's basis that moves to the child, in [0, 1]. REQUIRED. */
    basisAllocationFraction: number;
}
Fields, parameters and returned members (5)
Name · typeMeaning · unitRequired · default
basisAllocationFractionnumber

Fraction of the parent's basis that moves to the child, in [0, 1]. REQUIRED.

decimal fraction / multiple
RequiredNo @default declared
childInstrumentIdstring—unitless by nameRequiredNo @default declared
eventType'corporate.spin-off'—unitless by nameRequiredNo @default declared
parentInstrumentIdstring—unitless by nameRequiredNo @default declared
sharesPerParentSharenumber—decimal fraction / multipleRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

StockSplitEvent

#

A forward or reverse stock split: every lot's quantity scales by sharesAfterSplit / sharesBeforeSplit and its per-unit basis by the inverse, so total cost basis is preserved exactly. Cash-in-lieu of fractional shares is a separate (later) event.

Signature
import type { StockSplitEvent } from '@insiderfinance/totalfinance/portfolio';

/**
 * A forward or reverse stock split: every lot's quantity scales by
 * `sharesAfterSplit / sharesBeforeSplit` and its per-unit basis by the inverse, so total cost
 * basis is preserved exactly. Cash-in-lieu of fractional shares is a separate (later) event.
 */
export interface StockSplitEvent {
    eventType: 'corporate.split';
    instrumentId: string;
    /** Shares held after the split per `sharesBeforeSplit` held before; positive integer. */
    sharesAfterSplit: number;
    /** Positive integer; a 2-for-1 split is `{ sharesAfterSplit: 2, sharesBeforeSplit: 1 }`. */
    sharesBeforeSplit: number;
}
Fields, parameters and returned members (4)
Name · typeMeaning · unitRequired · default
eventType'corporate.split'—unitless by nameRequiredNo @default declared
instrumentIdstring—unitless by nameRequiredNo @default declared
sharesAfterSplitnumber

Shares held after the split per sharesBeforeSplit held before; positive integer.

unitless by name
RequiredNo @default declared
sharesBeforeSplitnumber

Positive integer; a 2-for-1 split is { sharesAfterSplit: 2, sharesBeforeSplit: 1 }.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SymbolChangeEvent

#

The instrument is renamed; lots, basis, and lot ids carry over.

Signature
import type { SymbolChangeEvent } from '@insiderfinance/totalfinance/portfolio';

/** The instrument is renamed; lots, basis, and lot ids carry over. */
export interface SymbolChangeEvent {
    eventType: 'corporate.symbol-change';
    fromInstrumentId: string;
    toInstrumentId: string;
}
Fields, parameters and returned members (3)
Name · typeMeaning · unitRequired · default
eventType'corporate.symbol-change'—unitless by nameRequiredNo @default declared
fromInstrumentIdstring—unitless by nameRequiredNo @default declared
toInstrumentIdstring—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

const

TRADE_PLAN_KIND

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import { TRADE_PLAN_KIND } from '@insiderfinance/totalfinance/portfolio';

export declare const TRADE_PLAN_KIND: 'totalfinance.trade-plan';

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

const

TRADE_PLAN_SCHEMA_VERSION

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import { TRADE_PLAN_SCHEMA_VERSION } from '@insiderfinance/totalfinance/portfolio';

export declare const TRADE_PLAN_SCHEMA_VERSION: 1;

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TargetGroup

#

The group a target applies to — EXACTLY ONE key. instrumentId and sleeveId resolve through the model; the classification keys resolve through the caller's instrumentClassification (currency through each position's trading currency). { assetClass: 'cash' } targets cash.

Signature
import type { TargetGroup } from '@insiderfinance/totalfinance/portfolio';

// ---------------------------------------------------------------------------------------------------
// Public types — targets
// ---------------------------------------------------------------------------------------------------
/**
 * The group a target applies to — EXACTLY ONE key. `instrumentId` and `sleeveId` resolve through
 * the model; the classification keys resolve through the caller's `instrumentClassification`
 * (`currency` through each position's trading currency). `{ assetClass: 'cash' }` targets cash.
 */
export interface TargetGroup {
    instrumentId?: string;
    sleeveId?: string;
    assetClass?: string;
    currency?: string;
    tag?: string;
    underlying?: string;
    strategy?: string;
}
Fields, parameters and returned members (7)
Name · typeMeaning · unitRequired · default
assetClassstring—unitless by nameOptionalNo @default declared
currencystring—unitless by nameOptionalNo @default declared
instrumentIdstring—unitless by nameOptionalNo @default declared
sleeveIdstring—unitless by nameOptionalNo @default declared
strategystring—unitless by nameOptionalNo @default declared
tagstring—unitless by nameOptionalNo @default declared
underlyingstring—unitless by nameOptionalNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

TargetGroupKey

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { TargetGroupKey } from '@insiderfinance/totalfinance/portfolio';

export type TargetGroupKey = keyof TargetGroup;

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TargetSet

#

A dated, complete set of targets.

Signature
import type { TargetSet } from '@insiderfinance/totalfinance/portfolio';

/** A dated, complete set of targets. */
export interface TargetSet {
    /** When the set becomes effective (`'YYYY-MM-DD'`, zoned ISO datetime, or epoch ms). */
    effectiveFrom: EpochMs | string;
    /** Optional end of effectiveness (exclusive) — for tactical overrides. */
    effectiveTo?: EpochMs | string;
    targets: AllocationTarget[];
    note?: string;
}
Fields, parameters and returned members (4)
Name · typeMeaning · unitRequired · default
effectiveFromstring | number

When the set becomes effective ('YYYY-MM-DD', zoned ISO datetime, or epoch ms).

unitless by name
RequiredNo @default declared
effectiveTostring | number

Optional end of effectiveness (exclusive) — for tactical overrides.

unitless by name
OptionalNo @default declared
notestring—unitless by nameOptionalNo @default declared
targetsAllocationTarget[]—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TaxLot

#

One tax lot. Long lots have quantity > 0; short lots quantity < 0.

Signature
import type { TaxLot } from '@insiderfinance/totalfinance/portfolio';

/** One tax lot. Long lots have `quantity > 0`; short lots `quantity < 0`. */
export interface TaxLot {
    /** Deterministic fold identity (`lot-<n>`), stable across replays — addressable by
     * `specific-lot` relief. */
    lotId: string;
    openedByEventId: string;
    openedTimestampMs: EpochMs;
    /** Signed remaining quantity; fractional supported. */
    quantity: number;
    /** For long lots: acquisition price per unit. For short lots: opening proceeds per unit. */
    costBasisPerUnit: number;
}
Fields, parameters and returned members (5)
Name · typeMeaning · unitRequired · default
costBasisPerUnitnumber

For long lots: acquisition price per unit. For short lots: opening proceeds per unit.

currency per unit
RequiredNo @default declared
lotIdstring

Deterministic fold identity (lot-<n>), stable across replays — addressable by specific-lot relief.

unitless by name
RequiredNo @default declared
openedByEventIdstring—unitless by nameRequiredNo @default declared
openedTimestampMsnumber—epoch milliseconds (UTC instant)RequiredNo @default declared
quantitynumber

Signed remaining quantity; fractional supported.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

TimeInForce

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { TimeInForce } from '@insiderfinance/totalfinance/portfolio';

export type TimeInForce = 'day' | 'gtc';

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TradeCostEstimate

#

Public declaration. Read the signature and member contracts below; no additional behaviour is inferred.

Signature
import type { TradeCostEstimate } from '@insiderfinance/totalfinance/portfolio';

export interface TradeCostEstimate {
    commission: number;
    spread: number;
    slippage: number;
    total: number;
}
Fields, parameters and returned members (4)
Name · typeMeaning · unitRequired · default
commissionnumber—unitless by nameRequiredNo @default declared
slippagenumber—unitless by nameRequiredNo @default declared
spreadnumber—unitless by nameRequiredNo @default declared
totalnumber—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TradeFillEvent

#

An executed fill — the audited bridge from the execution journal into economic holdings (Permanent law 3). Buys open/extend long lots or cover short lots; sells relieve long lots or open short lots. This slice prices cash as quantity × pricePerUnit (contract multipliers arrive with the derivative-lifecycle slice).

Signature
import type { TradeFillEvent } from '@insiderfinance/totalfinance/portfolio';

/**
 * An executed fill — the audited bridge from the execution journal into economic holdings
 * (Permanent law 3). Buys open/extend long lots or cover short lots; sells relieve long lots or
 * open short lots. This slice prices cash as `quantity × pricePerUnit` (contract multipliers
 * arrive with the derivative-lifecycle slice).
 */
export interface TradeFillEvent {
    eventType: 'trade.fill';
    instrumentId: string;
    side: 'buy' | 'sell';
    /** Filled quantity, > 0 (fractional supported); `side` carries the direction. */
    quantity: number;
    /** Execution price per unit in `currency`. Finite; sign-unconstrained (negative prints are real). */
    pricePerUnit: number;
    currency: string;
    /** When the cash leg settles (trade date vs settlement date); omitted = settles immediately. */
    settleTimestampMs?: EpochMs;
    /** Required exactly when the ledger's `lotRelief` is `'specific-lot'` AND this fill closes. */
    lotSelections?: TradeFillLotSelection[];
    /**
     * Units of the underlying per unit of `quantity` (an equity option's 100, a futures contract
     * size). Omitted = 1 (one unit per unit). REQUIRED when `contract` is given — a derivative fill
     * states its multiplier. Cash and lot values scale by it; the lot basis stays per unit.
     */
    contractMultiplier?: number;
    /**
     * `'cash-on-trade'` (equities, options, spot; the default) books `quantity × pricePerUnit ×
     * contractMultiplier` at the fill. `'variation-margin'` (futures, perpetuals) books NO cash at
     * the fill: P&L is realized by `derivative.variation-margin` settlements and on close. REQUIRED
     * as `'variation-margin'` when `contract.kind` is `'future'` or `'perpetual'`.
     */
    settlementStyle?: SettlementStyle;
    /** The derivative's terms (option type/strike/expiry, future expiry, perpetual) — stored on the position. */
    contract?: DerivativeContractTerms;
    /**
     * Accrued interest paid with a bond purchase (or received on a sale), in `currency` — booked as
     * an income adjustment (negative on a buy), NEVER into the lot basis; the next coupon recovers it.
     */
    accruedInterest?: number;
}
Fields, parameters and returned members (17)

Loading 17 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TradeFillLotSelection

#

One specific-lot relief instruction: which lot, and how much of it, this fill closes.

Signature
import type { TradeFillLotSelection } from '@insiderfinance/totalfinance/portfolio';

/** One `specific-lot` relief instruction: which lot, and how much of it, this fill closes. */
export interface TradeFillLotSelection {
    lotId: string;
    /** Quantity relieved from the named lot, > 0 (an unsigned magnitude). */
    quantity: number;
}
Fields, parameters and returned members (2)
Name · typeMeaning · unitRequired · default
lotIdstring—unitless by nameRequiredNo @default declared
quantitynumber

Quantity relieved from the named lot, > 0 (an unsigned magnitude).

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TradeIntent

#

The desired economic action, without a broker payload or a credential (law 5).

Signature
import type { TradeIntent } from '@insiderfinance/totalfinance/portfolio';

/** The desired economic action, without a broker payload or a credential (law 5). */
export interface TradeIntent {
    kind: typeof TRADE_INTENT_KIND;
    schemaVersion: number;
    accountId: string;
    asOf: EpochMs;
    orders: TradeIntentOrder[];
    /** The combos the lines' `comboId`s name, when a net limit is wanted; a combo without terms needs no entry. */
    combos?: TradeIntentCombo[];
    /** Metadata: recorded, never read by any stage. */
    rationale?: string;
    /** Artifact ids the intent rests on. */
    evidence?: string[];
}
Fields, parameters and returned members (8)
Name · typeMeaning · unitRequired · default
accountIdstring—unitless by nameRequiredNo @default declared
asOfnumber—an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)RequiredNo @default declared
combosTradeIntentCombo[]

The combos the lines' comboIds name, when a net limit is wanted; a combo without terms needs no entry.

unitless by name
OptionalNo @default declared
evidencestring[]

Artifact ids the intent rests on.

unitless by name
OptionalNo @default declared
kind'totalfinance.trade-intent'—unitless by nameRequiredNo @default declared
ordersTradeIntentOrder[]—unitless by nameRequiredNo @default declared
rationalestring

Metadata: recorded, never read by any stage.

unitless by name
OptionalNo @default declared
schemaVersionnumber—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.