@pulsepairs/sdk 0.4.0 → 0.5.1

package/README.md

@@ -314,6 +314,47 @@ this cap across partial fills.
 
 ---
 
+## PnL — positions marked to market (v0.5.0)
+
+The matcher hands you the *ingredients* for PnL (`shares` / `avgPrice` /
+`costBasis` on positions, `winner` + order book on markets) but never a PnL
+number. `getPnl` assembles one, marking each position:
+
+- **resolved market** → won shares at full face (10000 bps), lost shares at 0;
+- **live market** → the order-book **mid** for that option;
+- **no book signal** → the position's own `avgPrice` (an honest 0-PnL mark,
+  flagged `markSource: "cost"` so you can tell it apart).
+
+```ts
+const client = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+
+const pnl = await client.getPnl(wallet, { includeFees: true });
+console.log(pnl.unrealizedPnlUsdt, pnl.roiPct); // e.g. -3, -30
+for (const p of pnl.positions) {
+  console.log(p.optionLabel, p.markSource, p.unrealizedPnlUsdt);
+}
+```
+
+All money math is BigInt-exact on **atomic** units and returned as decimal
+strings (`costBasis`, `markValue`, `unrealizedPnl` — signed); the `*Usdt` /
+`roiPct` floats are display-only. Cost basis is **fee-exclusive** (matching the
+backend's fold), so fees are a separate `fees` line, reported not netted.
+
+Already holding the data? The pure helpers are transport-free and unit-tested:
+
+```ts
+import { positionPnl, computePortfolioPnl, midBps, feesPaidByWallet } from "@pulsepairs/sdk";
+
+positionPnl(position, { markBps: 7000 });        // one position, explicit mark
+positionPnl(position, { winner: 1 });            // settled: full-face / zero
+computePortfolioPnl(positions, marketsByKey);    // roll-up from market details
+```
+
+Units: `shares` atomic (= USDT face at settlement), price/`avgPrice`/`markBps`
+in **bps** (10000 = full face), fees atomic. `Option` is `1 = UP`, `2 = DOWN`.
+
+---
+
 ## API surface
 
 ```
@@ -324,6 +365,9 @@ EIP-712          ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES,
                  findPairBySettlement, parseCompositeMarketKey
 Trade-math       centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic,
                  MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC
+PnL (v0.5.0)     UpDownHttpClient.getPnl, positionPnl, portfolioPnl,
+                 computePortfolioPnl, markValueAtomic, midBps, markForOption,
+                 feesPaidByWallet, atomicToUsdt, isResolvedWinner
 Approve (EOA)    ensureSettlementAllowance, MAX_UINT256
 Account Kit      UpDownAccountKitSigner (connect, onboard, approve, withdraw,
                  signTypedDataBare, signWsAuth, isDeployed, grantSession,

package/dist/http.d.ts

@@ -1,4 +1,5 @@
 import type { ApiConfig, Balance, CancelOrderBody, MarketDetail, MarketListItem, OrderBookFull, OrdersResponse, PairSymbol, PostOrderBody, Position, Stats, Trade, Version } from "./types.js";
+import { type PortfolioPnl } from "./pnl.js";
 export declare class UpDownHttpClient {
     private readonly baseUrl;
     constructor(baseUrl: string);
@@ -21,6 +22,24 @@ export declare class UpDownHttpClient {
         limit?: number;
         offset?: number;
     }): Promise<Trade[]>;
+    /**
+     * Portfolio PnL for a wallet: fetches open positions, marks each to its
+     * market (settled winner → full-face/zero, else order-book mid, else cost),
+     * and rolls the results up. One `/markets/:address` read per distinct market;
+     * a failed read degrades that position to a cost-basis mark rather than
+     * aborting the whole report.
+     *
+     * See `pnl.ts` for the unit contract and the standalone (transport-free)
+     * helpers if you already hold the positions/markets.
+     *
+     * @param opts.includeFees fetch `/trades/:wallet` and report total fees paid
+     *   (default false — it costs an extra request; fees are reported, not netted).
+     * @param opts.usdtDecimals display-float decimals (default 6).
+     */
+    getPnl(wallet: string, opts?: {
+        includeFees?: boolean;
+        usdtDecimals?: number;
+    }): Promise<PortfolioPnl>;
     getOrders(wallet: string, opts?: {
         status?: string[];
         limit?: number;

package/dist/http.js

@@ -1,3 +1,4 @@
+import { computePortfolioPnl, feesPaidByWallet } from "./pnl.js";
 function buildUrl(base, path, query) {
     const b = base.replace(/\/$/, "");
     const p = path.startsWith("/") ? path : `/${path}`;
@@ -75,6 +76,43 @@ export class UpDownHttpClient {
         }));
         return parseJson(res);
     }
+    /**
+     * Portfolio PnL for a wallet: fetches open positions, marks each to its
+     * market (settled winner → full-face/zero, else order-book mid, else cost),
+     * and rolls the results up. One `/markets/:address` read per distinct market;
+     * a failed read degrades that position to a cost-basis mark rather than
+     * aborting the whole report.
+     *
+     * See `pnl.ts` for the unit contract and the standalone (transport-free)
+     * helpers if you already hold the positions/markets.
+     *
+     * @param opts.includeFees fetch `/trades/:wallet` and report total fees paid
+     *   (default false — it costs an extra request; fees are reported, not netted).
+     * @param opts.usdtDecimals display-float decimals (default 6).
+     */
+    async getPnl(wallet, opts) {
+        const positions = await this.getPositions(wallet);
+        if (positions.length === 0) {
+            return computePortfolioPnl([], new Map(), { usdtDecimals: opts?.usdtDecimals });
+        }
+        const marketKeys = Array.from(new Set(positions.map((p) => p.market)));
+        const details = await Promise.all(marketKeys.map((key) => this.getMarket(key).catch(() => null)));
+        const marketsByKey = new Map();
+        marketKeys.forEach((key, i) => {
+            const md = details[i];
+            if (md)
+                marketsByKey.set(key, { winner: md.winner, orderBook: md.orderBook });
+        });
+        let fees;
+        if (opts?.includeFees) {
+            const trades = await this.getTrades(wallet, { limit: 500 });
+            fees = feesPaidByWallet(wallet, trades);
+        }
+        return computePortfolioPnl(positions, marketsByKey, {
+            fees,
+            usdtDecimals: opts?.usdtDecimals,
+        });
+    }
     async getOrders(wallet, opts) {
         const params = new URLSearchParams();
         if (opts?.limit != null)

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export { ensureSettlementAllowance, MAX_UINT256, DEFAULT_APPROVAL_AMOUNT, type E
 export { readOnChainHolderShares, reconcileFills, reportedFromPositions, type OnChainHolderShares, type ShareReconciliation, type ReconcileStatus, type FillReconciliationReport, } from "./reconcile.js";
 export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, type UpDownAccountKitConfig, type Eip1193Provider, type GrantSessionResult, type RawTypedDataSigner, } from "./accountKit.js";
 export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession, type RawTransaction, type OrderSessionRecord, } from "./accountKit.js";
+export { PRICE_BPS_SCALE, WIN_MARK_BPS, LOSE_MARK_BPS, DEFAULT_USDT_DECIMALS, atomicToUsdt, markValueAtomic, midBps, markForOption, isResolvedWinner, positionPnl, feesPaidByWallet, portfolioPnl, computePortfolioPnl, type MarkSource, type PositionPnl, type PortfolioPnl, type PositionPnlOptions, } from "./pnl.js";
 export { OrderType, OrderSide, Option, type ApiConfig, type Balance, type CancelOrderBody, type Eip712Domain, type MarketDetail, type MarketListItem, type OptionValue, type OrderBookFull, type OrderBookLevel, type OrderBookSide, type OrderRow, type OrderSideKey, type OrderSideValue, type OrderStatus, type OrderTypeKey, type OrderTypeValue, type OrdersResponse, type PairConfig, type PairSymbol, type PostOrderBody, type Position, type Stats, type Trade, type Version, } from "./types.js";

package/dist/index.js

@@ -20,5 +20,9 @@ export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc64
 // session): on-chain setup builders → rain's exact `RawTransaction` shape, plus
 // a local order-session signer for the off-chain sigs their session can't make.
 export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession, } from "./accountKit.js";
+// PnL — profit-and-loss math over positions/markets/trades. Pure, BigInt-exact,
+// unit-faithful to the backend's own position fold (see pnl.ts for the unit
+// contract). `UpDownHttpClient.getPnl` is the batteries-included wrapper.
+export { PRICE_BPS_SCALE, WIN_MARK_BPS, LOSE_MARK_BPS, DEFAULT_USDT_DECIMALS, atomicToUsdt, markValueAtomic, midBps, markForOption, isResolvedWinner, positionPnl, feesPaidByWallet, portfolioPnl, computePortfolioPnl, } from "./pnl.js";
 // Types
 export { OrderType, OrderSide, Option, } from "./types.js";

package/dist/pnl.d.ts

@@ -0,0 +1,150 @@
+/**
+ * PnL — profit-and-loss math for a wallet's UpDown positions.
+ *
+ * The matcher exposes the *ingredients* for PnL (`GET /positions/:wallet` gives
+ * `shares` / `avgPrice` / `costBasis`; `GET /markets/:address` gives the live
+ * order book and the resolved `winner`) but never a PnL number itself. This
+ * module layers that number on top, in exactly the units the rest of the SDK
+ * and the backend already use — so a PnL here reconciles with the backend's own
+ * position accounting rather than drifting from it.
+ *
+ * ── Units (do not guess these; they are load-bearing) ───────────────────────
+ *   • `shares`   — atomic, same denomination as `Trade.amount`. Shares ≡ the
+ *                  USDT face value paid at settlement: a WINNING share redeems
+ *                  1:1 for its face (`shares` atomic USDT), a losing share for 0.
+ *                  (`UpDownSettlement._redeemToAllowZero` pays `userShares`.)
+ *   • `avgPrice` — basis points, 0..10000. 10000 bps = full face (1.0). This is
+ *                  what the backend's `avgPriceBps` returns.
+ *   • `costBasis`— atomic USDT = `shares * avgPrice / 10000`, FEE-EXCLUSIVE
+ *                  (the backend's fold ignores fees; so do we, so the two agree).
+ *   • order-book `price` — basis points, same scale as `avgPrice`.
+ *   • fees (`platformFee`/`makerFee`) — atomic USDT.
+ *
+ * ── What we compute ─────────────────────────────────────────────────────────
+ *   markValue      = shares * markBps / 10000            (atomic USDT)
+ *   unrealizedPnl  = markValue - costBasis               (atomic USDT, signed)
+ *   where `markBps` is:
+ *     • 10000 or 0 for a RESOLVED market (won → full face, lost → nothing).
+ *       This is the *realized-at-settlement* value; `resolved: true` flags it.
+ *     • the order-book mid for a live market (mark-to-market).
+ *     • the position's own `avgPrice` as a last resort when there is no book
+ *       signal — a deliberately honest 0-PnL mark, flagged `markSource: "cost"`.
+ *
+ * All money math is BigInt-exact on atomic units; the `*Usdt` / `roiPct` floats
+ * are derived once at the end for display only.
+ */
+import type { MarketDetail, OrderBookSide, Position, Trade } from "./types.js";
+/** Basis-points denominator shared by every price in the system. */
+export declare const PRICE_BPS_SCALE = 10000n;
+/** A winning share is worth its full face (10000 bps). */
+export declare const WIN_MARK_BPS = 10000;
+/** A losing share is worth nothing. */
+export declare const LOSE_MARK_BPS = 0;
+/** USDT atomic decimals on the demo/mainnet mock (1 USDT = 1e6). */
+export declare const DEFAULT_USDT_DECIMALS = 6;
+/** Where a position's mark price came from — surfaced so callers can tell a
+ *  real mark-to-market from a cost-basis fallback. */
+export type MarkSource = "settled" | "orderbook-mid" | "orderbook-bid" | "orderbook-ask" | "explicit" | "cost";
+/** PnL for a single open position, all atomic strings BigInt-exact. */
+export type PositionPnl = {
+    market: string;
+    option: number;
+    optionLabel: "UP" | "DOWN";
+    /** Atomic shares (echoed from the position). */
+    shares: string;
+    /** Atomic USDT cost, fee-exclusive (echoed from the position). */
+    costBasis: string;
+    /** Price used to value the shares, basis points. */
+    markBps: number;
+    markSource: MarkSource;
+    /** Atomic USDT the shares are worth at `markBps` (= shares * markBps / 10000). */
+    markValue: string;
+    /** Atomic USDT, signed: `markValue - costBasis`. Negative = loss. */
+    unrealizedPnl: string;
+    /** `unrealizedPnl` as a human USDT float (display only). */
+    unrealizedPnlUsdt: number;
+    /** `100 * unrealizedPnl / costBasis`, or null when costBasis is 0. */
+    roiPct: number | null;
+    /** True when `markBps` is a settled winner/loser value, not a live mark. */
+    resolved: boolean;
+};
+/** Portfolio roll-up across positions. */
+export type PortfolioPnl = {
+    positions: PositionPnl[];
+    /** Atomic USDT sums across all positions. */
+    costBasis: string;
+    markValue: string;
+    unrealizedPnl: string;
+    /** Display floats. */
+    unrealizedPnlUsdt: number;
+    roiPct: number | null;
+    /** Atomic USDT of fees paid on the wallet's trades, when trades were supplied
+     *  (see `feesPaidByWallet`); "0" otherwise. Not netted into `unrealizedPnl`
+     *  — cost basis is fee-exclusive, so fees stay a separate, explicit line. */
+    fees: string;
+};
+/** Options controlling how one position is valued. */
+export type PositionPnlOptions = {
+    /** Explicit mark, basis points. Ignored when `winner` marks the position as
+     *  resolved. When omitted and not resolved, we fall back to `avgPrice`. */
+    markBps?: number;
+    /** Label for an explicit `markBps` (defaults to "explicit"). */
+    markSource?: MarkSource;
+    /** Resolved winner: 1 = UP, 2 = DOWN, 0/null = not resolved. When set to a
+     *  real winner, the position is marked at full face (won) or 0 (lost). */
+    winner?: number | null;
+    /** USDT atomic decimals for the display float (default 6). */
+    usdtDecimals?: number;
+};
+/** Atomic → human float for display. Precision is ample for real stakes; never
+ *  feed the result back into money math (use the atomic strings for that). */
+export declare function atomicToUsdt(atomic: bigint | string, decimals?: number): number;
+/** Value of `sharesAtomic` shares marked at `markBps`, atomic USDT. Uses the
+ *  same floor-division as the backend's cost fold so the two never disagree by
+ *  a rounding unit. */
+export declare function markValueAtomic(sharesAtomic: bigint, markBps: number): bigint;
+/**
+ * Mid price (basis points) for one side of a book, from its best bid/ask.
+ * Prefers the two-sided mid; degrades to the single resting quote; returns null
+ * for an empty book so the caller can choose a fallback rather than invent one.
+ */
+export declare function midBps(side: OrderBookSide | undefined | null): {
+    bps: number;
+    source: MarkSource;
+} | null;
+/** The book side (`up`/`down`) an option trades on. UP = 1, DOWN = 2. */
+export declare function markForOption(orderBook: MarketDetail["orderBook"] | undefined, option: number): {
+    bps: number;
+    source: MarkSource;
+} | null;
+/** True once a market carries a definitive winner (1 = UP, 2 = DOWN). The
+ *  contract's `resolve` rejects any other value, so there is no draw/void. */
+export declare function isResolvedWinner(winner: number | null | undefined): winner is 1 | 2;
+/**
+ * PnL for a single position. Resolution wins over any supplied `markBps`: a
+ * settled market is worth exactly full-face or nothing, never a stale quote.
+ */
+export declare function positionPnl(position: Position, opts?: PositionPnlOptions): PositionPnl;
+/** Sum of `platformFee + makerFee` (atomic USDT) across every trade the wallet
+ *  took part in. A gross tally — it does not attempt maker/taker attribution,
+ *  so treat it as an upper bound on the wallet's own fee drag. */
+export declare function feesPaidByWallet(wallet: string, trades: Trade[]): string;
+/** Roll individual position PnLs up into a portfolio total. Pass `fees` (from
+ *  `feesPaidByWallet`) to carry a fee line through; it is reported, not netted. */
+export declare function portfolioPnl(items: PositionPnl[], opts?: {
+    fees?: string;
+    usdtDecimals?: number;
+}): PortfolioPnl;
+/**
+ * Given positions and the market details they live in, compute a full
+ * portfolio PnL. Transport-free: hand it data you already fetched. The HTTP
+ * client's `getPnl` is a thin wrapper that fetches the markets for you.
+ *
+ * `marketsByKey` maps a position's `market` key to its `MarketDetail`. A
+ * missing entry (or an empty book) degrades to a cost-basis mark for that
+ * position rather than dropping it.
+ */
+export declare function computePortfolioPnl(positions: Position[], marketsByKey: Map<string, Pick<MarketDetail, "winner" | "orderBook">>, opts?: {
+    fees?: string;
+    usdtDecimals?: number;
+}): PortfolioPnl;

package/dist/pnl.js

@@ -0,0 +1,157 @@
+/** Basis-points denominator shared by every price in the system. */
+export const PRICE_BPS_SCALE = 10000n;
+/** A winning share is worth its full face (10000 bps). */
+export const WIN_MARK_BPS = 10_000;
+/** A losing share is worth nothing. */
+export const LOSE_MARK_BPS = 0;
+/** USDT atomic decimals on the demo/mainnet mock (1 USDT = 1e6). */
+export const DEFAULT_USDT_DECIMALS = 6;
+/** BigInt-exact `numer/denom` as a percentage float with 4-decimal resolution;
+ *  null on a zero denominator. Sign-correct for negative numerators. */
+function pctOf(numer, denom) {
+    if (denom === 0n)
+        return null;
+    // scaled = ratio * 1e6, kept in BigInt so huge atomic values stay exact;
+    // /1e4 turns the ratio into a percentage carrying 4 decimal places.
+    const scaled = (numer * 1000000n) / denom;
+    return Number(scaled) / 10_000;
+}
+/** Atomic → human float for display. Precision is ample for real stakes; never
+ *  feed the result back into money math (use the atomic strings for that). */
+export function atomicToUsdt(atomic, decimals = DEFAULT_USDT_DECIMALS) {
+    const a = typeof atomic === "bigint" ? atomic : BigInt(atomic);
+    return Number(a) / 10 ** decimals;
+}
+/** Value of `sharesAtomic` shares marked at `markBps`, atomic USDT. Uses the
+ *  same floor-division as the backend's cost fold so the two never disagree by
+ *  a rounding unit. */
+export function markValueAtomic(sharesAtomic, markBps) {
+    return (sharesAtomic * BigInt(Math.trunc(markBps))) / PRICE_BPS_SCALE;
+}
+/**
+ * Mid price (basis points) for one side of a book, from its best bid/ask.
+ * Prefers the two-sided mid; degrades to the single resting quote; returns null
+ * for an empty book so the caller can choose a fallback rather than invent one.
+ */
+export function midBps(side) {
+    const bid = side?.bestBid?.price;
+    const ask = side?.bestAsk?.price;
+    const hasBid = typeof bid === "number" && Number.isFinite(bid);
+    const hasAsk = typeof ask === "number" && Number.isFinite(ask);
+    if (hasBid && hasAsk)
+        return { bps: Math.round((bid + ask) / 2), source: "orderbook-mid" };
+    if (hasBid)
+        return { bps: bid, source: "orderbook-bid" };
+    if (hasAsk)
+        return { bps: ask, source: "orderbook-ask" };
+    return null;
+}
+/** The book side (`up`/`down`) an option trades on. UP = 1, DOWN = 2. */
+export function markForOption(orderBook, option) {
+    if (!orderBook)
+        return null;
+    return midBps(option === 1 ? orderBook.up : orderBook.down);
+}
+/** True once a market carries a definitive winner (1 = UP, 2 = DOWN). The
+ *  contract's `resolve` rejects any other value, so there is no draw/void. */
+export function isResolvedWinner(winner) {
+    return winner === 1 || winner === 2;
+}
+/**
+ * PnL for a single position. Resolution wins over any supplied `markBps`: a
+ * settled market is worth exactly full-face or nothing, never a stale quote.
+ */
+export function positionPnl(position, opts = {}) {
+    const decimals = opts.usdtDecimals ?? DEFAULT_USDT_DECIMALS;
+    const shares = BigInt(position.shares);
+    const costBasis = BigInt(position.costBasis);
+    let markBps;
+    let markSource;
+    let resolved = false;
+    if (isResolvedWinner(opts.winner)) {
+        resolved = true;
+        markSource = "settled";
+        markBps = position.option === opts.winner ? WIN_MARK_BPS : LOSE_MARK_BPS;
+    }
+    else if (typeof opts.markBps === "number" && Number.isFinite(opts.markBps)) {
+        markBps = opts.markBps;
+        markSource = opts.markSource ?? "explicit";
+    }
+    else {
+        // No signal: mark at cost so unrealized PnL is 0 rather than a fiction.
+        markBps = position.avgPrice;
+        markSource = "cost";
+    }
+    const markValue = markValueAtomic(shares, markBps);
+    const unrealizedPnl = markValue - costBasis;
+    return {
+        market: position.market,
+        option: position.option,
+        optionLabel: position.optionLabel,
+        shares: shares.toString(),
+        costBasis: costBasis.toString(),
+        markBps,
+        markSource,
+        markValue: markValue.toString(),
+        unrealizedPnl: unrealizedPnl.toString(),
+        unrealizedPnlUsdt: atomicToUsdt(unrealizedPnl, decimals),
+        roiPct: pctOf(unrealizedPnl, costBasis),
+        resolved,
+    };
+}
+/** Sum of `platformFee + makerFee` (atomic USDT) across every trade the wallet
+ *  took part in. A gross tally — it does not attempt maker/taker attribution,
+ *  so treat it as an upper bound on the wallet's own fee drag. */
+export function feesPaidByWallet(wallet, trades) {
+    const w = wallet.toLowerCase();
+    let total = 0n;
+    for (const t of trades) {
+        if (t.buyer?.toLowerCase() !== w && t.seller?.toLowerCase() !== w)
+            continue;
+        total += BigInt(t.platformFee || "0") + BigInt(t.makerFee || "0");
+    }
+    return total.toString();
+}
+/** Roll individual position PnLs up into a portfolio total. Pass `fees` (from
+ *  `feesPaidByWallet`) to carry a fee line through; it is reported, not netted. */
+export function portfolioPnl(items, opts = {}) {
+    const decimals = opts.usdtDecimals ?? DEFAULT_USDT_DECIMALS;
+    let costBasis = 0n;
+    let markValue = 0n;
+    for (const it of items) {
+        costBasis += BigInt(it.costBasis);
+        markValue += BigInt(it.markValue);
+    }
+    const unrealizedPnl = markValue - costBasis;
+    return {
+        positions: items,
+        costBasis: costBasis.toString(),
+        markValue: markValue.toString(),
+        unrealizedPnl: unrealizedPnl.toString(),
+        unrealizedPnlUsdt: atomicToUsdt(unrealizedPnl, decimals),
+        roiPct: pctOf(unrealizedPnl, costBasis),
+        fees: opts.fees ?? "0",
+    };
+}
+/**
+ * Given positions and the market details they live in, compute a full
+ * portfolio PnL. Transport-free: hand it data you already fetched. The HTTP
+ * client's `getPnl` is a thin wrapper that fetches the markets for you.
+ *
+ * `marketsByKey` maps a position's `market` key to its `MarketDetail`. A
+ * missing entry (or an empty book) degrades to a cost-basis mark for that
+ * position rather than dropping it.
+ */
+export function computePortfolioPnl(positions, marketsByKey, opts = {}) {
+    const items = positions.map((pos) => {
+        const md = marketsByKey.get(pos.market);
+        const mark = md ? markForOption(md.orderBook, pos.option) : null;
+        return positionPnl(pos, {
+            winner: md?.winner ?? null,
+            markBps: mark?.bps,
+            markSource: mark?.source,
+            usdtDecimals: opts.usdtDecimals,
+        });
+    });
+    return portfolioPnl(items, opts);
+}

package/dist/ws.d.ts

@@ -110,6 +110,29 @@ export declare class UpDownWsClient {
      */
     connect(subscribe: SubscribePayload): void;
     disconnect(): void;
+    /**
+     * Add channels to the live subscription set on an already-connected
+     * client, without tearing down the socket. Sends `{type:'subscribe',
+     * channels}` immediately if the socket is OPEN; the channels are also
+     * merged into the connect-time set so they are replayed automatically
+     * after any reconnect (or after the auth handshake, on an authed
+     * client). Safe to call before the socket opens.
+     *
+     * Public channels (`markets`, `orderbook:*`, `trades:*`) work on any
+     * client. Private channels (`orders:*`, `balance:*`) still require the
+     * client to have been created via `connectAuthed` — the server drops
+     * private subs from an unauthenticated connection.
+     */
+    subscribe(channels: string[]): void;
+    /**
+     * Remove channels from the live subscription set. Sends
+     * `{type:'unsubscribe', channels}` if OPEN and drops them from the
+     * replay set so a later reconnect does not re-subscribe them. Channels
+     * not currently subscribed are ignored.
+     */
+    unsubscribe(channels: string[]): void;
+    /** The mutable connect-time channel array for the active mode. */
+    private modeChannels;
     private openSocket;
     private startHandshake;
     private runSignAndSendAuth;

package/dist/ws.js

@@ -93,17 +93,103 @@ export class UpDownWsClient {
         this.ws?.close();
         this.ws = null;
     }
+    /**
+     * Add channels to the live subscription set on an already-connected
+     * client, without tearing down the socket. Sends `{type:'subscribe',
+     * channels}` immediately if the socket is OPEN; the channels are also
+     * merged into the connect-time set so they are replayed automatically
+     * after any reconnect (or after the auth handshake, on an authed
+     * client). Safe to call before the socket opens.
+     *
+     * Public channels (`markets`, `orderbook:*`, `trades:*`) work on any
+     * client. Private channels (`orders:*`, `balance:*`) still require the
+     * client to have been created via `connectAuthed` — the server drops
+     * private subs from an unauthenticated connection.
+     */
+    subscribe(channels) {
+        if (!this.mode || channels.length === 0)
+            return;
+        const set = this.modeChannels();
+        const added = [];
+        for (const ch of channels) {
+            if (!set.includes(ch)) {
+                set.push(ch);
+                added.push(ch);
+            }
+        }
+        if (added.length === 0)
+            return;
+        this.send({ type: "subscribe", channels: added });
+    }
+    /**
+     * Remove channels from the live subscription set. Sends
+     * `{type:'unsubscribe', channels}` if OPEN and drops them from the
+     * replay set so a later reconnect does not re-subscribe them. Channels
+     * not currently subscribed are ignored.
+     */
+    unsubscribe(channels) {
+        if (!this.mode || channels.length === 0)
+            return;
+        const set = this.modeChannels();
+        const removed = [];
+        for (const ch of channels) {
+            const i = set.indexOf(ch);
+            if (i !== -1) {
+                set.splice(i, 1);
+                removed.push(ch);
+            }
+        }
+        if (removed.length === 0)
+            return;
+        this.send({ type: "unsubscribe", channels: removed });
+    }
+    /** The mutable connect-time channel array for the active mode. */
+    modeChannels() {
+        if (!this.mode)
+            return [];
+        return this.mode.kind === "public"
+            ? this.mode.channels
+            : this.mode.opts.channels;
+    }
     openSocket() {
         if (this.closed)
             return;
+        // Close any socket we're superseding before opening a new one. Without
+        // this, a rapid connect→(reconnect|reconnectMode) churn could leave the
+        // previous socket open — especially one still in CONNECTING, whose
+        // `onopen` fires after we've moved on.
+        if (this.ws) {
+            const stale = this.ws;
+            stale.onopen = stale.onmessage = stale.onclose = stale.onerror = null;
+            try {
+                stale.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
         const ws = new WebSocket(this.url);
         this.ws = ws;
         this.state = "idle";
         ws.onopen = () => {
+            // Guard: if we were disconnected, or a newer socket has superseded this
+            // one, this socket is an orphan (it finished CONNECTING after we moved
+            // on). Close it instead of leaving it open and streaming.
+            if (this.closed || this.ws !== ws) {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
             this.reconnect = 0;
             void this.startHandshake();
         };
         ws.onmessage = (ev) => {
+            if (this.ws !== ws)
+                return; // ignore frames from a superseded socket
             let parsed;
             try {
                 parsed = JSON.parse(String(ev.data));
@@ -114,7 +200,9 @@ export class UpDownWsClient {
             void this.handleIncoming(parsed);
         };
         ws.onclose = () => {
-            if (this.closed)
+            // A superseded socket's close must not trigger a reconnect — the live
+            // `this.ws` is a different, healthy socket.
+            if (this.closed || this.ws !== ws)
                 return;
             if (this.state === "unauthed-failure") {
                 // signAuth was rejected — don't reconnect into a hot loop.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.4.0",
-  "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.5.1",
+  "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",
@@ -11,6 +11,18 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./ws": {
+      "types": "./dist/ws.d.ts",
+      "import": "./dist/ws.js"
+    },
+    "./eip712": {
+      "types": "./dist/eip712.d.ts",
+      "import": "./dist/eip712.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
     }
   },
   "files": [
@@ -21,7 +33,7 @@
   "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",
+    "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",
     "prepublishOnly": "npm run build && npm test",
     "example:taker": "npx tsx examples/simple-taker.ts",
     "example:maker": "npx tsx examples/simple-maker.ts",