Copy page

Deep Dives

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.

Code
// 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:

Code
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:

Code
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:

Code
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:

Code
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.

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:

Code
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 maps every letter to its meaning. REST responses use full field names.

What's next

• Order Book Reconstruction — where sequence IDs and precision matter
• WebSocket Reference — full field tables