@cubexch/client - npm Package Compare versions

Comparing version 1.1.17 to 1.1.18

lib/methods/trade.d.ts

@@ -1,2 +0,2 @@
-import { Side, TimeInForce, OrderType, SelfTradePrevention, PostOnly, Credentials, OrderRequest, NewOrder, CancelOrder, ModifyOrder, MassCancel, Heartbeat, OrderResponse, NewOrderAck, CancelOrderAck, CancelOrderAck_Reason, ModifyOrderAck, MassCancelAck, MassCancelAck_Reason, NewOrderReject, NewOrderReject_Reason, CancelOrderReject, CancelOrderReject_Reason, ModifyOrderReject, ModifyOrderReject_Reason, Fill, AssetPosition, RawUnits, Bootstrap, RestingOrders, AssetPositions, Done, RestingOrder } from '../trade';
+import { Side, TimeInForce, OrderType, SelfTradePrevention, PostOnly, FixedPointDecimal, Credentials, OrderRequest, NewOrder, CancelOrder, ModifyOrder, MassCancel, Heartbeat, OrderResponse, NewOrderAck, CancelOrderAck, CancelOrderAck_Reason, ModifyOrderAck, MassCancelAck, MassCancelAck_Reason, NewOrderReject, NewOrderReject_Reason, CancelOrderReject, CancelOrderReject_Reason, ModifyOrderReject, ModifyOrderReject_Reason, Fill, AssetPosition, RawUnits, Bootstrap, RestingOrders, AssetPositions, Done, RestingOrder } from '../trade';
 import * as _m0 from "protobufjs/minimal";
@@ -23,2 +23,8 @@ export declare function sideFromJSON(object: any): Side;
 export declare function modifyOrderReject_ReasonToJSON(object: ModifyOrderReject_Reason): string;
+export declare const FixedPointDecimalMethods: {
+    encode(message: FixedPointDecimal, writer?: _m0.Writer): _m0.Writer;
+    decode(input: _m0.Reader | Uint8Array, length?: number): FixedPointDecimal;
+    fromJSON(object: any): FixedPointDecimal;
+    toJSON(message: FixedPointDecimal): unknown;
+};
 export declare const CredentialsMethods: {
@@ -25,0 +31,0 @@ encode(message: Credentials, writer?: _m0.Writer): _m0.Writer;

lib/trade.d.ts

@@ -51,2 +51,40 @@ export declare const protobufPackage = "trade";
  *
+ * ### Trading Fees
+ *
+ * Trading Fees are calculated on each individual trade as a ratio of the filled quantity,
+ * and are always charged as a deduction from the asset received in that trade.
+ *
+ * Fee ratios may vary from trade to trade based on the user's VIP level.
+ * For fee discounts based on Trading Volume, ratios are adjusted continuously
+ * at the time of each trade based on the user's trailing 30-day volume.
+ *
+ * To ensure that the client has enough information to determine the exact fee charged,
+ * the fee ratio is expressed as a fixed-point decimal number consisting of a mantissa and an exponent.
+ * Generally, the exponent will be "-4", indicating that the mantissa is equivalent to pips,
+ * Though some fees may be expressed with greater granularity.
+ *
+ * For example, consider the case of a trade where:
+ * - Asset received is BTC
+ * - `quantity` = 5
+ * - `fee_ratio.mantissa` = 11
+ * - `fee_ratio.exponent` = -4
+ *
+ * ...in which case:
+ * - The fee ratio would be 0.0011, or 11 pips.
+ * - The fee would be equal to 0.00055 BTC.
+ * - The total amount credited at settlement would be 4.9945 BTC.
+ *
+ * If you need exact granularity at time of trade, you can replicate the fee calculation performed by the exchange.
+ * To avoid rounding errors, this entire process is performed in integer math using the exponent as a devisor.
+ * In the example above, the full fee amount in indivisible [RawUnits](#raw-units) would be calculated as:
+ * ```text
+ * 5 * 100_000_000 * 11 / 10_000 = 550_000 RawUnits
+ *
+ * (in the BTC case, that would be 550,000 Satoshi)
+ * ```
+ *
+ * Since the fee is expressed with a decimal exponent, it's highly likely that this calculation results in a whole number.
+ * In the unlikely case that the final division results in a non-whole number, the result should be truncated,
+ * i.e. the fee is rounded down to the nearest `RawUnit`.
+ *
  * ### Exchange Order ID
@@ -98,3 +136,14 @@ *
 }
-/** Order-type specifies how the order will be placed into the order book. */
+/**
+ * Order-type specifies how the order will be placed into the order book.
+ *
+ * - Note that for LIMIT orders, there is a pre-flight check that there is
+ *   sufficient available balance to place this order at the price and quantity
+ *   specified. Otherwise, the order will be rejected with the
+ *   EXCEEDED_SPOT_POSITION reason.
+ * - For MARKET_LIMIT and MARKET_WITH_PROTECTION orders, there is no such
+ *   pre-flight check and a submitted order will be partially filled up until
+ *   the subaccount's position limit. The remaining quantity will be canceled
+ *   with the POSITION_LIMIT reason.
+ */
 export declare enum OrderType {
@@ -110,5 +159,6 @@ /**
      * MARKET_LIMIT - A market limit order crosses the bid-ask spread and, if not fully filled,
-     * becomes a limit order at the best available market price. If there is no
-     * opposing market, the order is rejected with the NO_OPPOSING_LIMIT_ORDER
-     * reason. Price must be null.
+     * becomes a limit order at the best available market price.
+     * - If there is no opposing market, the order is rejected with the
+     *   NO_OPPOSING_RESTING_ORDER reason.
+     * - The price must be null.
      */
@@ -118,6 +168,10 @@ MARKET_LIMIT = 1,
      * MARKET_WITH_PROTECTION - A market with protection order crosses the bid-ask spread and continues to
-     * cross until the order is fully filled or the price protection level,
-     * defined by the best market price widened by a market-specific protection
-     * point count, is reached. If there is no opposing market, the order is
-     * rejected with the NO_OPPOSING_LIMIT_ORDER reason. Price must be null.
+     * cross until the order is fully filled or the protection price is reached.
+     * - The protection price is defined as:
+     *   - If the price is provided, this price is used as the protection price.
+     *   - If the price is null, the best market price widened by a
+     *     market-specific protection point count.
+     * - If the protection price would not cross the resting market, the order is
+     *   rejected with the NO_OPPOSING_RESTING_ORDER reason instead of resting at
+     *   that level.
      */
@@ -160,2 +214,13 @@ MARKET_WITH_PROTECTION = 2
 /**
+ * A fixed-point decimal number.
+ * Matches the representation preferred by the FIX protocol,
+ * except that the exponent is int32 since Protobuf does not have an int8 type.
+ * The value is computed as `mantissa * 10^exponent`;
+ * for example, `mantissa = 1234` and `exponent = -2` is `12.34`.
+ */
+export interface FixedPointDecimal {
+    mantissa: bigint;
+    exponent: number;
+}
+/**
  * Sent by client on websocket initialization. Once the websocket has been
@@ -416,2 +481,4 @@ * connected, the client is expected to send this credentials message
     marketId: bigint;
+    /** [Exchange order ID](#exchange-order-id) */
+    exchangeOrderId: bigint;
 }
@@ -430,3 +497,8 @@ export declare enum CancelOrderAck_Reason {
     /** MASS_CANCEL - This order was covered by a mass-cancel request. */
-    MASS_CANCEL = 6
+    MASS_CANCEL = 6,
+    /**
+     * POSITION_LIMIT - This order was canceled because asset position limits would be otherwise
+     * breached.
+     */
+    POSITION_LIMIT = 7
 }
@@ -454,2 +526,4 @@ /**
     cumulativeQuantity: bigint;
+    /** [Exchange order ID](#exchange-order-id) */
+    exchangeOrderId: bigint;
 }
@@ -520,3 +594,3 @@ /**
     UNKNOWN_TRADER = 9,
-    PRICE_WITH_MARKET_ORDER = 10,
+    PRICE_WITH_MARKET_LIMIT_ORDER = 10,
     POST_ONLY_WITH_MARKET_ORDER = 11,
@@ -529,3 +603,4 @@ POST_ONLY_WITH_INVALID_TIF = 12,
     EXCEEDED_SPOT_POSITION = 13,
-    NO_OPPOSING_LIMIT_ORDER = 14,
+    /** NO_OPPOSING_RESTING_ORDER - There are no opposing resting orders to trade against. */
+    NO_OPPOSING_RESTING_ORDER = 14,
     /** POST_ONLY_WOULD_TRADE - The post-only order would have crossed and traded. */
@@ -539,3 +614,18 @@ POST_ONLY_WOULD_TRADE = 15,
     /** ONLY_ORDER_CANCEL_ACCEPTED - An exchange accepts no now orders at this time */
-    ONLY_ORDER_CANCEL_ACCEPTED = 17
+    ONLY_ORDER_CANCEL_ACCEPTED = 17,
+    /**
+     * PROTECTION_PRICE_WOULD_NOT_TRADE - A more specific error code for market-with-protection orders that could
+     * trade but have a user-specified protection price that is too tight.
+     */
+    PROTECTION_PRICE_WOULD_NOT_TRADE = 18,
+    /**
+     * NO_REFERENCE_PRICE - Market orders cannot be place because there is currently no internal
+     * reference price
+     */
+    NO_REFERENCE_PRICE = 19,
+    /**
+     * SLIPPAGE_TOO_HIGH - A market order would trade beyond the internal reference price offset by
+     * protection levels in the direction of aggress.
+     */
+    SLIPPAGE_TOO_HIGH = 20
 }
@@ -633,2 +723,14 @@ /** Cancel-order-reject indicates that a cancel-order request was not applied. */
     cumulativeQuantity: bigint;
+    side: Side;
+    aggressorIndicator: boolean;
+    /**
+     * Indicates the fee charged on this trade.
+     * See [Fees](#fees) for details.
+     */
+    feeRatio: FixedPointDecimal | undefined;
+    /**
+     * The unique trade ID associated with a match event. Each order
+     * participanting in the match event will receive this trade ID
+     */
+    tradeId: bigint;
 }
@@ -635,0 +737,0 @@ /**

lib/trade.js

@@ -55,2 +55,40 @@ "use strict";
  *
+ * ### Trading Fees
+ *
+ * Trading Fees are calculated on each individual trade as a ratio of the filled quantity,
+ * and are always charged as a deduction from the asset received in that trade.
+ *
+ * Fee ratios may vary from trade to trade based on the user's VIP level.
+ * For fee discounts based on Trading Volume, ratios are adjusted continuously
+ * at the time of each trade based on the user's trailing 30-day volume.
+ *
+ * To ensure that the client has enough information to determine the exact fee charged,
+ * the fee ratio is expressed as a fixed-point decimal number consisting of a mantissa and an exponent.
+ * Generally, the exponent will be "-4", indicating that the mantissa is equivalent to pips,
+ * Though some fees may be expressed with greater granularity.
+ *
+ * For example, consider the case of a trade where:
+ * - Asset received is BTC
+ * - `quantity` = 5
+ * - `fee_ratio.mantissa` = 11
+ * - `fee_ratio.exponent` = -4
+ *
+ * ...in which case:
+ * - The fee ratio would be 0.0011, or 11 pips.
+ * - The fee would be equal to 0.00055 BTC.
+ * - The total amount credited at settlement would be 4.9945 BTC.
+ *
+ * If you need exact granularity at time of trade, you can replicate the fee calculation performed by the exchange.
+ * To avoid rounding errors, this entire process is performed in integer math using the exponent as a devisor.
+ * In the example above, the full fee amount in indivisible [RawUnits](#raw-units) would be calculated as:
+ * ```text
+ * 5 * 100_000_000 * 11 / 10_000 = 550_000 RawUnits
+ *
+ * (in the BTC case, that would be 550,000 Satoshi)
+ * ```
+ *
+ * Since the fee is expressed with a decimal exponent, it's highly likely that this calculation results in a whole number.
+ * In the unlikely case that the final division results in a non-whole number, the result should be truncated,
+ * i.e. the fee is rounded down to the nearest `RawUnit`.
+ *
  * ### Exchange Order ID
@@ -104,3 +142,14 @@ *
 })(TimeInForce = exports.TimeInForce || (exports.TimeInForce = {}));
-/** Order-type specifies how the order will be placed into the order book. */
+/**
+ * Order-type specifies how the order will be placed into the order book.
+ *
+ * - Note that for LIMIT orders, there is a pre-flight check that there is
+ *   sufficient available balance to place this order at the price and quantity
+ *   specified. Otherwise, the order will be rejected with the
+ *   EXCEEDED_SPOT_POSITION reason.
+ * - For MARKET_LIMIT and MARKET_WITH_PROTECTION orders, there is no such
+ *   pre-flight check and a submitted order will be partially filled up until
+ *   the subaccount's position limit. The remaining quantity will be canceled
+ *   with the POSITION_LIMIT reason.
+ */
 var OrderType;
@@ -117,5 +166,6 @@ (function (OrderType) {
      * MARKET_LIMIT - A market limit order crosses the bid-ask spread and, if not fully filled,
-     * becomes a limit order at the best available market price. If there is no
-     * opposing market, the order is rejected with the NO_OPPOSING_LIMIT_ORDER
-     * reason. Price must be null.
+     * becomes a limit order at the best available market price.
+     * - If there is no opposing market, the order is rejected with the
+     *   NO_OPPOSING_RESTING_ORDER reason.
+     * - The price must be null.
      */
@@ -125,6 +175,10 @@ OrderType[OrderType["MARKET_LIMIT"] = 1] = "MARKET_LIMIT";
      * MARKET_WITH_PROTECTION - A market with protection order crosses the bid-ask spread and continues to
-     * cross until the order is fully filled or the price protection level,
-     * defined by the best market price widened by a market-specific protection
-     * point count, is reached. If there is no opposing market, the order is
-     * rejected with the NO_OPPOSING_LIMIT_ORDER reason. Price must be null.
+     * cross until the order is fully filled or the protection price is reached.
+     * - The protection price is defined as:
+     *   - If the price is provided, this price is used as the protection price.
+     *   - If the price is null, the best market price widened by a
+     *     market-specific protection point count.
+     * - If the protection price would not cross the resting market, the order is
+     *   rejected with the NO_OPPOSING_RESTING_ORDER reason instead of resting at
+     *   that level.
      */
@@ -182,2 +236,7 @@ OrderType[OrderType["MARKET_WITH_PROTECTION"] = 2] = "MARKET_WITH_PROTECTION";
     CancelOrderAck_Reason[CancelOrderAck_Reason["MASS_CANCEL"] = 6] = "MASS_CANCEL";
+    /**
+     * POSITION_LIMIT - This order was canceled because asset position limits would be otherwise
+     * breached.
+     */
+    CancelOrderAck_Reason[CancelOrderAck_Reason["POSITION_LIMIT"] = 7] = "POSITION_LIMIT";
 })(CancelOrderAck_Reason = exports.CancelOrderAck_Reason || (exports.CancelOrderAck_Reason = {}));
@@ -216,3 +275,3 @@ var MassCancelAck_Reason;
     NewOrderReject_Reason[NewOrderReject_Reason["UNKNOWN_TRADER"] = 9] = "UNKNOWN_TRADER";
-    NewOrderReject_Reason[NewOrderReject_Reason["PRICE_WITH_MARKET_ORDER"] = 10] = "PRICE_WITH_MARKET_ORDER";
+    NewOrderReject_Reason[NewOrderReject_Reason["PRICE_WITH_MARKET_LIMIT_ORDER"] = 10] = "PRICE_WITH_MARKET_LIMIT_ORDER";
     NewOrderReject_Reason[NewOrderReject_Reason["POST_ONLY_WITH_MARKET_ORDER"] = 11] = "POST_ONLY_WITH_MARKET_ORDER";
@@ -225,3 +284,4 @@ NewOrderReject_Reason[NewOrderReject_Reason["POST_ONLY_WITH_INVALID_TIF"] = 12] = "POST_ONLY_WITH_INVALID_TIF";
     NewOrderReject_Reason[NewOrderReject_Reason["EXCEEDED_SPOT_POSITION"] = 13] = "EXCEEDED_SPOT_POSITION";
-    NewOrderReject_Reason[NewOrderReject_Reason["NO_OPPOSING_LIMIT_ORDER"] = 14] = "NO_OPPOSING_LIMIT_ORDER";
+    /** NO_OPPOSING_RESTING_ORDER - There are no opposing resting orders to trade against. */
+    NewOrderReject_Reason[NewOrderReject_Reason["NO_OPPOSING_RESTING_ORDER"] = 14] = "NO_OPPOSING_RESTING_ORDER";
     /** POST_ONLY_WOULD_TRADE - The post-only order would have crossed and traded. */
@@ -236,2 +296,17 @@ NewOrderReject_Reason[NewOrderReject_Reason["POST_ONLY_WOULD_TRADE"] = 15] = "POST_ONLY_WOULD_TRADE";
     NewOrderReject_Reason[NewOrderReject_Reason["ONLY_ORDER_CANCEL_ACCEPTED"] = 17] = "ONLY_ORDER_CANCEL_ACCEPTED";
+    /**
+     * PROTECTION_PRICE_WOULD_NOT_TRADE - A more specific error code for market-with-protection orders that could
+     * trade but have a user-specified protection price that is too tight.
+     */
+    NewOrderReject_Reason[NewOrderReject_Reason["PROTECTION_PRICE_WOULD_NOT_TRADE"] = 18] = "PROTECTION_PRICE_WOULD_NOT_TRADE";
+    /**
+     * NO_REFERENCE_PRICE - Market orders cannot be place because there is currently no internal
+     * reference price
+     */
+    NewOrderReject_Reason[NewOrderReject_Reason["NO_REFERENCE_PRICE"] = 19] = "NO_REFERENCE_PRICE";
+    /**
+     * SLIPPAGE_TOO_HIGH - A market order would trade beyond the internal reference price offset by
+     * protection levels in the direction of aggress.
+     */
+    NewOrderReject_Reason[NewOrderReject_Reason["SLIPPAGE_TOO_HIGH"] = 20] = "SLIPPAGE_TOO_HIGH";
 })(NewOrderReject_Reason = exports.NewOrderReject_Reason || (exports.NewOrderReject_Reason = {}));
@@ -238,0 +313,0 @@ var CancelOrderReject_Reason;

package.json

 {
   "name": "@cubexch/client",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "scripts": {
@@ -5,0 +5,0 @@ "build": "tsc"

No alert changes

Improved metrics

Total package byte prevSize

394287

increased by3.93%

Lines of code

9688

increased by3.53%

No dependency changes