Fair-Value Tooling#

@seesaw/core includes pure client-side helpers for estimating binary market fair value and side-aware edge. They are designed for terminals, bots, and market-maker dashboards that already have a market snapshot and an oracle price.

These helpers do not fetch data, host triggers, subscribe to streams, submit orders, or simulate transactions. They are local math utilities over caller provided inputs. Use your own Solana RPC, stream provider, hosted Seesaw API read, or self-custody account read to source the inputs.

Model#

computeLogReturnBinaryFairValue uses a transparent log-return normal model:

• UP means settlement price is greater than or equal to the market start price, matching the protocol tie-break.
• annualizedVolatilityBps is annualized log-return volatility in basis points, so 2_000 means 20%.
• driftBps is optional annualized log-return drift. When omitted, the model is zero-drift.
• toBeatBps is the arithmetic premium over the strike, rounded from ((currentPrice - startPrice) / startPrice) * 10_000. It is not log-space and must not be mixed with the log-space driftBps or annualizedVolatilityBps inputs.
• When secondsToExpiry <= 0, the output is deterministic under the protocol tie-break.
• Deterministic expiry and zero-volatility branches return zScore as Infinity or -Infinity. JavaScript's JSON.stringify serializes either value as null, so use a non-finite-aware encoding if the exact zScore must survive payload storage.

The output is not an oracle and not a hosted Seesaw quote. It is a transparent model result that a trader can compare against the order book.

// docs-check: semantic
import { OrderSide, computeLogReturnBinaryFairValue, evaluateFairValueEdge } from '@seesaw/core';

const fairValue = computeLogReturnBinaryFairValue({
  startPrice: 100,
  currentPrice: 110,
  secondsToExpiry: 15 * 60,
  annualizedVolatilityBps: 2_000,
});

const edge = evaluateFairValueEdge({
  fairYesProbabilityBps: fairValue.upProbabilityBps,
  side: OrderSide.BuyYes,
  priceBps: 5_800,
});

console.log({
  upProbabilityBps: fairValue.upProbabilityBps,
  downProbabilityBps: fairValue.downProbabilityBps,
  toBeatBps: fairValue.toBeatBps,
  edgeBps: edge.edgeBps,
  kellyFractionBps: edge.kellyFractionBps,
});

Edge Semantics#

evaluateFairValueEdge returns edge in the submitted side denomination:

• BuyYes: fairYes - yesPrice
• SellYes: yesPrice - fairYes
• BuyNo: fairNo - noPrice
• SellNo: noPrice - fairNo

It also returns a synthetic binary-buy view used for fractional Kelly sizing. For example, SellYes @ 6500 is equivalent to buying NO @ 3500 for sizing purposes.

Integration Notes#

• Treat model output as advisory. The signed order price, order type, and on-chain matching rules remain authoritative.
• Use the orderbook/fill-estimate helpers before sending IOC-style flow; fair value answers "is this price attractive?", not "will this size fill?".
• Store the model assumptions alongside any bot decision. assumptions, zScore, yearsToExpiry, volatility, and drift are part of the returned payload so execution review is reproducible. Remember that deterministic zScore values are non-finite and become null under JSON.stringify.
• For self-custody integrations, fetch market start price, expiry, and orderbook state directly from Solana accounts, then run these helpers locally.