TVX SDK 0.1.0: API contracts

Source: OpenForex TVX SDK 0.1.0, docs/API.md. The source text below is reproduced from the bundled implementation documentation. The SDK code and documentation are MIT licensed.

Read the toolkit overview, download the source archive, or verify the release checksums.

All exports are available from @openforex/tvx after installing the downloaded

tarball. Type declarations are generated in dist/index.d.ts.

Numeric representation

Decimal is a TypeScript alias for string; runtime validation is authoritative.

Inputs are unsigned base-10 decimals, at most 96 characters with at most 36

fractional digits. Exponents, whitespace, grouping separators, leading plus/minus,

leading zeros (except zero itself), empty strings, NaN, and Infinity are rejected.

amount may be zero; TVX values must be strictly positive.

Outputs are decimal strings with the requested fixed scale. Default output scale

is 8, allowed range 0–18. Default rounding is half-even; half-up and down

are also supported. Precision and rounding are library choices, not a statement

that these defaults are mandated by a monetary standard.

convert(input) and calculate(input)

convert returns the target amount. calculate returns a frozen record with

the original inputs, result, output policy, and exactNumerator/exactDenominator.

The fraction is not reduced, so compare ratios rather than numerator text across

different input representations. Same-currency conversion still applies output

rounding; it is not a bypass around input validation.

pairRate(fromValue, toValue, decimals?, rounding?)

Computes the result for one source unit. Use convert for an amount calculation

rather than multiply a separately rounded pair rate. Reverse a pair by swapping

the values. Reciprocal/triangular identities may differ after output rounding.

createSnapshot(input)

Validates unknown input and returns a copied, frozen snapshot with frozen

observations. Required metadata: id, source, method, referenceUnit.

Each is a nonempty string of at most 256 characters. values must contain

1–10,000 observations keyed by codes matching [A-Z][A-Z0-9]{1,11}.

Each observation requires value and observedAt. Timestamps use UTC ISO format

with seconds and either no fraction or exactly three millisecond digits:

2026-09-24T12:00:00Z or 2026-09-24T12:00:00.000Z.

Impossible calendar dates and local/offset timestamps are rejected; normalize

provider times explicitly before creating the snapshot.

quote(input)

Requires snapshot, amount, from, to, now, and maxAgeMs; accepts the same optional

numeric policy as convert. maxAgeMs is a nonnegative safe integer. Selected

observations in the future are rejected. Age equal to maxAgeMs is accepted.

Returns calculation fields plus from, to, snapshotId, source, method,

referenceUnit, quotedAt, sourceObservedAt, and targetObservedAt. The snapshot is

revalidated before computation; all its observations must be structurally valid,

but freshness checks apply to the selected pair. No current clock is read.

fromSapaPayload(payload, metadata, options?)

Input is an unknown JSON object. success must equal true; currencies must be a

nonempty array. Each row needs code, tvx_value, and rate_quoted_at. Codes are

uppercased; whitespace is not silently trimmed. Metadata supplies the same four

fields as createSnapshot. Feed-level quoted_at is not substituted for a missing

row timestamp because it can conceal older observations.

Options: aliases explicitly maps source codes to canonical codes;

allowNumberValues allows finite Number inputs to be converted to decimal text.

If that conversion produces exponent notation it is rejected by the decimal

contract. Prefer decimal strings at the provider boundary.

Other fields are ignored. The adapter never substitutes market_rate_to_usd,

board_rate_to_usd, tvx_rate_to_usd, an AFRA value, or a cached fallback.

If the provider includes unusable rows, an upstream integration may deliberately

select a valid subset and record that selection before calling this adapter.

structuralValue(input, policy)

Input: population, gdpNominal, gdpPpp, efficiency, supportFactor; optional

gdpEffectiveNominal and gdpEffectivePpp override corresponding raw GDP values.

Provided overrides must be positive; an invalid override does not silently fall

back. Policy: goldAnchor, goldWeight, alpha, beta, gamma, delta. Weights must be

nonnegative and have a finite positive sum; other consumed values must be finite

and strictly positive. No live policy defaults are supplied.

Returns value (Number), normalizedWeights, effectiveGdpNominal, and

effectiveGdpPpp. Fractional powers and their products have binary floating-point

error; extreme magnitudes may fail with NUMERIC_RANGE. A consuming valuation

pipeline must specify decimal serialization, calibration, and accepted error

tolerance before using this output as a quote observation.

Error codes

Catch TvxError and inspect .code; messages provide context but are not stable

machine identifiers. Invalid JavaScript call shapes outside the typed API can

also produce a native TypeError; validate transport request bodies first.

The library does not prescribe HTTP status codes. An API wrapper should define

its own authenticated request contract and map failures without exposing secrets.