@katanaperps/katana-perps-sdk 2.1.0-beta.13 → 2.1.0-beta.14

package/dist/orderbook/buySellPanelEstimate.d.ts

@@ -0,0 +1,155 @@
+import { OrderSide, TimeInForce } from '#types/enums/request';
+import type { LeverageParameters } from '#orderbook/quantities';
+import type { OrderBookLevelL2 } from '#types/orderBook';
+import type { KatanaPerpsInitialMarginFractionOverride, KatanaPerpsMarket, KatanaPerpsOrder, KatanaPerpsWallet } from '#types/rest/endpoints/index';
+/**
+ * The quantity for a buy/sell panel estimate may be expressed in one of three
+ * ways: in base asset terms, in quote asset terms, or as a fraction of the
+ * wallet's available collateral to be consumed (the panel's slider; `1` (one
+ * pip-fraction, i.e. {@link oneInPips}) consumes all available collateral).
+ *
+ * Exactly one of the three must be provided.
+ */
+export type BuySellPanelEstimateQuantity = {
+    baseQuantity: bigint;
+    quoteQuantity?: undefined;
+    availableCollateralRatio?: undefined;
+} | {
+    baseQuantity?: undefined;
+    quoteQuantity: bigint;
+    availableCollateralRatio?: undefined;
+} | {
+    baseQuantity?: undefined;
+    quoteQuantity?: undefined;
+    /** Fraction of available collateral to consume, in pips (`0` to {@link oneInPips}) */
+    availableCollateralRatio: bigint;
+};
+/**
+ * The buy/sell panel's order inputs.
+ *
+ * - Omitting {@link BuySellPanelOrder.limitPrice limitPrice} produces a market
+ *   order estimate; providing it produces a limit order estimate.
+ * - {@link BuySellPanelOrder.timeInForce timeInForce} defaults to
+ *   {@link TimeInForce.gtc gtc}.
+ */
+export type BuySellPanelOrder = {
+    side: OrderSide;
+    /** Present for limit orders only; in pips */
+    limitPrice?: bigint;
+    /** Defaults to {@link TimeInForce.gtc} */
+    timeInForce?: TimeInForce;
+    /** Defaults to `false` */
+    reduceOnly?: boolean;
+} & BuySellPanelEstimateQuantity;
+export interface BuySellPanelEstimateArgs {
+    market: Pick<KatanaPerpsMarket, 'market' | 'indexPrice' | keyof LeverageParameters | 'maintenanceMarginFraction' | 'marketOrderExecutionPriceLimit' | 'limitOrderExecutionPriceLimit'>;
+    /**
+     * The wallet placing the order, as returned by the "Get Wallets" endpoint
+     * (with positions included).
+     */
+    wallet: Pick<KatanaPerpsWallet, 'equity' | 'heldCollateral' | 'quoteBalance' | 'marginRatio' | 'makerFeeRate' | 'takerFeeRate' | 'positions'>;
+    /**
+     * The order book of the order's market. {@link OrderBookLevelL2.size size}
+     * values are expected to include the wallet's own standing orders. Asks are
+     * expected to be sorted ascending (lowest price first) and bids descending
+     * (highest price first); both are re-sorted defensively.
+     */
+    orderBook: {
+        asks: OrderBookLevelL2[];
+        bids: OrderBookLevelL2[];
+    };
+    /**
+     * All of the wallet's standing (open) orders. Orders in other markets are
+     * ignored. Used to detect self-trades and to determine how the wallet's held
+     * collateral changes as a result of the estimated order.
+     */
+    walletsStandingOrders?: Pick<KatanaPerpsOrder, 'market' | 'side' | 'price' | 'originalQuantity' | 'executedQuantity' | 'status'>[];
+    /**
+     * The wallet's initial margin fraction overrides, as returned by the "Get
+     * Initial Margin Fraction Override" endpoint. Only the entry for the order's
+     * market is used.
+     */
+    walletInitialMarginFractionOverrides?: KatanaPerpsInitialMarginFractionOverride[];
+    /**
+     * The taker gas fee charged per matched maker order, in quote asset pips. Not
+     * exposed by the public API; defaults to zero. The sum of the trade and gas
+     * fee on any single fill is capped at 5% of the fill's quote quantity.
+     */
+    takerTradeGasFee?: bigint;
+    order: BuySellPanelOrder;
+}
+export interface BuySellPanelEstimate {
+    /** Base quantity of the portion of the order that crosses the spread (a trade) */
+    tradeBaseQuantity: bigint;
+    /** Quote quantity of the portion of the order that crosses the spread (a trade) */
+    tradeQuoteQuantity: bigint;
+    /** Base quantity of the portion of the order that would rest on the books */
+    makerBaseQuantity: bigint;
+    /**
+     * The change in the wallet's available collateral, in quote asset pips. A
+     * positive value is a cost (available collateral decreases); a negative value
+     * indicates that available collateral increases (e.g. when closing a position
+     * frees up collateral).
+     */
+    cost: bigint;
+    /**
+     * The index price at which the account would be liquidated after the
+     * estimated order, in pips. `null` if the resulting position is zero (no
+     * liquidation risk), `0n` if the account cannot be liquidated by an adverse
+     * move (a positive liquidation price does not exist).
+     */
+    liquidationPrice: bigint | null;
+    /** `true` if the estimate matched one of the wallet's own standing orders */
+    selfTradeEncountered: boolean;
+    /**
+     * `true` if the crossing portion of the order would leave the wallet below
+     * its margin requirement (the order would be rejected)
+     */
+    freeCollateralExceeded: boolean;
+    /**
+     * `true` if a non-crossing (resting) order's held collateral would exceed the
+     * wallet's available collateral (the order would be rejected)
+     */
+    availableCollateralExceeded: boolean;
+    /**
+     * `true` if the order's price (limit orders) or a matched price (market
+     * orders) lies outside the market's allowed execution price range
+     */
+    executionPriceLimitExceeded: boolean;
+    /** `true` if the resulting position would exceed the maximum position size */
+    maximumPositionSizeExceeded: boolean;
+    /** `true` if a post-only ({@link TimeInForce.gtx gtx}) order would cross the spread (rejected) */
+    postOnlyWouldCross: boolean;
+    /** `true` if a fill-or-kill ({@link TimeInForce.fok fok}) order could not be fully filled (rejected) */
+    fillOrKillWouldNotExecute: boolean;
+    /** `true` if a reduce-only order is on the same side as the open position (rejected) */
+    reduceOnlyWouldNotReducePosition: boolean;
+    /** `true` if a reduce-only order is placed with no open position (rejected) */
+    reduceOnlyNoOpenPosition: boolean;
+    /**
+     * `true` if a reduce-only order's resting (maker) quantity would exceed the
+     * remaining open position size (the order would not be fully reducing)
+     */
+    reduceOnlyOpenPositionSizeExceeded: boolean;
+}
+/**
+ * Generates an estimate of how a taker order submitted via the buy/sell panel
+ * would be executed by the trading engine. The estimate takes into account
+ * trade and gas fees, the (incremental) initial margin fraction and its
+ * overrides, the maximum position size, collateral freed up by the reduction of
+ * positions, the effect of differences between the execution and index price on
+ * collateral, self-trades, held collateral (for standing orders), and changes
+ * in held collateral as a result of self-trades and position size changes.
+ *
+ * The minimum taker quantity is intentionally ignored; the estimate generates
+ * results for quantities that do not meet the minimum.
+ *
+ * The order's quantity may be expressed in base asset terms, in quote asset
+ * terms, or as a fraction of the wallet's available collateral to consume (the
+ * panel's slider). See {@link BuySellPanelEstimateQuantity}.
+ *
+ * All quantities, prices, and collateral values are expressed in pips
+ * (see {@link decimalToPip}).
+ */
+export declare function calculateBuySellPanelEstimate(args: BuySellPanelEstimateArgs): BuySellPanelEstimate;
+//# sourceMappingURL=buySellPanelEstimate.d.ts.map

package/dist/orderbook/buySellPanelEstimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buySellPanelEstimate.d.ts","sourceRoot":"","sources":["../../src/orderbook/buySellPanelEstimate.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EACV,wCAAwC,EACxC,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,6BAA6B,CAAC;AAUrC;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GACpC;IACE,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,wBAAwB,CAAC,EAAE,SAAS,CAAC;CACtC,GACD;IACE,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB,CAAC,EAAE,SAAS,CAAC;CACtC,GACD;IACE,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,sFAAsF;IACtF,wBAAwB,EAAE,MAAM,CAAC;CAClC,CAAC;AAEN;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0BAA0B;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,4BAA4B,CAAC;AAEjC,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,IAAI,CACV,iBAAiB,EACf,QAAQ,GACR,YAAY,GACZ,MAAM,kBAAkB,GACxB,2BAA2B,GAC3B,gCAAgC,GAChC,+BAA+B,CAClC,CAAC;IACF;;;OAGG;IACH,MAAM,EAAE,IAAI,CACV,iBAAiB,EACf,QAAQ,GACR,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,cAAc,GACd,cAAc,GACd,WAAW,CACd,CAAC;IACF;;;;;OAKG;IACH,SAAS,EAAE;QAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;QAAC,IAAI,EAAE,gBAAgB,EAAE,CAAA;KAAE,CAAC;IAClE;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,IAAI,CAC1B,gBAAgB,EACd,QAAQ,GACR,MAAM,GACN,OAAO,GACP,kBAAkB,GAClB,kBAAkB,GAClB,QAAQ,CACX,EAAE,CAAC;IACJ;;;;OAIG;IACH,oCAAoC,CAAC,EAAE,wCAAwC,EAAE,CAAC;IAClF;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,6EAA6E;IAC7E,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,sBAAsB,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,2BAA2B,EAAE,OAAO,CAAC;IACrC;;;OAGG;IACH,2BAA2B,EAAE,OAAO,CAAC;IACrC,8EAA8E;IAC9E,2BAA2B,EAAE,OAAO,CAAC;IACrC,kGAAkG;IAClG,kBAAkB,EAAE,OAAO,CAAC;IAC5B,wGAAwG;IACxG,yBAAyB,EAAE,OAAO,CAAC;IACnC,wFAAwF;IACxF,gCAAgC,EAAE,OAAO,CAAC;IAC1C,+EAA+E;IAC/E,wBAAwB,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,kCAAkC,EAAE,OAAO,CAAC;CAC7C;AA69BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,wBAAwB,GAC7B,oBAAoB,CA0BtB"}