# Deep Dive — Data Types

The SDK preserves exchange values exactly as sent, without silent precision loss. This means some fields are `bigint` and monetary values are strings. Understanding why prevents subtle bugs.

## Numeric types in REST responses

The SDK's generated types reflect what the OpenAPI spec declares for each field. **Not all monetary values are the same type:**

- **String fields** — order prices, quantities, and amounts on prediction-market and trading endpoints are strings (e.g. `"50123.45"`). Use a decimal library for arithmetic.
- **Number fields** — some endpoints return `number` for amounts and rates. Examples: `Balance.amount`, `Balance.available`, `FxRate.rate`, `SymbolDetails.tick_size`, `SymbolDetails.quote_increment`, and candle OHLCV values.

Check the TypeScript types in your IDE to see which fields are `string` vs `number` for each endpoint. The general rule: **WebSocket prices are always strings; REST responses vary by endpoint.**

```ts
// REST: Balance amounts are number
const balances = await client.accountServices.getAvailableBalances({});
// balances[0].amount is number, not string

// REST: Order prices are string
const order = await client.predictions.placeOrder({ price: "0.65", /* ... */ });

// WebSocket: always strings
trades.on("message", (t) => {
  // t.p is a string — "50123.45"
});
```

For financial arithmetic on string fields, use a decimal library:

```ts
import Decimal from "decimal.js";
const notional = new Decimal(order.price).times(order.quantity);
```

The order book's `spread()` and `mid()` return floats for display only — do not use them for exact execution math.

## BigInt for large integers

The exchange sends integers that exceed JavaScript's safe integer range (`Number.MAX_SAFE_INTEGER`, 2^53 − 1) — specifically nanosecond timestamps and sequence IDs. The SDK preserves these as `bigint`:

```ts
const trades = client.websocket.trades("BTCUSD");
trades.on("message", (t) => {
  // t.E is a bigint: event time in nanoseconds
  // t.t is a bigint: trade ID
  const millis = Number(t.E / 1_000_000n); // convert ns → ms for Date
  console.log(new Date(millis));
});
```

Fields typed `number | bigint` are `bigint` when the value exceeds the safe range and `number` otherwise. To be safe, always handle both — `BigInt(x)` normalizes either:

```ts
const eventTimeNs = BigInt(t.E);
```

### Why this matters

A plain `JSON.parse` silently rounds integers beyond 2^53 to the nearest double, corrupting IDs and timestamps with no error. A trade ID like `9007199254740993` would round to `9007199254740992` — a different, wrong ID.

The SDK parses JSON with a source-text-aware reviver (Node 22+ `JSON.parse` source access) that recovers the exact digits and preserves them as `bigint`. Strings (prices), floats, and safe integers are unchanged.

### Runtime requirement

Lossless parsing requires Node 22+ (or a runtime with `JSON.parse` source access). On older runtimes, if the SDK encounters an integer beyond the safe range it throws an `SdkError` rather than hand back a silently-rounded value:

```
lossless JSON parsing requires JSON source access (Node 22+)
```

This is a deliberate fail-loud: corrupt IDs are worse than a clear error. See [runtime compatibility](/tools/typescript-sdk/patterns#runtime-compatibility).

## int64 request inputs

Where an endpoint accepts a 64-bit integer input, the SDK's generated types accept `bigint | number` so you can pass either:

```ts
await client.marketData.getFXRate({
  symbol: "EURUSD",
  timestamp: 1710547200000n, // milliseconds since epoch
});
```

Response `int64` paths are normalized automatically based on generated operation metadata — you always receive `bigint` for those fields.

## Wire format field names

WebSocket payloads use compact single-letter field names (`p`, `q`, `E`, `i`, `X`, …). This is the exchange's wire format, preserved by the SDK rather than renamed. The [WebSocket Reference](/tools/typescript-sdk/reference/websocket#wire-format) maps every letter to its meaning. REST responses use full field names.

## What's next

- [Order Book Reconstruction](/tools/typescript-sdk/deep-dives/order-book) — where sequence IDs and precision matter
- [WebSocket Reference](/tools/typescript-sdk/reference/websocket) — full field tables