Developer documentation API v1

Instruments, prices and numeric units

Resolve identity before joining observations or valuing a portfolio.

Instrument discriminated union

typescript

type Instrument =
  | { kind: "equity"; id: string; issuer_ref: string;
      venue: string; currency: string }
  | { kind: "token"; id: string; chain_id: string;
      contract: string; decimals: number;
      underlying_id: string | null }
  | { kind: "derivative"; id: string; venue: string;
      underlying_id: string; contract_spec_ref: string }
  | { kind: "event_outcome"; id: string;
      market_id: string; outcome_id: string;
      resolution_rules_ref: string };

type Amount = { asset: string; atoms: string; scale: number };
// amount in whole units = integer(atoms) / 10**scale
// JSON numbers are not the wire format for transaction quantities.

Identity and mapping validity

An issuer, security and venue listing have separate identities. A SEC CIK identifies a filer, not a share class or trading venue. Seer instrument discovery returns a canonical listing ID, issuer reference, security reference, venue, currency and time-valid symbols. For example, equity:listing:apple-common-xnas names the example listing; issuer:sec:0000320193 identifies its issuer. Treat returned IDs as opaque values rather than constructing them from tickers.

A symbol change does not create a new security and a reused symbol does not merge unrelated securities. Stock tokens, ordinary shares, depositary receipts, options and perpetual contracts remain distinct instruments. Unresolved or multiple matches require selection before price retrieval or execution.

Observation semantics

Object	Required context
OHLCV interval	Instrument, start/end, session, currency, adjustment convention, finality and missing bars.
Quote	Bid/ask or reference type, venue, observation time, size and expiry where relevant.
Company fact	Concept, unit, fiscal period, filing reference and amendment.
Macro series	Period, frequency, seasonal adjustment, vintage and release time if known.
Token exposure	Chain/contract, decimals, underlying relationship and time-valid multiplier.

Token reference valuation

q_atoms is integer token quantity; d is token precision; m_t is shares per token at time t; P is price per underlying share in the valuation currency. This reference value is not an executable token quote. Do not apply the multiplier again to a feed already expressed per token.

V_{\mathrm{ref}}=\frac{q_{\mathrm{atoms}}}{10^d}m_tP_{\mathrm{underlying},t}

Precision and comparability

Monetary quantities use integer atoms and a declared scale. Calculations convert units explicitly and apply the rounding rule associated with the consuming operation. Price precision, quantity precision, minimum lot size and the smallest billable SCC increment are different constraints.

Cross-instrument comparisons share a valuation currency, observation cutoff and price convention. A stale close, executable ask and midpoint have different semantics even when their numeric values are similar. Their timestamps and price-type labels remain attached to the resulting artifact.

Valuation with currency conversion

q is instrument quantity, m converts it to underlying exposure, P is the price per exposure unit in currency c, X is base-currency units per unit of c, and C is cash in base currency b. All terms use compatible observation and settlement conventions. For a direct instrument price, m=1.

V_t=\sum_{i=1}^{n}q_i\,m_{i,t}\,P_{i,t}^{(c_i)}\,X_t^{c_i\rightarrow b}+C_t^{(b)}

Sampling and microstructure semantics

A bar aggregates observations over a session interval. Open, high, low, close and volume describe that aggregation; they are not simultaneous executable quotes. Price-based indicators use an explicit adjustment convention so splits and distributions do not become unexplained jumps.

Asynchronous markets introduce an additional alignment problem. Two daily closes can refer to different information cutoffs, and forward-filled values introduce stale observations into covariance estimates. Joined numerical artifacts retain their sampling calendar, alignment rule and missingness policy. This makes a comparison reproducible without asserting that all assets traded at one common instant.