# Your first TVX integration

Build a small reproducible calculation before connecting a data provider. The downloadable TVX SDK 0.1.0 supplies the same calculation used in the website's learning lab.

## 1. Install a known artifact

Download the package and checksums from the [developer toolkit](?page=developer/tvx-sdk). Verify the artifact hash, then install the local tarball in your own project.

```sh
npm install ./openforex-tvx-0.1.0.tgz
```

Use the source archive if you want the test suite and build configuration. Its README describes the supported runtime and build commands.

## 2. Produce an evidence record

```typescript
import { calculate } from '@openforex/tvx';

const calculation = calculate({
  amount: '120.00',
  fromValue: '0.50',
  toValue: '6.00',
  decimals: 2,
  rounding: 'half-even'
});
// calculation.result === '10.00'
```

All three numeric inputs are decimal strings. Preserve the returned inputs, rounding rule, output scale, exact numerator, and exact denominator with the result.

## 3. Test failure cases early

The amount may be zero. Both reference values must be greater than zero. Decimal inputs reject signs, grouping separators, exponent notation, and malformed strings. Output precision must be an integer from 0 through 18.

Test a zero denominator, malformed input, and a rounding tie. For snapshot-based quotes, also test missing instruments, future observations, and observations older than your chosen policy permits.

## 4. Define the provider boundary

Before connecting a feed, document its reference unit, valuation method, observation timestamps, and source identifiers. Retain a copy of each snapshot used for a result. Set a freshness policy deliberately; a recent network response can still contain an old observation.

The SDK's createSnapshot and quote functions validate this context. The [toolkit reference](?page=developer/tvx-sdk) describes feed adaptation and points to the complete API contracts in the source download.

## 5. Keep application responsibilities explicit

The calculation library does not fetch prices, hold balances, execute orders, or settle obligations. An application adding those functions needs separately defined behavior for authentication, fees, spreads, accounting, and operational failures.

Read the [OpenForex Stack](?page=seed-content/ofs/index) and [kernel reference](?page=seed-content/ofs-kernel/1.0.0) to understand the separation of responsibilities.

## A useful first deliverable

Prepare a small example with pinned source, inputs, expected outputs, actual outputs, and instructions another developer can run. Use the [contribution brief builder](?page=contribute) to organize a problem or proposed improvement after you can reproduce it.


## Source references

The [SDK API contracts](?page=developer/toolkit-contracts) define numeric inputs, output precision, rounding, and error behavior. The [implementation provenance](?page=developer/toolkit-provenance) records the origin and scope of the software. These are project implementation sources; synthetic arithmetic is not independent validation of a valuation methodology.