@pulsepairs/sdk 0.5.1 → 0.6.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/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/index.d.ts

@@ -7,4 +7,4 @@ export { readOnChainHolderShares, reconcileFills, reportedFromPositions, type On
 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";
+export { OrderType, OrderSide, Option, takerPriceBps, 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

@@ -25,4 +25,4 @@ export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSess
 // 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";
+export { OrderType, OrderSide, Option, takerPriceBps, } from "./types.js";

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

@@ -140,18 +140,40 @@ export type Position = {
 export type Trade = {
     tradeId: string;
     market: string;
+    /** The TAKER leg's option (1=UP, 2=DOWN). On a MINT/MERGE the maker leg is
+     *  the opposite option. */
     option: number;
     buyOrderId: string;
     sellOrderId: string;
+    /** NORMAL: the buyer. MINT/MERGE: the aggressor (taker) — a buyer on MINT,
+     *  a seller on MERGE. */
     buyer: string;
+    /** NORMAL: the seller. MINT/MERGE: the resting maker, on the OPPOSITE option
+     *  to `option`. */
     seller: string;
+    /** Basis points — the resting MAKER's pegged execution price. On a
+     *  complementary fill the taker executed at the complement; render taker
+     *  fills with `takerPrice`, not this. */
     price: number;
     amount: string;
     platformFee: string;
     makerFee: string;
     settlementStatus: string;
     createdAt: string;
+    /** Match geometry. NORMAL = same-option fill. MINT/MERGE = complementary
+     *  cross (opposite-option legs). Optional so a pre-2026-07-17 backend
+     *  (field absent) degrades rather than breaking a consumer. */
+    matchType?: "NORMAL" | "MINT" | "MERGE";
+    /** Basis points the taker actually executed at: `price` on NORMAL,
+     *  `10000 − price` on MINT/MERGE. Prefer this over `price` when rendering a
+     *  wallet's own fills. Optional for the same back-compat reason. */
+    takerPrice?: number;
 };
+/** The price the AGGRESSOR paid/received per share, in bps. Mirrors the
+ *  backend's `takerPriceBps`: the complement on a complementary fill, else the
+ *  row price. Falls back to computing the complement if a row predates the
+ *  `takerPrice` field. */
+export declare function takerPriceBps(trade: Pick<Trade, "price" | "matchType" | "takerPrice">): number;
 export type OrderStatus = "OPEN" | "PARTIALLY_FILLED" | "FILLED" | "CANCEL_PENDING" | "CANCELLED" | string;
 export type OrderRow = {
     orderId: string;

package/dist/types.js

@@ -18,3 +18,14 @@ export const Option = {
     UP: 1,
     DOWN: 2,
 };
+/** The price the AGGRESSOR paid/received per share, in bps. Mirrors the
+ *  backend's `takerPriceBps`: the complement on a complementary fill, else the
+ *  row price. Falls back to computing the complement if a row predates the
+ *  `takerPrice` field. */
+export function takerPriceBps(trade) {
+    if (typeof trade.takerPrice === "number")
+        return trade.takerPrice;
+    return trade.matchType === "MINT" || trade.matchType === "MERGE"
+        ? 10000 - trade.price
+        : trade.price;
+}

package/package.json

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