@taphubhq/sdk-core 0.15.0 → 0.15.2

package/dist/index.cjs

@@ -885,6 +885,10 @@ var GAME_SCOPED_SUFFIXES = ["config", "ideal_config"];
 var USER_SCOPED_SUFFIXES = ["bid_result", "balance_update"];
 var TOPIC_PREFIX = "game";
 var MARKET_TOPIC_PREFIX = "market";
+var WALLET_TOPIC_PREFIX = "wallet";
+function walletBalanceTopic(userId) {
+  return `${WALLET_TOPIC_PREFIX}/users/${userId}/balance`;
+}
 function agencyPairStatsTopic(aid, gamePairId) {
   return `public/agency/${aid}/pair/${gamePairId}/stats`;
 }
@@ -905,6 +909,7 @@ function createMqttTransport(endpoint, opts = {}) {
   const subscriptions = /* @__PURE__ */ new Map();
   const candleSubscriptions = /* @__PURE__ */ new Map();
   const statsSubscriptions = /* @__PURE__ */ new Map();
+  const walletSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -973,6 +978,18 @@ function createMqttTransport(endpoint, opts = {}) {
         statsSub.onStats(receivedTopic, payload2);
         return;
       }
+      const walletSub = [...walletSubscriptions.values()].find((s) => s.topic === receivedTopic);
+      if (walletSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          walletSub.onError(new Error(`Invalid JSON on topic ${receivedTopic}`));
+          return;
+        }
+        walletSub.onMessage(receivedTopic, payload2);
+        return;
+      }
       let matched;
       for (const sub of subscriptions.values()) {
         if (sub.topics.includes(receivedTopic)) {
@@ -1047,6 +1064,19 @@ function createMqttTransport(endpoint, opts = {}) {
       if (client) client.unsubscribe(entry.topic);
       statsSubscriptions.delete(topic);
     },
+    subscribeWallet(userId, onMessage, onError) {
+      if (walletSubscriptions.has(userId)) return;
+      const topic = walletBalanceTopic(userId);
+      const mqttClient = ensureConnected();
+      walletSubscriptions.set(userId, { topic, onMessage, onError });
+      mqttClient.subscribe(topic, { qos: 0 });
+    },
+    unsubscribeWallet(userId) {
+      const entry = walletSubscriptions.get(userId);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      walletSubscriptions.delete(userId);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -1084,10 +1114,14 @@ function createMqttTransport(endpoint, opts = {}) {
         for (const entry of statsSubscriptions.values()) {
           client.unsubscribe(entry.topic);
         }
+        for (const entry of walletSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
       }
       subscriptions.clear();
       candleSubscriptions.clear();
       statsSubscriptions.clear();
+      walletSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1097,7 +1131,7 @@ function createMqttTransport(endpoint, opts = {}) {
 }
 
 // src/modules/realtime/index.ts
-var import_eventemitter32 = __toESM(require("eventemitter3"));
+var import_eventemitter33 = __toESM(require("eventemitter3"));
 
 // src/modules/realtime/GameChannel.ts
 var import_eventemitter3 = __toESM(require("eventemitter3"));
@@ -1109,6 +1143,16 @@ var GameChannel = class extends import_eventemitter3.default {
   }
 };
 
+// src/modules/realtime/WalletChannel.ts
+var import_eventemitter32 = __toESM(require("eventemitter3"));
+var WalletChannel = class extends import_eventemitter32.default {
+  userId;
+  constructor(userId) {
+    super();
+    this.userId = userId;
+  }
+};
+
 // src/modules/realtime/index.ts
 var TOPIC_SUFFIX_CANDLE = "candle";
 var TOPIC_SUFFIX_BID_RESULT = "bid_result";
@@ -1168,6 +1212,16 @@ function mapWireBalanceUpdate(raw) {
     balance: p.balance
   };
 }
+function mapWireWalletBalance(raw) {
+  const p = raw;
+  return {
+    id: p.id,
+    balance: p.balance,
+    reservedAmount: p.reserved_amount,
+    currency: p.currency,
+    reason: p.reason ?? ""
+  };
+}
 function mapWireConfig(raw) {
   const p = raw;
   return {
@@ -1205,9 +1259,11 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-var RealtimeModule = class extends import_eventemitter32.default {
+var RealtimeModule = class extends import_eventemitter33.default {
   #transport;
   #entries = /* @__PURE__ */ new Map();
+  #walletEntries = /* @__PURE__ */ new Map();
+  // keyed by userId
   #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
@@ -1287,6 +1343,56 @@ var RealtimeModule = class extends import_eventemitter32.default {
     target.channel.removeAllListeners();
     this.#transport.unsubscribeAll(gameId, target.userId);
   }
+  /**
+   * Subscribe to the user-scoped wallet balance stream for `userId`, topic
+   * `wallet/users/{userId}/balance`. Returns a `WalletChannel` that emits
+   * `walletBalanceUpdate` on every balance change (deposit / transfer / refund /
+   * reserve / commit / cancel / bid settlement) — independent of any game.
+   *
+   * Reference-counted by `userId`, mirroring `subscribe`/`unsubscribe`: repeat
+   * calls return the same channel and the topic is torn down only when balanced
+   * `unsubscribeWallet` calls bring the count to zero. The wallet lifecycle is
+   * fully independent of game subscriptions.
+   */
+  subscribeWallet(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) {
+      throw new TaphubError("userId is required to subscribe to wallet balance", {
+        code: "UserIdRequired"
+      });
+    }
+    const existing = this.#walletEntries.get(cleanUserId);
+    if (existing) {
+      existing.refcount += 1;
+      return existing.channel;
+    }
+    const channel = new WalletChannel(cleanUserId);
+    const onMessage = (_topic, payload) => {
+      channel.emit("walletBalanceUpdate", mapWireWalletBalance(payload));
+    };
+    const onError = (err) => {
+      channel.emit("error", err);
+    };
+    this.#walletEntries.set(cleanUserId, { userId: cleanUserId, channel, refcount: 1 });
+    this.#transport.subscribeWallet(cleanUserId, onMessage, onError);
+    return channel;
+  }
+  /**
+   * Decrement the wallet subscription refcount for `userId`. Tears down the MQTT
+   * topic and removes the `WalletChannel` only when the count reaches zero.
+   * No-op if there is no active wallet subscription for `userId`.
+   */
+  unsubscribeWallet(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) return;
+    const entry = this.#walletEntries.get(cleanUserId);
+    if (!entry) return;
+    entry.refcount -= 1;
+    if (entry.refcount > 0) return;
+    this.#walletEntries.delete(cleanUserId);
+    entry.channel.removeAllListeners();
+    this.#transport.unsubscribeWallet(cleanUserId);
+  }
   /**
    * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
    * Independent of game/agency — candle is market-wide public data.
@@ -1330,6 +1436,10 @@ var RealtimeModule = class extends import_eventemitter32.default {
       entry.channel.removeAllListeners();
     }
     this.#entries.clear();
+    for (const entry of this.#walletEntries.values()) {
+      entry.channel.removeAllListeners();
+    }
+    this.#walletEntries.clear();
     this.#transport.close();
   }
 };
@@ -1398,11 +1508,30 @@ function normaliseMyWalletByCurrencyResponse(body) {
   }
   return normaliseWalletNode(body.myWalletByCurrency);
 }
+function normaliseUserPnL(node) {
+  if (!node) {
+    throw new TaphubServerError("Invalid response from server", {
+      code: "InvalidResponse"
+    });
+  }
+  return {
+    gain: node.gain,
+    totalWagered: node.total_wagered,
+    totalPayout: node.total_payout,
+    totalBids: node.total_bids,
+    totalWins: node.total_wins
+  };
+}
 
 // src/modules/user/queries.ts
 var ME_QUERY = "query Me { me { id username wallet_address balance is_demo } }";
 var MY_WALLETS_QUERY = "query MyWallets { myWallets { id amount currency isEnable } }";
 var MY_WALLET_BY_CURRENCY_QUERY = "query MyWalletByCurrency($currency: String!) { myWalletByCurrency(currency: $currency) { id amount currency isEnable } }";
+var USER_PNL_QUERY = `query UserPnL($period: String) {
+  userPnL(period: $period) {
+    gain total_wagered total_payout total_bids total_wins
+  }
+}`;
 
 // src/modules/user/index.ts
 var UserModule = class {
@@ -1419,6 +1548,20 @@ var UserModule = class {
     const body = await this.#graphql.request(ME_QUERY);
     return normaliseMeResponse(body);
   }
+  /**
+   * Fetch the authenticated user's realized PnL (grid-api).
+   * `period` defaults to 'all_time' ('weekly' also accepted). Agency scope is
+   * resolved server-side from the JWT — never passed from the client.
+   */
+  async pnl(args) {
+    const period = args?.period ?? "all_time";
+    const body = await this.#graphql.request(
+      USER_PNL_QUERY,
+      { period },
+      args?.signal ? { signal: args.signal } : void 0
+    );
+    return normaliseUserPnL(body.userPnL);
+  }
   async wallets(opts) {
     const body = await this.#graphqlUser.request(
       MY_WALLETS_QUERY,

package/dist/index.d.mts

@@ -482,7 +482,19 @@ interface MqttWireAgencyPairStats {
     maxCoef: number;
     ts: number;
 }
-type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats;
+/**
+ * Wire payload on the user-scoped wallet topic `wallet/users/{userId}/balance`,
+ * published by `taphub-user-service` (`streams/wallet.go`). All fields are JSON
+ * strings. `reserved_amount` is snake_case on the wire.
+ */
+interface MqttWireWalletBalance {
+    id: string;
+    balance: string;
+    reserved_amount: string;
+    currency: string;
+    reason: string;
+}
+type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats | MqttWireWalletBalance;
 type MqttMessageHandler = (gameId: string, topic: string, payload: MqttWirePayload) => void;
 type MqttErrorHandler = (err: Error) => void;
 type MqttLifecycleEvent = {
@@ -503,6 +515,7 @@ type MqttLifecycleEvent = {
 type MqttLifecycleHook = (event: MqttLifecycleEvent) => void;
 type MqttCandleHandler = (topic: string, payload: MqttWirePayload) => void;
 type MqttAgencyPairStatsHandler = (topic: string, payload: MqttWirePayload) => void;
+type MqttWalletMessageHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
      * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
@@ -536,6 +549,15 @@ interface MqttTransport {
     subscribeAgencyPairStats(aid: string, gamePairId: string, onStats: MqttAgencyPairStatsHandler): void;
     /** Tear down the stats subscription for an `(aid, gamePairId)`. */
     unsubscribeAgencyPairStats(aid: string, gamePairId: string): void;
+    /**
+     * Subscribe to the user-scoped wallet balance stream, topic
+     * `wallet/users/{userId}/balance`. Independent of any game subscription — NOT
+     * torn down by `unsubscribeAll`. Idempotent: repeat calls for the same
+     * `userId` are deduplicated. Subscribed at QoS 0 to match the publisher.
+     */
+    subscribeWallet(userId: string, onMessage: MqttWalletMessageHandler, onError: MqttErrorHandler): void;
+    /** Tear down the wallet subscription for a `userId`. No-op if not subscribed. */
+    unsubscribeWallet(userId: string): void;
     close(): void;
 }
 
@@ -598,6 +620,36 @@ interface MqttBalanceEvent {
     userId: string;
     balance: string;
 }
+/**
+ * Cause of a wallet balance change. Byte-mirrors `BalanceUpdateReason` in the
+ * backend (`taphub-user-service` `streams/wallet.go`). `''` is the documented
+ * unspecified/legacy value. Treat unknown reasons defensively (enum fallback) —
+ * the SDK passes through values it does not recognise rather than dropping the
+ * event.
+ */
+type WalletBalanceReason = 'transfer' | 'refund' | 'reserve' | 'commit' | 'cancel' | 'bid_placed' | 'bid_won' | '';
+/**
+ * Wallet-level balance event from the user-scoped MQTT topic
+ * `wallet/users/{userId}/balance`. Fires on deposit / agency transfer / refund /
+ * reserve / commit / cancel / bid settlement — i.e. every balance change, with
+ * NO game context (unlike the game-scoped `MqttBalanceEvent`).
+ *
+ * Money fields (`balance`, `reservedAmount`) are kept as wire strings verbatim;
+ * the SDK does NOT coerce decimal money to `number`. Consumers coerce at the
+ * app edge if they need a number.
+ */
+interface MqttWalletBalanceEvent {
+    /** Wallet id (the backend `id` field). */
+    id: string;
+    /** Spendable balance, as the raw wire string. */
+    balance: string;
+    /** Amount held by PENDING reservations, as the raw wire string. */
+    reservedAmount: string;
+    /** Wallet currency (e.g. "USDC.e"). */
+    currency: string;
+    /** Cause of the change; unknown values are passed through as-is. */
+    reason: WalletBalanceReason;
+}
 interface MqttConfigEvent {
     minBidAmount: number;
     maxBidAmount: number;
@@ -638,6 +690,20 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
     constructor(gameId: string);
 }
 
+interface WalletChannelEvents {
+    walletBalanceUpdate: [MqttWalletBalanceEvent];
+    error: [Error];
+}
+/**
+ * User-scoped wallet channel. Emits `walletBalanceUpdate` for every balance
+ * change on `wallet/users/{userId}/balance`, independent of any game. Mirror of
+ * {@link GameChannel} but keyed by `userId` rather than `gameId`.
+ */
+declare class WalletChannel extends EventEmitter<WalletChannelEvents> {
+    readonly userId: string;
+    constructor(userId: string);
+}
+
 interface RealtimeModuleOptions {
     mqttEndpoint: string;
     /**
@@ -665,6 +731,24 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
     get _transport(): MqttTransport;
     subscribe(gameId: string, userId?: string | null): GameChannel;
     unsubscribe(gameId: string, userId?: string | null): void;
+    /**
+     * Subscribe to the user-scoped wallet balance stream for `userId`, topic
+     * `wallet/users/{userId}/balance`. Returns a `WalletChannel` that emits
+     * `walletBalanceUpdate` on every balance change (deposit / transfer / refund /
+     * reserve / commit / cancel / bid settlement) — independent of any game.
+     *
+     * Reference-counted by `userId`, mirroring `subscribe`/`unsubscribe`: repeat
+     * calls return the same channel and the topic is torn down only when balanced
+     * `unsubscribeWallet` calls bring the count to zero. The wallet lifecycle is
+     * fully independent of game subscriptions.
+     */
+    subscribeWallet(userId: string): WalletChannel;
+    /**
+     * Decrement the wallet subscription refcount for `userId`. Tears down the MQTT
+     * topic and removes the `WalletChannel` only when the count reaches zero.
+     * No-op if there is no active wallet subscription for `userId`.
+     */
+    unsubscribeWallet(userId: string): void;
     /**
      * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
      * Independent of game/agency — candle is market-wide public data.
@@ -701,6 +785,19 @@ interface Wallet {
     currency: string;
     isEnable: boolean;
 }
+type UserPnLPeriod = 'weekly' | 'all_time';
+/**
+ * Public, normalised PnL shape (camelCase). The wire shape is the codegen'd
+ * `UserPnL` from `@/types/gql/grid`; `normaliseUserPnL` maps wire → this.
+ */
+interface UserPnL {
+    /** Realized PnL: totalPayout − totalWagered. Decimal string. */
+    gain: string;
+    totalWagered: string;
+    totalPayout: string;
+    totalBids: number;
+    totalWins: number;
+}
 
 interface UserModuleDeps {
     rest: RestTransport;
@@ -714,6 +811,15 @@ declare class UserModule {
     #private;
     constructor(deps: UserModuleDeps);
     me(): Promise<Me>;
+    /**
+     * Fetch the authenticated user's realized PnL (grid-api).
+     * `period` defaults to 'all_time' ('weekly' also accepted). Agency scope is
+     * resolved server-side from the JWT — never passed from the client.
+     */
+    pnl(args?: {
+        period?: UserPnLPeriod;
+        signal?: AbortSignal;
+    }): Promise<UserPnL>;
     wallets(opts?: RequestOpts): Promise<Wallet[]>;
     walletByCurrency(currency: string, opts?: RequestOpts): Promise<Wallet>;
     get currencies(): Currency[] | null;
@@ -879,4 +985,4 @@ declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number,
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): 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 Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, 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 MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type PlaceBidInput, RealtimeModule, type Sample, type SampleReason, type SignalSource, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserModule, type Wallet as UserWallet, type Wallet$1 as Wallet, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };
+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 Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, 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 MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type PlaceBidInput, RealtimeModule, type Sample, type SampleReason, type SignalSource, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, 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 };

package/dist/index.d.ts

@@ -482,7 +482,19 @@ interface MqttWireAgencyPairStats {
     maxCoef: number;
     ts: number;
 }
-type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats;
+/**
+ * Wire payload on the user-scoped wallet topic `wallet/users/{userId}/balance`,
+ * published by `taphub-user-service` (`streams/wallet.go`). All fields are JSON
+ * strings. `reserved_amount` is snake_case on the wire.
+ */
+interface MqttWireWalletBalance {
+    id: string;
+    balance: string;
+    reserved_amount: string;
+    currency: string;
+    reason: string;
+}
+type MqttWirePayload = MqttWireCandle | MqttWireBidResult | MqttWireBalanceUpdate | MqttWireConfig | MqttWireAgencyPairStats | MqttWireWalletBalance;
 type MqttMessageHandler = (gameId: string, topic: string, payload: MqttWirePayload) => void;
 type MqttErrorHandler = (err: Error) => void;
 type MqttLifecycleEvent = {
@@ -503,6 +515,7 @@ type MqttLifecycleEvent = {
 type MqttLifecycleHook = (event: MqttLifecycleEvent) => void;
 type MqttCandleHandler = (topic: string, payload: MqttWirePayload) => void;
 type MqttAgencyPairStatsHandler = (topic: string, payload: MqttWirePayload) => void;
+type MqttWalletMessageHandler = (topic: string, payload: MqttWirePayload) => void;
 interface MqttTransport {
     /**
      * Subscribe to a game's MQTT topics (config, ideal_config, bid_result, balance)
@@ -536,6 +549,15 @@ interface MqttTransport {
     subscribeAgencyPairStats(aid: string, gamePairId: string, onStats: MqttAgencyPairStatsHandler): void;
     /** Tear down the stats subscription for an `(aid, gamePairId)`. */
     unsubscribeAgencyPairStats(aid: string, gamePairId: string): void;
+    /**
+     * Subscribe to the user-scoped wallet balance stream, topic
+     * `wallet/users/{userId}/balance`. Independent of any game subscription — NOT
+     * torn down by `unsubscribeAll`. Idempotent: repeat calls for the same
+     * `userId` are deduplicated. Subscribed at QoS 0 to match the publisher.
+     */
+    subscribeWallet(userId: string, onMessage: MqttWalletMessageHandler, onError: MqttErrorHandler): void;
+    /** Tear down the wallet subscription for a `userId`. No-op if not subscribed. */
+    unsubscribeWallet(userId: string): void;
     close(): void;
 }
 
@@ -598,6 +620,36 @@ interface MqttBalanceEvent {
     userId: string;
     balance: string;
 }
+/**
+ * Cause of a wallet balance change. Byte-mirrors `BalanceUpdateReason` in the
+ * backend (`taphub-user-service` `streams/wallet.go`). `''` is the documented
+ * unspecified/legacy value. Treat unknown reasons defensively (enum fallback) —
+ * the SDK passes through values it does not recognise rather than dropping the
+ * event.
+ */
+type WalletBalanceReason = 'transfer' | 'refund' | 'reserve' | 'commit' | 'cancel' | 'bid_placed' | 'bid_won' | '';
+/**
+ * Wallet-level balance event from the user-scoped MQTT topic
+ * `wallet/users/{userId}/balance`. Fires on deposit / agency transfer / refund /
+ * reserve / commit / cancel / bid settlement — i.e. every balance change, with
+ * NO game context (unlike the game-scoped `MqttBalanceEvent`).
+ *
+ * Money fields (`balance`, `reservedAmount`) are kept as wire strings verbatim;
+ * the SDK does NOT coerce decimal money to `number`. Consumers coerce at the
+ * app edge if they need a number.
+ */
+interface MqttWalletBalanceEvent {
+    /** Wallet id (the backend `id` field). */
+    id: string;
+    /** Spendable balance, as the raw wire string. */
+    balance: string;
+    /** Amount held by PENDING reservations, as the raw wire string. */
+    reservedAmount: string;
+    /** Wallet currency (e.g. "USDC.e"). */
+    currency: string;
+    /** Cause of the change; unknown values are passed through as-is. */
+    reason: WalletBalanceReason;
+}
 interface MqttConfigEvent {
     minBidAmount: number;
     maxBidAmount: number;
@@ -638,6 +690,20 @@ declare class GameChannel extends EventEmitter<GameChannelEvents> {
     constructor(gameId: string);
 }
 
+interface WalletChannelEvents {
+    walletBalanceUpdate: [MqttWalletBalanceEvent];
+    error: [Error];
+}
+/**
+ * User-scoped wallet channel. Emits `walletBalanceUpdate` for every balance
+ * change on `wallet/users/{userId}/balance`, independent of any game. Mirror of
+ * {@link GameChannel} but keyed by `userId` rather than `gameId`.
+ */
+declare class WalletChannel extends EventEmitter<WalletChannelEvents> {
+    readonly userId: string;
+    constructor(userId: string);
+}
+
 interface RealtimeModuleOptions {
     mqttEndpoint: string;
     /**
@@ -665,6 +731,24 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
     get _transport(): MqttTransport;
     subscribe(gameId: string, userId?: string | null): GameChannel;
     unsubscribe(gameId: string, userId?: string | null): void;
+    /**
+     * Subscribe to the user-scoped wallet balance stream for `userId`, topic
+     * `wallet/users/{userId}/balance`. Returns a `WalletChannel` that emits
+     * `walletBalanceUpdate` on every balance change (deposit / transfer / refund /
+     * reserve / commit / cancel / bid settlement) — independent of any game.
+     *
+     * Reference-counted by `userId`, mirroring `subscribe`/`unsubscribe`: repeat
+     * calls return the same channel and the topic is torn down only when balanced
+     * `unsubscribeWallet` calls bring the count to zero. The wallet lifecycle is
+     * fully independent of game subscriptions.
+     */
+    subscribeWallet(userId: string): WalletChannel;
+    /**
+     * Decrement the wallet subscription refcount for `userId`. Tears down the MQTT
+     * topic and removes the `WalletChannel` only when the count reaches zero.
+     * No-op if there is no active wallet subscription for `userId`.
+     */
+    unsubscribeWallet(userId: string): void;
     /**
      * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
      * Independent of game/agency — candle is market-wide public data.
@@ -701,6 +785,19 @@ interface Wallet {
     currency: string;
     isEnable: boolean;
 }
+type UserPnLPeriod = 'weekly' | 'all_time';
+/**
+ * Public, normalised PnL shape (camelCase). The wire shape is the codegen'd
+ * `UserPnL` from `@/types/gql/grid`; `normaliseUserPnL` maps wire → this.
+ */
+interface UserPnL {
+    /** Realized PnL: totalPayout − totalWagered. Decimal string. */
+    gain: string;
+    totalWagered: string;
+    totalPayout: string;
+    totalBids: number;
+    totalWins: number;
+}
 
 interface UserModuleDeps {
     rest: RestTransport;
@@ -714,6 +811,15 @@ declare class UserModule {
     #private;
     constructor(deps: UserModuleDeps);
     me(): Promise<Me>;
+    /**
+     * Fetch the authenticated user's realized PnL (grid-api).
+     * `period` defaults to 'all_time' ('weekly' also accepted). Agency scope is
+     * resolved server-side from the JWT — never passed from the client.
+     */
+    pnl(args?: {
+        period?: UserPnLPeriod;
+        signal?: AbortSignal;
+    }): Promise<UserPnL>;
     wallets(opts?: RequestOpts): Promise<Wallet[]>;
     walletByCurrency(currency: string, opts?: RequestOpts): Promise<Wallet>;
     get currencies(): Currency[] | null;
@@ -879,4 +985,4 @@ declare function adaptiveSimpson(f: (x: number) => number, a: number, b: number,
 declare function calculateProbWin(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): number;
 declare function calculateProbWin_v2(time1: number, time2: number, _price1: number, price2: number, creationTime: number, currentPrice: number, volatility: number): 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 Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, 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 MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type PlaceBidInput, RealtimeModule, type Sample, type SampleReason, type SignalSource, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, UserModule, type Wallet as UserWallet, type Wallet$1 as Wallet, adaptiveSimpson, autoDetectStorage, calculateProbWin, calculateProbWin_v2, errorFunction, isCancelled, isLoss, isPending, isTerminal, isWin, normalCDF, normalPDF };
+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 Game, GameChannel, type GameConfig, GameModule, type GamePairInfo, 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 MqttBalanceEvent, type MqttBidAcceptedEvent, type MqttBidLostEvent, type MqttBidWonEvent, type MqttCandleEvent, type MqttConfigEvent, type MqttIdealConfigEvent, type MqttWalletBalanceEvent, type NetworkLevel, type NetworkQuality, NetworkQualityMonitor, type PlaceBidInput, RealtimeModule, type Sample, type SampleReason, type SignalSource, TaphubAuthError, TaphubClient, type TaphubClientConfig, TaphubError, TaphubEventBus, type TaphubEventMap, TaphubNetworkError, TaphubServerError, TaphubSlippageError, TaphubStorage, type TaphubStorageAdapter, TaphubValidationError, type User, 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 };

package/dist/index.js

@@ -820,6 +820,10 @@ var GAME_SCOPED_SUFFIXES = ["config", "ideal_config"];
 var USER_SCOPED_SUFFIXES = ["bid_result", "balance_update"];
 var TOPIC_PREFIX = "game";
 var MARKET_TOPIC_PREFIX = "market";
+var WALLET_TOPIC_PREFIX = "wallet";
+function walletBalanceTopic(userId) {
+  return `${WALLET_TOPIC_PREFIX}/users/${userId}/balance`;
+}
 function agencyPairStatsTopic(aid, gamePairId) {
   return `public/agency/${aid}/pair/${gamePairId}/stats`;
 }
@@ -840,6 +844,7 @@ function createMqttTransport(endpoint, opts = {}) {
   const subscriptions = /* @__PURE__ */ new Map();
   const candleSubscriptions = /* @__PURE__ */ new Map();
   const statsSubscriptions = /* @__PURE__ */ new Map();
+  const walletSubscriptions = /* @__PURE__ */ new Map();
   const { onLifecycle } = opts;
   let connectStartedAt = 0;
   function fireLifecycle(event) {
@@ -908,6 +913,18 @@ function createMqttTransport(endpoint, opts = {}) {
         statsSub.onStats(receivedTopic, payload2);
         return;
       }
+      const walletSub = [...walletSubscriptions.values()].find((s) => s.topic === receivedTopic);
+      if (walletSub) {
+        let payload2;
+        try {
+          payload2 = JSON.parse(message.toString());
+        } catch {
+          walletSub.onError(new Error(`Invalid JSON on topic ${receivedTopic}`));
+          return;
+        }
+        walletSub.onMessage(receivedTopic, payload2);
+        return;
+      }
       let matched;
       for (const sub of subscriptions.values()) {
         if (sub.topics.includes(receivedTopic)) {
@@ -982,6 +999,19 @@ function createMqttTransport(endpoint, opts = {}) {
       if (client) client.unsubscribe(entry.topic);
       statsSubscriptions.delete(topic);
     },
+    subscribeWallet(userId, onMessage, onError) {
+      if (walletSubscriptions.has(userId)) return;
+      const topic = walletBalanceTopic(userId);
+      const mqttClient = ensureConnected();
+      walletSubscriptions.set(userId, { topic, onMessage, onError });
+      mqttClient.subscribe(topic, { qos: 0 });
+    },
+    unsubscribeWallet(userId) {
+      const entry = walletSubscriptions.get(userId);
+      if (!entry) return;
+      if (client) client.unsubscribe(entry.topic);
+      walletSubscriptions.delete(userId);
+    },
     unsubscribeAll(gameId, userId) {
       const matches = entriesForGame(gameId);
       if (matches.length === 0) return;
@@ -1019,10 +1049,14 @@ function createMqttTransport(endpoint, opts = {}) {
         for (const entry of statsSubscriptions.values()) {
           client.unsubscribe(entry.topic);
         }
+        for (const entry of walletSubscriptions.values()) {
+          client.unsubscribe(entry.topic);
+        }
       }
       subscriptions.clear();
       candleSubscriptions.clear();
       statsSubscriptions.clear();
+      walletSubscriptions.clear();
       if (client) {
         client.end(true);
         client = null;
@@ -1032,7 +1066,7 @@ function createMqttTransport(endpoint, opts = {}) {
 }
 
 // src/modules/realtime/index.ts
-import EventEmitter2 from "eventemitter3";
+import EventEmitter3 from "eventemitter3";
 
 // src/modules/realtime/GameChannel.ts
 import EventEmitter from "eventemitter3";
@@ -1044,6 +1078,16 @@ var GameChannel = class extends EventEmitter {
   }
 };
 
+// src/modules/realtime/WalletChannel.ts
+import EventEmitter2 from "eventemitter3";
+var WalletChannel = class extends EventEmitter2 {
+  userId;
+  constructor(userId) {
+    super();
+    this.userId = userId;
+  }
+};
+
 // src/modules/realtime/index.ts
 var TOPIC_SUFFIX_CANDLE = "candle";
 var TOPIC_SUFFIX_BID_RESULT = "bid_result";
@@ -1103,6 +1147,16 @@ function mapWireBalanceUpdate(raw) {
     balance: p.balance
   };
 }
+function mapWireWalletBalance(raw) {
+  const p = raw;
+  return {
+    id: p.id,
+    balance: p.balance,
+    reservedAmount: p.reserved_amount,
+    currency: p.currency,
+    reason: p.reason ?? ""
+  };
+}
 function mapWireConfig(raw) {
   const p = raw;
   return {
@@ -1140,9 +1194,11 @@ function mapWireToEvent(topic, payload) {
 function normaliseUserId2(userId) {
   return userId && userId !== "" ? userId : null;
 }
-var RealtimeModule = class extends EventEmitter2 {
+var RealtimeModule = class extends EventEmitter3 {
   #transport;
   #entries = /* @__PURE__ */ new Map();
+  #walletEntries = /* @__PURE__ */ new Map();
+  // keyed by userId
   #agencyId;
   constructor(mqttEndpointOrOptions) {
     super();
@@ -1222,6 +1278,56 @@ var RealtimeModule = class extends EventEmitter2 {
     target.channel.removeAllListeners();
     this.#transport.unsubscribeAll(gameId, target.userId);
   }
+  /**
+   * Subscribe to the user-scoped wallet balance stream for `userId`, topic
+   * `wallet/users/{userId}/balance`. Returns a `WalletChannel` that emits
+   * `walletBalanceUpdate` on every balance change (deposit / transfer / refund /
+   * reserve / commit / cancel / bid settlement) — independent of any game.
+   *
+   * Reference-counted by `userId`, mirroring `subscribe`/`unsubscribe`: repeat
+   * calls return the same channel and the topic is torn down only when balanced
+   * `unsubscribeWallet` calls bring the count to zero. The wallet lifecycle is
+   * fully independent of game subscriptions.
+   */
+  subscribeWallet(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) {
+      throw new TaphubError("userId is required to subscribe to wallet balance", {
+        code: "UserIdRequired"
+      });
+    }
+    const existing = this.#walletEntries.get(cleanUserId);
+    if (existing) {
+      existing.refcount += 1;
+      return existing.channel;
+    }
+    const channel = new WalletChannel(cleanUserId);
+    const onMessage = (_topic, payload) => {
+      channel.emit("walletBalanceUpdate", mapWireWalletBalance(payload));
+    };
+    const onError = (err) => {
+      channel.emit("error", err);
+    };
+    this.#walletEntries.set(cleanUserId, { userId: cleanUserId, channel, refcount: 1 });
+    this.#transport.subscribeWallet(cleanUserId, onMessage, onError);
+    return channel;
+  }
+  /**
+   * Decrement the wallet subscription refcount for `userId`. Tears down the MQTT
+   * topic and removes the `WalletChannel` only when the count reaches zero.
+   * No-op if there is no active wallet subscription for `userId`.
+   */
+  unsubscribeWallet(userId) {
+    const cleanUserId = normaliseUserId2(userId);
+    if (!cleanUserId) return;
+    const entry = this.#walletEntries.get(cleanUserId);
+    if (!entry) return;
+    entry.refcount -= 1;
+    if (entry.refcount > 0) return;
+    this.#walletEntries.delete(cleanUserId);
+    entry.channel.removeAllListeners();
+    this.#transport.unsubscribeWallet(cleanUserId);
+  }
   /**
    * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
    * Independent of game/agency — candle is market-wide public data.
@@ -1265,6 +1371,10 @@ var RealtimeModule = class extends EventEmitter2 {
       entry.channel.removeAllListeners();
     }
     this.#entries.clear();
+    for (const entry of this.#walletEntries.values()) {
+      entry.channel.removeAllListeners();
+    }
+    this.#walletEntries.clear();
     this.#transport.close();
   }
 };
@@ -1333,11 +1443,30 @@ function normaliseMyWalletByCurrencyResponse(body) {
   }
   return normaliseWalletNode(body.myWalletByCurrency);
 }
+function normaliseUserPnL(node) {
+  if (!node) {
+    throw new TaphubServerError("Invalid response from server", {
+      code: "InvalidResponse"
+    });
+  }
+  return {
+    gain: node.gain,
+    totalWagered: node.total_wagered,
+    totalPayout: node.total_payout,
+    totalBids: node.total_bids,
+    totalWins: node.total_wins
+  };
+}
 
 // src/modules/user/queries.ts
 var ME_QUERY = "query Me { me { id username wallet_address balance is_demo } }";
 var MY_WALLETS_QUERY = "query MyWallets { myWallets { id amount currency isEnable } }";
 var MY_WALLET_BY_CURRENCY_QUERY = "query MyWalletByCurrency($currency: String!) { myWalletByCurrency(currency: $currency) { id amount currency isEnable } }";
+var USER_PNL_QUERY = `query UserPnL($period: String) {
+  userPnL(period: $period) {
+    gain total_wagered total_payout total_bids total_wins
+  }
+}`;
 
 // src/modules/user/index.ts
 var UserModule = class {
@@ -1354,6 +1483,20 @@ var UserModule = class {
     const body = await this.#graphql.request(ME_QUERY);
     return normaliseMeResponse(body);
   }
+  /**
+   * Fetch the authenticated user's realized PnL (grid-api).
+   * `period` defaults to 'all_time' ('weekly' also accepted). Agency scope is
+   * resolved server-side from the JWT — never passed from the client.
+   */
+  async pnl(args) {
+    const period = args?.period ?? "all_time";
+    const body = await this.#graphql.request(
+      USER_PNL_QUERY,
+      { period },
+      args?.signal ? { signal: args.signal } : void 0
+    );
+    return normaliseUserPnL(body.userPnL);
+  }
   async wallets(opts) {
     const body = await this.#graphqlUser.request(
       MY_WALLETS_QUERY,

package/package.json

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