aftermath-ts-sdk - v3.3.3
    Preparing search index...

    Class PerpetualsMarket

    High-level wrapper around a single perpetuals market.

    This class provides:

    • Lightweight accessors for immutable market properties:
      • marketId, indexPrice, collateralPrice, collateralCoinType
      • marketParams, marketState
    • Read endpoints for:
      • Orderbook snapshots
      • 24h stats and order history
      • Market prices and derived funding metrics
    • Helpers for:
      • Order sizing (max size, lot/tick rounding)
      • Margin and collateral calculations
      • Constructing an “empty” position for a market

    Typical usage:

    const perps = new Perpetuals(config);
    const { markets } = await perps.getMarkets({ marketIds: ["0x..."] });
    const market = markets[0];

    const { orderbook } = await market.getOrderbook();
    const stats = await market.get24hrStats();
    const { basePrice, collateralPrice } = await market.getPrices();

    Hierarchy (View Summary)

    Index
    constructor
    api? collateralCoinType collateralPrice config indexPrice marketData marketId marketParams marketState metadata
    calcCollateralUsedForOrder emptyPosition estimatedFundingRate get24hrStats getMaxOrderSize getOrderbook getOrderHistory getPlaceLimitOrderPreview getPlaceMarketOrderPreview getPlaceScaleOrderPreview getPrices initialMarginRatio lotSize maintenanceMarginRatio maxLeverage nextFundingTimeMs roundToValidPrice roundToValidPriceBigInt roundToValidSize roundToValidSizeBigInt tickSize timeUntilNextFundingMs apiBaseUrlForNetwork defaultFullnodeUrl
    api?: AftermathApi

    Optional shared AftermathApi provider instance.

    collateralCoinType: string

    Sui type of the collateral coin (e.g. "0x2::sui::SUI").

    collateralPrice: number

    Current price of the collateral asset in USD (or the platform's base pricing unit).

    config: CallerConfig

    The mutable configuration used for subsequent requests.

    indexPrice: number

    Current oracle/index price for the market's underlying asset, quoted in the index unit (typically USD).

    marketData: PerpetualsMarketData

    Snapshot of market configuration and state.

    marketId: string

    Unique identifier for this perpetuals market (object ID on chain).

    marketParams: PerpetualsMarketParams

    Static market configuration parameters (lot size, tick size, margins, etc.).

    marketState: PerpetualsMarketState

    Dynamic market state (funding rates, open interest, etc.).

    metadata: PerpetualsMarketMetadata | null

    Display metadata (symbol, label, artwork, category) for this market, or null when none is available.

    • Calculate the collateral required to support an order given leverage and prices.

      The computed collateral is based on the remaining unfilled size: remaining = initialSize - filledSize.

      USD requirement:

      remainingBase * indexPrice * initialMarginRatio

      where initialMarginRatio = 1 / leverage (or 1 if leverage is falsy).

      Parameters

      • inputs: {
            collateralPrice: number;
            indexPrice: number;
            leverage: number;
            orderData: PerpetualsOrderData;
        }
        • collateralPrice: number

          Price of the collateral asset.

        • indexPrice: number

          Index/oracle price of the base asset.

        • leverage: number

          Target leverage for the order (>= 1).

        • orderData: PerpetualsOrderData

          Order data containing initialSize and filledSize.

      Returns { collateral: number; collateralUsd: number }

      Object with:

      • collateralUsd: required collateral in USD
      • collateral: required collateral in collateral coin units

    • Estimated funding rate per period for this market.

      This is read directly from marketData.estimatedFundingRate.

      Returns number

      Estimated funding rate as a fraction (e.g. 0.01 = 1%).

    • Compute the maximum order size that can be placed by a given account in this market, under optional leverage and price assumptions.

      This is a common frontend helper for:

      • "max size" buttons
      • input validation against risk limits

      Note: This is routed through the account namespace because it depends on the account's collateral and positions.

      Parameters

      • inputs: Omit<ApiPerpetualsMaxOrderSizeBody, "marketId">
        • accountId

          Perpetuals account ID.

        • side

          Order side (Bid/Ask).

        • leverage

          Optional assumed leverage.

        • price

          Optional assumed price (e.g. for limit orders).

      Returns Promise<{ maxOrderSize: bigint }>

      { maxOrderSize } in base units (scaled integer as bigint).

      const { maxOrderSize } = await market.getMaxOrderSize({
        accountId: 123n,
        side: PerpetualsOrderSide.Bid,
        leverage: 5,
      });

    • Fetch the current prices for this market.

      Internally calls Perpetuals.getPrices and returns the first result.

      Returns Promise<
          {
              basePrice: number;
              collateralPrice: number;
              marketId: string;
              markPrice: number;
              midPrice: number
              | undefined;
          },
      >

      { marketId, basePrice, collateralPrice, midPrice, markPrice }.

      This method instantiates a new Perpetuals client using this.config. If you rely on a shared api, call perps.getPrices(...) directly instead.

    • Get the initial margin ratio for this market.

      This is the minimum margin required when opening a position.

      Returns number

      Initial margin ratio as a fraction (e.g. 0.05 = 20x).

    • Get the base-asset lot size for this market as a number.

      Order sizes must be multiples of this lot size.

      Returns number

      Lot size in base asset units.

    • Get the maintenance margin ratio for this market.

      Falling below this ratio may trigger liquidation.

      Returns number

      Maintenance margin ratio as a fraction.

    • Get the scheduled timestamp for the next funding event, in milliseconds.

      Safety behavior:

      • If marketData.nextFundingTimestampMs exceeds Number.MAX_SAFE_INTEGER, this returns Number.MAX_SAFE_INTEGER.

      Returns number

      Next funding timestamp (ms) as a JS number.

    • Round a price to the nearest valid tick for this market.

      Rounding mode:

      • floor: true => round down
      • ceil: true => round up
      • neither => nearest tick (Math.round)

      Parameters

      • inputs: { ceil?: boolean; floor?: boolean; price: number }
        • Optionalceil?: boolean

          Force ceil rounding.

        • Optionalfloor?: boolean

          Force floor rounding.

        • price: number

          Raw price to round.

      Returns number

      Price snapped to the market tick size.

    • Round a price to the nearest valid tick as a fixed-point bigint (1e9 precision).

      This is helpful when you need the on-chain representation directly (e.g. order price fields stored in 9-decimal fixed).

      Parameters

      • inputs: { ceil?: boolean; floor?: boolean; price: number }
        • Optionalceil?: boolean

          Force ceil rounding.

        • Optionalfloor?: boolean

          Force floor rounding.

        • price: number

          Raw price as a JS number.

      Returns bigint

      Tick-snapped price scaled by 1e9.

    • Round a base-asset size to the nearest valid lot size for this market.

      Rounding mode:

      • floor: true => round down
      • ceil: true => round up
      • neither => nearest lot (Math.round)

      Parameters

      • inputs: { ceil?: boolean; floor?: boolean; size: number }
        • Optionalceil?: boolean

          Force ceil rounding.

        • Optionalfloor?: boolean

          Force floor rounding.

        • size: number

          Raw size in base asset units.

      Returns number

      Size snapped to the market lot size.

    • Round a base-asset size to the nearest valid lot as a fixed-point bigint (1e9 precision).

      Parameters

      • inputs: { ceil?: boolean; floor?: boolean; size: number }
        • Optionalceil?: boolean

          Force ceil rounding.

        • Optionalfloor?: boolean

          Force floor rounding.

        • size: number

          Raw base size as a JS number.

      Returns bigint

      Lot-snapped size scaled by 1e9.

    • Get the minimal price tick size for this market as a number.

      Limit prices must be multiples of this tick size.

      Returns number

      Tick size in quote units (e.g. USD).

    • Compute the remaining time until the next funding event, in milliseconds.

      Returns number

      nextFundingTimeMs() - Date.now().

      If the next funding timestamp does not fit safely into a JS number, nextFundingTimeMs returns Number.MAX_SAFE_INTEGER, and the difference may be very large.

    • Returns the canonical Aftermath API host for a Sui network.

      To target a custom or local host, pass baseUrl in CallerConfig to the constructor instead.

      Parameters

      • network: SuiNetwork

        The Sui network whose host to return.

      Returns string

      The network's HTTPS or local HTTP API host.

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods