@pulsepairs/sdk 0.3.0 → 0.5.0

package/README.md

@@ -65,11 +65,14 @@ import { createPublicClient, createWalletClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { arbitrum } from "viem/chains";
 import {
-  UpDownHttpClient, buildOrderTypedData, ensureSettlementAllowance,
+  UpDownHttpClient, buildOrderTypedData, ensureSettlementAllowance, freshNonce,
   parseCompositeMarketKey, parseStake, OrderType, OrderSide, Option,
 } from "@pulsepairs/sdk";
 
-const api = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+// Point the bot at a matcher YOU chose. Don't hardcode ours into a process
+// that holds a funded key — and assert the chain matches your RPC's chain
+// before you approve anything (see "Handling a funded key" below).
+const api = new UpDownHttpClient(process.env.UPND_API!);
 const cfg = await api.getConfig();                    // never hardcode addresses
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 const [live] = (await api.getMarkets({ pair: "BTC-USD", timeframe: 300 }))
@@ -77,8 +80,18 @@ const [live] = (await api.getMarkets({ pair: "BTC-USD", timeframe: 300 }))
 const { settlementAddress, marketId } = parseCompositeMarketKey(live.address)!;
 
 const amount = parseStake("5");
+
+// BOUNDED approve. `settlementAddress` is server-supplied (it came from the
+// matcher's market list), so cap its reach at what you actually intend to
+// spend. `amount` = how much to approve; `threshold` = when to top back up.
+// Omitting `amount` still approves MAX_UINT256 — that default is legacy.
+await ensureSettlementAllowance({
+  publicClient, walletClient, usdt: cfg.usdtAddress, settlement: settlementAddress,
+  amount: amount * 20n, threshold: amount,
+});
+
 const maxFee = (amount * BigInt(cfg.platformFeeBps + cfg.makerFeeBps)) / 10000n; // peak fee
-const nonce = BigInt(Math.floor(Math.random() * 1e12));
+const nonce = freshNonce();                           // CSPRNG; never Math.random/Date.now
 const typedData = buildOrderTypedData({
   cfg, settlementAddress,
   message: { maker: account.address, market: BigInt(marketId), option: BigInt(Option.UP),
@@ -91,8 +104,54 @@ await api.postOrder({ maker: account.address, market: live.address, option: Opti
   maxFee: maxFee.toString(), nonce: Number(nonce), expiry: live.endTime, signature });
 ```
 
-Full runnable scripts: `examples/simple-taker.ts` (MARKET), `examples/simple-maker.ts`
-(LIMIT + authed WS), `examples/full-dmm-bot.ts` (two-sided quoting).
+Full runnable scripts live in the **repo** under `examples/` — `simple-taker.ts`
+(MARKET), `simple-maker.ts` (LIMIT + authed WS), `full-dmm-bot.ts` (two-sided
+quoting). They are **not in the npm tarball** (`files: ["dist","README.md"]`), so
+if you installed from npm without repo access, this README is your reference —
+the safe patterns are inlined here on purpose.
+
+---
+
+## Handling a funded key
+
+This SDK is normally driven by a hot key that holds real USDT. Three rules,
+each of which exists because the failure is silent:
+
+**1. Never default your endpoints.** A bot signs orders for whatever matcher you
+point it at, and then grants that matcher's *server-supplied* settlement address
+a USDT allowance. A defaulted `UPND_API` plus a defaulted mainnet RPC means a
+real funded key trading against a box you never chose. Require both explicitly:
+
+```ts
+const API = process.env.UPND_API;
+if (!API) throw new Error("Set UPND_API — refusing to default a funded key to a third-party endpoint");
+const RPC = process.env.ARBITRUM_RPC_URL;
+if (!RPC) throw new Error("Set ARBITRUM_RPC_URL");
+```
+
+**2. Assert the matcher and the RPC agree on the chain**, before the approve.
+This one check catches the whole class — a testnet/demo matcher paired with a
+mainnet key can't survive it:
+
+```ts
+const cfg = await api.getConfig();
+const rpcChainId = await publicClient.getChainId();
+if (cfg.chainId !== rpcChainId) {
+  throw new Error(`chain mismatch: matcher says ${cfg.chainId}, RPC says ${rpcChainId}`);
+}
+```
+
+**3. Bound the allowance.** Pass `amount` to `ensureSettlementAllowance` (EOA) /
+`onboard`/`approve` (Account Kit) / `buildApproveSettlementTx` (raw-tx tier).
+All four default to `MAX_UINT256` for backwards compatibility; that default is
+an unbounded claim on your balance by an address the server named. A bounded
+allowance is consumed by fills, so re-run the helper on a timer — if it runs dry
+mid-session your fills revert with `insufficient allowance`.
+
+Use `freshNonce()` for order/cancel nonces. It draws from `crypto.getRandomValues`
+and stays under 2^53 so `Number(nonce)` on the wire matches the value you signed.
+`Math.random()`/`Date.now()` nonces are guessable, which lets anyone pre-burn your
+next nonce against the replay store and block your order flow.
 
 ---
 
@@ -255,16 +314,60 @@ 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
 
 ```
 Clients          UpDownHttpClient, UpDownWsClient, wsUrlFromHttpBase
 EIP-712          ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES,
                  buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData,
-                 freshSessionId, domainForSettlement, findPairBySettlement,
-                 parseCompositeMarketKey
+                 freshSessionId, freshNonce, domainForSettlement,
+                 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/accountKit.d.ts

@@ -253,15 +253,22 @@ export declare class UpDownAccountKitSigner {
      * popup-less. Order-session prep failures degrade to plain deploy+approve
      * (owner-key signing per order). Uses the owner client so it works before
      * any session exists; deployment is carried by the account init-code.
+     *
+     * `amount` bounds the allowance (default unlimited) — see
+     * `ensureSettlementAllowance`'s notes; the same argument applies here,
+     * since `settlement` comes from the matcher's own config.
      */
     onboard(args: {
         usdt: Address;
         settlement: Address;
+        amount?: bigint;
     }): Promise<Hex>;
-    /** Idempotent USDT approve to the settlement (gasless UserOp). */
+    /** Idempotent USDT approve to the settlement (gasless UserOp). `amount`
+     *  bounds the allowance; defaults to unlimited (MAX_UINT256). */
     approve(args: {
         usdt: Address;
         settlement: Address;
+        amount?: bigint;
     }): Promise<Hex>;
     /** Transfer USDT out of the SCA to `to` (gasless UserOp). */
     withdraw(args: {

package/dist/accountKit.js

@@ -483,10 +483,14 @@ export class UpDownAccountKitSigner {
      * popup-less. Order-session prep failures degrade to plain deploy+approve
      * (owner-key signing per order). Uses the owner client so it works before
      * any session exists; deployment is carried by the account init-code.
+     *
+     * `amount` bounds the allowance (default unlimited) — see
+     * `ensureSettlementAllowance`'s notes; the same argument applies here,
+     * since `settlement` comes from the matcher's own config.
      */
     async onboard(args) {
         const calls = [
-            { to: args.usdt, data: encodeApprove(args.settlement) },
+            { to: args.usdt, data: encodeApprove(args.settlement, args.amount ?? MAX_UINT256) },
         ];
         let record = null;
         if (this.orderSessionsEnabled && !(await this.orderSessionAccount().catch(() => null))) {
@@ -504,9 +508,13 @@ export class UpDownAccountKitSigner {
             this.persistOrderSession(record);
         return txHash;
     }
-    /** Idempotent USDT approve to the settlement (gasless UserOp). */
+    /** Idempotent USDT approve to the settlement (gasless UserOp). `amount`
+     *  bounds the allowance; defaults to unlimited (MAX_UINT256). */
     async approve(args) {
-        return this.sendCall({ to: args.usdt, data: encodeApprove(args.settlement) });
+        return this.sendCall({
+            to: args.usdt,
+            data: encodeApprove(args.settlement, args.amount ?? MAX_UINT256),
+        });
     }
     /** Transfer USDT out of the SCA to `to` (gasless UserOp). */
     async withdraw(args) {
@@ -617,7 +625,10 @@ async function buildOrderSessionInstall(sca, moduleChain) {
     // Random 4-byte entity id (≥2): 0 is the owner entity, and installing an
     // id that already exists on the account reverts — random keeps collisions
     // with prior sessions (lost storage, other hosts) vanishingly unlikely.
-    const entityId = 2 + Math.floor(Math.random() * 0x7ffffff0);
+    // CSPRNG-drawn: a predictable id lets an observer front-run the install
+    // and brick onboarding by burning the id we're about to claim (the revert
+    // is the whole failure mode this randomness exists to avoid).
+    const entityId = 2 + randomUint31();
     const data = viemMod.encodeFunctionData({
         abi: semiModularAccountBytecodeAbi,
         functionName: "installValidation",
@@ -708,6 +719,18 @@ export async function signWithOrderSession(args) {
 }
 /* ───────────────────────── calldata encoders ───────────────────────── */
 const MAX_UINT256 = (1n << 256n) - 1n;
+/** Uniform CSPRNG draw in [0, 0x7ffffff0). Mirrors `freshSessionId`'s
+ *  contract: throws rather than silently degrading to a weak source. */
+function randomUint31() {
+    const bytes = new Uint8Array(4);
+    const g = globalThis;
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") {
+        throw new Error("globalThis.crypto.getRandomValues unavailable; use Node 18+ or a modern browser");
+    }
+    g.crypto.getRandomValues(bytes);
+    const raw = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0;
+    return raw % 0x7ffffff0;
+}
 function encodeApprove(spender, amount = MAX_UINT256) {
     // approve(address,uint256) selector 0x095ea7b3
     return ("0x095ea7b3" + pad(spender) + pad(amount));

package/dist/approve.d.ts

@@ -1,16 +1,32 @@
 /**
- * One-time USDT.approve(settlement, MaxUint256) helper.
+ * USDT.approve(settlement, …) helper.
  *
  * Path-1 settlement pulls USDT directly from the maker via `transferFrom`
  * inside `enterPosition`. Without this approval the first BUY reverts
  * with `ERC20: insufficient allowance`. Idempotent: reads current
  * allowance and only submits a tx when below threshold.
  *
+ * `amount` defaults to a BOUNDED amount (`DEFAULT_APPROVAL_AMOUNT`, 100k USDT),
+ * not MAX_UINT256 (S2): `settlement` is routinely sourced from a server-supplied
+ * `/config` or market list, so an unlimited approval would grant a server-named
+ * spender unbounded reach into a funded hot wallet. A hot bot key SHOULD still
+ * pass its own inventory-sized bound; `MAX_UINT256` is exported for the rare
+ * caller that explicitly opts into unlimited.
+ *
  * `viem` is a peer dependency — pass in the public + wallet clients you
  * already have so this helper doesn't bake in a transport choice.
  */
 import type { Address, PublicClient, WalletClient } from "viem";
 export declare const MAX_UINT256: bigint;
+/**
+ * S2: bounded default approval (100k USDT, atomic). Caps the blast radius of a
+ * settlement-contract bug (or a hostile server-supplied spender) to one
+ * inventory bound instead of the wallet's entire USDT balance, while sitting
+ * comfortably above `DEFAULT_THRESHOLD` so a continuously-quoting bot isn't
+ * re-approving on every call. Bots with larger inventory should pass their own
+ * `amount`. This is 6-decimal USDT, so 100k * 1e6.
+ */
+export declare const DEFAULT_APPROVAL_AMOUNT: bigint;
 export type EnsureAllowanceResult = {
     status: "already_ok";
     allowance: bigint;
@@ -30,12 +46,27 @@ export type EnsureAllowanceResult = {
  *                          `cfg.pairs[0].settlementAddress` for today's
  *                          single-settlement deploy).
  * @param args.threshold — Re-approve when current allowance is below this
- *                         atomic-USDT amount. Default 10,000 USDT.
+ *                         atomic-USDT amount. Default 10,000 USDT. This is
+ *                         WHEN to top up, not HOW MUCH — see `amount`.
+ * @param args.amount — How much to approve when a top-up is sent. Defaults
+ *                      to `DEFAULT_APPROVAL_AMOUNT` (100k USDT, BOUNDED — S2),
+ *                      not `MAX_UINT256`. `settlement` is routinely sourced
+ *                      from the matcher's own `/config` or market list, so an
+ *                      unlimited approval would grant a server-supplied spender
+ *                      unbounded reach into a funded hot wallet — size this to
+ *                      the inventory the bot actually needs between top-ups.
+ *                      It must exceed `threshold`, or every call re-approves.
+ *                      Pass `MAX_UINT256` to explicitly opt into unlimited.
  *
  * Returns `already_ok` if nothing needed to be done, `approved` with the
- * tx hash if a new approval was sent. Caller can `await
- * publicClient.waitForTransactionReceipt({ hash })` if it wants to confirm
- * before placing orders.
+ * tx hash and the amount approved if a new approval was sent. Caller can
+ * `await publicClient.waitForTransactionReceipt({ hash })` if it wants to
+ * confirm before placing orders.
+ *
+ * Operational note for bounded approvals: the allowance is consumed by
+ * fills, so a bot that quotes continuously WILL run it down. This helper
+ * only tops up when called — call it on your quoting loop, not just at
+ * startup, or fills start reverting with `insufficient allowance` mid-session.
  */
 export declare function ensureSettlementAllowance(args: {
     publicClient: PublicClient;
@@ -43,4 +74,5 @@ export declare function ensureSettlementAllowance(args: {
     usdt: Address;
     settlement: Address;
     threshold?: bigint;
+    amount?: bigint;
 }): Promise<EnsureAllowanceResult>;

package/dist/approve.js

@@ -21,10 +21,17 @@ const ERC20_ABI = [
     },
 ];
 export const MAX_UINT256 = (1n << 256n) - 1n;
-/** Default refresh threshold — re-approve if allowance falls below 10k USDT.
- *  MaxUint256 effectively never decreases with USDT, but if a partial
- *  approval was set in some flow this guards against drift. */
+/** Default refresh threshold — re-approve if allowance falls below 10k USDT. */
 const DEFAULT_THRESHOLD = 10000n * 1000000n;
+/**
+ * S2: bounded default approval (100k USDT, atomic). Caps the blast radius of a
+ * settlement-contract bug (or a hostile server-supplied spender) to one
+ * inventory bound instead of the wallet's entire USDT balance, while sitting
+ * comfortably above `DEFAULT_THRESHOLD` so a continuously-quoting bot isn't
+ * re-approving on every call. Bots with larger inventory should pass their own
+ * `amount`. This is 6-decimal USDT, so 100k * 1e6.
+ */
+export const DEFAULT_APPROVAL_AMOUNT = 100000n * 1000000n;
 /**
  * Ensure the maker has enough USDT allowance on the settlement contract.
  *
@@ -36,12 +43,27 @@ const DEFAULT_THRESHOLD = 10000n * 1000000n;
  *                          `cfg.pairs[0].settlementAddress` for today's
  *                          single-settlement deploy).
  * @param args.threshold — Re-approve when current allowance is below this
- *                         atomic-USDT amount. Default 10,000 USDT.
+ *                         atomic-USDT amount. Default 10,000 USDT. This is
+ *                         WHEN to top up, not HOW MUCH — see `amount`.
+ * @param args.amount — How much to approve when a top-up is sent. Defaults
+ *                      to `DEFAULT_APPROVAL_AMOUNT` (100k USDT, BOUNDED — S2),
+ *                      not `MAX_UINT256`. `settlement` is routinely sourced
+ *                      from the matcher's own `/config` or market list, so an
+ *                      unlimited approval would grant a server-supplied spender
+ *                      unbounded reach into a funded hot wallet — size this to
+ *                      the inventory the bot actually needs between top-ups.
+ *                      It must exceed `threshold`, or every call re-approves.
+ *                      Pass `MAX_UINT256` to explicitly opt into unlimited.
  *
  * Returns `already_ok` if nothing needed to be done, `approved` with the
- * tx hash if a new approval was sent. Caller can `await
- * publicClient.waitForTransactionReceipt({ hash })` if it wants to confirm
- * before placing orders.
+ * tx hash and the amount approved if a new approval was sent. Caller can
+ * `await publicClient.waitForTransactionReceipt({ hash })` if it wants to
+ * confirm before placing orders.
+ *
+ * Operational note for bounded approvals: the allowance is consumed by
+ * fills, so a bot that quotes continuously WILL run it down. This helper
+ * only tops up when called — call it on your quoting loop, not just at
+ * startup, or fills start reverting with `insufficient allowance` mid-session.
  */
 export async function ensureSettlementAllowance(args) {
     const account = args.walletClient.account;
@@ -49,6 +71,11 @@ export async function ensureSettlementAllowance(args) {
         throw new Error("walletClient has no account");
     const owner = account.address;
     const threshold = args.threshold ?? DEFAULT_THRESHOLD;
+    const amount = args.amount ?? DEFAULT_APPROVAL_AMOUNT;
+    if (amount < threshold) {
+        throw new Error(`approve amount (${amount}) is below the re-approve threshold (${threshold}) — ` +
+            "every call would send a redundant approve tx; raise amount or lower threshold");
+    }
     const current = (await args.publicClient.readContract({
         address: args.usdt,
         abi: ERC20_ABI,
@@ -63,7 +90,7 @@ export async function ensureSettlementAllowance(args) {
         address: args.usdt,
         abi: ERC20_ABI,
         functionName: "approve",
-        args: [args.settlement, MAX_UINT256],
+        args: [args.settlement, amount],
     });
-    return { status: "approved", txHash, allowance: MAX_UINT256 };
+    return { status: "approved", txHash, allowance: amount };
 }

package/dist/eip712.d.ts

@@ -60,6 +60,29 @@ export declare function buildWsAuthTypedData(args: {
  * no sessionId).
  */
 export declare function freshSessionId(): `0x${string}`;
+/**
+ * Generate a fresh order/cancel `nonce` from a CSPRNG.
+ *
+ * The nonce is the only thing standing between an order and the backend's
+ * replay store: a PREDICTABLE nonce lets anyone pre-burn a maker's next
+ * nonce and grief their order flow (a liveness attack — the signature
+ * itself still can't be forged). `Math.random()` is not a CSPRNG and
+ * `Date.now()` is public knowledge; neither is acceptable here.
+ *
+ * Deliberately 48 bits, NOT the full uint256: `PostOrderBody.nonce` is a
+ * JSON `number`, so the value must survive `Number(nonce)` losslessly —
+ * anything above 2^53 would silently round and the posted nonce would stop
+ * matching the signed one, failing signature recovery. Across 2^48 values the
+ * CUMULATIVE (birthday-bound) chance that ANY two of one maker's ~750k orders
+ * collide is ~1e-3 (~k²/2·2^48) — about one in a thousand, not vanishing; the
+ * ~1-in-10^9 figure is only the MARGINAL odds that a single new draw hits an
+ * existing nonce at that point. Either way a collision is a rejected order
+ * (retry with a fresh nonce), not a loss.
+ *
+ * Single-writer bots may prefer a monotonic counter (no birthday bound at
+ * all) — seed it from this rather than from the clock.
+ */
+export declare function freshNonce(): bigint;
 /**
  * EIP-712 type schemas. Mirrors the backend's `EIP712_ORDER_TYPES` /
  * `EIP712_CANCEL_TYPES` exactly — if these drift, signatures stop being

package/dist/eip712.js

@@ -66,6 +66,40 @@ export function freshSessionId() {
     }
     return hex;
 }
+/**
+ * Generate a fresh order/cancel `nonce` from a CSPRNG.
+ *
+ * The nonce is the only thing standing between an order and the backend's
+ * replay store: a PREDICTABLE nonce lets anyone pre-burn a maker's next
+ * nonce and grief their order flow (a liveness attack — the signature
+ * itself still can't be forged). `Math.random()` is not a CSPRNG and
+ * `Date.now()` is public knowledge; neither is acceptable here.
+ *
+ * Deliberately 48 bits, NOT the full uint256: `PostOrderBody.nonce` is a
+ * JSON `number`, so the value must survive `Number(nonce)` losslessly —
+ * anything above 2^53 would silently round and the posted nonce would stop
+ * matching the signed one, failing signature recovery. Across 2^48 values the
+ * CUMULATIVE (birthday-bound) chance that ANY two of one maker's ~750k orders
+ * collide is ~1e-3 (~k²/2·2^48) — about one in a thousand, not vanishing; the
+ * ~1-in-10^9 figure is only the MARGINAL odds that a single new draw hits an
+ * existing nonce at that point. Either way a collision is a rejected order
+ * (retry with a fresh nonce), not a loss.
+ *
+ * Single-writer bots may prefer a monotonic counter (no birthday bound at
+ * all) — seed it from this rather than from the clock.
+ */
+export function freshNonce() {
+    const bytes = new Uint8Array(6);
+    const g = globalThis;
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") {
+        throw new Error("globalThis.crypto.getRandomValues unavailable; use Node 18+ or a modern browser");
+    }
+    g.crypto.getRandomValues(bytes);
+    let n = 0n;
+    for (let i = 0; i < bytes.length; i++)
+        n = (n << 8n) | BigInt(bytes[i]);
+    return n;
+}
 /**
  * EIP-712 type schemas. Mirrors the backend's `EIP712_ORDER_TYPES` /
  * `EIP712_CANCEL_TYPES` exactly — if these drift, signatures stop being

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

@@ -1,8 +1,10 @@
 export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
 export { UpDownWsClient, type UpDownWsMessage, type SubscribePayload, type WsAuthCredentials, type ConnectAuthedOptions, } from "./ws.js";
-export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, type OrderSignMessage, type CancelSignMessage, type WsAuthMessage, type ParsedComposite, } from "./eip712.js";
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, type OrderSignMessage, type CancelSignMessage, type WsAuthMessage, type ParsedComposite, } from "./eip712.js";
 export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, type ClobAuthDomain, type ClobAuthMessage, } from "./auth.js";
-export { ensureSettlementAllowance, MAX_UINT256, type EnsureAllowanceResult, } from "./approve.js";
+export { ensureSettlementAllowance, MAX_UINT256, DEFAULT_APPROVAL_AMOUNT, type EnsureAllowanceResult, } from "./approve.js";
+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

@@ -2,11 +2,15 @@
 export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
 export { UpDownWsClient, } from "./ws.js";
 // EIP-712 helpers
-export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, } from "./eip712.js";
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, } from "./eip712.js";
 // Phase 3 / Gate 1 — L2 HMAC auth helpers
 export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, } from "./auth.js";
 // Approve helper
-export { ensureSettlementAllowance, MAX_UINT256, } from "./approve.js";
+export { ensureSettlementAllowance, MAX_UINT256, DEFAULT_APPROVAL_AMOUNT, } from "./approve.js";
+// S5 — on-chain fill reconciliation (independent detector for the B1/B6
+// off-chain ledger bugs: diffs authoritative on-chain `userShares` against
+// what the matcher reported).
+export { readOnChainHolderShares, reconcileFills, reportedFromPositions, } from "./reconcile.js";
 // Account Kit (Alchemy SCA) — owner-key ERC-1271 order signing + gasless custody.
 // Peer deps (@account-kit/*, @aa-sdk/core) are lazy-imported; importing this
 // module does NOT require them unless you construct/connect the signer.
@@ -16,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/reconcile.d.ts

@@ -0,0 +1,103 @@
+/**
+ * S5 — on-chain fill reconciliation.
+ *
+ * The matcher reports an MM's positions off-chain (`GET /positions/:wallet`,
+ * `GET /markets/:address/holders`). On-chain, `UpDownSettlement.userShares`
+ * (a public mapping) is the AUTHORITATIVE record of what each holder actually
+ * owns — it is the number `redeemFor`/`redeem` pays against. A bot that trusts
+ * only the matcher cannot see the off-chain ledger-integrity failures in the
+ * pre-prod review (B1 collateral double-commit, B6 phantom positions): both
+ * manifest as the matcher REPORTING shares (or a fill) that on-chain state does
+ * not back. This helper closes that gap — it reads `userShares` directly and
+ * diffs it against what the matcher reported, so an MM has an independent
+ * detector rather than taking the API's word for its own book.
+ *
+ * `viem` is a peer dependency — pass the `PublicClient` you already have.
+ */
+import type { Address, PublicClient } from "viem";
+import { type OptionValue } from "./types.js";
+/** Authoritative on-chain shares for one holder in one market. */
+export interface OnChainHolderShares {
+    marketId: bigint;
+    holder: Address;
+    /** `userShares[marketId][holder][UP]` (atomic). */
+    up: bigint;
+    /** `userShares[marketId][holder][DOWN]` (atomic). */
+    down: bigint;
+    resolved: boolean;
+    /** Winning option once resolved: `Option.UP`/`Option.DOWN`, or 0 if unresolved. */
+    winner: OptionValue | 0;
+}
+/**
+ * Read a holder's authoritative on-chain shares (both options) and the market's
+ * resolution state in one batch of `readContract` calls.
+ */
+export declare function readOnChainHolderShares(args: {
+    publicClient: PublicClient;
+    settlement: Address;
+    marketId: bigint;
+    holder: Address;
+}): Promise<OnChainHolderShares>;
+export type ReconcileStatus = "match" | "reported_over" | "reported_under";
+/** Per-option reconciliation of matcher-reported vs on-chain shares. */
+export interface ShareReconciliation {
+    option: OptionValue;
+    optionLabel: "UP" | "DOWN";
+    /** Authoritative on-chain `userShares`. */
+    onChain: bigint;
+    /** What the matcher reported off-chain. */
+    reported: bigint;
+    /** `reported - onChain`. Positive = matcher over-reports (phantom risk). */
+    drift: bigint;
+    status: ReconcileStatus;
+}
+export interface FillReconciliationReport {
+    marketId: bigint;
+    holder: Address;
+    resolved: boolean;
+    winner: OptionValue | 0;
+    lines: ShareReconciliation[];
+    /** True when every option reconciles exactly. */
+    ok: boolean;
+    /**
+     * True when the matcher reports MORE shares than the chain backs on some
+     * option (`reported_over`) — the dangerous direction: a phantom position the
+     * MM would price against but cannot redeem. Post-redemption a winner-side
+     * `reported_over` is benign (the holder was already paid and `userShares`
+     * zeroed); check `resolved`/`winner` before alerting.
+     */
+    hasPhantom: boolean;
+}
+/**
+ * Reconcile matcher-reported net shares against on-chain `userShares` for one
+ * holder in one market. `reported` is the net shares the matcher attributes to
+ * the holder per option (atomic units), e.g. folded from `GET /positions/:wallet`
+ * — see {@link reportedFromPositions}.
+ *
+ * Returns a per-option diff plus `ok` / `hasPhantom` flags an MM can gate on.
+ * A healthy market reconciles exactly; a divergence is the on-chain signature of
+ * the B1/B6 ledger bugs (or of a redemption the off-chain ledger hasn't caught
+ * up to yet — hence the `resolved`/`winner` context).
+ */
+export declare function reconcileFills(args: {
+    publicClient: PublicClient;
+    settlement: Address;
+    marketId: bigint;
+    holder: Address;
+    reported: {
+        up: bigint;
+        down: bigint;
+    };
+}): Promise<FillReconciliationReport>;
+/**
+ * Fold a matcher `Position[]` list (from `GET /positions/:wallet`, already
+ * filtered to one market) into the `{ up, down }` atomic-share shape
+ * {@link reconcileFills} expects. Unknown option labels are ignored.
+ */
+export declare function reportedFromPositions(positions: ReadonlyArray<{
+    optionLabel: "UP" | "DOWN";
+    shares: string;
+}>): {
+    up: bigint;
+    down: bigint;
+};

package/dist/reconcile.js

@@ -0,0 +1,129 @@
+import { Option } from "./types.js";
+/** Minimal read-only slice of the settlement ABI — no write surface. */
+const SETTLEMENT_RECON_ABI = [
+    {
+        type: "function",
+        name: "userShares",
+        stateMutability: "view",
+        inputs: [
+            { name: "marketId", type: "uint256" },
+            { name: "holder", type: "address" },
+            { name: "option", type: "uint8" },
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "getMarket",
+        stateMutability: "view",
+        inputs: [{ name: "marketId", type: "uint256" }],
+        outputs: [
+            {
+                name: "",
+                type: "tuple",
+                components: [
+                    { name: "pairId", type: "bytes32" },
+                    { name: "cashUpFlow", type: "uint128" },
+                    { name: "cashDownFlow", type: "uint128" },
+                    { name: "startTime", type: "uint64" },
+                    { name: "endTime", type: "uint64" },
+                    { name: "duration", type: "uint32" },
+                    { name: "winner", type: "uint8" },
+                    { name: "resolved", type: "bool" },
+                    { name: "settled", type: "bool" },
+                    { name: "strikePrice", type: "int128" },
+                    { name: "settlementPrice", type: "int128" },
+                ],
+            },
+        ],
+    },
+];
+/**
+ * Read a holder's authoritative on-chain shares (both options) and the market's
+ * resolution state in one batch of `readContract` calls.
+ */
+export async function readOnChainHolderShares(args) {
+    const { publicClient, settlement, marketId, holder } = args;
+    const read = (option) => publicClient.readContract({
+        address: settlement,
+        abi: SETTLEMENT_RECON_ABI,
+        functionName: "userShares",
+        args: [marketId, holder, option],
+    });
+    const [up, down, market] = await Promise.all([
+        read(Option.UP),
+        read(Option.DOWN),
+        publicClient.readContract({
+            address: settlement,
+            abi: SETTLEMENT_RECON_ABI,
+            functionName: "getMarket",
+            args: [marketId],
+        }),
+    ]);
+    const winnerNum = Number(market.winner);
+    const winner = winnerNum === Option.UP ? Option.UP : winnerNum === Option.DOWN ? Option.DOWN : 0;
+    return { marketId, holder, up, down, resolved: market.resolved, winner };
+}
+function classify(onChain, reported) {
+    if (reported === onChain)
+        return "match";
+    return reported > onChain ? "reported_over" : "reported_under";
+}
+/**
+ * Reconcile matcher-reported net shares against on-chain `userShares` for one
+ * holder in one market. `reported` is the net shares the matcher attributes to
+ * the holder per option (atomic units), e.g. folded from `GET /positions/:wallet`
+ * — see {@link reportedFromPositions}.
+ *
+ * Returns a per-option diff plus `ok` / `hasPhantom` flags an MM can gate on.
+ * A healthy market reconciles exactly; a divergence is the on-chain signature of
+ * the B1/B6 ledger bugs (or of a redemption the off-chain ledger hasn't caught
+ * up to yet — hence the `resolved`/`winner` context).
+ */
+export async function reconcileFills(args) {
+    const chain = await readOnChainHolderShares(args);
+    const lines = [
+        {
+            option: Option.UP,
+            optionLabel: "UP",
+            onChain: chain.up,
+            reported: args.reported.up,
+            drift: args.reported.up - chain.up,
+            status: classify(chain.up, args.reported.up),
+        },
+        {
+            option: Option.DOWN,
+            optionLabel: "DOWN",
+            onChain: chain.down,
+            reported: args.reported.down,
+            drift: args.reported.down - chain.down,
+            status: classify(chain.down, args.reported.down),
+        },
+    ];
+    return {
+        marketId: args.marketId,
+        holder: args.holder,
+        resolved: chain.resolved,
+        winner: chain.winner,
+        lines,
+        ok: lines.every((l) => l.status === "match"),
+        hasPhantom: lines.some((l) => l.status === "reported_over"),
+    };
+}
+/**
+ * Fold a matcher `Position[]` list (from `GET /positions/:wallet`, already
+ * filtered to one market) into the `{ up, down }` atomic-share shape
+ * {@link reconcileFills} expects. Unknown option labels are ignored.
+ */
+export function reportedFromPositions(positions) {
+    let up = 0n;
+    let down = 0n;
+    for (const p of positions) {
+        const s = BigInt(p.shares);
+        if (p.optionLabel === "UP")
+            up += s;
+        else if (p.optionLabel === "DOWN")
+            down += s;
+    }
+    return { up, down };
+}

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,6 +93,64 @@ 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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.3.0",
-  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets — matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
+  "version": "0.5.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.",
   "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",
+    "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",