@taphubhq/sdk-core 0.25.4 → 0.25.6

package/README.md

@@ -1,6 +1,10 @@
 # @taphubhq/sdk-core
 
-Framework-agnostic TypeScript SDK for the TabHub platform.
+Framework-agnostic TypeScript SDK for the TapHub platform. Wraps the grid-api and
+user-service GraphQL endpoints plus the MQTT realtime streams behind one client.
+
+For React bindings (hooks, providers, i18n), use
+[`@taphubhq/sdk-react`](https://github.com/TaphubHQ/taphub-sdk/blob/main/packages/sdk-react/README.md), which builds on this package.
 
 ## Install
 
@@ -16,9 +20,11 @@ import { TaphubClient } from '@taphubhq/sdk-core';
 const client = new TaphubClient({
   agencyId: 'acme-corp',
   // Shared API base. The SDK derives:
-  //   - grid-api    → ${endpoint}/grid-api/grid-gql
+  //   - grid-api     → ${endpoint}/grid-api/grid-gql
   //   - user-service → ${endpoint}/taphub-user-service/th-user-gql
   endpoint: 'https://builder.taptrading.net/api',
+  // Optional — omit to run without realtime (client.realtime stays undefined).
+  mqttEndpoint: 'wss://mqtt.taptrading.net/mqtt',
 });
 
 // Session-token login via user-service GraphQL (preferred).
@@ -27,16 +33,276 @@ await client.auth.loginWithSession(upstreamSessionToken);
 const me = await client.user.me();
 ```
 
-### Login methods
+### Config
+
+| Field          | Required | Notes |
+|----------------|----------|-------|
+| `agencyId`     | yes      | Sent as `x-builder-code` on every request. Also namespaces token storage and scopes agency MQTT topics. |
+| `endpoint`     | yes      | Absolute URL of the shared API base. Must parse as a URL — the constructor throws `TaphubValidationError` (`code: 'InvalidConfig'`) otherwise. |
+| `mqttEndpoint` | no       | When absent, `client.realtime` is `undefined`; every other module still works. |
+| `mqttAuth`     | no       | `{ username, password }`, forwarded verbatim to the broker. For the TapHub/EMQX JWT-in-username setup, pass the session token as `username` and `''` as `password`. Read once when the connection opens — no refresh on reconnect. Ignored without `mqttEndpoint`. |
+| `storage`      | no       | `TaphubStorageAdapter` for token persistence. Defaults to `localStorage` in the browser, in-memory elsewhere. |
+| `fetch`        | no       | Custom `fetch` implementation (SSR, instrumentation, test doubles). |
+
+### Naming: `pairId` vs `agencyPairId`
+
+- **`pairId`** — the system-wide pair id, e.g. `grid-ETH-USD`. **Slash-free** by
+  design so it is safe inside MQTT topics, URLs, and Redis keys. This is what
+  every SDK method takes.
+- **`agencyPairId`** — the agency-scoped composite `{agencyId}:{pairId}`, e.g.
+  `acme-corp:grid-ETH-USD`. The server composes it from your `x-builder-code` /
+  JWT; you only meet it as an MQTT `gameId` and on `PairInfo.agencyPairId`.
+- **`ETH/USD`** is a *display* name (`Pair.pair`, `AgencyPairStats.pair`), never
+  an id.
+
+The pre-`bid-260602-v2` names `game` / `gameId` / `gamePairId` are retired from
+the public surface.
+
+## Client surface
+
+| Accessor            | Module                  | Auth |
+|---------------------|-------------------------|------|
+| `client.auth`       | `AuthModule`            | — |
+| `client.user`       | `UserModule`            | JWT |
+| `client.pair`       | `PairModule`            | JWT (anon-tolerant) |
+| `client.bid`        | `BidModule`             | JWT |
+| `client.leaderboard`| `LeaderboardModule`     | mixed (see below) |
+| `client.agencyPairs`| `AgencyPairModule`      | anon (`x-builder-code`) |
+| `client.locale`     | `LocaleModule`          | anon |
+| `client.realtime`   | `RealtimeModule \| undefined` | broker creds |
+| `client.network`    | `NetworkQualityMonitor` | — |
+
+Token helpers live on the client itself: `getToken()`, `setToken(token, { isDemo })`,
+`isDemo()`.
+
+> **Anon vs JWT reads.** `agencyPairs.list()`, `leaderboard.list()` and
+> `leaderboard.rankBoard()` deliberately send **`x-builder-code` only, never the
+> JWT**. A signed-in user can hold a JWT for a different agency than the one in
+> context (a builder's demo user is always issued a `taptrading` JWT); attaching
+> it would make the backend take its "JWT wins" branch and return the wrong
+> agency's data.
+
+## Auth
+
+```ts
+await client.auth.loginWithSession(sessionToken); // → LoginResult
+await client.auth.logout();
+```
 
-| Method                          | Transport          | Status      |
-|---------------------------------|--------------------|-------------|
+| Method                           | Transport            | Status        |
+|----------------------------------|----------------------|---------------|
 | `loginWithSession(sessionToken)` | user-service GraphQL | **Preferred** |
-| `createDemoUser(username?)`     | grid-api GraphQL    | Active        |
-| `loginWithGoogle(idToken)`      | grid-api REST       | `@deprecated` |
-| `demoLogin(username?)`          | grid-api REST       | `@deprecated` |
+| `createDemoUser(username?, opts?)` | grid-api GraphQL   | Active        |
+| `loginWithGoogle(idToken)`       | grid-api REST        | `@deprecated` |
+| `demoLogin(username?)`           | grid-api REST        | `@deprecated` |
+
+REST-backed methods continue to work until the gateway retires the routes in a
+follow-up change.
+
+## User
+
+```ts
+const me       = await client.user.me();                          // Me
+const pnl      = await client.user.pnl({ period: 'weekly' });     // UserPnL — 'weekly' | '30d'
+const wallets  = await client.user.wallets();                     // UserWallet[]
+const usdc     = await client.user.walletByCurrency('USDC.e');    // UserWallet
+const enabled  = await client.user.refreshCurrencies();           // Currency[]
+client.user.clearCurrencies();                                    // drop the cached list
+```
+
+`UserPnL` carries `gain` (= `totalPayout − totalWagered`), the wagered/payout
+totals, bid/win counts, and both competition ranks (`pnlRank`, `volRank`; `0`
+means unranked).
+
+> `client.user.wallets()` returns `UserWallet` (`{ id, amount, currency, isEnable }`),
+> which is **not** the `Wallet` returned by the auth module (`{ balance, isEnabled }`).
+> The distinct export alias is deliberate — see the note in `src/index.ts`.
+
+## Pairs
+
+```ts
+const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' }); // PairInfo[]
+const pair  = await client.pair.get('grid-ETH-USD');                              // Pair
+const bars  = await client.pair.chartHistory('grid-ETH-USD');                     // Candle[]
+```
+
+- `get(pairId)` throws `TaphubValidationError` with `code: 'GameNotFound'` when
+  the pair has no configured game for the agency in context. It also feeds the
+  clock-offset estimate (see [Clock sync](#clock-sync)).
+- `chartHistory(pairId, limit?)` defaults to `DEFAULT_CHART_HISTORY_LIMIT` (600);
+  the server clamps any request to its cache size (1500).
+- **`Candle.time` from GraphQL is Unix epoch SECONDS.** The MQTT
+  `MqttCandleEvent.time` is **milliseconds**. Do not multiply the MQTT value.
+- `PairInfo.agencyPairId` is populated only for authenticated callers, and is the
+  value to feed into `realtime.subscribe()`.
+- `Pair.config` carries `gridConfig` (`cellSizeTime`, `cellSizeValue`,
+  `candleSize`, `baseline`, `baselineTime`), `constraints`, bid amount bounds, and
+  the effective cancel policy (`bidCancelMinSeconds`, `bidCancelRefundRate`).
+  Treat `undefined` / `0` on the cancel fields as "use the platform default".
+
+## Bids
+
+```ts
+const bid = await client.bid.placeBid({
+  pairId: 'grid-ETH-USD',
+  walletId,                 // required — grid-api's wallet_id is ID!
+  time1, time2,             // window, unix seconds
+  price1, price2,           // decimal strings
+  coefficient: '2.35',
+  amount: '10',
+  slippage: 5,              // tolerance percent
+});
+
+const result = await client.bid.cancelBid(bid.id);   // { bid, refundAmount, newBalance }
+const mine   = await client.bid.listBids({ statuses: ['pending'], limit: 20, pairId });
+```
+
+`placeBid` auto-stamps `ct` (raw client send time) and `clockOffset` at dispatch
+so the server can record skew-corrected latency into `bid.meta`. Both are
+untrusted tracing data — do not supply them yourself.
+
+`listBids` takes `statuses: BidStatus[]` (include-semantics). The singular
+`status` is `@deprecated` and folded into a one-element list; `statuses` wins when
+both are present.
+
+Status classifiers avoid string-literal typos:
+
+```ts
+import { isPending, isTerminal, isWin, isLoss, isCancelled } from '@taphubhq/sdk-core';
+```
+
+`Bid.refundRate` / `Bid.refundAmount` are present only on cancelled bids. Prefer
+`refundAmount` for display — it is the exact credited value, so it needs no
+recompute from a config rate. `Bid.meta.pairName` holds the display pair frozen
+at placement; read it instead of mapping `pairId` yourself.
+
+## Leaderboard & rank
+
+```ts
+const board = await client.leaderboard.rankBoard({
+  period: 'last_7d',        // 'today' | 'yesterday' | 'last_7d' | 'last_30d' | 'all_time' | 'custom'
+  sort: 'pnl',              // 'pnl' | 'vol'
+  sortDir: 'desc',
+  limit: 50, offset: 0,
+});                          // RankBoard — public, identical for every caller
+
+const me = await client.leaderboard.myRank({ period: 'last_7d' }); // MyRank | null
+```
+
+- `period: 'custom'` requires an **hour-aligned** ISO-8601 UTC `range`.
+- The board carries no per-user data by design (`bid-260606-leaderboard-split-my-rank`)
+  so it stays cacheable — `myRank()` is the per-user companion and does attach
+  the JWT. It returns `null` when nobody is signed in, and `MyRank.entry === null`
+  when the caller has no activity in the window.
+- `leaderboard.list({ period, sortBy })` is the v1 query and is `@deprecated` on
+  both the SDK and the backend.
+
+## Agency pairs (market list)
+
+```ts
+const rows = await client.agencyPairs.list({ filter: { status: 'active' } }); // AgencyPairStats[]
+```
+
+Returns the agency-in-context's pairs with `currentPrice`, `currentVol24h`
+(sliding 24h bid-amount sum), `maxCoef`, `thumb`, and `ordering`. There is no
+argument to target another agency by design. Seed your UI from this call, then
+keep it live with `realtime.subscribeAgencyPairStats()` — the backend suppresses
+unchanged ticks, so a subscriber may receive nothing until price or volume moves.
+
+## Locale & error copy
+
+```ts
+const res = await client.locale.get('vi', lastSeenVersion);
+// → { lang, version, notModified, translations }
+```
+
+Pass the last-seen `version` as `knownVersion` to get `{ notModified: true,
+translations: null }` when the body is unchanged, and keep your prior state.
+
+Error copy is a separate catalog keyed by the backend `extensions.code`:
 
-REST-backed methods continue to work until the gateway retires the routes in a follow-up change.
+```ts
+await client.locale.loadErrorMessages(navigator.language); // never throws
+
+// …later, inside a catch:
+showToast(client.locale.errorMessage(e.code, 'Could not place your bid.'));
+
+// with placeholders filled from the error's meta:
+client.locale.errorMessage('Bid_CoefficientMismatch', 'Odds changed — try again.', {
+  serverCoef: e.serverCoef,
+});
+```
+
+- `loadErrorMessages(lang)` is background hydration: it **never throws and never
+  rejects**. Any failure leaves the last-known-good catalog in place — failing to
+  translate an error must not itself become an error. The tag is normalised
+  (region dropped, Chinese scripts kept apart), and concurrent calls for the same
+  language share one request.
+- `errorMessage(code, fallback, meta?)` is **synchronous by design** — error copy
+  is read inside a `catch`, where React hooks are illegal. It returns `fallback`
+  whenever the catalog cannot produce a usable sentence, never an empty string and
+  never the raw code. `meta` fills `{name}` placeholders; unfilled placeholders are
+  stripped so raw braces never reach the user.
+- `getErrorMessages(lang, knownVersion?)` is the throwing sibling, for callers who
+  want to see why a fetch failed.
+- `refresh()` is an admin operation — the backend re-pulls the source sheet for
+  every supported language and requires an `X-API-Key` header.
+
+## Realtime (MQTT)
+
+`client.realtime` is `undefined` unless `mqttEndpoint` was configured. Channels
+are refcounted: N `subscribe()` calls for the same key return the same channel and
+need N matching `unsubscribe()` calls.
+
+```ts
+const channel = client.realtime?.subscribe(agencyPairId, userId); // GameChannel
+channel?.on('candle', (e) => drawCandle(e));         // MqttCandleEvent
+channel?.on('bidAccepted', (e) => addLiveTrade(e));  // MqttBidAcceptedEvent
+channel?.on('bidWon', (e) => celebrate(e));
+channel?.on('bidLost', (e) => dim(e));
+channel?.on('bidCancelled', (e) => remove(e.bidId));
+channel?.on('balanceUpdate', (e) => setBalance(e.balance));
+channel?.on('configUpdate', (e) => setBidBounds(e));
+channel?.on('idealConfigUpdate', (e) => suggestCellSize(e));
+channel?.on('error', (err) => report(err));
+client.realtime?.unsubscribe(agencyPairId, userId);
+```
+
+| Subscription | Key | Emits |
+|---|---|---|
+| `subscribe(gameId, userId?)` | `agencyPairId` (+ user) | `GameChannel` — candle, bid lifecycle, balance, config |
+| `subscribeWallet(userId)` | `userId` | `WalletChannel` — `walletBalanceUpdate` on **every** balance change, no game context |
+| `subscribeUserBids(userId)` | `userId` | `UserBidsChannel` — `bidWon` / `bidLost` across **all** pairs, survives pair switches |
+| `subscribeCandle(pairId, handler)` | `pairId` | raw `MqttCandleEvent`, market-wide public data |
+| `subscribeAgencyPairStats(pairId, handler)` | `pairId` | `MqttAgencyPairStatsEvent` for the client's own agency |
+
+Each has a matching `unsubscribe*`; `disconnect()` tears everything down.
+
+Gotchas worth reading twice:
+
+- **`MqttCandleEvent.time` is MILLISECONDS**, unlike the GraphQL `Candle.time`
+  (seconds). Compare against `CANDLE_EVENT.NEW` / `CANDLE_EVENT.UPDATE` rather
+  than bare string literals.
+- `volatility` is the **fast** σ that prices coefficients; `slowVolatility` is the
+  slow σ used for grid geometry only.
+- `MqttAcceptedBid` mirrors the wire shape, **not** the GraphQL `Bid`:
+  `coordinates` is nested, `coefficient` / `price1` / `price2` are numbers, and
+  `createdAt` is epoch milliseconds. `gameUuid` is `@deprecated` — read `pairId`.
+- Won/lost payloads carry no pair, so the SDK recovers `pairId` from the result
+  topic. `pairIdFromBidResultTopic(topic)` is exported if you parse topics
+  yourself; it returns `undefined` on an unrecognised shape rather than throwing.
+- `subscribeAgencyPairStats` throws `TaphubError` (`code: 'AgencyIdRequired'`) if
+  the client was built without an `agencyId`.
+- `MqttWalletBalanceEvent.reason` is an open enum — unknown values are passed
+  through rather than dropped, so handle the default case.
+
+## Clock sync
+
+`client.pair.get()` brackets its request to measure RTT and records a one-shot
+server-clock offset. `placeBid` then stamps that offset alongside the raw client
+send time. This is best-effort: the estimate is set-once and finite-guarded, so it
+never throws and never blocks the pair load. Nothing to configure — just be aware
+that a client which never calls `pair.get()` reports an offset of `0`.
 
 ## Error Handling
 
@@ -81,6 +347,9 @@ The GraphQL transport classifies errors by the first entry's `extensions.code` a
 
 `TaphubSlippageError extends TaphubValidationError`, so existing `instanceof TaphubValidationError` catch blocks keep working. Place the `TaphubSlippageError` check first when both branches exist.
 
+To turn a thrown `code` into a user-facing sentence, use
+[`client.locale.errorMessage()`](#locale--error-copy) rather than hardcoding copy.
+
 ### Slippage error fallback
 
 `TaphubSlippageError` is only thrown when `extensions.meta.clientCoef`, `extensions.meta.serverCoef`, and `extensions.meta.slippage` are all finite numbers. The `slippage` field is the client-submitted tolerance percent (e.g. `5` for 5%). If `meta` is missing or malformed, the SDK falls back to a generic `TaphubValidationError` with `code === 'Bid_CoefficientMismatch'`. Consumers SHOULD treat the generic fallback as the same user-facing rejection but without typed coefficient access.
@@ -114,6 +383,79 @@ The monitor is always present, even when `mqttEndpoint` is not configured. In SS
 - Connection samples from `navigator.connection` are used only as a cold-start fallback; once 3 real samples accumulate they no longer contribute to the EMA.
 - MQTT QoS1 `puback` timing is not yet plumbed; v1 derives MQTT signal from `connect` / `reconnect` / `disconnect` events only.
 
+## Events
+
+A small client-wide bus for cross-cutting signals:
+
+```ts
+import type { TaphubEventMap } from '@taphubhq/sdk-core';
+// 'auth-expired'   → void
+// 'network:change' → { previous: NetworkQuality; current: NetworkQuality }
+```
+
+## Storage
+
+Token persistence goes through a 3-method adapter, namespaced per agency
+(`taphub:{agencyId}:token`):
+
+```ts
+import { TaphubStorage, autoDetectStorage } from '@taphubhq/sdk-core';
+
+new TaphubClient({ ..., storage: TaphubStorage.memory() }); // SSR / tests
+```
+
+`autoDetectStorage()` is the default: `localStorage` in the browser, in-memory
+elsewhere. Implement `TaphubStorageAdapter` (`get` / `set` / `remove`) for
+anything else.
+
+## Coefficient math
+
+`placeBid` takes a `coefficient`, so a headless client has to compute one before it
+can bid. `calculateCoefficientWrapper` is the model the server validates against —
+the same first-passage computation the grid chart renders with, and the same one
+grid-api runs at placement:
+
+```ts
+import {
+  calculateCoefficientWrapper,
+  type CoefficientInput,
+} from '@taphubhq/sdk-core';
+
+const coefficient = calculateCoefficientWrapper({
+  time1, time2, price1, price2,          // the cell you are bidding on
+  candleTime, candleClose, volatility,   // the live candle
+  coefMults, minCoef,                    // from pair.config
+  cellSizeTime, candleSize,              // from pair.config
+});
+```
+
+A return of `Number.POSITIVE_INFINITY` means the cell cannot be priced right now —
+do not pass it to `placeBid`.
+
+The server stays authoritative: a value that disagrees beyond your `slippage`
+tolerance is rejected with `Bid_CoefficientMismatch` (see
+[Slippage error fallback](#slippage-error-fallback)).
+
+**Candle-interval variants.** `candleSize` is part of `CoefficientInput` but does not
+enter the coefficient: the cell width is measured in bars (`cellSizeTime`), and
+`calculateProbHit` already prices the real seconds window, so dividing by
+`candleSize` a second time would double-penalise the 1m/5m variants by roughly
+60×/300× (`bid-260703`). Pass the value from `pair.config` anyway —
+`computeBaseline` uses it.
+
+### Deprecated helpers
+
+`calculateProbWin` and `calculateProbWin_v2` are **deprecated**. They compute a
+one-sided exceedance probability and ignore `price1`, so they do not match the model
+placement validates against. A coefficient derived from them can pass the
+server's one-directional slippage check and lock a lower payout than the cell is
+worth. Use `calculateCoefficientWrapper`. They remain exported, unchanged, for
+existing callers.
+
+The lower-level pieces — `calculateProbHit`, `roundCoefToSignificantDigits`,
+`computeBaseline`, `normalCDF`, `normalPDF`, `errorFunction`, `adaptiveSimpson` —
+are also exported for consumers that need to build on them directly.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -33,6 +33,8 @@ __export(index_exports, {
   AgencyPairModule: () => AgencyPairModule,
   AuthModule: () => AuthModule,
   BidModule: () => BidModule,
+  CANDLE_EVENT: () => CANDLE_EVENT,
+  DEFAULT_CHART_HISTORY_LIMIT: () => DEFAULT_CHART_HISTORY_LIMIT,
   LeaderboardModule: () => LeaderboardModule,
   LocaleModule: () => LocaleModule,
   NetworkQualityMonitor: () => NetworkQualityMonitor,
@@ -50,8 +52,11 @@ __export(index_exports, {
   UserModule: () => UserModule,
   adaptiveSimpson: () => adaptiveSimpson,
   autoDetectStorage: () => autoDetectStorage,
+  calculateCoefficientWrapper: () => calculateCoefficientWrapper,
+  calculateProbHit: () => calculateProbHit,
   calculateProbWin: () => calculateProbWin,
   calculateProbWin_v2: () => calculateProbWin_v2,
+  computeBaseline: () => computeBaseline,
   errorFunction: () => errorFunction,
   isCancelled: () => isCancelled,
   isLoss: () => isLoss,
@@ -61,7 +66,8 @@ __export(index_exports, {
   normalCDF: () => normalCDF,
   normalPDF: () => normalPDF,
   normaliseLang: () => normaliseLang,
-  pairIdFromBidResultTopic: () => pairIdFromBidResultTopic
+  pairIdFromBidResultTopic: () => pairIdFromBidResultTopic,
+  roundCoefToSignificantDigits: () => roundCoefToSignificantDigits
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1147,6 +1153,9 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
   }
 }`;
 
+// src/modules/pair/types.ts
+var DEFAULT_CHART_HISTORY_LIMIT = 600;
+
 // src/modules/pair/index.ts
 var PairModule = class {
   #graphql;
@@ -1204,11 +1213,8 @@ var PairModule = class {
     return body.builderAvailableGamePairs.map(normalisePairInfo);
   }
   // REVIEW[bid-260602-v2]: chartHistory param/variable renamed pairId (was: agencyPairId/gameId)
-  async chartHistory(pairId, limit, opts) {
-    const variables = { pairId };
-    if (limit !== void 0) {
-      variables.limit = limit;
-    }
+  async chartHistory(pairId, limit = DEFAULT_CHART_HISTORY_LIMIT, opts) {
+    const variables = { pairId, limit };
     const body = await this.#graphql.request(
       CHART_HISTORY_QUERY,
       variables,
@@ -3159,6 +3165,12 @@ var TaphubClient = class {
   }
 };
 
+// src/modules/realtime/types.ts
+var CANDLE_EVENT = {
+  NEW: "new",
+  UPDATE: "update"
+};
+
 // src/utils/coefficient.ts
 function errorFunction(x) {
   const a1 = 0.254829592;
@@ -3243,11 +3255,122 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   const prob = 1 - normalCDF(z);
   return Math.max(0, Math.min(1, prob));
 }
+function simpsonForHit(f, a, b, eps = 3e-5, maxDepth = 14) {
+  function simpsonRule(a2, b2) {
+    const c = (a2 + b2) / 2;
+    const h = b2 - a2;
+    return h / 6 * (f(a2) + 4 * f(c) + f(b2));
+  }
+  function recurse(a2, b2, eps2, whole2, depth) {
+    const c = (a2 + b2) / 2;
+    const left = simpsonRule(a2, c);
+    const right = simpsonRule(c, b2);
+    if (depth >= maxDepth || Math.abs(left + right - whole2) <= 15 * eps2) {
+      return left + right + (left + right - whole2) / 15;
+    }
+    return recurse(a2, c, eps2 / 2, left, depth + 1) + recurse(c, b2, eps2 / 2, right, depth + 1);
+  }
+  const whole = simpsonRule(a, b);
+  return recurse(a, b, eps, whole, 0);
+}
+function calculateProbHit(time1, time2, price1, price2, creationTime, currentPrice, volatility) {
+  if (volatility <= 0 || currentPrice <= 0) return 0;
+  const sigma = volatility;
+  const L = Math.log(price1 / currentPrice);
+  const U = Math.log(price2 / currentPrice);
+  let T1 = time1 - creationTime;
+  if (T1 < 0) T1 = 0;
+  const dT = time2 - time1;
+  if (dT <= 0) return 0;
+  let probInside;
+  if (T1 <= 0) {
+    probInside = currentPrice >= price1 && currentPrice <= price2 ? 1 : 0;
+  } else {
+    const sqrtT12 = Math.sqrt(T1);
+    const sigSqrtT12 = sigma * sqrtT12;
+    if (sigSqrtT12 < 1e-12) {
+      probInside = currentPrice >= price1 && currentPrice <= price2 ? 1 : 0;
+    } else {
+      probInside = normalCDF(U / sigSqrtT12) - normalCDF(L / sigSqrtT12);
+    }
+  }
+  if (T1 <= 0) {
+    return Math.max(0, Math.min(1, probInside));
+  }
+  const sqrtT1 = Math.sqrt(T1);
+  const sigSqrtT1 = sigma * sqrtT1;
+  const sqrtRatio = Math.sqrt(T1 / dT);
+  const sigSqrtDT = sigma * Math.sqrt(dT);
+  const zU = U / sigSqrtT1;
+  const integrandAbove = (z) => {
+    return 2 * normalCDF(U / sigSqrtDT - z * sqrtRatio) * normalPDF(z);
+  };
+  const pFromAbove = simpsonForHit(integrandAbove, zU, zU + 7, 3e-5, 14);
+  const zL = L / sigSqrtT1;
+  const integrandBelow = (z) => {
+    return 2 * normalCDF(z * sqrtRatio - L / sigSqrtDT) * normalPDF(z);
+  };
+  const pFromBelow = simpsonForHit(integrandBelow, zL - 7, zL, 3e-5, 14);
+  const result = probInside + pFromAbove + pFromBelow;
+  return Math.max(0, Math.min(1, result));
+}
+function calculateCoefficientWrapper(params) {
+  const {
+    time1,
+    time2,
+    price1,
+    price2,
+    candleTime,
+    candleClose,
+    volatility,
+    coefMults,
+    cellSizeTime,
+    minCoef
+  } = params;
+  const currentPrice = candleClose;
+  const creationTime = candleTime;
+  const probability = calculateProbHit(
+    time1,
+    time2,
+    price1,
+    price2,
+    creationTime,
+    currentPrice,
+    volatility
+  );
+  if (probability <= 0) return Number.POSITIVE_INFINITY;
+  const rawCoef = 1 / probability;
+  const rawIndex = rawCoef < 1 ? 0 : Math.floor(Math.log2(rawCoef));
+  const coefMultIndex = Math.min(rawIndex, coefMults.length - 1);
+  const multiplier = coefMults[coefMultIndex] || 1;
+  const timeRatio = cellSizeTime;
+  const adjustedProb = probability * (timeRatio / 5);
+  if (adjustedProb <= 0) return Number.POSITIVE_INFINITY;
+  const floor = typeof minCoef === "number" && minCoef > 0 ? minCoef : 1;
+  const finalCoef = Math.max(floor, multiplier / adjustedProb);
+  return roundCoefToSignificantDigits(finalCoef);
+}
+function roundCoefToSignificantDigits(value) {
+  if (!Number.isFinite(value) || value <= 0) return value;
+  const magnitude = Math.floor(Math.log10(value));
+  const leadingDigit = Math.floor(value / 10 ** magnitude);
+  const sigDigits = leadingDigit === 1 ? 3 : 2;
+  const factor = 10 ** (sigDigits - magnitude - 1);
+  return Math.round(value * factor) / factor;
+}
+function computeBaseline(candleClose, candleTimeSec, cellSizeValue, cellSizeTime, candleSize) {
+  const baseline = Math.floor(candleClose / cellSizeValue) * cellSizeValue;
+  const cellSizeTimeSec = candleSize * cellSizeTime;
+  const baselineTime = Math.floor(candleTimeSec / cellSizeTimeSec) * cellSizeTimeSec + 0.5;
+  return { baseline, baselineTime };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgencyPairModule,
   AuthModule,
   BidModule,
+  CANDLE_EVENT,
+  DEFAULT_CHART_HISTORY_LIMIT,
   LeaderboardModule,
   LocaleModule,
   NetworkQualityMonitor,
@@ -3265,8 +3388,11 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   UserModule,
   adaptiveSimpson,
   autoDetectStorage,
+  calculateCoefficientWrapper,
+  calculateProbHit,
   calculateProbWin,
   calculateProbWin_v2,
+  computeBaseline,
   errorFunction,
   isCancelled,
   isLoss,
@@ -3276,5 +3402,6 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   normalCDF,
   normalPDF,
   normaliseLang,
-  pairIdFromBidResultTopic
+  pairIdFromBidResultTopic,
+  roundCoefToSignificantDigits
 });

package/dist/index.d.mts

@@ -709,6 +709,13 @@ interface PairInfo {
      */
     agencyPairId: string | null;
 }
+/**
+ * Default number of candles fetched on initial chart load when the caller does
+ * not pass an explicit limit. The server clamps any request to its cache size
+ * (grid-api services.ChartHistoryMaxLimit = 1500), so this is purely how much
+ * history the chart shows by default — kept lower than the cap for faster init.
+ */
+declare const DEFAULT_CHART_HISTORY_LIMIT = 600;
 interface Candle {
     /** Unix epoch SECONDS (not ms). Multiply by 1000 for JS Date. */
     time: number;
@@ -906,6 +913,16 @@ interface MqttTransport {
     close(): void;
 }
 
+/**
+ * Candle tick kind. `new` = a fresh bar opened; `update` = the current bar was
+ * revised. Exported as named constants so consumers compare against these
+ * instead of bare string literals (a typo on a literal fails silently).
+ */
+declare const CANDLE_EVENT: {
+    readonly NEW: "new";
+    readonly UPDATE: "update";
+};
+type CandleEventType = (typeof CANDLE_EVENT)[keyof typeof CANDLE_EVENT];
 /**
  * Candle tick from MQTT.
  * WARNING: `time` is Unix epoch MILLISECONDS.
@@ -913,7 +930,7 @@ interface MqttTransport {
  * Do NOT multiply MQTT candle time by 1000.
  */
 interface MqttCandleEvent {
-    type: 'new' | 'update';
+    type: CandleEventType;
     /** Unix epoch **milliseconds** — differs from GQL chartHistory (seconds) */
     time: number;
     o: number;
@@ -1412,7 +1429,75 @@ declare function errorFunction(x: number): number;
 declare function normalCDF(x: number): number;
 declare function normalPDF(x: number): number;
 declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number, tolerance?: number, maxDepth?: number): number;
+/**
+ * @deprecated Does NOT match the model grid-api validates a bid against. Use
+ * {@link calculateCoefficientWrapper} to derive the `coefficient` argument for
+ * `placeBid`.
+ *
+ * This computes a one-sided exceedance probability — roughly "will the price end up
+ * past `price2`" — and takes `price1` without using it. The game pays out when the
+ * price *visits the band* `[price1, price2]`, which is a first-passage probability;
+ * {@link calculateProbHit} computes that one. Measured against grid-api's reference
+ * inputs, this function returns only 1.0, 0.5 or 0.0 and does not move at all when
+ * `price1` goes from 2869.75 to 2800.00.
+ *
+ * The consequence is not a rejected bid. `placeBid`'s slippage check is
+ * one-directional — it rejects a coefficient *higher* than the server's, never a
+ * lower one — so a coefficient derived from this function (e.g. 1.0 where the server
+ * computes 6.1) is accepted and locked, and the player is paid at the lower
+ * coefficient on a win, with no error raised anywhere.
+ *
+ * Retained unchanged because it is published API (TH-491, Add-Deprecate-Remove).
+ */
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+/**
+ * @deprecated Does NOT match the model grid-api validates a bid against. Use
+ * {@link calculateCoefficientWrapper} to derive the `coefficient` argument for
+ * `placeBid`.
+ *
+ * This computes a one-sided exceedance probability — roughly "will the price end up
+ * past `price2`" — and takes `price1` without using it. The game pays out when the
+ * price *visits the band* `[price1, price2]`, which is a first-passage probability;
+ * {@link calculateProbHit} computes that one. Measured against grid-api's reference
+ * inputs, this function returns only 1.0, 0.5 or 0.0 and does not move at all when
+ * `price1` goes from 2869.75 to 2800.00.
+ *
+ * The consequence is not a rejected bid. `placeBid`'s slippage check is
+ * one-directional — it rejects a coefficient *higher* than the server's, never a
+ * lower one — so a coefficient derived from this function (e.g. 1.0 where the server
+ * computes 6.1) is accepted and locked, and the player is paid at the lower
+ * coefficient on a win, with no error raised anywhere.
+ *
+ * Retained unchanged because it is published API (TH-491, Add-Deprecate-Remove).
+ */
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+interface CoefficientInput {
+    time1: number;
+    time2: number;
+    price1: number;
+    price2: number;
+    candleTime: number;
+    candleClose: number;
+    volatility: number;
+    coefMults: number[];
+    cellSizeTime: number;
+    candleSize: number;
+    minCoef?: number;
+}
+/**
+ * First-passage hitting probability: chance the price visits [price1, price2]
+ * at any point during [time1, time2], given GBM dynamics.
+ *
+ * P_hit = P_inside + P_from_above + P_from_below
+ *
+ * Matches Go backend algorithm.
+ */
+declare function calculateProbHit(time1: number, time2: number, price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+declare function calculateCoefficientWrapper(params: CoefficientInput): number;
+declare function roundCoefToSignificantDigits(value: number): number;
+declare function computeBaseline(candleClose: number, candleTimeSec: number, cellSizeValue: number, cellSizeTime: number, candleSize: number): {
+    baseline: number;
+    baselineTime: number;
+};
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, type ErrorMessageCatalog, type ErrorMessageMeta, type ErrorMessagesResponse, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttAuthConfig, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserBidsChannel, type UserBidsChannelEvents, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, normaliseLang, pairIdFromBidResultTopic };
+export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, CANDLE_EVENT, type CancelBidResult, type Candle, type CandleEventType, type CoefficientInput, type Constraints, type Currency, DEFAULT_CHART_HISTORY_LIMIT, type ErrorMessageCatalog, type ErrorMessageMeta, type ErrorMessagesResponse, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttAuthConfig, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserBidsChannel, type UserBidsChannelEvents, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateCoefficientWrapper, calculateProbHit, calculateProbWin, calculateProbWin_v2, computeBaseline, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, normaliseLang, pairIdFromBidResultTopic, roundCoefToSignificantDigits };

package/dist/index.d.ts

@@ -709,6 +709,13 @@ interface PairInfo {
      */
     agencyPairId: string | null;
 }
+/**
+ * Default number of candles fetched on initial chart load when the caller does
+ * not pass an explicit limit. The server clamps any request to its cache size
+ * (grid-api services.ChartHistoryMaxLimit = 1500), so this is purely how much
+ * history the chart shows by default — kept lower than the cap for faster init.
+ */
+declare const DEFAULT_CHART_HISTORY_LIMIT = 600;
 interface Candle {
     /** Unix epoch SECONDS (not ms). Multiply by 1000 for JS Date. */
     time: number;
@@ -906,6 +913,16 @@ interface MqttTransport {
     close(): void;
 }
 
+/**
+ * Candle tick kind. `new` = a fresh bar opened; `update` = the current bar was
+ * revised. Exported as named constants so consumers compare against these
+ * instead of bare string literals (a typo on a literal fails silently).
+ */
+declare const CANDLE_EVENT: {
+    readonly NEW: "new";
+    readonly UPDATE: "update";
+};
+type CandleEventType = (typeof CANDLE_EVENT)[keyof typeof CANDLE_EVENT];
 /**
  * Candle tick from MQTT.
  * WARNING: `time` is Unix epoch MILLISECONDS.
@@ -913,7 +930,7 @@ interface MqttTransport {
  * Do NOT multiply MQTT candle time by 1000.
  */
 interface MqttCandleEvent {
-    type: 'new' | 'update';
+    type: CandleEventType;
     /** Unix epoch **milliseconds** — differs from GQL chartHistory (seconds) */
     time: number;
     o: number;
@@ -1412,7 +1429,75 @@ declare function errorFunction(x: number): number;
 declare function normalCDF(x: number): number;
 declare function normalPDF(x: number): number;
 declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number, tolerance?: number, maxDepth?: number): number;
+/**
+ * @deprecated Does NOT match the model grid-api validates a bid against. Use
+ * {@link calculateCoefficientWrapper} to derive the `coefficient` argument for
+ * `placeBid`.
+ *
+ * This computes a one-sided exceedance probability — roughly "will the price end up
+ * past `price2`" — and takes `price1` without using it. The game pays out when the
+ * price *visits the band* `[price1, price2]`, which is a first-passage probability;
+ * {@link calculateProbHit} computes that one. Measured against grid-api's reference
+ * inputs, this function returns only 1.0, 0.5 or 0.0 and does not move at all when
+ * `price1` goes from 2869.75 to 2800.00.
+ *
+ * The consequence is not a rejected bid. `placeBid`'s slippage check is
+ * one-directional — it rejects a coefficient *higher* than the server's, never a
+ * lower one — so a coefficient derived from this function (e.g. 1.0 where the server
+ * computes 6.1) is accepted and locked, and the player is paid at the lower
+ * coefficient on a win, with no error raised anywhere.
+ *
+ * Retained unchanged because it is published API (TH-491, Add-Deprecate-Remove).
+ */
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+/**
+ * @deprecated Does NOT match the model grid-api validates a bid against. Use
+ * {@link calculateCoefficientWrapper} to derive the `coefficient` argument for
+ * `placeBid`.
+ *
+ * This computes a one-sided exceedance probability — roughly "will the price end up
+ * past `price2`" — and takes `price1` without using it. The game pays out when the
+ * price *visits the band* `[price1, price2]`, which is a first-passage probability;
+ * {@link calculateProbHit} computes that one. Measured against grid-api's reference
+ * inputs, this function returns only 1.0, 0.5 or 0.0 and does not move at all when
+ * `price1` goes from 2869.75 to 2800.00.
+ *
+ * The consequence is not a rejected bid. `placeBid`'s slippage check is
+ * one-directional — it rejects a coefficient *higher* than the server's, never a
+ * lower one — so a coefficient derived from this function (e.g. 1.0 where the server
+ * computes 6.1) is accepted and locked, and the player is paid at the lower
+ * coefficient on a win, with no error raised anywhere.
+ *
+ * Retained unchanged because it is published API (TH-491, Add-Deprecate-Remove).
+ */
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+interface CoefficientInput {
+    time1: number;
+    time2: number;
+    price1: number;
+    price2: number;
+    candleTime: number;
+    candleClose: number;
+    volatility: number;
+    coefMults: number[];
+    cellSizeTime: number;
+    candleSize: number;
+    minCoef?: number;
+}
+/**
+ * First-passage hitting probability: chance the price visits [price1, price2]
+ * at any point during [time1, time2], given GBM dynamics.
+ *
+ * P_hit = P_inside + P_from_above + P_from_below
+ *
+ * Matches Go backend algorithm.
+ */
+declare function calculateProbHit(time1: number, time2: number, price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
+declare function calculateCoefficientWrapper(params: CoefficientInput): number;
+declare function roundCoefToSignificantDigits(value: number): number;
+declare function computeBaseline(candleClose: number, candleTimeSec: number, cellSizeValue: number, cellSizeTime: number, candleSize: number): {
+    baseline: number;
+    baselineTime: number;
+};
 
-export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, type CancelBidResult, type Candle, type Constraints, type Currency, type ErrorMessageCatalog, type ErrorMessageMeta, type ErrorMessagesResponse, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttAuthConfig, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserBidsChannel, type UserBidsChannelEvents, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, normaliseLang, pairIdFromBidResultTopic };
+export { type AgencyPairFilter, AgencyPairModule, type AgencyPairStats, type AgencyPairStatus, AuthModule, type BackendHealth, type Bid, BidModule, type BidStatus, CANDLE_EVENT, type CancelBidResult, type Candle, type CandleEventType, type CoefficientInput, type Constraints, type Currency, DEFAULT_CHART_HISTORY_LIMIT, type ErrorMessageCatalog, type ErrorMessageMeta, type ErrorMessagesResponse, GameChannel, type GameConfig, type GridConfig, type LeaderboardEntry, LeaderboardModule, type LeaderboardPeriod, type LeaderboardSortBy, LocaleModule, type LocaleRefreshResult, type LocaleResponse, type LocaleTranslations, type LoginResult, type Me, type MqttAcceptedBid, type MqttAgencyPairStatsEvent, type MqttAuthConfig, type MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type MyRank, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type Pair, type PairInfo, PairModule, type PlaceBidInput, type RankBoard, type RankEntry, type RankPeriod, type RankSort, RealtimeModule, type Sample, type SampleReason, type SignalSource, type SortDir, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserBidsChannel, type UserBidsChannelEvents, UserModule, type UserPnL, type UserPnLPeriod, type Wallet as UserWallet, type Wallet$1 as Wallet, type WalletBalanceReason, WalletChannel, adaptiveSimpson, autoDetectStorage, calculateCoefficientWrapper, calculateProbHit, calculateProbWin, calculateProbWin_v2, computeBaseline, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF, normaliseLang, pairIdFromBidResultTopic, roundCoefToSignificantDigits };

package/dist/index.js

@@ -1080,6 +1080,9 @@ var BUILDER_AVAILABLE_GAME_PAIRS_QUERY = `query BuilderAvailableGamePairs($gamep
   }
 }`;
 
+// src/modules/pair/types.ts
+var DEFAULT_CHART_HISTORY_LIMIT = 600;
+
 // src/modules/pair/index.ts
 var PairModule = class {
   #graphql;
@@ -1137,11 +1140,8 @@ var PairModule = class {
     return body.builderAvailableGamePairs.map(normalisePairInfo);
   }
   // REVIEW[bid-260602-v2]: chartHistory param/variable renamed pairId (was: agencyPairId/gameId)
-  async chartHistory(pairId, limit, opts) {
-    const variables = { pairId };
-    if (limit !== void 0) {
-      variables.limit = limit;
-    }
+  async chartHistory(pairId, limit = DEFAULT_CHART_HISTORY_LIMIT, opts) {
+    const variables = { pairId, limit };
     const body = await this.#graphql.request(
       CHART_HISTORY_QUERY,
       variables,
@@ -3092,6 +3092,12 @@ var TaphubClient = class {
   }
 };
 
+// src/modules/realtime/types.ts
+var CANDLE_EVENT = {
+  NEW: "new",
+  UPDATE: "update"
+};
+
 // src/utils/coefficient.ts
 function errorFunction(x) {
   const a1 = 0.254829592;
@@ -3176,10 +3182,121 @@ function calculateProbWin_v2(time1, time2, _price1, price2, creationTime, curren
   const prob = 1 - normalCDF(z);
   return Math.max(0, Math.min(1, prob));
 }
+function simpsonForHit(f, a, b, eps = 3e-5, maxDepth = 14) {
+  function simpsonRule(a2, b2) {
+    const c = (a2 + b2) / 2;
+    const h = b2 - a2;
+    return h / 6 * (f(a2) + 4 * f(c) + f(b2));
+  }
+  function recurse(a2, b2, eps2, whole2, depth) {
+    const c = (a2 + b2) / 2;
+    const left = simpsonRule(a2, c);
+    const right = simpsonRule(c, b2);
+    if (depth >= maxDepth || Math.abs(left + right - whole2) <= 15 * eps2) {
+      return left + right + (left + right - whole2) / 15;
+    }
+    return recurse(a2, c, eps2 / 2, left, depth + 1) + recurse(c, b2, eps2 / 2, right, depth + 1);
+  }
+  const whole = simpsonRule(a, b);
+  return recurse(a, b, eps, whole, 0);
+}
+function calculateProbHit(time1, time2, price1, price2, creationTime, currentPrice, volatility) {
+  if (volatility <= 0 || currentPrice <= 0) return 0;
+  const sigma = volatility;
+  const L = Math.log(price1 / currentPrice);
+  const U = Math.log(price2 / currentPrice);
+  let T1 = time1 - creationTime;
+  if (T1 < 0) T1 = 0;
+  const dT = time2 - time1;
+  if (dT <= 0) return 0;
+  let probInside;
+  if (T1 <= 0) {
+    probInside = currentPrice >= price1 && currentPrice <= price2 ? 1 : 0;
+  } else {
+    const sqrtT12 = Math.sqrt(T1);
+    const sigSqrtT12 = sigma * sqrtT12;
+    if (sigSqrtT12 < 1e-12) {
+      probInside = currentPrice >= price1 && currentPrice <= price2 ? 1 : 0;
+    } else {
+      probInside = normalCDF(U / sigSqrtT12) - normalCDF(L / sigSqrtT12);
+    }
+  }
+  if (T1 <= 0) {
+    return Math.max(0, Math.min(1, probInside));
+  }
+  const sqrtT1 = Math.sqrt(T1);
+  const sigSqrtT1 = sigma * sqrtT1;
+  const sqrtRatio = Math.sqrt(T1 / dT);
+  const sigSqrtDT = sigma * Math.sqrt(dT);
+  const zU = U / sigSqrtT1;
+  const integrandAbove = (z) => {
+    return 2 * normalCDF(U / sigSqrtDT - z * sqrtRatio) * normalPDF(z);
+  };
+  const pFromAbove = simpsonForHit(integrandAbove, zU, zU + 7, 3e-5, 14);
+  const zL = L / sigSqrtT1;
+  const integrandBelow = (z) => {
+    return 2 * normalCDF(z * sqrtRatio - L / sigSqrtDT) * normalPDF(z);
+  };
+  const pFromBelow = simpsonForHit(integrandBelow, zL - 7, zL, 3e-5, 14);
+  const result = probInside + pFromAbove + pFromBelow;
+  return Math.max(0, Math.min(1, result));
+}
+function calculateCoefficientWrapper(params) {
+  const {
+    time1,
+    time2,
+    price1,
+    price2,
+    candleTime,
+    candleClose,
+    volatility,
+    coefMults,
+    cellSizeTime,
+    minCoef
+  } = params;
+  const currentPrice = candleClose;
+  const creationTime = candleTime;
+  const probability = calculateProbHit(
+    time1,
+    time2,
+    price1,
+    price2,
+    creationTime,
+    currentPrice,
+    volatility
+  );
+  if (probability <= 0) return Number.POSITIVE_INFINITY;
+  const rawCoef = 1 / probability;
+  const rawIndex = rawCoef < 1 ? 0 : Math.floor(Math.log2(rawCoef));
+  const coefMultIndex = Math.min(rawIndex, coefMults.length - 1);
+  const multiplier = coefMults[coefMultIndex] || 1;
+  const timeRatio = cellSizeTime;
+  const adjustedProb = probability * (timeRatio / 5);
+  if (adjustedProb <= 0) return Number.POSITIVE_INFINITY;
+  const floor = typeof minCoef === "number" && minCoef > 0 ? minCoef : 1;
+  const finalCoef = Math.max(floor, multiplier / adjustedProb);
+  return roundCoefToSignificantDigits(finalCoef);
+}
+function roundCoefToSignificantDigits(value) {
+  if (!Number.isFinite(value) || value <= 0) return value;
+  const magnitude = Math.floor(Math.log10(value));
+  const leadingDigit = Math.floor(value / 10 ** magnitude);
+  const sigDigits = leadingDigit === 1 ? 3 : 2;
+  const factor = 10 ** (sigDigits - magnitude - 1);
+  return Math.round(value * factor) / factor;
+}
+function computeBaseline(candleClose, candleTimeSec, cellSizeValue, cellSizeTime, candleSize) {
+  const baseline = Math.floor(candleClose / cellSizeValue) * cellSizeValue;
+  const cellSizeTimeSec = candleSize * cellSizeTime;
+  const baselineTime = Math.floor(candleTimeSec / cellSizeTimeSec) * cellSizeTimeSec + 0.5;
+  return { baseline, baselineTime };
+}
 export {
   AgencyPairModule,
   AuthModule,
   BidModule,
+  CANDLE_EVENT,
+  DEFAULT_CHART_HISTORY_LIMIT,
   LeaderboardModule,
   LocaleModule,
   NetworkQualityMonitor,
@@ -3197,8 +3314,11 @@ export {
   UserModule,
   adaptiveSimpson,
   autoDetectStorage,
+  calculateCoefficientWrapper,
+  calculateProbHit,
   calculateProbWin,
   calculateProbWin_v2,
+  computeBaseline,
   errorFunction,
   isCancelled,
   isLoss,
@@ -3208,5 +3328,6 @@ export {
   normalCDF,
   normalPDF,
   normaliseLang,
-  pairIdFromBidResultTopic
+  pairIdFromBidResultTopic,
+  roundCoefToSignificantDigits
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taphubhq/sdk-core",
-  "version": "0.25.4",
+  "version": "0.25.6",
   "description": "Core SDK for building on the TabHub platform",
   "license": "MIT",
   "main": "./dist/index.cjs",