@pulsepairs/sdk 0.6.0 → 0.7.0

package/DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # `@pulsepairs/sdk` — Reference Documentation
 
-**Version:** 0.6.0 · **License:** UNLICENSED · **Runtime:** Node ≥ 18 or a modern browser
+**Version:** 0.7.0 · **License:** UNLICENSED · **Runtime:** Node ≥ 18 or a modern browser
 
 Complete reference for the UpDown (PulsePairs) TypeScript SDK: every export, its
 units, its failure modes, and the protocol it speaks.
@@ -699,19 +699,32 @@ fresh nonce. Single-writer bots may prefer a monotonic counter — seed it from
 centsToBps(cents: number): number      // 55 → 5500; 49.5 → 4950. Throws outside (0,100)
 bpsToCents(bps: number): number        // 5500 → 55. Throws outside (0,10000)
 parseStake(usd: string | number): bigint   // "5.50" → 5_500_000n. Rejects negative/non-finite
-assertStakeBounds(amountAtomic: bigint): void
+assertStakeBounds(amountAtomic: bigint, side?: "BUY" | "SELL"): void
 feeAtomic(notionalAtomic, priceBps, cfg): bigint
 
-MIN_STAKE_ATOMIC = 5_000_000n     // $5
-MAX_STAKE_ATOMIC = 500_000_000n   // $500
+MIN_STAKE_ATOMIC = 1_000_000n     // $1 of share FACE value (BUY only)
+MAX_STAKE_ATOMIC = 500_000_000n   // $500 of share FACE value
 ```
 
 Both `centsToBps` and `bpsToCents` are exclusive at both ends — 0¢ and 100¢ are
 not tradeable prices, and passing either throws.
 
-`assertStakeBounds` is defence in depth. The frontend gates these bounds and the
-backend enforces only the upper one today, so validating **before signing**
-means a bad stake never becomes a signed payload at all.
+`assertStakeBounds` is defence in depth. The backend enforces the same window at
+the API boundary, so validating **before signing** means a bad stake never
+becomes a signed payload at all.
+
+Two things about the window that bite integrators:
+
+- **The bound is on FACE, not cash.** `Order.amount` is a share count; the buyer
+  pays `amount × price / 10000`. A $1 minimum is $1 of face — about **$0.51 of
+  cash at 51¢**, $0.09 at 9¢. If your UI collects a cash budget, convert to
+  shares first (`cash / price`), which is always ≥ the cash figure, so a
+  cash-denominated gate at $1 sits safely above this bound at every price.
+- **The minimum is entry-only.** Pass `side: "SELL"` for exits — a holder left
+  with 0.42 shares after a partial fill must be able to sell them. The maximum
+  still applies to both sides.
+
+> Changed 2026-07-23 (SDK 0.7.0): minimum was `5_000_000n` ($5, both sides).
 
 `feeAtomic` mirrors the backend and contract formula (§3.4). Treats a missing
 `cfg.feeModel` as probability-weighted:
@@ -1234,8 +1247,8 @@ type MarketListItem = {
   duration: number;                 // sec
   status: "ACTIVE" | "TRADING_ENDED" | "RESOLVED" | "CLAIMED" | string;
   winner: number | null;            // 1 = UP, 2 = DOWN, null = unresolved
-  upPrice: string;
-  downPrice: string;
+  upPrice: number | null;           // bps of $1 from the live book mid; null = no price
+  downPrice: number | null;         // always 10000 - upPrice; null exactly when upPrice is
   strikePrice?: string;
   settlementPrice?: string;
   volume: string;

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/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.6.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.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",