@pear-protocol/types 1.16.0 → 1.18.0

package/dist/notification/responses.d.ts

@@ -10,18 +10,19 @@ export declare const NotificationListResponse: z.ZodObject<{
             STOP_LOSS_FAILED: "STOP_LOSS_FAILED";
             TRIGGER_ORDER_FAILED: "TRIGGER_ORDER_FAILED";
             ATTACHED_TRIGGER_DISCARDED: "ATTACHED_TRIGGER_DISCARDED";
+            AUTO_REBALANCE_EXECUTED: "AUTO_REBALANCE_EXECUTED";
+            AUTO_REBALANCE_FAILED: "AUTO_REBALANCE_FAILED";
+            AUTO_REBALANCE_PAUSED: "AUTO_REBALANCE_PAUSED";
         }>;
         parameters: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            type: z.ZodLiteral<"take_profit">;
-            triggerId: z.ZodUUID;
-            positionId: z.ZodUUID;
-            connector: z.ZodEnum<{
-                hyperliquid: "hyperliquid";
-                binance: "binance";
-                bybit: "bybit";
-                okx: "okx";
-                lighter: "lighter";
-            }>;
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
             metric: z.ZodOptional<z.ZodEnum<{
                 price: "price";
                 notional: "notional";
@@ -41,8 +42,7 @@ export declare const NotificationListResponse: z.ZodObject<{
             }>>;
             level: z.ZodOptional<z.ZodNumber>;
             reason: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"stop_loss">;
+            type: z.ZodLiteral<"take_profit">;
             triggerId: z.ZodUUID;
             positionId: z.ZodUUID;
             connector: z.ZodEnum<{
@@ -52,6 +52,15 @@ export declare const NotificationListResponse: z.ZodObject<{
                 okx: "okx";
                 lighter: "lighter";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
             metric: z.ZodOptional<z.ZodEnum<{
                 price: "price";
                 notional: "notional";
@@ -71,8 +80,7 @@ export declare const NotificationListResponse: z.ZodObject<{
             }>>;
             level: z.ZodOptional<z.ZodNumber>;
             reason: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"trigger_order">;
+            type: z.ZodLiteral<"stop_loss">;
             triggerId: z.ZodUUID;
             positionId: z.ZodUUID;
             connector: z.ZodEnum<{
@@ -82,6 +90,15 @@ export declare const NotificationListResponse: z.ZodObject<{
                 okx: "okx";
                 lighter: "lighter";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
             metric: z.ZodOptional<z.ZodEnum<{
                 price: "price";
                 notional: "notional";
@@ -101,9 +118,9 @@ export declare const NotificationListResponse: z.ZodObject<{
             }>>;
             level: z.ZodOptional<z.ZodNumber>;
             reason: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"default_trigger">;
+            type: z.ZodLiteral<"trigger_order">;
             triggerId: z.ZodUUID;
+            positionId: z.ZodUUID;
             connector: z.ZodEnum<{
                 hyperliquid: "hyperliquid";
                 binance: "binance";
@@ -111,6 +128,15 @@ export declare const NotificationListResponse: z.ZodObject<{
                 okx: "okx";
                 lighter: "lighter";
             }>;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
             metric: z.ZodOptional<z.ZodEnum<{
                 price: "price";
                 notional: "notional";
@@ -130,7 +156,24 @@ export declare const NotificationListResponse: z.ZodObject<{
             }>>;
             level: z.ZodOptional<z.ZodNumber>;
             reason: z.ZodOptional<z.ZodString>;
+            type: z.ZodLiteral<"default_trigger">;
+            triggerId: z.ZodUUID;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
         }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
             type: z.ZodLiteral<"attached_trigger_discarded">;
             positionId: z.ZodUUID;
             positionKey: z.ZodString;
@@ -170,6 +213,91 @@ export declare const NotificationListResponse: z.ZodObject<{
                 }>;
             }, z.core.$strip>>;
             activeTriggerLimit: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+                currentWeight: z.ZodNumber;
+                targetWeight: z.ZodNumber;
+            }, z.core.$strip>>;
+            driftPct: z.ZodNumber;
+            notionalUsd: z.ZodNumber;
+            configId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            positionKey: z.ZodString;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            weightSource: z.ZodEnum<{
+                INITIAL_WEIGHT: "INITIAL_WEIGHT";
+                LIVE_BETA: "LIVE_BETA";
+            }>;
+            type: z.ZodLiteral<"auto_rebalance_executed">;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+                currentWeight: z.ZodNumber;
+                targetWeight: z.ZodNumber;
+            }, z.core.$strip>>;
+            driftPct: z.ZodNumber;
+            reason: z.ZodString;
+            configId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            positionKey: z.ZodString;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            weightSource: z.ZodEnum<{
+                INITIAL_WEIGHT: "INITIAL_WEIGHT";
+                LIVE_BETA: "LIVE_BETA";
+            }>;
+            type: z.ZodLiteral<"auto_rebalance_failed">;
+        }, z.core.$strip>, z.ZodObject<{
+            legs: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                symbol: z.ZodString;
+                side: z.ZodEnum<{
+                    BUY: "BUY";
+                    SELL: "SELL";
+                }>;
+            }, z.core.$strip>>;
+            pausedReason: z.ZodEnum<{
+                POSITION_CHANGED: "POSITION_CHANGED";
+                REPEATED_FAILURES: "REPEATED_FAILURES";
+                INVALID_LIVE_BETA_EXPOSURE: "INVALID_LIVE_BETA_EXPOSURE";
+            }>;
+            configId: z.ZodUUID;
+            positionId: z.ZodUUID;
+            positionKey: z.ZodString;
+            connector: z.ZodEnum<{
+                hyperliquid: "hyperliquid";
+                binance: "binance";
+                bybit: "bybit";
+                okx: "okx";
+                lighter: "lighter";
+            }>;
+            weightSource: z.ZodEnum<{
+                INITIAL_WEIGHT: "INITIAL_WEIGHT";
+                LIVE_BETA: "LIVE_BETA";
+            }>;
+            type: z.ZodLiteral<"auto_rebalance_paused">;
         }, z.core.$strip>], "type">;
         isRead: z.ZodBoolean;
         createdAt: z.ZodString;

package/dist/position/entities.d.ts

@@ -91,3 +91,230 @@ export declare const Position: z.ZodObject<{
     updatedAt: z.ZodString;
 }, z.core.$strip>;
 export type Position = z.output<typeof Position>;
+/** Which way a closed basket's leg was held. */
+export declare const ClosedTradeLegSide: z.ZodEnum<{
+    LONG: "LONG";
+    SHORT: "SHORT";
+}>;
+export type ClosedTradeLegSide = z.output<typeof ClosedTradeLegSide>;
+/**
+ * What one asset did inside one step.
+ *
+ * A discriminated union rather than optional fields: only a priced reduction closes
+ * against a basis and books PnL, and the other two kinds must not be able to carry
+ * either. REDUCE_UNPRICED is a real third state, not a degenerate REDUCE — it is the
+ * per-step face of `undeterminedSize`, where quantity closed but no price existed to
+ * value it. Collapsing it into REDUCE would invent a basis; collapsing it into
+ * INCREASE would report a close as an add.
+ */
+export declare const ClosedTradeStepLeg: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"INCREASE">;
+    asset: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    quantity: z.ZodString;
+    price: z.ZodString;
+    tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"REDUCE">;
+    asset: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    quantity: z.ZodString;
+    price: z.ZodString;
+    entryBasis: z.ZodString;
+    grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"REDUCE_UNPRICED">;
+    asset: z.ZodString;
+    side: z.ZodEnum<{
+        BUY: "BUY";
+        SELL: "SELL";
+    }>;
+    quantity: z.ZodString;
+    tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+}, z.core.$strip>], "kind">;
+export type ClosedTradeStepLeg = z.output<typeof ClosedTradeStepLeg>;
+/**
+ * One action taken on the position, in the order it happened: the open, each add, each
+ * reduction, and the close.
+ *
+ * Grouped by the execution that placed the fills wherever one was recorded. Exchange
+ * sync records none, so those fills fall back to grouping by identical fill time —
+ * best effort, since the legs of one basket action land on the same instant. Two
+ * genuinely separate actions sharing an instant therefore merge into one step; the
+ * `executionId` being absent is the signal that a step was grouped this way.
+ */
+export declare const ClosedTradeStep: z.ZodObject<{
+    executionId: z.ZodOptional<z.ZodString>;
+    at: z.ZodString;
+    grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    legs: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"INCREASE">;
+        asset: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+        quantity: z.ZodString;
+        price: z.ZodString;
+        tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"REDUCE">;
+        asset: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+        quantity: z.ZodString;
+        price: z.ZodString;
+        entryBasis: z.ZodString;
+        grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"REDUCE_UNPRICED">;
+        asset: z.ZodString;
+        side: z.ZodEnum<{
+            BUY: "BUY";
+            SELL: "SELL";
+        }>;
+        quantity: z.ZodString;
+        tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type ClosedTradeStep = z.output<typeof ClosedTradeStep>;
+/**
+ * One leg of a closed trade, with its own entry and exit economics.
+ *
+ * Both optional prices are absent rather than "0" whenever they cannot be derived:
+ * "0" is a real price, and claiming one the ledger never recorded would be a lie.
+ * Absence is the honest answer.
+ */
+export declare const ClosedTradeLeg: z.ZodObject<{
+    asset: z.ZodString;
+    side: z.ZodEnum<{
+        LONG: "LONG";
+        SHORT: "SHORT";
+    }>;
+    entryVwap: z.ZodOptional<z.ZodString>;
+    exitVwap: z.ZodOptional<z.ZodString>;
+    grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    netPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    totalFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    tradeFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    pearFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    funding: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    entryNotional: z.ZodString;
+    exitQuantity: z.ZodString;
+    undeterminedSize: z.ZodString;
+}, z.core.$strip>;
+export type ClosedTradeLeg = z.output<typeof ClosedTradeLeg>;
+/**
+ * One closed position, composed server-side into the trade a trader recognises:
+ * what it earned, what it cost, and what each leg did.
+ */
+export declare const ClosedTrade: z.ZodObject<{
+    positionId: z.ZodUUID;
+    connector: z.ZodEnum<{
+        hyperliquid: "hyperliquid";
+        binance: "binance";
+        bybit: "bybit";
+        okx: "okx";
+        lighter: "lighter";
+    }>;
+    openedAt: z.ZodString;
+    closedAt: z.ZodString;
+    closedReason: z.ZodOptional<z.ZodEnum<{
+        NETTED: "NETTED";
+        USER: "USER";
+        LIQUIDATED: "LIQUIDATED";
+    }>>;
+    origin: z.ZodEnum<{
+        PARTIAL: "PARTIAL";
+        PEAR: "PEAR";
+        EXTERNAL: "EXTERNAL";
+    }>;
+    grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    netPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    totalFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    tradeFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    pearFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    totalFunding: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+    entryNotional: z.ZodString;
+    exitNotional: z.ZodString;
+    exitNotionalComplete: z.ZodBoolean;
+    hasSyntheticFills: z.ZodBoolean;
+    unstableHistoricalData: z.ZodBoolean;
+    longAssets: z.ZodArray<z.ZodString>;
+    shortAssets: z.ZodArray<z.ZodString>;
+    legs: z.ZodArray<z.ZodObject<{
+        asset: z.ZodString;
+        side: z.ZodEnum<{
+            LONG: "LONG";
+            SHORT: "SHORT";
+        }>;
+        entryVwap: z.ZodOptional<z.ZodString>;
+        exitVwap: z.ZodOptional<z.ZodString>;
+        grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        netPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        totalFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        tradeFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        pearFees: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        funding: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        entryNotional: z.ZodString;
+        exitQuantity: z.ZodString;
+        undeterminedSize: z.ZodString;
+    }, z.core.$strip>>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        executionId: z.ZodOptional<z.ZodString>;
+        at: z.ZodString;
+        grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        legs: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"INCREASE">;
+            asset: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+            quantity: z.ZodString;
+            price: z.ZodString;
+            tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+            pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"REDUCE">;
+            asset: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+            quantity: z.ZodString;
+            price: z.ZodString;
+            entryBasis: z.ZodString;
+            grossPnl: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+            tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+            pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"REDUCE_UNPRICED">;
+            asset: z.ZodString;
+            side: z.ZodEnum<{
+                BUY: "BUY";
+                SELL: "SELL";
+            }>;
+            quantity: z.ZodString;
+            tradeFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+            pearFee: z.ZodPipe<z.ZodString, z.ZodTransform<`-${string}` | `+${string}`, string>>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ClosedTrade = z.output<typeof ClosedTrade>;

package/dist/position/entities.js

@@ -60,5 +60,145 @@ const Position = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
+const ClosedTradeLegSide = z.enum(["LONG", "SHORT"]);
+const ClosedTradeStepLeg = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("INCREASE"),
+    asset: InstrumentId,
+    side: z.enum(["BUY", "SELL"]),
+    quantity: UnsignedDecimalString,
+    /** "0" on an unpriceable synthetic — the ledger recorded no price to report. */
+    price: UnsignedDecimalString,
+    /** The venue's charge and Pear's, kept apart. Signed, so a maker rebate reads negative. */
+    tradeFee: SignedDecimalString,
+    pearFee: SignedDecimalString
+  }),
+  z.object({
+    kind: z.literal("REDUCE"),
+    asset: InstrumentId,
+    side: z.enum(["BUY", "SELL"]),
+    /** The quantity that actually closed. On a flip this is less than the fill's own size. */
+    quantity: UnsignedDecimalString,
+    price: UnsignedDecimalString,
+    /** The running cost basis this reduction closed against, as the PnL walk held it. */
+    entryBasis: UnsignedDecimalString,
+    /** (price − entryBasis) × quantity, signed by direction. Booked by the walk, not re-derived. */
+    grossPnl: SignedDecimalString,
+    tradeFee: SignedDecimalString,
+    pearFee: SignedDecimalString
+  }),
+  z.object({
+    kind: z.literal("REDUCE_UNPRICED"),
+    asset: InstrumentId,
+    side: z.enum(["BUY", "SELL"]),
+    quantity: UnsignedDecimalString,
+    tradeFee: SignedDecimalString,
+    pearFee: SignedDecimalString
+  })
+]);
+const ClosedTradeStep = z.object({
+  /**
+   * The execution that placed these fills. Absent when the fills recorded none, in
+   * which case the step was grouped by fill time and is best effort.
+   */
+  executionId: z.string().optional(),
+  /** When the step's fills landed. */
+  at: z.string(),
+  /** Realized PnL this step booked: the sum of its reductions. "+0" for a pure increase. */
+  grossPnl: SignedDecimalString,
+  legs: z.array(ClosedTradeStepLeg)
+});
+const ClosedTradeLeg = z.object({
+  asset: InstrumentId,
+  side: ClosedTradeLegSide,
+  /** Size-weighted average price the leg opened at. Absent with no priced entry. */
+  entryVwap: UnsignedDecimalString.optional(),
+  /** Size-weighted average price the leg closed at. Absent when nothing closed at a known price. */
+  exitVwap: UnsignedDecimalString.optional(),
+  /** Realized PnL before fees. */
+  grossPnl: SignedDecimalString,
+  /** Realized PnL after fees. */
+  netPnl: SignedDecimalString,
+  /** Signed: a venue maker rebate makes a fee negative. */
+  totalFees: SignedDecimalString,
+  tradeFees: SignedDecimalString,
+  pearFees: SignedDecimalString,
+  /**
+   * Funding attributed to this leg over the position's life (signed; negative = net paid).
+   *
+   * Reported beside netPnl, never folded into it: netPnl carries the same fills-only
+   * meaning here as in /portfolio, and funding is a separate cash flow. A caller that
+   * wants the leg's all-in result adds the two.
+   */
+  funding: SignedDecimalString,
+  entryNotional: UnsignedDecimalString,
+  /**
+   * Size closed at a known price. With undeterminedSize this accounts for every unit
+   * the leg closed, so the total closed size is the sum of the two. It is not reported
+   * separately, because a value derivable from two others can only drift.
+   */
+  exitQuantity: UnsignedDecimalString,
+  /**
+   * Closed size whose PnL is unpriceable, because it closed against a 0-price
+   * synthetic or against an entry basis that was itself unpriced. It contributes
+   * nothing to grossPnl or exitVwap.
+   */
+  undeterminedSize: UnsignedDecimalString
+});
+const ClosedTrade = z.object({
+  positionId: z.uuid(),
+  connector: Connector,
+  /** When the position opened. */
+  openedAt: z.string(),
+  /** When the position closed. Falls back to the last update for rows that never recorded a close. */
+  closedAt: z.string(),
+  closedReason: PositionClosedReason.optional(),
+  origin: PositionOrigin,
+  grossPnl: SignedDecimalString,
+  netPnl: SignedDecimalString,
+  totalFees: SignedDecimalString,
+  tradeFees: SignedDecimalString,
+  pearFees: SignedDecimalString,
+  /**
+   * Funding attributed to the whole trade (signed; negative = net paid).
+   *
+   * Totals every asset the position carried exposure on, which can exceed the sum of
+   * the legs: funding follows exposure, and an asset with exposure but no confirmed
+   * fill earns no leg. Summing the legs instead would understate what the trade paid.
+   *
+   * Reported beside netPnl, never folded into it. See the leg field's note.
+   */
+  totalFunding: SignedDecimalString,
+  entryNotional: UnsignedDecimalString,
+  /**
+   * Proceeds of the priced closes. Understates whenever part of the position closed
+   * unpriceably — exitNotionalComplete says whether that happened.
+   */
+  exitNotional: UnsignedDecimalString,
+  /**
+   * True when every closed unit had a known price, so exitNotional is the whole story.
+   *
+   * This is NOT the negation of hasSyntheticFills. A synthetic fill can carry a real
+   * price and stay complete, and a priced closing fill still breaks completeness when
+   * the entry basis it closed against was unpriced.
+   */
+  exitNotionalComplete: z.boolean(),
+  /** Whether any fill on the position was a synthetic bridge fill (gap/gone reconstruction). */
+  hasSyntheticFills: z.boolean(),
+  /** Whether a backfilled fill made this position's historical metrics unreliable. */
+  unstableHistoricalData: z.boolean(),
+  longAssets: z.array(InstrumentId),
+  shortAssets: z.array(InstrumentId),
+  legs: z.array(ClosedTradeLeg),
+  /**
+   * What happened to the position, oldest first: the open, every add, every reduction
+   * and the close. `legs` says how each asset finished; this says how it got there.
+   *
+   * Absent unless the request asks for it, because the array is unbounded — one entry
+   * per recorded action, so a heavily traded position produces a long one. `openedAt`
+   * carries the open time that step 1 would otherwise have been the only source of.
+   */
+  steps: z.array(ClosedTradeStep).optional()
+});
 
-export { Position, PositionClosedReason, PositionEntryPrices, PositionExposure, PositionInitialExposureUSD, PositionOrigin, PositionStatus, PositionTotalFundingPayment };
+export { ClosedTrade, ClosedTradeLeg, ClosedTradeLegSide, ClosedTradeStep, ClosedTradeStepLeg, Position, PositionClosedReason, PositionEntryPrices, PositionExposure, PositionInitialExposureUSD, PositionOrigin, PositionStatus, PositionTotalFundingPayment };

package/dist/position/queries.d.ts

@@ -17,3 +17,19 @@ export declare const PositionListParams: z.ZodObject<{
 }, z.core.$strip>;
 export type PositionListParamsInput = z.input<typeof PositionListParams>;
 export type PositionListParams = z.output<typeof PositionListParams>;
+/**
+ * Closed-trade history page.
+ *
+ * Ordering is fixed at newest-closed-first, so there is no `orderBy`: one order keeps
+ * the cursor and the supporting index single-purpose. The connector comes from the
+ * trade-account guard rather than the query.
+ */
+export declare const ClosedPositionListParams: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<number>>>;
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+    includeSteps: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCodec<z.ZodString, z.ZodBoolean>]>>>;
+}, z.core.$strip>;
+export type ClosedPositionListParamsInput = z.input<typeof ClosedPositionListParams>;
+export type ClosedPositionListParams = z.output<typeof ClosedPositionListParams>;

package/dist/position/queries.js

@@ -24,5 +24,29 @@ const PositionListParams = CursorFindParams.extend({
    */
   orderBy: OrderBy.default("-createdAt")
 });
+const ClosedPositionListParams = CursorFindParams.extend({
+  /**
+   * Capped below the shared 2000 because every row drags its fills along — 2000
+   * closed positions could pull tens of thousands of fill rows into one response.
+   */
+  limit: z.coerce.number().int().positive().max(200).optional().default(20),
+  /**
+   * Inclusive bounds on the close time. They filter the same
+   * `coalesce(closed_at, updated_at)` expression the ordering and cursor use, so
+   * filtering and paging cannot disagree. Absent means unbounded.
+   */
+  startDate: z.string().optional(),
+  endDate: z.string().optional(),
+  /**
+   * Whether to return each trade's `steps` timeline. Off by default because the array
+   * is unbounded, and a caller listing history rarely needs every recorded action of
+   * every row. `openedAt` is always present, so omitting steps costs no timestamp.
+   *
+   * Accepts a real boolean from an SDK caller and its text form from a query string.
+   * Deliberately not `z.coerce.boolean()`, which reads the string "false" as true and
+   * so cannot be switched off from a URL at all.
+   */
+  includeSteps: z.union([z.boolean(), z.stringbool()]).optional().default(false)
+});
 
-export { PositionListParams };
+export { ClosedPositionListParams, PositionListParams };