@pulsepairs/sdk 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.10.0 — 2026-09-30
+
+### Added
+
+- **Collateral unit helpers**, so an integrator no longer hand-rolls them. The
+  venue's decimals are `usdtDecimals` on `GET /config`: **18 on dev (USDR), 6 on
+  prod (USDT0)**. Every amount the API sends or accepts is in base units at that
+  scale.
+  - `client.ensureUsdtDecimals(): Promise<number>` — reads `usdtDecimals` from
+    `/config` once per client and caches it; concurrent callers share one
+    request. An invalid or missing value (anything but an integer 0–36) rejects
+    and is not cached, so the caller can retry.
+  - `client.getUsdtDecimals(): number` — the cached value, synchronously. Before
+    it is loaded it returns 6 and warns once (a caller bug: await
+    `ensureUsdtDecimals()` first).
+  - `client.setUsdtDecimals(d)` — stores `d` if valid, e.g. from a `getConfig()`
+    response the caller already has.
+  - `usdToAtomic(usd, decimals?)` — whole tokens → base units, through a decimal
+    string (`parseUnits`), never multiplication, which is inexact at 18 decimals.
+  - `atomicToUsd(atomic, decimals?)` — base units → whole tokens via
+    `formatUnits`; `null`/`""` → 0; never throws.
+  - `roundTripToleranceAtomic(decimals?)` — `10n ** max(0, decimals − 6)`, for
+    snapping a MAX sell onto the exact owned balance.
+  - `isValidUsdtDecimals(d)` — the validity check the above use.
+
+  The three standalone helpers default to the decimals the client loaded.
+- **Client-bound forms** — `client.usdToAtomic`, `client.atomicToUsd`,
+  `client.roundTripToleranceAtomic` — at that client's own decimals, for a
+  process that talks to more than one venue (e.g. dev at 18 and prod at 6).
+  Once two clients load different decimals the standalone helpers' shared
+  default is ambiguous: `usdToAtomic` and `roundTripToleranceAtomic` then throw
+  rather than sign at a guessed scale, and `atomicToUsd` keeps its never-throw
+  contract (warns once, returns 0). Explicit `decimals` always works.
+  A client only ever uses its OWN decimals: before it has loaded, it answers
+  6 and warns once per client, never another client's value. At worst an
+  unloaded client under-signs (the venue's $1 minimum rejects it); it can never
+  over-sign at another venue's scale.
+
+### Fixed
+
+- The README order example and the five example scripts (`simple-taker`,
+  `simple-maker`, `rain-taker`, `account-kit-taker`, `full-dmm-bot`) signed
+  amounts with `parseStake`, which is 6-decimal only, so on the 18-decimal dev
+  venue they signed 10^12 too little. They now load `usdtDecimals` from the
+  config they already fetch and use `client.usdToAtomic`, and check the $1
+  minimum against `client.usdToAtomic(1)` instead of `assertStakeBounds`, whose
+  minimum is 6-decimal. `parseStake` and `assertStakeBounds` themselves are
+  unchanged and documented as 6-decimal only.
+
+No existing method changed.

package/DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # `@pulsepairs/sdk` — Reference Documentation
 
-**Version:** 0.7.0 · **License:** UNLICENSED · **Runtime:** Node ≥ 18 or a modern browser
+**Version:** 0.10.0 · **License:** UNLICENSED · **Runtime:** Node ≥ 18 or a modern browser
 
 Complete reference for the UpDown TypeScript SDK: every export, its
 units, its failure modes, and the protocol it speaks.
@@ -43,10 +43,14 @@ returns, what unit a number is in, or why a signature is being rejected.
 ## 1. What this SDK is
 
 UpDown is a binary prediction market: *will BTC-USD (or ETH-USD) be UP or DOWN at
-the end of this 5-minute / 15-minute / 1-hour cycle?* Trading is an **off-chain
+the end of this 5-minute or 15-minute cycle?* Trading is an **off-chain
 central limit order book** (the "matcher"); settlement is **on-chain** on
 Arbitrum.
 
+60-minute cycles were retired on 2026-08-18 and no new ones are created. The
+`3600` timeframe is still accepted and still returns the historical rounds — see
+`getMarkets` under [§5 `UpDownHttpClient`](#5-updownhttpclient--rest-client).
+
 The SDK gives you three layers, usable independently:
 
 | Layer | Modules | What it does |
@@ -725,7 +729,10 @@ fresh nonce. Single-writer bots may prefer a monotonic counter — seed it from
 centsToBps(cents: number): number      // 55 → 5500; 49.5 → 4950. Throws outside (0,100)
 bpsToCents(bps: number): number        // 5500 → 55. Throws outside (0,10000)
 parseStake(usd: string | number): bigint   // "5.50" → 5_500_000n. Rejects negative/non-finite
+                                           // 6-DECIMAL ONLY (prod USDT0). For the venue's scale use usdToAtomic.
 assertStakeBounds(amountAtomic: bigint, side?: "BUY" | "SELL"): void
+                                           // 6-DECIMAL ONLY: its $1 minimum is 1_000_000. On other
+                                           // scales compare against client.usdToAtomic(1).
 feeAtomic(notionalAtomic, priceBps, cfg): bigint
 
 MIN_STAKE_ATOMIC = 1_000_000n     // $1 of share FACE value (BUY only)

package/README.md

@@ -1,7 +1,7 @@
 # @pulsepairs/sdk
 
 Standalone SDK for the **UpDown** up/down prediction markets —
-BTC-USD / ETH-USD, UP or DOWN, on 5-minute / 15-minute / 1-hour cycles.
+BTC-USD / ETH-USD, UP or DOWN, on 5-minute and 15-minute cycles.
 
 > **On the name:** the product is **UpDown**. "PulsePairs" is a retired name that
 > survives in two places for compatibility reasons only — this npm package's name
@@ -83,7 +83,7 @@ import { privateKeyToAccount } from "viem/accounts";
 import { arbitrum } from "viem/chains";
 import {
   UpDownHttpClient, buildOrderTypedData, ensureSettlementAllowance, freshNonce,
-  parseCompositeMarketKey, parseStake, OrderType, OrderSide, Option,
+  parseCompositeMarketKey, OrderType, OrderSide, Option,
 } from "@pulsepairs/sdk";
 
 // Point the bot at a matcher YOU chose. Don't hardcode ours into a process
@@ -96,7 +96,10 @@ const [live] = (await api.getMarkets({ pair: "BTC-USD", timeframe: 300 }))
   .filter((m) => m.status === "ACTIVE");
 const { settlementAddress, marketId } = parseCompositeMarketKey(live.address)!;
 
-const amount = parseStake("5");
+// Amounts are base units at the venue's decimals (18 on dev, 6 on prod) — see
+// "Collateral units" below. `parseStake` is 6-decimal only (prod USDT0).
+api.setUsdtDecimals(cfg.usdtDecimals);                // or: await api.ensureUsdtDecimals()
+const amount = api.usdToAtomic(5);                    // 5 × 10^decimals
 
 // BOUNDED approve. `settlementAddress` is server-supplied (it came from the
 // matcher's market list), so cap its reach at what you actually intend to
@@ -395,7 +398,7 @@ EIP-712          ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES,
                  buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData,
                  freshSessionId, freshNonce, domainForSettlement,
                  findPairBySettlement, parseCompositeMarketKey
-Trade-math       centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic,
+Trade-math       centsToBps, bpsToCents, parseStake (6-decimal only), assertStakeBounds (6-decimal only), feeAtomic,
                  MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC
 PnL (v0.5.0)     UpDownHttpClient.getPnl, positionPnl, portfolioPnl,
                  computePortfolioPnl, markValueAtomic, midBps, markForOption,
@@ -413,6 +416,32 @@ Enums/types      OrderType, OrderSide, Option, ApiConfig, PairConfig, PostOrderB
 
 ---
 
+## Collateral units (v0.10.0)
+
+Amounts are base units at the venue's collateral decimals — `usdtDecimals` on
+`GET /config`: **18 on dev (USDR), 6 on prod (USDT0)**. Load them once, then
+convert with the helpers; never hardcode 6.
+
+```ts
+import { UpDownHttpClient, usdToAtomic, atomicToUsd } from "@pulsepairs/sdk";
+
+const client = new UpDownHttpClient("https://dev-api-updown.rain.trade");
+await client.ensureUsdtDecimals();       // 18 on dev; one request, cached
+
+usdToAtomic(50);                          // 50000000000000000000n — sign this as `amount`
+atomicToUsd("101010101010101010101");     // 101.01… — render this
+```
+
+`usdToAtomic` goes through a decimal string (`parseUnits`), never
+`usd * 10 ** decimals`, which is inexact at 18 decimals. Reading the decimals
+before `ensureUsdtDecimals()` resolves falls back to 6 with a one-time warning.
+
+**Talking to more than one venue** (e.g. dev and prod in one process)? Use the
+client-bound forms — `client.usdToAtomic`, `client.atomicToUsd`,
+`client.roundTripToleranceAtomic` — which use that client's own decimals. The
+standalone helpers share one default; once two clients load different decimals
+it is ambiguous, and `usdToAtomic` throws rather than sign at a guessed scale.
+
 ## Cancel-and-replace, and bulk writes (v0.9.0)
 
 **`amendOrder` replaces a resting order in one request.** Doing it as
@@ -456,6 +485,32 @@ for (const f of bulkFailures(res)) {
 
 `index` is the position in the array you sent — results are positional.
 
+**On success the order is NESTED, and the single routes spread it.** This is
+the one asymmetry that bites, because nothing about the call site hints at it:
+
+```ts
+const single = await api.amendOrder({ cancelOrderId, order });
+single.id;                       // flat — the replacement's id
+
+const bulk = await api.amendOrdersBulk({ amends });
+for (const r of bulk.results) {
+  if (!r.ok) continue;           // narrow first; failures have no `order`
+  r.order.id;                    // NESTED — `r.id` is undefined
+  r.replaced;                    // the id that was retired
+  r.priorityKept;                // false when queue position was forfeited
+  r.remaining;                   // atomic USDT carried to the replacement
+}
+```
+
+`postOrdersBulk` nests the same way: `results[i].order`, never `results[i].id`.
+
+Reading `results[i].id` yields `undefined` rather than throwing, so the mistake
+survives to wherever that id is used — usually a later cancel that silently
+matches nothing. SDK **0.9.0 typed the bulk result flat** and shipped that
+mistake into the types themselves; 0.9.1 corrected them. The wire shape never
+changed, so no server behaviour depends on which version you are on — but on
+0.9.0 the compiler will agree with you while you read the wrong field.
+
 Two behavioural differences worth knowing, because they change how latency
 scales:
 

package/dist/http.d.ts

@@ -2,7 +2,40 @@ import type { AmendOrderBody, AmendOrderResult, ApiConfig, Balance, BulkAmendBod
 import { type PortfolioPnl } from "./pnl.js";
 export declare class UpDownHttpClient {
     private readonly baseUrl;
+    /** `usdtDecimals` from /config, once loaded. See `ensureUsdtDecimals`. */
+    private usdtDecimals;
+    /** The one /config request concurrent `ensureUsdtDecimals` callers share. */
+    private usdtDecimalsInflight;
+    /** getUsdtDecimals() warns once per client when read before loading. */
+    private warnedUnloaded;
     constructor(baseUrl: string);
+    /**
+     * The venue's collateral decimals (`usdtDecimals` on `GET /config`: 18 on dev,
+     * 6 on prod), fetched once per client and cached. Concurrent callers share one
+     * request. An invalid or missing value REJECTS rather than being guessed at, and
+     * a rejection is not cached, so the caller can retry. Also becomes the default
+     * for `usdToAtomic` / `atomicToUsd` / `roundTripToleranceAtomic`.
+     */
+    ensureUsdtDecimals(): Promise<number>;
+    /**
+     * This client's decimals, synchronously. Called before `ensureUsdtDecimals`
+     * has resolved, it answers 6 and warns once — that is a bug in the caller. It
+     * never reads another client's value.
+     */
+    getUsdtDecimals(): number;
+    /**
+     * `usdToAtomic` / `atomicToUsd` / `roundTripToleranceAtomic` at THIS client's
+     * decimals. Use these when a process talks to more than one venue (dev at 18,
+     * prod at 6): the standalone helpers share one default, which is ambiguous
+     * then. Before this client's `ensureUsdtDecimals` resolves they use 6 and
+     * warn once, like `getUsdtDecimals` — never another client's decimals.
+     */
+    usdToAtomic(usd: number): bigint;
+    atomicToUsd(atomic: bigint | string | number | null | undefined): number;
+    roundTripToleranceAtomic(): bigint;
+    /** Cache `d` if it is a valid decimal count (integer 0–36); otherwise ignored.
+     *  Lets a `getConfig()` response the caller already has populate the cache. */
+    setUsdtDecimals(d: unknown): void;
     getVersion(): Promise<Version>;
     getHealth(): Promise<{
         status: string;

package/dist/http.js

@@ -1,4 +1,5 @@
 import { computePortfolioPnl, feesPaidByWallet } from "./pnl.js";
+import { atomicToUsd, isValidUsdtDecimals, publishUsdtDecimals, roundTripToleranceAtomic, usdToAtomic, } from "./units.js";
 function buildUrl(base, path, query) {
     const b = base.replace(/\/$/, "");
     const p = path.startsWith("/") ? path : `/${path}`;
@@ -31,9 +32,85 @@ async function parseJson(res) {
 }
 export class UpDownHttpClient {
     baseUrl;
+    /** `usdtDecimals` from /config, once loaded. See `ensureUsdtDecimals`. */
+    usdtDecimals;
+    /** The one /config request concurrent `ensureUsdtDecimals` callers share. */
+    usdtDecimalsInflight;
+    /** getUsdtDecimals() warns once per client when read before loading. */
+    warnedUnloaded = false;
     constructor(baseUrl) {
         this.baseUrl = baseUrl;
     }
+    /**
+     * The venue's collateral decimals (`usdtDecimals` on `GET /config`: 18 on dev,
+     * 6 on prod), fetched once per client and cached. Concurrent callers share one
+     * request. An invalid or missing value REJECTS rather than being guessed at, and
+     * a rejection is not cached, so the caller can retry. Also becomes the default
+     * for `usdToAtomic` / `atomicToUsd` / `roundTripToleranceAtomic`.
+     */
+    async ensureUsdtDecimals() {
+        if (this.usdtDecimals !== undefined)
+            return this.usdtDecimals;
+        if (!this.usdtDecimalsInflight) {
+            this.usdtDecimalsInflight = this.getConfig()
+                .then((cfg) => {
+                const d = cfg.usdtDecimals;
+                if (!isValidUsdtDecimals(d)) {
+                    throw new Error(`[@pulsepairs/sdk] /config returned an invalid usdtDecimals: ${String(d)}`);
+                }
+                this.setUsdtDecimals(d);
+                return d;
+            })
+                .finally(() => {
+                this.usdtDecimalsInflight = undefined;
+            });
+        }
+        return this.usdtDecimalsInflight;
+    }
+    /**
+     * This client's decimals, synchronously. Called before `ensureUsdtDecimals`
+     * has resolved, it answers 6 and warns once — that is a bug in the caller. It
+     * never reads another client's value.
+     */
+    getUsdtDecimals() {
+        if (this.usdtDecimals !== undefined)
+            return this.usdtDecimals;
+        // THIS client's value only — never another client's shared default. A prod
+        // client that has not loaded would otherwise inherit a dev client's 18 and
+        // sign a $5 order 10^12 too large (PR #437 re-review). Unloaded, it answers
+        // the documented 6 and warns once per client: at worst it under-signs, which
+        // the venue's $1 minimum rejects, and it can never over-sign.
+        if (!this.warnedUnloaded) {
+            this.warnedUnloaded = true;
+            console.warn("[@pulsepairs/sdk] this client's usdtDecimals is not loaded — using 6. " +
+                "Await ensureUsdtDecimals() first (the venue may use 18).");
+        }
+        return 6;
+    }
+    /**
+     * `usdToAtomic` / `atomicToUsd` / `roundTripToleranceAtomic` at THIS client's
+     * decimals. Use these when a process talks to more than one venue (dev at 18,
+     * prod at 6): the standalone helpers share one default, which is ambiguous
+     * then. Before this client's `ensureUsdtDecimals` resolves they use 6 and
+     * warn once, like `getUsdtDecimals` — never another client's decimals.
+     */
+    usdToAtomic(usd) {
+        return usdToAtomic(usd, this.getUsdtDecimals());
+    }
+    atomicToUsd(atomic) {
+        return atomicToUsd(atomic, this.getUsdtDecimals());
+    }
+    roundTripToleranceAtomic() {
+        return roundTripToleranceAtomic(this.getUsdtDecimals());
+    }
+    /** Cache `d` if it is a valid decimal count (integer 0–36); otherwise ignored.
+     *  Lets a `getConfig()` response the caller already has populate the cache. */
+    setUsdtDecimals(d) {
+        if (!isValidUsdtDecimals(d))
+            return;
+        this.usdtDecimals = d;
+        publishUsdtDecimals(d);
+    }
     async getVersion() {
         const res = await fetch(buildUrl(this.baseUrl, "/version"));
         return parseJson(res);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { UpDownHttpClient, wsUrlFromHttpBase, bulkFailures } from "./http.js";
+export { usdToAtomic, atomicToUsd, roundTripToleranceAtomic, isValidUsdtDecimals } from "./units.js";
 export { UpDownWsClient, type UpDownWsMessage, type SubscribePayload, type WsAuthCredentials, type ConnectAuthedOptions, } from "./ws.js";
 export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, type OrderSignMessage, type CancelSignMessage, type WsAuthMessage, type ParsedComposite, } from "./eip712.js";
 export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, type ClobAuthDomain, type ClobAuthMessage, } from "./auth.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 // HTTP + WS clients
 export { UpDownHttpClient, wsUrlFromHttpBase, bulkFailures } from "./http.js";
+// Collateral units (usdtDecimals from /config: 18 on dev USDR, 6 on prod USDT0)
+export { usdToAtomic, atomicToUsd, roundTripToleranceAtomic, isValidUsdtDecimals } from "./units.js";
 export { UpDownWsClient, } from "./ws.js";
 // EIP-712 helpers
 export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, 

package/dist/units.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Collateral unit helpers — whole-token ("USD") amounts ↔ on-chain base units.
+ *
+ * The venue's collateral decimals are published as `usdtDecimals` on
+ * `GET /config`: 18 on dev (USDR), 6 on prod (USDT0). Every amount the API
+ * sends or accepts is in base units at that scale, so a client must read it
+ * rather than assume 6 — a 6-decimal assumption against an 18-decimal venue is
+ * off by 10^12 on every order and every displayed amount.
+ *
+ * `UpDownHttpClient.ensureUsdtDecimals()` fetches the value and caches it here;
+ * the helpers below default to that cached value.
+ */
+/** Integer 0–36: the range a real ERC-20 uses. Anything else is not guessed at. */
+export declare function isValidUsdtDecimals(d: unknown): d is number;
+/** @internal Store a validated value as the default for the helpers below. */
+export declare function publishUsdtDecimals(d: number): void;
+/**
+ * @internal The decimals the helpers default to. Before the value is loaded it
+ * answers 6 and warns ONCE: reading it early is a bug in the caller (it should
+ * have awaited `ensureUsdtDecimals()`), and 6 is wrong on an 18-decimal venue.
+ */
+export declare function defaultUsdtDecimals(): number;
+/** @internal tests only. */
+export declare function _resetUsdtDecimalsForTests(): void;
+/**
+ * Whole tokens → base units, e.g. `usdToAtomic(0.1, 18) === 100000000000000000n`.
+ *
+ * Goes through a decimal STRING (`parseUnits(usd.toFixed(min(decimals, 12)))`),
+ * never `usd * 10 ** decimals`: at 18 decimals that product is past 2^53 and
+ * float error lands in the integer (1.1 * 1e18 is 1100000000000000128).
+ * `toFixed` is capped at 12 places, well beyond any display precision.
+ * Non-finite input → 0n.
+ *
+ * Without `decimals`, THROWS if clients in this process loaded different
+ * decimals: signing at a guessed scale is the failure this refuses. Use
+ * `client.usdToAtomic` in a multi-venue process.
+ */
+export declare function usdToAtomic(usd: number, decimals?: number): bigint;
+/**
+ * Base units → whole tokens, e.g. `atomicToUsd("5000000", 6) === 5`.
+ *
+ * Integer input (bigint, integer string or integer number) goes through
+ * `formatUnits`, so 18-decimal amounts convert without float loss. A
+ * non-integer number falls back to `atomic / 10 ** decimals`. `null`,
+ * `undefined` and `""` → 0. Never throws; a non-finite result → 0.
+ */
+export declare function atomicToUsd(atomic: bigint | string | number | null | undefined, decimals?: number): number;
+/**
+ * The slack, in base units, for snapping a MAX sell onto the exact owned
+ * balance after a round trip through a 6-decimal display value:
+ * `10n ** BigInt(max(0, decimals - 6))`. 1n at 6 decimals, 10^12 at 18.
+ */
+export declare function roundTripToleranceAtomic(decimals?: number): bigint;

package/dist/units.js

@@ -0,0 +1,137 @@
+import { formatUnits, parseUnits } from "viem";
+/**
+ * Collateral unit helpers — whole-token ("USD") amounts ↔ on-chain base units.
+ *
+ * The venue's collateral decimals are published as `usdtDecimals` on
+ * `GET /config`: 18 on dev (USDR), 6 on prod (USDT0). Every amount the API
+ * sends or accepts is in base units at that scale, so a client must read it
+ * rather than assume 6 — a 6-decimal assumption against an 18-decimal venue is
+ * off by 10^12 on every order and every displayed amount.
+ *
+ * `UpDownHttpClient.ensureUsdtDecimals()` fetches the value and caches it here;
+ * the helpers below default to that cached value.
+ */
+/** Integer 0–36: the range a real ERC-20 uses. Anything else is not guessed at. */
+export function isValidUsdtDecimals(d) {
+    return typeof d === "number" && Number.isInteger(d) && d >= 0 && d <= 36;
+}
+/** The fallback before the value is loaded — prod's USDT0. */
+const FALLBACK_DECIMALS = 6;
+let cachedDecimals;
+let warnedUnloaded = false;
+/**
+ * Set once two clients have loaded DIFFERENT decimals (a process talking to dev
+ * at 18 and prod at 6). The shared default is then ambiguous: it would be
+ * whichever loaded last, and a signed amount at the wrong scale is 10^12 off.
+ * From then on the standalone helpers refuse to guess — see defaultUsdtDecimals.
+ * Per-client conversion stays exact: `client.usdToAtomic` etc.
+ */
+let conflictingDecimals = false;
+/** @internal Store a validated value as the default for the helpers below. */
+export function publishUsdtDecimals(d) {
+    if (cachedDecimals !== undefined && cachedDecimals !== d)
+        conflictingDecimals = true;
+    cachedDecimals = d;
+}
+/**
+ * @internal The decimals the helpers default to. Before the value is loaded it
+ * answers 6 and warns ONCE: reading it early is a bug in the caller (it should
+ * have awaited `ensureUsdtDecimals()`), and 6 is wrong on an 18-decimal venue.
+ */
+export function defaultUsdtDecimals() {
+    if (conflictingDecimals) {
+        throw new Error("[@pulsepairs/sdk] clients in this process loaded different usdtDecimals " +
+            "(e.g. dev 18 and prod 6), so there is no single default. Pass `decimals` " +
+            "explicitly, or use client.usdToAtomic / client.atomicToUsd.");
+    }
+    if (cachedDecimals !== undefined)
+        return cachedDecimals;
+    if (!warnedUnloaded) {
+        warnedUnloaded = true;
+        console.warn("[@pulsepairs/sdk] usdtDecimals read before it was loaded — using 6. " +
+            "Await client.ensureUsdtDecimals() first (the venue may use 18).");
+    }
+    return FALLBACK_DECIMALS;
+}
+/** @internal tests only. */
+export function _resetUsdtDecimalsForTests() {
+    cachedDecimals = undefined;
+    warnedUnloaded = false;
+    conflictingDecimals = false;
+    warnedAmbiguous = false;
+}
+/**
+ * Whole tokens → base units, e.g. `usdToAtomic(0.1, 18) === 100000000000000000n`.
+ *
+ * Goes through a decimal STRING (`parseUnits(usd.toFixed(min(decimals, 12)))`),
+ * never `usd * 10 ** decimals`: at 18 decimals that product is past 2^53 and
+ * float error lands in the integer (1.1 * 1e18 is 1100000000000000128).
+ * `toFixed` is capped at 12 places, well beyond any display precision.
+ * Non-finite input → 0n.
+ *
+ * Without `decimals`, THROWS if clients in this process loaded different
+ * decimals: signing at a guessed scale is the failure this refuses. Use
+ * `client.usdToAtomic` in a multi-venue process.
+ */
+export function usdToAtomic(usd, decimals = defaultUsdtDecimals()) {
+    if (!Number.isFinite(usd))
+        return 0n;
+    return parseUnits(usd.toFixed(Math.min(decimals, 12)), decimals);
+}
+/**
+ * Base units → whole tokens, e.g. `atomicToUsd("5000000", 6) === 5`.
+ *
+ * Integer input (bigint, integer string or integer number) goes through
+ * `formatUnits`, so 18-decimal amounts convert without float loss. A
+ * non-integer number falls back to `atomic / 10 ** decimals`. `null`,
+ * `undefined` and `""` → 0. Never throws; a non-finite result → 0.
+ */
+export function atomicToUsd(atomic, decimals) {
+    try {
+        if (atomic === null || atomic === undefined || atomic === "")
+            return 0;
+        // Resolved inside the try: an ambiguous default (clients disagree) must not
+        // make this throw — it warns once and answers 0 instead.
+        if (decimals === undefined) {
+            try {
+                decimals = defaultUsdtDecimals();
+            }
+            catch (e) {
+                warnAmbiguousOnce(e);
+                return 0;
+            }
+        }
+        let out;
+        if (typeof atomic === "bigint") {
+            out = Number(formatUnits(atomic, decimals));
+        }
+        else if (typeof atomic === "string") {
+            const s = atomic.trim();
+            out = /^-?\d+$/.test(s) ? Number(formatUnits(BigInt(s), decimals)) : Number(s) / 10 ** decimals;
+        }
+        else {
+            out = Number.isInteger(atomic)
+                ? Number(formatUnits(BigInt(atomic), decimals))
+                : atomic / 10 ** decimals;
+        }
+        return Number.isFinite(out) ? out : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+let warnedAmbiguous = false;
+function warnAmbiguousOnce(e) {
+    if (warnedAmbiguous)
+        return;
+    warnedAmbiguous = true;
+    console.warn(String(e instanceof Error ? e.message : e));
+}
+/**
+ * The slack, in base units, for snapping a MAX sell onto the exact owned
+ * balance after a round trip through a 6-decimal display value:
+ * `10n ** BigInt(max(0, decimals - 6))`. 1n at 6 decimals, 10^12 at 18.
+ */
+export function roundTripToleranceAtomic(decimals = defaultUsdtDecimals()) {
+    return 10n ** BigInt(Math.max(0, decimals - 6));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.9.1",
-  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets \u2014 matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
+  "version": "0.10.0",
+  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets — matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
   "license": "UNLICENSED",
   "type": "module",
   "main": "dist/index.js",
@@ -28,13 +28,14 @@
   "files": [
     "dist",
     "README.md",
-    "DOCUMENTATION.md"
+    "DOCUMENTATION.md",
+    "CHANGELOG.md"
   ],
   "sideEffects": false,
   "scripts": {
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc",
-    "test": "node scripts/eip712-golden.test.mjs && node scripts/rawtx-tier.test.mjs && node scripts/hot-key-safety.test.mjs && node scripts/reconcile.test.mjs && node scripts/pnl.test.mjs && node scripts/ws-subscribe.test.mjs && node scripts/ws-onerror.test.mjs && node scripts/amend-wrappers.test.mjs && node scripts/amend-integration.test.mjs",
+    "test": "node scripts/eip712-golden.test.mjs && node scripts/rawtx-tier.test.mjs && node scripts/hot-key-safety.test.mjs && node scripts/reconcile.test.mjs && node scripts/pnl.test.mjs && node scripts/ws-subscribe.test.mjs && node scripts/ws-onerror.test.mjs && node scripts/amend-wrappers.test.mjs && node scripts/amend-integration.test.mjs && node scripts/usdt-units.test.mjs",
     "test:integration": "UPND_INTEGRATION=1 node scripts/amend-integration.test.mjs",
     "prepublishOnly": "npm run build && npm test",
     "example:taker": "npx tsx examples/simple-taker.ts",