@pulsepairs/sdk 0.5.2 → 0.7.0

package/README.md

@@ -19,6 +19,10 @@ It gives you three things:
    Alchemy smart-contract account (the SAME wallet rain.trade uses), plus
    gasless onboarding / approve / withdraw.
 
+> This README is the quickstart. For the exhaustive reference — every export,
+> its units, its failure modes, the WS protocol, the full type surface and a
+> troubleshooting table — see **[`DOCUMENTATION.md`](./DOCUMENTATION.md)**.
+
 > **Live integration environment:** a public demo of the full stack (markets
 > cycling 24/7 on Arbitrum One, mock oracle, mintable test USDT) runs at
 > **https://demo-pulsepairs.rainwins.com** with the matcher API/WS at

package/dist/eip712.d.ts

@@ -218,20 +218,28 @@ export declare function parseCompositeMarketKey(market: string): ParsedComposite
 export declare function centsToBps(cents: number): number;
 /** Bps → cents (5500 → 55). Inverse of `centsToBps`. */
 export declare function bpsToCents(bps: number): number;
-/** Atomic-USDT denomination of the documented $5–$500 stake window. */
-export declare const MIN_STAKE_ATOMIC = 5000000n;
+/**
+ * Atomic denomination of the documented stake window, in SHARE FACE VALUE
+ * — `Order.amount` is a share count, not the cash spent (the buyer pays
+ * `amount × price / 10000`). A $1 floor is $1 of face: ~$0.51 of cash at
+ * 51¢. Lowered from $5 → $1 on 2026-07-23 (Polymarket parity).
+ */
+export declare const MIN_STAKE_ATOMIC = 1000000n;
 export declare const MAX_STAKE_ATOMIC = 500000000n;
 /** Parse a USD string (e.g. "5", "5.50", "12.345") into atomic USDT.
  *  Rejects negatives + non-finite. */
 export declare function parseStake(usd: string | number): bigint;
 /**
- * Defense-in-depth stake clamp. Throws if `amountAtomic` is outside the
- * documented `$5 ≤ stake ≤ $500` window. Frontend gates these too; backend
- * enforces only the upper bound today (BUG-S2.1 — see PULSEPAIRS_BACKLOG).
- * SDK callers should validate before signing so a bad stake never produces
- * a signed payload at all.
+ * Defense-in-depth stake clamp. Throws if `amountAtomic` (share face value)
+ * is outside the documented `$1 ≤ stake ≤ $500` window; the backend applies
+ * the same window at the API boundary. SDK callers should validate before
+ * signing so a bad stake never produces a signed payload at all.
+ *
+ * Pass `side: "SELL"` for exits: the minimum is ENTRY-ONLY, so a holder left
+ * with a sub-$1 position (routine after a partial fill) can always sell it.
+ * The default stays "BUY" so existing callers keep the strict branch.
  */
-export declare function assertStakeBounds(amountAtomic: bigint): void;
+export declare function assertStakeBounds(amountAtomic: bigint, side?: "BUY" | "SELL"): void;
 /**
  * Probability-weighted fee in atomic USDT. Mirrors the backend / contract
  * formula. Returns the fee for `notionalAtomic` filled at `priceBps`.

package/dist/eip712.js

@@ -220,8 +220,13 @@ export function bpsToCents(bps) {
     }
     return bps / 100;
 }
-/** Atomic-USDT denomination of the documented $5–$500 stake window. */
-export const MIN_STAKE_ATOMIC = 5000000n;
+/**
+ * Atomic denomination of the documented stake window, in SHARE FACE VALUE
+ * — `Order.amount` is a share count, not the cash spent (the buyer pays
+ * `amount × price / 10000`). A $1 floor is $1 of face: ~$0.51 of cash at
+ * 51¢. Lowered from $5 → $1 on 2026-07-23 (Polymarket parity).
+ */
+export const MIN_STAKE_ATOMIC = 1000000n;
 export const MAX_STAKE_ATOMIC = 500000000n;
 /** Parse a USD string (e.g. "5", "5.50", "12.345") into atomic USDT.
  *  Rejects negatives + non-finite. */
@@ -233,14 +238,17 @@ export function parseStake(usd) {
     return BigInt(Math.round(n * 1e6));
 }
 /**
- * Defense-in-depth stake clamp. Throws if `amountAtomic` is outside the
- * documented `$5 ≤ stake ≤ $500` window. Frontend gates these too; backend
- * enforces only the upper bound today (BUG-S2.1 — see PULSEPAIRS_BACKLOG).
- * SDK callers should validate before signing so a bad stake never produces
- * a signed payload at all.
+ * Defense-in-depth stake clamp. Throws if `amountAtomic` (share face value)
+ * is outside the documented `$1 ≤ stake ≤ $500` window; the backend applies
+ * the same window at the API boundary. SDK callers should validate before
+ * signing so a bad stake never produces a signed payload at all.
+ *
+ * Pass `side: "SELL"` for exits: the minimum is ENTRY-ONLY, so a holder left
+ * with a sub-$1 position (routine after a partial fill) can always sell it.
+ * The default stays "BUY" so existing callers keep the strict branch.
  */
-export function assertStakeBounds(amountAtomic) {
-    if (amountAtomic < MIN_STAKE_ATOMIC) {
+export function assertStakeBounds(amountAtomic, side = "BUY") {
+    if (side === "BUY" && amountAtomic < MIN_STAKE_ATOMIC) {
         throw new Error(`stake below $${Number(MIN_STAKE_ATOMIC) / 1e6} minimum`);
     }
     if (amountAtomic > MAX_STAKE_ATOMIC) {

package/dist/http.d.ts

@@ -18,6 +18,18 @@ export declare class UpDownHttpClient {
     getOrderbook(marketAddress: string): Promise<OrderBookFull>;
     getBalance(wallet: string): Promise<Balance>;
     getPositions(wallet: string): Promise<Position[]>;
+    /**
+     * Open positions PLUS the wallet-level realized-from-sells scalar (atomic
+     * USDT, signed). Uses `?includeRealized=1`; `getPositions` keeps the plain
+     * bare-array response for callers that don't need the realized term.
+     *
+     * Tolerant of a backend that predates the envelope: if the body comes back a
+     * bare array, the realized term is simply reported as "0" rather than failing.
+     */
+    getPositionsWithRealized(wallet: string): Promise<{
+        positions: Position[];
+        realizedFromSells: string;
+    }>;
     getTrades(wallet: string, opts?: {
         limit?: number;
         offset?: number;

package/dist/http.js

@@ -69,6 +69,21 @@ export class UpDownHttpClient {
         const res = await fetch(buildUrl(this.baseUrl, `/positions/${wallet}`));
         return parseJson(res);
     }
+    /**
+     * Open positions PLUS the wallet-level realized-from-sells scalar (atomic
+     * USDT, signed). Uses `?includeRealized=1`; `getPositions` keeps the plain
+     * bare-array response for callers that don't need the realized term.
+     *
+     * Tolerant of a backend that predates the envelope: if the body comes back a
+     * bare array, the realized term is simply reported as "0" rather than failing.
+     */
+    async getPositionsWithRealized(wallet) {
+        const res = await fetch(buildUrl(this.baseUrl, `/positions/${wallet}`, { includeRealized: 1 }));
+        const body = await parseJson(res);
+        if (Array.isArray(body))
+            return { positions: body, realizedFromSells: "0" };
+        return { positions: body.positions ?? [], realizedFromSells: body.realizedFromSells ?? "0" };
+    }
     async getTrades(wallet, opts) {
         const res = await fetch(buildUrl(this.baseUrl, `/trades/${wallet}`, {
             limit: opts?.limit,
@@ -91,9 +106,15 @@ export class UpDownHttpClient {
      * @param opts.usdtDecimals display-float decimals (default 6).
      */
     async getPnl(wallet, opts) {
-        const positions = await this.getPositions(wallet);
+        // Fetch the realized-from-sells scalar alongside the positions so the
+        // rolled-up PnL carries realized (from manual sells) as well as unrealized.
+        // Backward-tolerant: an old backend yields "0" here, not an error.
+        const { positions, realizedFromSells } = await this.getPositionsWithRealized(wallet);
         if (positions.length === 0) {
-            return computePortfolioPnl([], new Map(), { usdtDecimals: opts?.usdtDecimals });
+            return computePortfolioPnl([], new Map(), {
+                usdtDecimals: opts?.usdtDecimals,
+                realizedFromSells,
+            });
         }
         const marketKeys = Array.from(new Set(positions.map((p) => p.market)));
         const details = await Promise.all(marketKeys.map((key) => this.getMarket(key).catch(() => null)));
@@ -111,6 +132,7 @@ export class UpDownHttpClient {
         return computePortfolioPnl(positions, marketsByKey, {
             fees,
             usdtDecimals: opts?.usdtDecimals,
+            realizedFromSells,
         });
     }
     async getOrders(wallet, opts) {

package/dist/pnl.d.ts

@@ -82,6 +82,18 @@ export type PortfolioPnl = {
      *  (see `feesPaidByWallet`); "0" otherwise. Not netted into `unrealizedPnl`
      *  — cost basis is fee-exclusive, so fees stay a separate, explicit line. */
     fees: string;
+    /**
+     * Atomic USDT (signed) realized P&L booked from manual market-SELLs, across
+     * ALL of the wallet's positions — including ones sold to zero net shares,
+     * which never appear in `positions`. "0" when the caller did not supply it
+     * (or the backend predates the `?includeRealized=1` envelope).
+     *
+     * Report it ALONGSIDE `unrealizedPnl`, which already carries settled
+     * survivors at full-face/zero (`resolved: true`); the two together are the
+     * wallet's complete realized+unrealized P&L. It is average-cost per sell, so
+     * only the combined figure is order-invariant — never surface it standalone.
+     */
+    realizedFromSells: string;
 };
 /** Options controlling how one position is valued. */
 export type PositionPnlOptions = {
@@ -130,9 +142,13 @@ export declare function positionPnl(position: Position, opts?: PositionPnlOption
  *  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. */
+ *  `feesPaidByWallet`) to carry a fee line through; it is reported, not netted.
+ *  Pass `realizedFromSells` (atomic USDT string, from `GET
+ *  /positions/:wallet?includeRealized=1`) to carry the manual-sell realized
+ *  term; likewise reported, never netted into `unrealizedPnl`. */
 export declare function portfolioPnl(items: PositionPnl[], opts?: {
     fees?: string;
+    realizedFromSells?: string;
     usdtDecimals?: number;
 }): PortfolioPnl;
 /**
@@ -146,5 +162,6 @@ export declare function portfolioPnl(items: PositionPnl[], opts?: {
  */
 export declare function computePortfolioPnl(positions: Position[], marketsByKey: Map<string, Pick<MarketDetail, "winner" | "orderBook">>, opts?: {
     fees?: string;
+    realizedFromSells?: string;
     usdtDecimals?: number;
 }): PortfolioPnl;

package/dist/pnl.js

@@ -113,7 +113,10 @@ export function feesPaidByWallet(wallet, trades) {
     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. */
+ *  `feesPaidByWallet`) to carry a fee line through; it is reported, not netted.
+ *  Pass `realizedFromSells` (atomic USDT string, from `GET
+ *  /positions/:wallet?includeRealized=1`) to carry the manual-sell realized
+ *  term; likewise reported, never netted into `unrealizedPnl`. */
 export function portfolioPnl(items, opts = {}) {
     const decimals = opts.usdtDecimals ?? DEFAULT_USDT_DECIMALS;
     let costBasis = 0n;
@@ -131,6 +134,7 @@ export function portfolioPnl(items, opts = {}) {
         unrealizedPnlUsdt: atomicToUsdt(unrealizedPnl, decimals),
         roiPct: pctOf(unrealizedPnl, costBasis),
         fees: opts.fees ?? "0",
+        realizedFromSells: opts.realizedFromSells ?? "0",
     };
 }
 /**

package/dist/types.d.ts

@@ -81,8 +81,24 @@ export type MarketListItem = {
     duration: number;
     status: "ACTIVE" | "TRADING_ENDED" | "RESOLVED" | "CLAIMED" | string;
     winner: number | null;
-    upPrice: string;
-    downPrice: string;
+    /**
+     * Odds in basis points of $1 (5000 = 50%), from the mid of the live book.
+     * `null` when no price is defined (empty / one-sided book, or trading not
+     * open) — render "—", never 0%. `0` / `10000` occur only on a settled
+     * market, where they are the outcome. When non-null,
+     * `upPrice + downPrice === 10000`.
+     *
+     * BREAKING 2026-07-26: previously `string`, and previously carried the
+     * on-chain cumulative collateral flow rather than any price.
+     */
+    upPrice: number | null;
+    downPrice: number | null;
+    /**
+     * Why `upPrice`/`downPrice` are what they are, so a `null` is explained
+     * rather than merely absent. Widened to `string` deliberately: this is an
+     * OPEN set and new values may be added — do not switch exhaustively.
+     */
+    priceSource?: "settled" | "pending_resolution" | "not_trading" | "book_mid" | "none" | string;
     strikePrice?: string;
     settlementPrice?: string;
     volume: string;
@@ -159,6 +175,13 @@ export type Trade = {
     platformFee: string;
     makerFee: string;
     settlementStatus: string;
+    /** Hash of the on-chain settlement tx, for linking a fill to the explorer.
+     *  Null until the tx is broadcast — and reset to null if a reconcile drops
+     *  it — so treat absence as "pending", not "missing". Complementary
+     *  (MINT/MERGE) fills settle in batches, so the same hash legitimately
+     *  repeats across several trades. Optional for back-compat with a
+     *  pre-2026-07-21 backend. */
+    settlementTxHash?: string | null;
     createdAt: string;
     /** Match geometry. NORMAL = same-option fill. MINT/MERGE = complementary
      *  cross (opposite-option legs). Optional so a pre-2026-07-17 backend

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.5.2",
-  "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.7.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",
@@ -27,7 +27,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "DOCUMENTATION.md"
   ],
   "sideEffects": false,
   "scripts": {