Market

Complete Reference for the PerpetualsMarket Class

Overview

The PerpetualsMarket class is a high-level wrapper around a single perpetuals market that provides convenient access to market data, order book information, pricing, and order placement previews.

Key Features:

• Lightweight accessors for market properties (prices, parameters, state)

• Order book snapshots and real-time market data

• Order placement preview and validation

• Max order size calculations

• Price and size rounding to valid tick/lot sizes

• Margin and collateral calculations

• 24-hour statistics and historical data

Typical Usage:

import { Aftermath } from "aftermath-ts-sdk";

const afSdk = new Aftermath("MAINNET");
await afSdk.init();

const perps = afSdk.Perpetuals();

// Get a market
const { market } = await perps.getMarket({
	marketId:
		"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
});

// Use market methods
const { orderbook } = await market.getOrderbook();
const stats = await market.get24hrStats();
const maxSize = await market.getMaxOrderSize({
	accountId: 123n,
	side: PerpetualsOrderSide.Bid,
	leverage: 5,
});

---

Constructor

constructor

constructor(
  public marketData: PerpetualsMarketData,
  config?: CallerConfig,
  public readonly Provider?: AftermathApi
)

Creates a new PerpetualsMarket wrapper instance from raw market data.

Parameters:

• marketData: PerpetualsMarketData

  • Snapshot of market configuration and state

  • Contains:

    • objectId: Market ID

    • indexPrice: Current index/oracle price

    • collateralPrice: Price of collateral asset

    • collateralCoinType: Collateral coin type

    • marketParams: Static market parameters

    • marketState: Dynamic market state

    • baseCoinType: Base asset type

    • Other market metadata

• config (optional): CallerConfig

  • Configuration object containing:

    • network: The Sui network ("MAINNET", "TESTNET", "DEVNET", or "LOCAL")

    • accessToken: Optional authentication token

    • Other caller-specific settings

• Provider (optional): AftermathApi

  • Shared provider instance for advanced operations

  • Used for transaction building and additional functionality

Remarks:

• This class extends Caller with the "perpetuals" route prefix

• All HTTP requests resolve under /perpetuals/...

• Typically obtained via Perpetuals.getMarket() or Perpetuals.getMarkets() rather than direct construction

Example:

// Standard usage via Perpetuals class
const perps = afSdk.Perpetuals();
const { market } = await perps.getMarket({
	marketId:
		"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
});

// Direct construction (advanced usage)
const rawMarketData: PerpetualsMarketData = {
	objectId: "0x1234...",
	indexPrice: 42000,
	collateralPrice: 1.0,
	collateralCoinType:
		"0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN",
	marketParams: {
		/* ... */
	},
	marketState: {
		/* ... */
	},
	baseCoinType: "0x...::btc::BTC",
	// ... other fields
};

const customConfig = {
	network: "MAINNET" as SuiNetwork,
};

const market = new PerpetualsMarket(rawMarketData, customConfig);

// Access market properties
console.log(`Market ID: ${market.marketId}`);
console.log(`Index Price: $${market.indexPrice}`);
console.log(`Collateral: ${market.collateralCoinType}`);

Use Cases:

1. Market Wrapping: Wrap raw market data with convenient methods

2. Testing: Create market instances with mock data

3. Custom Initialization: Initialize with specific network configs

---

Public Properties

marketId

public readonly marketId: PerpetualsMarketId;

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

Example:

console.log(`Market ID: ${market.marketId}`);
// "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

---

indexPrice

public readonly indexPrice: number;

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

Example:

console.log(`Current BTC Price: $${market.indexPrice}`);
// "Current BTC Price: $42000"

// Calculate position value
const positionSize = 0.5; // BTC
const positionValue = positionSize * market.indexPrice;
console.log(`Position Value: $${positionValue}`);

---

collateralPrice

public readonly collateralPrice: number;

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

Example:

console.log(`USDC Price: $${market.collateralPrice}`);
// "USDC Price: $1.0"

// Convert collateral to USD
const collateralAmount = 10000; // USDC
const usdValue = collateralAmount * market.collateralPrice;
console.log(`USD Value: $${usdValue}`);

---

collateralCoinType

public readonly collateralCoinType: CoinType;

Sui type of the collateral coin used by this market.

Example:

console.log(`Collateral Type: ${market.collateralCoinType}`);
// "Collateral Type: 0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN"

// Check if market uses specific collateral
const isUsdcMarket = market.collateralCoinType.includes("COIN");
console.log(`Uses USDC: ${isUsdcMarket}`);

---

marketParams

public readonly marketParams: PerpetualsMarketParams;

Static market configuration parameters including lot size, tick size, margins, fees, and other immutable settings.

Available Fields:

• lotSize: Minimum order size increment (bigint, 9 decimals)

• tickSize: Minimum price increment (bigint, 9 decimals)

• marginRatioInitial: Initial margin ratio for opening positions

• marginRatioMaintenance: Maintenance margin ratio (liquidation threshold)

• insuranceFundFee: Insurance fund fee percentage

• makerFee: Maker fee percentage

• takerFee: Taker fee percentage

• Other market-specific parameters

Example:

// Access market parameters
console.log(`Lot Size: ${market.marketParams.lotSize}`);
console.log(`Tick Size: ${market.marketParams.tickSize}`);
console.log(`Initial Margin: ${market.marketParams.marginRatioInitial * 100}%`);
console.log(
	`Maintenance Margin: ${market.marketParams.marginRatioMaintenance * 100}%`,
);
console.log(`Maker Fee: ${market.marketParams.makerFee * 100}%`);
console.log(`Taker Fee: ${market.marketParams.takerFee * 100}%`);

// Calculate max leverage
const maxLeverage = 1 / market.marketParams.marginRatioInitial;
console.log(`Max Leverage: ${maxLeverage}x`);

// Use for order validation
const orderSize = 1.5;
const lotSizeFloat =
	Number(market.marketParams.lotSize) / Casting.Fixed.fixedOneN9;
const isValidSize = orderSize % lotSizeFloat === 0;
console.log(`Valid size: ${isValidSize}`);

---

marketState

public readonly marketState: PerpetualsMarketState;

Dynamic market state including funding rates, open interest, and other time-varying metrics.

Available Fields:

• cumFundingRateLong: Cumulative funding rate for long positions

• cumFundingRateShort: Cumulative funding rate for short positions

• openInterestLong: Total long open interest

• openInterestShort: Total short open interest

• premiumTwap: Premium TWAP used to derive the live funding rate

• nextFundingTime: Timestamp of next funding event

• Other dynamic state fields

Example:

// Access market state
console.log(`Long OI: ${market.marketState.openInterestLong}`);
console.log(`Short OI: ${market.marketState.openInterestShort}`);
console.log(
	`Cumulative Funding (Long): ${market.marketState.cumFundingRateLong}`,
);
console.log(
	`Cumulative Funding (Short): ${market.marketState.cumFundingRateShort}`,
);

// Calculate OI imbalance
const totalOI =
	market.marketState.openInterestLong + market.marketState.openInterestShort;
const oiImbalance =
	(market.marketState.openInterestLong -
		market.marketState.openInterestShort) /
	totalOI;
console.log(`OI Imbalance: ${oiImbalance * 100}%`);

// Check next funding time
const nextFunding = new Date(market.marketState.nextFundingTime);
console.log(`Next Funding: ${nextFunding.toLocaleString()}`);

// Derive the live funding rate
const fundingRate =
	market.indexPrice !== 0
		? market.marketState.premiumTwap / market.indexPrice
		: 0;
console.log(`Funding Rate: ${fundingRate * 100}%`);

---

Market Data Methods

getOrderbookMidPrice

async getOrderbookMidPrice(): Promise<{
  midPrice: number | undefined;
}>

Fetch the mid price for this market's orderbook.

What This Returns:

The midpoint between the best bid and best ask prices. Returns undefined if the orderbook is empty or one side is missing.

Formula:

midPrice = (bestBid + bestAsk) / 2

Returns:

Object containing:

• midPrice: number | undefined

  • Mid price if orderbook has both sides

  • undefined if orderbook is empty or incomplete

Example:

// Get mid price
const { midPrice } = await market.getOrderbookMidPrice();

if (midPrice !== undefined) {
	console.log(`Mid Price: $${midPrice}`);

	// Use for order placement
	const limitPrice = midPrice * 0.999; // 0.1% below mid
	console.log(`Limit Buy Price: $${limitPrice}`);
} else {
	console.log("No mid price available (empty orderbook)");
}

// Compare with index price
const { midPrice: mid } = await market.getOrderbookMidPrice();
if (mid !== undefined) {
	const spread = Math.abs(mid - market.indexPrice);
	const spreadPercent = (spread / market.indexPrice) * 100;

	console.log(`Index: $${market.indexPrice}`);
	console.log(`Mid: $${mid}`);
	console.log(`Spread: ${spreadPercent.toFixed(4)}%`);
}

// Monitor mid price changes
async function monitorMidPrice(interval: number = 5000) {
	setInterval(async () => {
		const { midPrice } = await market.getOrderbookMidPrice();
		if (midPrice !== undefined) {
			console.log(
				`[${new Date().toISOString()}] Mid Price: $${midPrice}`,
			);
		}
	}, interval);
}

// Usage
monitorMidPrice(5000); // Check every 5 seconds

Use Cases:

1. Order Placement: Determine competitive limit prices

2. Spread Analysis: Calculate bid-ask spread

3. Market Quality: Monitor orderbook depth and liquidity

4. Trading Signals: Detect price movements

---

get24hrStats

async get24hrStats(): Promise<PerpetualsMarket24hrStats>

Fetch 24-hour statistics for this specific market.

What This Provides:

Comprehensive 24-hour market metrics including volume, price changes, high/low prices, and trade count.

Implementation:

Under the hood, this calls Perpetuals.getMarkets24hrStats() with this market's ID and returns the result.

Returns:

PerpetualsMarket24hrStats object containing:

• marketId: Market identifier

• volume24h: 24-hour trading volume

• priceChange24h: Price change percentage

• priceChangeAbsolute24h: Absolute price change

• high24h: Highest price in 24h

• low24h: Lowest price in 24h

• open24h: Opening price 24h ago

• close24h: Most recent price

• trades24h: Number of trades

Example:

// Get 24-hour stats
const stats = await market.get24hrStats();

console.log(`=== 24-Hour Statistics ===`);
console.log(`Volume: $${stats.volume24h.toLocaleString()}`);
console.log(
	`Price Change: ${stats.priceChange24h > 0 ? "+" : ""}${stats.priceChange24h.toFixed(2)}%`,
);
console.log(`High: $${stats.high24h}`);
console.log(`Low: $${stats.low24h}`);
console.log(`Open: $${stats.open24h}`);
console.log(`Close: $${stats.close24h}`);
console.log(`Trades: ${stats.trades24h}`);

// Calculate 24h range
const range = stats.high24h - stats.low24h;
const rangePercent = (range / stats.low24h) * 100;
console.log(`24h Range: $${range} (${rangePercent.toFixed(2)}%)`);

// Determine market sentiment
function getMarketSentiment(stats: PerpetualsMarket24hrStats): string {
	if (stats.priceChange24h > 2) return "🟢 Strong Bullish";
	if (stats.priceChange24h > 0.5) return "🟢 Bullish";
	if (stats.priceChange24h > -0.5) return "⚪ Neutral";
	if (stats.priceChange24h > -2) return "🔴 Bearish";
	return "🔴 Strong Bearish";
}

const sentiment = getMarketSentiment(stats);
console.log(`Market Sentiment: ${sentiment}`);

// Display in UI component
function MarketStatsCard() {
	const stats = await market.get24hrStats();

	return {
		volume: `$${(stats.volume24h / 1e6).toFixed(2)}M`,
		change: `${stats.priceChange24h > 0 ? "+" : ""}${stats.priceChange24h.toFixed(2)}%`,
		high: `$${stats.high24h.toLocaleString()}`,
		low: `$${stats.low24h.toLocaleString()}`,
		trades: stats.trades24h.toLocaleString(),
	};
}

// Compare with other periods
async function comparePerformance() {
	const stats = await market.get24hrStats();

	// Calculate intraday performance
	const currentPrice = stats.close24h;
	const openPrice = stats.open24h;
	const intradayChange = ((currentPrice - openPrice) / openPrice) * 100;

	console.log(`24h Change: ${stats.priceChange24h.toFixed(2)}%`);
	console.log(`Intraday Change: ${intradayChange.toFixed(2)}%`);

	// Volatility indicator
	const avgPrice = (stats.high24h + stats.low24h) / 2;
	const volatility = ((stats.high24h - stats.low24h) / avgPrice) * 100;
	console.log(`Volatility: ${volatility.toFixed(2)}%`);
}

Use Cases:

1. Market Dashboard: Display key market metrics

2. Performance Tracking: Monitor 24-hour performance

3. Volatility Analysis: Calculate price ranges and volatility

4. Trading Signals: Identify momentum and trends

---

getOrderbook

async getOrderbook(): Promise<{
  orderbook: PerpetualsOrderbook;
}>

Fetch the full orderbook snapshot for this market.

What This Returns:

Complete orderbook with all bid and ask levels, including prices, sizes, and order IDs.

Returns:

Object containing:

• orderbook: PerpetualsOrderbook

  • bids: Array of bid orders (buy orders), sorted by price (high to low)

    • Each entry: { price, size, orderId }

  • asks: Array of ask orders (sell orders), sorted by price (low to high)

    • Each entry: { price, size, orderId }

Example:

// Get orderbook
const { orderbook } = await market.getOrderbook();

console.log(`=== Orderbook ===`);
console.log(`Bids: ${orderbook.bids.length} levels`);
console.log(`Asks: ${orderbook.asks.length} levels`);

// Display top of book
if (orderbook.bids.length > 0 && orderbook.asks.length > 0) {
	const bestBid = orderbook.bids[0];
	const bestAsk = orderbook.asks[0];

	console.log(`Best Bid: $${bestBid.price} (${bestBid.size})`);
	console.log(`Best Ask: $${bestAsk.price} (${bestAsk.size})`);

	const spread = bestAsk.price - bestBid.price;
	const spreadBps = (spread / bestBid.price) * 10000;
	console.log(`Spread: $${spread} (${spreadBps.toFixed(2)} bps)`);
}

// Display order book depth
console.log(`\nTop 5 Bids:`);
orderbook.bids.slice(0, 5).forEach((bid, i) => {
	console.log(`  ${i + 1}. $${bid.price} - ${bid.size}`);
});

console.log(`\nTop 5 Asks:`);
orderbook.asks.slice(0, 5).forEach((ask, i) => {
	console.log(`  ${i + 1}. $${ask.price} - ${ask.size}`);
});

// Calculate total liquidity
function calculateLiquidity(orderbook: PerpetualsOrderbook) {
	const bidLiquidity = orderbook.bids.reduce(
		(sum, bid) => sum + bid.price * bid.size,
		0,
	);

	const askLiquidity = orderbook.asks.reduce(
		(sum, ask) => sum + ask.price * ask.size,
		0,
	);

	return {
		bidLiquidity,
		askLiquidity,
		totalLiquidity: bidLiquidity + askLiquidity,
	};
}

const liquidity = calculateLiquidity(orderbook);
console.log(`\nLiquidity:`);
console.log(`  Bid Side: $${liquidity.bidLiquidity.toLocaleString()}`);
console.log(`  Ask Side: $${liquidity.askLiquidity.toLocaleString()}`);
console.log(`  Total: $${liquidity.totalLiquidity.toLocaleString()}`);

// Find liquidity at price level
function getLiquidityAtPrice(
	orderbook: PerpetualsOrderbook,
	targetPrice: number,
	tolerance: number = 0.001,
): { bids: number; asks: number } {
	const bidLiq = orderbook.bids
		.filter(
			(b) => Math.abs(b.price - targetPrice) / targetPrice < tolerance,
		)
		.reduce((sum, b) => sum + b.size, 0);

	const askLiq = orderbook.asks
		.filter(
			(a) => Math.abs(a.price - targetPrice) / targetPrice < tolerance,
		)
		.reduce((sum, a) => sum + a.size, 0);

	return { bids: bidLiq, asks: askLiq };
}

const liquidityAt42k = getLiquidityAtPrice(orderbook, 42000);
console.log(`Liquidity at $42,000:`);
console.log(`  Bids: ${liquidityAt42k.bids}`);
console.log(`  Asks: ${liquidityAt42k.asks}`);

// Visualize order book
function visualizeOrderbook(
	orderbook: PerpetualsOrderbook,
	levels: number = 10,
) {
	const maxSize = Math.max(
		...orderbook.bids.slice(0, levels).map((b) => b.size),
		...orderbook.asks.slice(0, levels).map((a) => a.size),
	);

	console.log(`\n=== Order Book Visualization ===`);

	// Asks (reversed to show highest first)
	orderbook.asks
		.slice(0, levels)
		.reverse()
		.forEach((ask) => {
			const bars = "█".repeat(Math.ceil((ask.size / maxSize) * 20));
			console.log(
				`🔴 $${ask.price.toFixed(2)} ${bars} ${ask.size.toFixed(4)}`,
			);
		});

	console.log(`--- SPREAD ---`);

	// Bids
	orderbook.bids.slice(0, levels).forEach((bid) => {
		const bars = "█".repeat(Math.ceil((bid.size / maxSize) * 20));
		console.log(
			`🟢 $${bid.price.toFixed(2)} ${bars} ${bid.size.toFixed(4)}`,
		);
	});
}

visualizeOrderbook(orderbook, 10);

// Calculate market depth for order execution
function estimateSlippage(
	orderbook: PerpetualsOrderbook,
	side: "buy" | "sell",
	size: number,
): { avgPrice: number; slippage: number } {
	const orders = side === "buy" ? orderbook.asks : orderbook.bids;

	let remainingSize = size;
	let totalCost = 0;

	for (const order of orders) {
		const fillSize = Math.min(remainingSize, order.size);
		totalCost += fillSize * order.price;
		remainingSize -= fillSize;

		if (remainingSize <= 0) break;
	}

	if (remainingSize > 0) {
		throw new Error(`Insufficient liquidity for order size ${size}`);
	}

	const avgPrice = totalCost / size;
	const bestPrice = orders[0].price;
	const slippage = Math.abs((avgPrice - bestPrice) / bestPrice);

	return { avgPrice, slippage };
}

try {
	const buySlippage = estimateSlippage(orderbook, "buy", 1.5);
	console.log(`\nBuying 1.5 units:`);
	console.log(`  Average Price: $${buySlippage.avgPrice.toFixed(2)}`);
	console.log(`  Slippage: ${buySlippage.slippage * 100}%`);
} catch (error) {
	console.error(error.message);
}

Use Cases:

1. Order Book Display: Show market depth in trading UI

2. Liquidity Analysis: Assess available liquidity at price levels

3. Slippage Estimation: Calculate expected execution prices

4. Market Making: Identify optimal bid/ask placement

---

getMaxOrderSize

async getMaxOrderSize(inputs: {
  accountId: PerpetualsAccountId;
  side: PerpetualsOrderSide;
  leverage?: number;
  price?: number;
}): Promise<{
  maxOrderSize: bigint;
}>

Compute the maximum order size that can be placed by a given account in this market.

What This Calculates:

The maximum position size an account can open based on:

• Available collateral

• Existing positions

• Target leverage

• Initial margin requirements

• Optional price (for limit orders)

Common Use Cases:

• "Max" buttons in trading interfaces

• Input validation

• Position size suggestions

• Risk limit checks

Parameters:

• accountId: PerpetualsAccountId

  • Perpetuals account ID (bigint)

  • Account to calculate max size for

• side: PerpetualsOrderSide

  • Order side (Bid = buy/long, Ask = sell/short)

  • Determines direction of position

• leverage (optional): number

  • Target leverage for the position

  • If omitted, uses maximum available leverage

  • Must be >= 1 and <= max leverage for market

• price (optional): number

  • Expected execution price

  • For limit orders, use limit price

  • For market orders, can be omitted (uses current index price)

Returns:

Object containing:

• maxOrderSize: bigint

  • Maximum order size in base asset units

  • Scaled by 1e9 (9 decimal places)

  • Must be converted to float for display

Example:

// Basic max size calculation
const { maxOrderSize } = await market.getMaxOrderSize({
	accountId: 123n,
	side: PerpetualsOrderSide.Bid,
});

// Convert to human-readable
const maxSizeFloat = Number(maxOrderSize) / Casting.Fixed.fixedOneN9;
console.log(`Max Order Size: ${maxSizeFloat} BTC`);

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

const maxSize5x = Number(maxWith5x) / Casting.Fixed.fixedOneN9;
console.log(`Max Size at 5x: ${maxSize5x} BTC`);

// With specific limit price
const limitPrice = 42000;
const { maxOrderSize: maxAtPrice } = await market.getMaxOrderSize({
	accountId: 123n,
	side: PerpetualsOrderSide.Bid,
	leverage: 3,
	price: limitPrice,
});

const maxSizeAtPrice = Number(maxAtPrice) / Casting.Fixed.fixedOneN9;
console.log(`Max Size at $${limitPrice}: ${maxSizeAtPrice} BTC`);

// Trading UI integration
async function handleMaxButtonClick(
	accountId: bigint,
	side: PerpetualsOrderSide,
	leverage: number,
) {
	try {
		const { maxOrderSize } = await market.getMaxOrderSize({
			accountId,
			side,
			leverage,
		});

		// Round to valid lot size
		const maxSizeRounded = market.roundToValidSize({
			size: Number(maxOrderSize) / Casting.Fixed.fixedOneN9,
			floor: true, // Round down for safety
		});

		console.log(`Setting order size to: ${maxSizeRounded}`);
		return maxSizeRounded;
	} catch (error) {
		console.error("Failed to calculate max size:", error);
		return 0;
	}
}

// Validate user input against max size
async function validateOrderSize(
	accountId: bigint,
	side: PerpetualsOrderSide,
	requestedSize: number,
	leverage: number,
): Promise<{ valid: boolean; maxSize: number; error?: string }> {
	const { maxOrderSize } = await market.getMaxOrderSize({
		accountId,
		side,
		leverage,
	});

	const maxSizeFloat = Number(maxOrderSize) / Casting.Fixed.fixedOneN9;

	if (requestedSize > maxSizeFloat) {
		return {
			valid: false,
			maxSize: maxSizeFloat,
			error: `Size ${requestedSize} exceeds maximum ${maxSizeFloat}`,
		};
	}

	return {
		valid: true,
		maxSize: maxSizeFloat,
	};
}

// Usage
const validation = await validateOrderSize(
	123n,
	PerpetualsOrderSide.Bid,
	2.5,
	5,
);
if (!validation.valid) {
	console.error(validation.error);
	console.log(`Max allowed: ${validation.maxSize}`);
}

// Compare max sizes across leverage levels
async function compareMaxSizesByLeverage(
	accountId: bigint,
	side: PerpetualsOrderSide,
) {
	const leverages = [1, 2, 5, 10, 20];

	console.log(`Max Sizes by Leverage:`);
	for (const lev of leverages) {
		try {
			const { maxOrderSize } = await market.getMaxOrderSize({
				accountId,
				side,
				leverage: lev,
			});

			const size = Number(maxOrderSize) / Casting.Fixed.fixedOneN9;
			console.log(`  ${lev}x: ${size.toFixed(4)} BTC`);
		} catch (error) {
			console.log(`  ${lev}x: Not available`);
		}
	}
}

// Calculate max position value
async function getMaxPositionValue(
	accountId: bigint,
	side: PerpetualsOrderSide,
	leverage: number,
) {
	const { maxOrderSize } = await market.getMaxOrderSize({
		accountId,
		side,
		leverage,
	});

	const size = Number(maxOrderSize) / Casting.Fixed.fixedOneN9;
	const value = size * market.indexPrice;

	console.log(`Max Position Value: $${value.toLocaleString()}`);
	console.log(`  Size: ${size} BTC`);
	console.log(`  Price: $${market.indexPrice}`);
	console.log(`  Leverage: ${leverage}x`);

	return value;
}

Use Cases:

1. Max Button: Auto-fill maximum safe order size

2. Input Validation: Prevent orders exceeding capacity

3. Position Calculator: Show maximum position value

4. Risk Management: Enforce position limits

---

Order Preview Methods

getPlaceMarketOrderPreview

async getPlaceMarketOrderPreview(
  inputs: {
    side: PerpetualsOrderSide;
    size: bigint;
    leverage?: number;
    collateralChange?: number;
    slippageTolerance?: number;
  },
  abortSignal?: AbortSignal
): Promise<ApiPerpetualsPreviewPlaceOrderResponse>

Market-level preview of placing a market order.

What This Does:

Simulates a market order execution without requiring a specific account's on-chain state. This is useful for:

• Pre-trade analysis

• Slippage estimation

• Position preview

• UI simulations

Difference from PerpetualsAccount.getPlaceMarketOrderPreview:

• PerpetualsMarket.getPlaceMarketOrderPreview: Generic preview, doesn't account for existing account state

• PerpetualsAccount.getPlaceMarketOrderPreview: Accounts for existing positions, collateral, and fees

Parameters:

• side: PerpetualsOrderSide

  • Order side (Bid = buy, Ask = sell)

• size: bigint

  • Order size in base asset units (scaled by 1e9)

  • Must be multiple of lot size

• leverage (optional): number

  • Target leverage for position

  • Affects margin requirements

• collateralChange (optional): number

  • Collateral amount to add/remove with order

  • Positive = add, Negative = remove

• slippageTolerance (optional): number

  • Maximum acceptable slippage (as fraction)

  • Example: 0.01 = 1%

• abortSignal (optional): AbortSignal

  • Signal to cancel the request

Returns:

ApiPerpetualsPreviewPlaceOrderResponse which is either:

• Success: Object containing:

  • updatedPosition: Simulated position after order

  • slippage: Expected slippage

  • filledSize: Amount filled

  • postedSize: Amount posted to orderbook

  • collateralChange: Actual collateral change

  • executionPrice: Average execution price

  • Other preview data

• Error: { error: string } if preview fails

Example:

// Basic market order preview
const preview = await market.getPlaceMarketOrderPreview({
	side: PerpetualsOrderSide.Bid,
	size: 1500000000n, // 1.5 BTC
});

if ("error" in preview) {
	console.error(`Preview failed: ${preview.error}`);
} else {
	console.log(`=== Market Order Preview ===`);
	console.log(`Execution Price: $${preview.executionPrice}`);
	console.log(`Slippage: ${preview.slippage * 100}%`);
	console.log(
		`Filled Size: ${Number(preview.filledSize) / Casting.Fixed.fixedOneN9}`,
	);
	console.log(
		`Posted Size: ${Number(preview.postedSize) / Casting.Fixed.fixedOneN9}`,
	);
}

// Preview with leverage
const leveragedPreview = await market.getPlaceMarketOrderPreview({
	side: PerpetualsOrderSide.Bid,
	size: 2000000000n, // 2 BTC
	leverage: 5,
});

if (!("error" in leveragedPreview)) {
	console.log(`\n5x Leveraged Order:`);
	console.log(
		`Position Size: ${leveragedPreview.updatedPosition.baseAssetAmount}`,
	);
	console.log(
		`Required Margin: ${leveragedPreview.updatedPosition.collateral}`,
	);
	console.log(`Leverage: ${leveragedPreview.updatedPosition.leverage}x`);
}

// Preview with collateral change
const withCollateral = await market.getPlaceMarketOrderPreview({
	side: PerpetualsOrderSide.Bid,
	size: 1000000000n, // 1 BTC
	collateralChange: 5000, // Add 5000 USDC
	leverage: 3,
});

// Preview with slippage tolerance
const withSlippage = await market.getPlaceMarketOrderPreview({
	side: PerpetualsOrderSide.Ask,
	size: 500000000n, // 0.5 BTC
	slippageTolerance: 0.005, // 0.5% max slippage
});

if (!("error" in withSlippage)) {
	if (withSlippage.slippage > 0.005) {
		console.warn(
			`Slippage ${withSlippage.slippage * 100}% exceeds tolerance!`,
		);
	} else {
		console.log(`Slippage ${withSlippage.slippage * 100}% is acceptable`);
	}
}

// Trading interface integration
async function previewMarketOrder(
	side: PerpetualsOrderSide,
	sizeFloat: number,
	leverage: number = 1,
) {
	// Convert to bigint
	const size = BigInt(Math.round(sizeFloat * Casting.Fixed.fixedOneN9));

	// Get preview
	const preview = await market.getPlaceMarketOrderPreview({
		side,
		size,
		leverage,
		slippageTolerance: 0.01, // 1% max
	});

	if ("error" in preview) {
		return {
			success: false,
			error: preview.error,
		};
	}

	// Format for UI
	return {
		success: true,
		executionPrice: preview.executionPrice,
		slippage: (preview.slippage * 100).toFixed(2) + "%",
		filled: Number(preview.filledSize) / Casting.Fixed.fixedOneN9,
		total:
			(Number(preview.filledSize) / Casting.Fixed.fixedOneN9) *
			preview.executionPrice,
		warning: preview.slippage > 0.01 ? "High slippage!" : null,
	};
}

// Usage
const result = await previewMarketOrder(PerpetualsOrderSide.Bid, 1.5, 5);
console.log(result);

// Estimate PnL after order
async function estimatePnL(
	side: PerpetualsOrderSide,
	size: bigint,
	exitPrice: number,
) {
	const preview = await market.getPlaceMarketOrderPreview({
		side,
		size,
	});

	if ("error" in preview) {
		console.error(preview.error);
		return;
	}

	const entryPrice = preview.executionPrice;
	const sizeFloat = Number(size) / Casting.Fixed.fixedOneN9;

	let pnl: number;
	if (side === PerpetualsOrderSide.Bid) {
		// Long position
		pnl = (exitPrice - entryPrice) * sizeFloat;
	} else {
		// Short position
		pnl = (entryPrice - exitPrice) * sizeFloat;
	}

	const pnlPercent = (pnl / (entryPrice * sizeFloat)) * 100;

	console.log(`Entry: $${entryPrice}`);
	console.log(`Exit: $${exitPrice}`);
	console.log(`PnL: $${pnl.toFixed(2)} (${pnlPercent.toFixed(2)}%)`);

	return pnl;
}

// Abort long-running preview
const controller = new AbortController();

setTimeout(() => {
	controller.abort();
	console.log("Preview request aborted");
}, 5000);

try {
	const preview = await market.getPlaceMarketOrderPreview(
		{
			side: PerpetualsOrderSide.Bid,
			size: 1000000000n,
		},
		controller.signal,
	);
} catch (error) {
	if (error.name === "AbortError") {
		console.log("Request was aborted");
	}
}

Use Cases:

1. Order Confirmation: Show expected execution before placing

2. Slippage Warning: Alert users to high slippage

3. Position Planning: Preview position state after order

4. Risk Analysis: Evaluate margin requirements

---

getPlaceLimitOrderPreview

async getPlaceLimitOrderPreview(
  inputs: {
    side: PerpetualsOrderSide;
    size: bigint;
    price: number;
    leverage?: number;
    collateralChange?: number;
  },
  abortSignal?: AbortSignal
): Promise<ApiPerpetualsPreviewPlaceOrderResponse>

Market-level preview of placing a limit order.

What This Does:

Simulates a limit order placement without requiring a specific account's on-chain state. Similar to market order preview but for limit orders at a specific price.

Difference from Market Order Preview:

• Limit orders specify exact price

• May be partially or fully posted to orderbook

• Execution depends on order matching

Parameters:

• side: PerpetualsOrderSide

  • Order side (Bid = buy, Ask = sell)

• size: bigint

  • Order size in base asset units (scaled by 1e9)

• price: number

  • Limit price

  • Must be multiple of tick size

• leverage (optional): number

  • Target leverage

• collateralChange (optional): number

  • Collateral to add/remove

• abortSignal (optional): AbortSignal

  • Signal to cancel request

Returns:

ApiPerpetualsPreviewPlaceOrderResponse (same as market order preview)

Example:

// Basic limit order preview
const limitPrice = 42000;
const preview = await market.getPlaceLimitOrderPreview({
	side: PerpetualsOrderSide.Bid,
	size: 1000000000n, // 1 BTC
	price: limitPrice,
});

if (!("error" in preview)) {
	console.log(`=== Limit Order Preview ===`);
	console.log(`Limit Price: $${limitPrice}`);
	console.log(`Execution Price: $${preview.executionPrice}`);
	console.log(
		`Filled: ${Number(preview.filledSize) / Casting.Fixed.fixedOneN9}`,
	);
	console.log(
		`Posted: ${Number(preview.postedSize) / Casting.Fixed.fixedOneN9}`,
	);

	// Check if order will execute immediately
	if (Number(preview.filledSize) > 0) {
		console.log(`⚠️  Order will fill immediately (partial market order)`);
	} else {
		console.log(`✓ Order will be posted to orderbook`);
	}
}

// Round price to valid tick
const rawPrice = 42123.45;
const validPrice = market.roundToValidPrice({ price: rawPrice });

const roundedPreview = await market.getPlaceLimitOrderPreview({
	side: PerpetualsOrderSide.Bid,
	size: 1500000000n,
	price: validPrice,
});

console.log(`Raw price: $${rawPrice}`);
console.log(`Valid price: $${validPrice}`);

// Compare limit vs market execution
async function compareLimitVsMarket(
	side: PerpetualsOrderSide,
	size: bigint,
	limitPrice: number,
) {
	const [marketPreview, limitPreview] = await Promise.all([
		market.getPlaceMarketOrderPreview({ side, size }),
		market.getPlaceLimitOrderPreview({ side, size, price: limitPrice }),
	]);

	if ("error" in marketPreview || "error" in limitPreview) {
		console.error("Preview failed");
		return;
	}

	console.log(`=== Limit vs Market ===`);
	console.log(`Market Execution: $${marketPreview.executionPrice}`);
	console.log(`Limit Price: $${limitPrice}`);
	console.log(
		`Limit Filled: ${Number(limitPreview.filledSize) / Casting.Fixed.fixedOneN9}`,
	);
	console.log(
		`Limit Posted: ${Number(limitPreview.postedSize) / Casting.Fixed.fixedOneN9}`,
	);

	const savings = Math.abs(marketPreview.executionPrice - limitPrice);
	const savingsPercent = (savings / marketPreview.executionPrice) * 100;

	console.log(
		`Potential Savings: $${savings.toFixed(2)} (${savingsPercent.toFixed(2)}%)`,
	);
}

// Optimal limit price finder
async function findOptimalLimitPrice(
	side: PerpetualsOrderSide,
	size: bigint,
	maxSlippage: number = 0.001,
) {
	const { orderbook } = await market.getOrderbook();

	// Start from best price
	const bestPrice =
		side === PerpetualsOrderSide.Bid
			? orderbook.asks[0]?.price
			: orderbook.bids[0]?.price;

	if (!bestPrice) {
		console.error("No orderbook data");
		return null;
	}

	// Try prices with increasing slippage
	const priceAdjustments = [0, 0.001, 0.002, 0.005, 0.01];

	for (const adjustment of priceAdjustments) {
		const testPrice =
			side === PerpetualsOrderSide.Bid
				? bestPrice * (1 + adjustment)
				: bestPrice * (1 - adjustment);

		const validPrice = market.roundToValidPrice({ price: testPrice });

		const preview = await market.getPlaceLimitOrderPreview({
			side,
			size,
			price: validPrice,
		});

		if (!("error" in preview)) {
			const fillRatio = Number(preview.filledSize) / Number(size);

			if (fillRatio >= 0.9) {
				// At least 90% filled
				console.log(
					`Optimal price: $${validPrice} (${adjustment * 100}% from best)`,
				);
				return validPrice;
			}
		}
	}

	console.log("Could not find optimal price within slippage tolerance");
	return null;
}

// Ladder order preview
async function previewLadderOrders(
	side: PerpetualsOrderSide,
	totalSize: bigint,
	numOrders: number,
	priceRange: number,
) {
	const { orderbook } = await market.getOrderbook();
	const midPrice =
		side === PerpetualsOrderSide.Bid
			? orderbook.asks[0]?.price
			: orderbook.bids[0]?.price;

	if (!midPrice) return;

	const sizePerOrder = totalSize / BigInt(numOrders);
	const priceStep = (midPrice * priceRange) / numOrders;

	console.log(`=== Ladder Order Preview ===`);
	console.log(`Total Size: ${Number(totalSize) / Casting.Fixed.fixedOneN9}`);
	console.log(`Orders: ${numOrders}`);
	console.log(`Price Range: ${priceRange * 100}%`);

	for (let i = 0; i < numOrders; i++) {
		const price =
			side === PerpetualsOrderSide.Bid
				? midPrice - priceStep * i
				: midPrice + priceStep * i;

		const validPrice = market.roundToValidPrice({ price });

		const preview = await market.getPlaceLimitOrderPreview({
			side,
			size: sizePerOrder,
			price: validPrice,
		});

		if (!("error" in preview)) {
			console.log(`\nOrder ${i + 1}:`);
			console.log(`  Price: $${validPrice}`);
			console.log(
				`  Size: ${Number(sizePerOrder) / Casting.Fixed.fixedOneN9}`,
			);
			console.log(
				`  Will Fill: ${Number(preview.filledSize) / Casting.Fixed.fixedOneN9}`,
			);
			console.log(
				`  Will Post: ${Number(preview.postedSize) / Casting.Fixed.fixedOneN9}`,
			);
		}
	}
}

// Usage
await previewLadderOrders(
	PerpetualsOrderSide.Bid,
	5000000000n, // 5 BTC total
	5, // 5 orders
	0.02, // 2% price range
);

Use Cases:

1. Limit Order Placement: Preview limit order execution

2. Order Strategy: Plan multi-order strategies

3. Price Discovery: Find optimal limit prices

4. Orderbook Interaction: Understand order matching

---

getPlaceScaleOrderPreview

async getPlaceScaleOrderPreview(
  inputs: SdkPerpetualsPlaceScaleOrderPreviewInputs,
  abortSignal?: AbortSignal
): Promise<ApiPerpetualsPreviewPlaceOrderResponse>

Market-level preview of placing a scale order.

What This Does:

Simulates a scale order placement without requiring a specific account's on-chain state. A scale order distributes a total size across multiple limit orders evenly spaced between a start and end price. An optional sizeSkew parameter controls whether the distribution is uniform or weighted toward one end.

This preview runs without account context (accountId: undefined), so it cannot factor in existing positions or collateral. Use PerpetualsAccount.getPlaceScaleOrderPreview() for account-specific previews.

Parameters:

• marketId: PerpetualsMarketId

  • Target market

• side: PerpetualsOrderSide

  • Order side (Bid = buy, Ask = sell)

• totalSize: bigint

  • Total size distributed across all orders (scaled by 1e9)

• startPrice: bigint

  • Starting price of the range (inclusive, scaled by 1e9)

• endPrice: bigint

  • Ending price of the range (inclusive, scaled by 1e9)

• numberOfOrders: number

  • Number of limit orders to place across the range

• orderType: PerpetualsOrderType

  • Order type (e.g. Standard, PostOnly, ImmediateOrCancel, FillOrKill)

• reduceOnly: boolean

  • If true, orders can only reduce an existing position

• sizeSkew (optional): number

  • Size ratio between last and first order. 1.0 = uniform distribution, 2.0 = last order is 2x the size of the first

• leverage (optional): number

  • Target leverage

• expiryTimestamp (optional): bigint

  • Expiration timestamp in milliseconds since epoch

• abortSignal (optional): AbortSignal

  • Signal to cancel request

Returns:

ApiPerpetualsPreviewPlaceOrderResponse (same as market/limit order previews)

Example:

// Basic scale order preview — 5 buy orders from $40k to $42k
const preview = await market.getPlaceScaleOrderPreview({
	marketId: market.marketId,
	side: PerpetualsOrderSide.Bid,
	totalSize: 5n * Casting.Fixed.fixedOneN9, // 5 units total
	startPrice: 40_000n * Casting.Fixed.fixedOneN9,
	endPrice: 42_000n * Casting.Fixed.fixedOneN9,
	numberOfOrders: 5,
	orderType: PerpetualsOrderType.PostOnly,
	reduceOnly: false,
});

if (!("error" in preview)) {
	console.log(`=== Scale Order Preview ===`);
	console.log(`Execution Price: $${preview.executionPrice}`);
	console.log(
		`Filled: ${Number(preview.filledSize) / Casting.Fixed.fixedOneN9}`,
	);
	console.log(
		`Posted: ${Number(preview.postedSize) / Casting.Fixed.fixedOneN9}`,
	);
	console.log(`Slippage: ${preview.percentSlippage * 100}%`);
}

// Preview with size skew — weighted toward lower prices
const skewedPreview = await market.getPlaceScaleOrderPreview({
	marketId: market.marketId,
	side: PerpetualsOrderSide.Bid,
	totalSize: 10n * Casting.Fixed.fixedOneN9,
	startPrice: 38_000n * Casting.Fixed.fixedOneN9,
	endPrice: 42_000n * Casting.Fixed.fixedOneN9,
	numberOfOrders: 10,
	orderType: PerpetualsOrderType.Standard,
	reduceOnly: false,
	sizeSkew: 2.0, // Last order is 2x the size of the first
});

// Compare uniform vs skewed distribution
async function compareScaleDistributions(
	side: PerpetualsOrderSide,
	totalSize: bigint,
	startPrice: bigint,
	endPrice: bigint,
	numberOfOrders: number,
) {
	const [uniform, skewed] = await Promise.all([
		market.getPlaceScaleOrderPreview({
			marketId: market.marketId,
			side,
			totalSize,
			startPrice,
			endPrice,
			numberOfOrders,
			orderType: PerpetualsOrderType.PostOnly,
			reduceOnly: false,
			sizeSkew: 1.0,
		}),
		market.getPlaceScaleOrderPreview({
			marketId: market.marketId,
			side,
			totalSize,
			startPrice,
			endPrice,
			numberOfOrders,
			orderType: PerpetualsOrderType.PostOnly,
			reduceOnly: false,
			sizeSkew: 2.0,
		}),
	]);

	if (!("error" in uniform) && !("error" in skewed)) {
		console.log(`=== Uniform vs Skewed ===`);
		console.log(
			`Uniform posted: ${Number(uniform.postedSize) / Casting.Fixed.fixedOneN9}`,
		);
		console.log(
			`Skewed posted: ${Number(skewed.postedSize) / Casting.Fixed.fixedOneN9}`,
		);
	}
}

Use Cases:

1. Scale Order Placement: Preview execution before committing to a transaction

2. Distribution Strategy: Compare uniform vs skewed distributions

3. Grid Trading: Plan order grids across a price range

4. DCA Strategies: Simulate dollar-cost averaging with multiple orders

---

getEstimatedExecutionPrice

async getEstimatedExecutionPrice(inputs: {
  side: PerpetualsOrderSide;
  size: bigint;
}): Promise<{
  estimatedPrice: number;
}>

Estimate the average execution price for a market order of a given size.

What This Calculates:

Simulates walking the orderbook to determine the average price at which an order would execute, considering available liquidity at each price level.

How It Works:

1. Fetches current orderbook

2. Walks through orders on opposite side

3. Calculates weighted average price

4. Accounts for partial fills at each level

Parameters:

• side: PerpetualsOrderSide

  • Order side (Bid = buy from asks, Ask = sell to bids)

• size: bigint

  • Order size in base asset units (scaled by 1e9)

Returns:

Object containing:

• estimatedPrice: number

  • Weighted average execution price

  • Returns 0 if insufficient liquidity

Example:

// Estimate execution price for market buy
const { estimatedPrice } = await market.getEstimatedExecutionPrice({
	side: PerpetualsOrderSide.Bid,
	size: 2000000000n, // 2 BTC
});

console.log(`Estimated Execution Price: $${estimatedPrice}`);

// Compare with index price
const indexPrice = market.indexPrice;
const priceImpact = ((estimatedPrice - indexPrice) / indexPrice) * 100;

console.log(`Index Price: $${indexPrice}`);
console.log(`Estimated Price: $${estimatedPrice}`);
console.log(`Price Impact: ${priceImpact.toFixed(2)}%`);

// Calculate slippage for different sizes
async function analyzeSlippageBySize(
	side: PerpetualsOrderSide,
	sizes: number[],
) {
	console.log(`=== Slippage Analysis ===`);

	const { orderbook } = await market.getOrderbook();
	const bestPrice =
		side === PerpetualsOrderSide.Bid
			? orderbook.asks[0]?.price
			: orderbook.bids[0]?.price;

	for (const sizeFloat of sizes) {
		const size = BigInt(Math.round(sizeFloat * Casting.Fixed.fixedOneN9));
		const { estimatedPrice } = await market.getEstimatedExecutionPrice({
			side,
			size,
		});

		const slippage = ((estimatedPrice - bestPrice) / bestPrice) * 100;

		console.log(`Size: ${sizeFloat} BTC`);
		console.log(`  Best Price: $${bestPrice}`);
		console.log(`  Avg Price: $${estimatedPrice}`);
		console.log(`  Slippage: ${slippage.toFixed(4)}%`);
	}
}

// Usage
await analyzeSlippageBySize(PerpetualsOrderSide.Bid, [0.1, 0.5, 1, 2, 5, 10]);

// Compare execution price vs limit price
async function shouldUseLimitOrder(
	side: PerpetualsOrderSide,
	size: bigint,
	maxSlippageBps: number = 10, // 10 basis points
): Promise<{
	useLimitOrder: boolean;
	limitPrice?: number;
	estimatedPrice: number;
}> {
	const { estimatedPrice } = await market.getEstimatedExecutionPrice({
		side,
		size,
	});

	const { orderbook } = await market.getOrderbook();
	const bestPrice =
		side === PerpetualsOrderSide.Bid
			? orderbook.asks[0]?.price
			: orderbook.bids[0]?.price;

	if (!bestPrice) {
		return { useLimitOrder: false, estimatedPrice: 0 };
	}

	const slippageBps = ((estimatedPrice - bestPrice) / bestPrice) * 10000;

	if (Math.abs(slippageBps) > maxSlippageBps) {
		// High slippage - recommend limit order
		const limitPrice =
			side === PerpetualsOrderSide.Bid
				? bestPrice * (1 + maxSlippageBps / 10000)
				: bestPrice * (1 - maxSlippageBps / 10000);

		return {
			useLimitOrder: true,
			limitPrice: market.roundToValidPrice({ price: limitPrice }),
			estimatedPrice,
		};
	}

	return {
		useLimitOrder: false,
		estimatedPrice,
	};
}

// Usage
const recommendation = await shouldUseLimitOrder(
	PerpetualsOrderSide.Bid,
	5000000000n, // 5 BTC
	10, // Max 10 bps slippage
);

if (recommendation.useLimitOrder) {
	console.log(`⚠️  Use limit order at $${recommendation.limitPrice}`);
	console.log(
		`Market order would execute at $${recommendation.estimatedPrice}`,
	);
} else {
	console.log(`✓ Market order OK at ~$${recommendation.estimatedPrice}`);
}

// Real-time price impact monitor
async function monitorPriceImpact(
	side: PerpetualsOrderSide,
	size: bigint,
	intervalMs: number = 5000,
) {
	setInterval(async () => {
		const { estimatedPrice } = await market.getEstimatedExecutionPrice({
			side,
			size,
		});

		const timestamp = new Date().toISOString();
		const priceImpact =
			((estimatedPrice - market.indexPrice) / market.indexPrice) * 100;

		console.log(`[${timestamp}]`);
		console.log(`  Est. Price: $${estimatedPrice}`);
		console.log(`  Impact: ${priceImpact.toFixed(4)}%`);
	}, intervalMs);
}

// Calculate total cost including fees
async function estimateTotalCost(
	side: PerpetualsOrderSide,
	size: bigint,
	isMaker: boolean = false,
) {
	const { estimatedPrice } = await market.getEstimatedExecutionPrice({
		side,
		size,
	});

	const sizeFloat = Number(size) / Casting.Fixed.fixedOneN9;
	const baseCost = estimatedPrice * sizeFloat;

	const feeRate = isMaker
		? market.marketParams.makerFee
		: market.marketParams.takerFee;

	const fee = baseCost * feeRate;
	const totalCost = baseCost + fee;

	console.log(`=== Total Cost Estimate ===`);
	console.log(`Base Cost: $${baseCost.toLocaleString()}`);
	console.log(`Fee (${feeRate * 100}%): $${fee.toFixed(2)}`);
	console.log(`Total: $${totalCost.toLocaleString()}`);

	return totalCost;
}

Use Cases:

1. Order Cost Estimation: Calculate total order cost

2. Slippage Analysis: Understand price impact

3. Order Type Selection: Choose between market/limit

4. Trading Strategy: Optimize order execution

---

Historical Data Methods

getOrderHistory

async getOrderHistory(inputs: {
  cursor?: string;
  limit?: number;
  accountId?: PerpetualsAccountId;
}): Promise<{
  orderHistory: PerpetualsFilledOrderData[];
  nextCursor: string | undefined;
}>

Fetch historical filled orders for this market.

What This Returns:

Paginated list of filled orders (trades) for the market, optionally filtered by account.

Parameters:

• cursor (optional): string

  • Pagination cursor from previous request

  • Omit or pass undefined for first page

• limit (optional): number

  • Maximum number of orders to return

  • Default/max depends on API settings

• accountId (optional): PerpetualsAccountId

  • Filter orders by specific account

  • Omit to get all market orders

Returns:

Object containing:

• orderHistory: PerpetualsFilledOrderData[]

  • Array of filled orders

  • Each order contains:

    • Order details (size, price, side)

    • Execution timestamp

    • Account information

    • Fees paid

• nextCursor: string | undefined

  • Cursor for next page

  • undefined if no more pages

Example:

// Fetch first page of order history
const { orderHistory, nextCursor } = await market.getOrderHistory({
	limit: 50,
});

console.log(`Fetched ${orderHistory.length} orders`);

// Display recent orders
orderHistory.slice(0, 10).forEach((order, i) => {
	console.log(`\n${i + 1}. Order:`);
	console.log(
		`  Side: ${order.side === PerpetualsOrderSide.Bid ? "Buy" : "Sell"}`,
	);
	console.log(`  Size: ${Number(order.size) / Casting.Fixed.fixedOneN9}`);
	console.log(`  Price: $${order.price}`);
	console.log(`  Time: ${new Date(order.timestamp).toLocaleString()}`);
	console.log(`  Fee: $${order.fee}`);
});

// Paginate through all orders
async function fetchAllOrders(
	maxPages: number = 10,
): Promise<PerpetualsFilledOrderData[]> {
	const allOrders: PerpetualsFilledOrderData[] = [];
	let cursor: string | undefined = undefined;
	let page = 0;

	while (page < maxPages) {
		const { orderHistory, nextCursor } = await market.getOrderHistory({
			cursor,
			limit: 100,
		});

		allOrders.push(...orderHistory);
		console.log(`Fetched page ${page + 1}: ${orderHistory.length} orders`);

		if (!nextCursor) break;

		cursor = nextCursor;
		page++;
	}

	console.log(`Total orders fetched: ${allOrders.length}`);
	return allOrders;
}

// Filter orders by account
const accountOrders = await market.getOrderHistory({
	accountId: 123n,
	limit: 100,
});

console.log(`Account orders: ${accountOrders.orderHistory.length}`);

// Analyze trading volume
function analyzeTradingVolume(orders: PerpetualsFilledOrderData[]) {
	let totalVolume = 0;
	let buyVolume = 0;
	let sellVolume = 0;

	for (const order of orders) {
		const orderVolume =
			(Number(order.size) / Casting.Fixed.fixedOneN9) * order.price;
		totalVolume += orderVolume;

		if (order.side === PerpetualsOrderSide.Bid) {
			buyVolume += orderVolume;
		} else {
			sellVolume += orderVolume;
		}
	}

	console.log(`=== Volume Analysis ===`);
	console.log(`Total: $${totalVolume.toLocaleString()}`);
	console.log(
		`Buy: $${buyVolume.toLocaleString()} (${((buyVolume / totalVolume) * 100).toFixed(1)}%)`,
	);
	console.log(
		`Sell: $${sellVolume.toLocaleString()} (${((sellVolume / totalVolume) * 100).toFixed(1)}%)`,
	);

	return { totalVolume, buyVolume, sellVolume };
}

const allOrders = await fetchAllOrders(5);
analyzeTradingVolume(allOrders);

// Calculate price-weighted average
function calculateVWAP(orders: PerpetualsFilledOrderData[]): number {
	let totalValue = 0;
	let totalVolume = 0;

	for (const order of orders) {
		const volume = Number(order.size) / Casting.Fixed.fixedOneN9;
		totalValue += order.price * volume;
		totalVolume += volume;
	}

	return totalValue / totalVolume;
}

const vwap = calculateVWAP(orderHistory);
console.log(`VWAP: $${vwap.toFixed(2)}`);

// Group orders by time period
function groupOrdersByHour(orders: PerpetualsFilledOrderData[]) {
	const hourly = new Map<string, PerpetualsFilledOrderData[]>();

	for (const order of orders) {
		const hour = new Date(order.timestamp);
		hour.setMinutes(0, 0, 0);
		const key = hour.toISOString();

		if (!hourly.has(key)) {
			hourly.set(key, []);
		}
		hourly.get(key)!.push(order);
	}

	console.log(`=== Hourly Breakdown ===`);
	for (const [hour, orders] of hourly) {
		const volume = orders.reduce(
			(sum, o) =>
				sum + (Number(o.size) / Casting.Fixed.fixedOneN9) * o.price,
			0,
		);
		console.log(
			`${hour}: ${orders.length} trades, $${volume.toLocaleString()}`,
		);
	}

	return hourly;
}

groupOrdersByHour(orderHistory);

// Find largest trades
function findLargestTrades(
	orders: PerpetualsFilledOrderData[],
	topN: number = 10,
) {
	const sorted = [...orders].sort((a, b) => {
		const aValue = (Number(a.size) / Casting.Fixed.fixedOneN9) * a.price;
		const bValue = (Number(b.size) / Casting.Fixed.fixedOneN9) * b.price;
		return bValue - aValue;
	});

	console.log(`=== Top ${topN} Largest Trades ===`);
	sorted.slice(0, topN).forEach((order, i) => {
		const value =
			(Number(order.size) / Casting.Fixed.fixedOneN9) * order.price;
		console.log(`${i + 1}. $${value.toLocaleString()} at $${order.price}`);
	});

	return sorted.slice(0, topN);
}

findLargestTrades(orderHistory, 10);

// Calculate fees paid
function calculateTotalFees(orders: PerpetualsFilledOrderData[]): number {
	return orders.reduce((sum, order) => sum + order.fee, 0);
}

const totalFees = calculateTotalFees(orderHistory);
console.log(`Total Fees Paid: $${totalFees.toFixed(2)}`);

Use Cases:

1. Trade History: Display user's trading history

2. Volume Analysis: Calculate trading volume metrics

3. Fee Tracking: Monitor fees paid

4. Market Analysis: Analyze market trading patterns

---

Price & Funding Methods

getPrices

async getPrices(): Promise<{
  basePrice: number;
  collateralPrice: number;
}>

Fetch current oracle prices for this market.

What This Returns:

Latest oracle prices for both the base asset (underlying) and collateral asset.

Returns:

Object containing:

• basePrice: number

  • Current oracle price of base asset (e.g., BTC price in USD)

• collateralPrice: number

  • Current price of collateral asset (e.g., USDC price in USD)

These values are also available as market.indexPrice and market.collateralPrice, but this method fetches the latest values from the API.

Example:

// Fetch latest prices
const { basePrice, collateralPrice } = await market.getPrices();

console.log(`Base Asset Price: $${basePrice}`);
console.log(`Collateral Price: $${collateralPrice}`);

// Compare with cached prices
console.log(`\nCached vs Fresh:`);
console.log(`  Cached Base: $${market.indexPrice}`);
console.log(`  Fresh Base: $${basePrice}`);
console.log(`  Cached Collateral: $${market.collateralPrice}`);
console.log(`  Fresh Collateral: $${collateralPrice}`);

// Monitor price updates
async function monitorPrices(intervalMs: number = 5000) {
	let previousPrice = market.indexPrice;

	setInterval(async () => {
		const { basePrice } = await market.getPrices();
		const change = basePrice - previousPrice;
		const changePercent = (change / previousPrice) * 100;

		console.log(`[${new Date().toISOString()}]`);
		console.log(`  Price: $${basePrice}`);
		console.log(
			`  Change: ${change > 0 ? "+" : ""}$${change.toFixed(2)} (${changePercent.toFixed(4)}%)`,
		);

		previousPrice = basePrice;
	}, intervalMs);
}

// Calculate position value in collateral
async function getPositionValueInCollateral(
	positionSize: number,
): Promise<number> {
	const { basePrice, collateralPrice } = await market.getPrices();

	const valueUsd = positionSize * basePrice;
	const valueInCollateral = valueUsd / collateralPrice;

	console.log(`Position Size: ${positionSize} BTC`);
	console.log(`Value (USD): $${valueUsd.toLocaleString()}`);
	console.log(
		`Value (Collateral): ${valueInCollateral.toLocaleString()} USDC`,
	);

	return valueInCollateral;
}

// Usage
await getPositionValueInCollateral(2.5); // 2.5 BTC

// Price deviation alert
async function checkPriceDeviation(maxDeviationPercent: number = 0.5) {
	const { basePrice, collateralPrice } = await market.getPrices();

	// Compare with cached
	const baseDeviation =
		Math.abs((basePrice - market.indexPrice) / market.indexPrice) * 100;
	const collateralDeviation =
		Math.abs(
			(collateralPrice - market.collateralPrice) / market.collateralPrice,
		) * 100;

	if (baseDeviation > maxDeviationPercent) {
		console.warn(`⚠️  Base price deviation: ${baseDeviation.toFixed(2)}%`);
	}

	if (collateralDeviation > maxDeviationPercent) {
		console.warn(
			`⚠️  Collateral price deviation: ${collateralDeviation.toFixed(2)}%`,
		);
	}
}

Use Cases:

1. Price Updates: Get latest oracle prices

2. Position Valuation: Calculate current position values

3. Price Monitoring: Track price changes

4. Liquidation Checks: Verify prices for risk calculations

---

timeUntilNextFundingMs

timeUntilNextFundingMs(): number

Calculate milliseconds until the next funding payment.

What This Returns:

Time remaining until next funding event in milliseconds.

Formula:

nextFundingTime - Date.now();

Returns:

• number: Milliseconds until next funding

  • Positive: Time remaining

  • Negative: Funding is overdue (rare)

Example:

// Get time until next funding
const msUntilFunding = market.timeUntilNextFundingMs();

console.log(`Milliseconds until funding: ${msUntilFunding}`);

// Convert to human-readable
const secondsUntil = msUntilFunding / 1000;
const minutesUntil = secondsUntil / 60;
const hoursUntil = minutesUntil / 60;

console.log(`Time until funding:`);
console.log(`  ${secondsUntil.toFixed(0)} seconds`);
console.log(`  ${minutesUntil.toFixed(1)} minutes`);
console.log(`  ${hoursUntil.toFixed(2)} hours`);

// Format as countdown
function formatCountdown(ms: number): string {
	const hours = Math.floor(ms / 3600000);
	const minutes = Math.floor((ms % 3600000) / 60000);
	const seconds = Math.floor((ms % 60000) / 1000);

	return `${hours}h ${minutes}m ${seconds}s`;
}

const countdown = formatCountdown(msUntilFunding);
console.log(`Funding in: ${countdown}`);

// Display next funding time
const nextFundingTime = new Date(Date.now() + msUntilFunding);
console.log(`Next funding: ${nextFundingTime.toLocaleString()}`);

// Countdown timer
function startFundingCountdown() {
	const interval = setInterval(() => {
		const ms = market.timeUntilNextFundingMs();

		if (ms <= 0) {
			console.log("🔔 Funding payment occurred!");
			clearInterval(interval);
			return;
		}

		console.log(`Funding in: ${formatCountdown(ms)}`);
	}, 1000);

	return interval;
}

// Usage
const countdownInterval = startFundingCountdown();
// Stop with: clearInterval(countdownInterval);

// Alert before funding
async function alertBeforeFunding(minutesBefore: number = 5) {
	const msUntilFunding = market.timeUntilNextFundingMs();
	const alertTime = msUntilFunding - minutesBefore * 60000;

	if (alertTime > 0) {
		setTimeout(() => {
			const fundingRate =
				market.indexPrice !== 0
					? market.marketState.premiumTwap / market.indexPrice
					: 0;
			console.log(`⚠️  Funding payment in ${minutesBefore} minutes!`);
			console.log(`Current funding rate: ${fundingRate * 100}%`);
		}, alertTime);
	}
}

// Usage
alertBeforeFunding(5); // Alert 5 minutes before

// Check if funding is imminent
function isFundingImminent(thresholdMinutes: number = 5): boolean {
	const msUntilFunding = market.timeUntilNextFundingMs();
	const thresholdMs = thresholdMinutes * 60000;

	return msUntilFunding <= thresholdMs;
}

if (isFundingImminent(5)) {
	console.log("⚠️  Funding payment coming soon!");
}

Use Cases:

1. Countdown Display: Show time until funding

2. Trading Timing: Plan trades around funding

3. Notifications: Alert users before funding

4. Position Management: Close positions before funding

---

estimatedFundingRate

estimatedFundingRate(): Percentage

Get the SDK's estimatedFundingRate field for this market.

What This Returns:

This accessor exposes the raw estimatedFundingRate value carried in the market snapshot. It can be useful for parity with the API response, but for trading logic and canonical live funding calculations you should derive funding from market.marketState.premiumTwap / market.indexPrice instead.

Returns:

• Percentage (number): Funding rate as a fraction

  • Example: 0.01 = 1%

  • Example: -0.005 = -0.5%

Example:

// Raw field from the API snapshot
const estimatedFundingRate = market.estimatedFundingRate();

// Canonical live funding calculation
const fundingRate =
	market.indexPrice !== 0
		? market.marketState.premiumTwap / market.indexPrice
		: 0;

console.log(`Estimated Funding Field: ${estimatedFundingRate * 100}%`);
console.log(`Funding Rate: ${fundingRate * 100}%`);
console.log(`Funding Rate (bps): ${fundingRate * 10000} bps`);

// Determine who pays
if (fundingRate > 0) {
	console.log("Longs pay shorts");
} else if (fundingRate < 0) {
	console.log("Shorts pay longs");
} else {
	console.log("No funding payment");
}

// Calculate funding payment for position
function calculateFundingPayment(
	positionSize: number,
	isLong: boolean,
): number {
	const rate =
		market.indexPrice !== 0
			? market.marketState.premiumTwap / market.indexPrice
			: 0;
	const positionValue = positionSize * market.indexPrice;

	// Longs pay when rate > 0, receive when rate < 0
	const payment = isLong ? -positionValue * rate : positionValue * rate;

	console.log(`Position: ${positionSize} BTC (${isLong ? "Long" : "Short"})`);
	console.log(`Value: $${positionValue.toLocaleString()}`);
	console.log(`Funding Rate: ${rate * 100}%`);
	console.log(`Payment: ${payment > 0 ? "+" : ""}$${payment.toFixed(2)}`);

	return payment;
}

// Calculate for long position
calculateFundingPayment(2.5, true);

// Calculate for short position
calculateFundingPayment(2.5, false);

// Funding rate thresholds
function getFundingRateStatus(rate: number): string {
	const ratePercent = rate * 100;

	if (ratePercent > 0.1) return "🔴 Very High (Longs pay)";
	if (ratePercent > 0.05) return "🟠 High (Longs pay)";
	if (ratePercent > 0.01) return "🟡 Moderate (Longs pay)";
	if (ratePercent > -0.01) return "🟢 Neutral";
	if (ratePercent > -0.05) return "🟡 Moderate (Shorts pay)";
	if (ratePercent > -0.1) return "🟠 High (Shorts pay)";
	return "🔴 Very High (Shorts pay)";
}

const status = getFundingRateStatus(fundingRate);
console.log(`Funding Status: ${status}`);

// Historical funding rate tracking
class FundingRateTracker {
	private rates: Array<{ timestamp: number; rate: number }> = [];

	record() {
		this.rates.push({
			timestamp: Date.now(),
			rate:
				market.indexPrice !== 0
					? market.marketState.premiumTwap / market.indexPrice
					: 0,
		});
	}

	getAverage(lastN?: number): number {
		const data = lastN ? this.rates.slice(-lastN) : this.rates;
		const sum = data.reduce((s, r) => s + r.rate, 0);
		return sum / data.length;
	}

	getHighLow(): { high: number; low: number } {
		const rates = this.rates.map((r) => r.rate);
		return {
			high: Math.max(...rates),
			low: Math.min(...rates),
		};
	}

	displayStats() {
		const currentRate =
			market.indexPrice !== 0
				? market.marketState.premiumTwap / market.indexPrice
				: 0;
		console.log(`=== Funding Rate Statistics ===`);
		console.log(`Current: ${currentRate * 100}%`);
		console.log(`Average (all): ${this.getAverage() * 100}%`);
		console.log(`Average (last 10): ${this.getAverage(10) * 100}%`);

		const { high, low } = this.getHighLow();
		console.log(`High: ${high * 100}%`);
		console.log(`Low: ${low * 100}%`);
	}
}

// Usage
const tracker = new FundingRateTracker();
setInterval(() => tracker.record(), 3600000); // Record every hour

// Funding arbitrage opportunity
function checkFundingArbitrage(
	threshold: number = 0.05, // 5%
): boolean {
	const rate =
		market.indexPrice !== 0
			? market.marketState.premiumTwap / market.indexPrice
			: 0;

	if (Math.abs(rate) > threshold) {
		const strategy =
			rate > 0
				? "Short perpetual, go long on spot"
				: "Long perpetual, go short on spot";

		console.log(`🎯 Funding Arbitrage Opportunity!`);
		console.log(`Rate: ${rate * 100}%`);
		console.log(`Strategy: ${strategy}`);

		return true;
	}

	return false;
}

Use Cases:

1. Funding Display: Show current funding rate

2. Cost Calculation: Estimate funding costs

3. Trading Strategy: Identify funding arbitrage

4. Position Management: Decide when to close positions

---

Collateral Calculation Methods

calcCollateralUsedForOrder

calcCollateralUsedForOrder(inputs: {
  leverage: number;
  orderData: PerpetualsOrderData;
  indexPrice: number;
  collateralPrice: number;
}): {
  collateral: number;
  collateralUsd: number;
}

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

What This Calculates:

The amount of collateral needed for the unfilled portion of an order, based on:

• Order size (initial - filled)

• Target leverage

• Current prices

• Initial margin requirements

Formula:

remainingSize = initialSize - filledSize;
collateralUsd = remainingSize * indexPrice * (1 / leverage);
collateral = collateralUsd / collateralPrice;

Parameters:

• leverage: number

  • Target leverage (>= 1)

  • Higher leverage = less collateral needed

• orderData: PerpetualsOrderData

  • Order data containing:

    • initialSize: Original order size (bigint, 9 decimals)

    • filledSize: Amount already filled (bigint, 9 decimals)

• indexPrice: number

  • Current index/oracle price of base asset

• collateralPrice: number

  • Current price of collateral asset

Returns:

Object containing:

• collateralUsd: number

  • Required collateral in USD

• collateral: number

  • Required collateral in collateral coin units

Example:

// Calculate collateral for an order
const orderData: PerpetualsOrderData = {
	initialSize: 2000000000n, // 2 BTC
	filledSize: 500000000n, // 0.5 BTC filled
	// ... other fields
};

const result = market.calcCollateralUsedForOrder({
	leverage: 5,
	orderData,
	indexPrice: market.indexPrice,
	collateralPrice: market.collateralPrice,
});

console.log(`Collateral Required:`);
console.log(`  USD: $${result.collateralUsd.toFixed(2)}`);
console.log(`  Collateral: ${result.collateral.toFixed(2)} USDC`);

// Calculate for different leverage levels
function compareCollateralByLeverage(orderData: PerpetualsOrderData) {
	const leverages = [1, 2, 5, 10, 20];

	console.log(`=== Collateral Requirements ===`);
	for (const lev of leverages) {
		const { collateral, collateralUsd } = market.calcCollateralUsedForOrder(
			{
				leverage: lev,
				orderData,
				indexPrice: market.indexPrice,
				collateralPrice: market.collateralPrice,
			},
		);

		console.log(
			`${lev}x: $${collateralUsd.toFixed(2)} (${collateral.toFixed(2)} USDC)`,
		);
	}
}

// Calculate remaining collateral after partial fill
function getRemainingCollateralNeeded(
	initialSize: bigint,
	filledSize: bigint,
	leverage: number,
): number {
	const orderData: PerpetualsOrderData = {
		initialSize,
		filledSize,
	} as PerpetualsOrderData;

	const { collateral } = market.calcCollateralUsedForOrder({
		leverage,
		orderData,
		indexPrice: market.indexPrice,
		collateralPrice: market.collateralPrice,
	});

	const remainingSize =
		Number(initialSize - filledSize) / Casting.Fixed.fixedOneN9;
	const filledPercent = (Number(filledSize) / Number(initialSize)) * 100;

	console.log(`Order Status:`);
	console.log(
		`  Initial: ${Number(initialSize) / Casting.Fixed.fixedOneN9} BTC`,
	);
	console.log(
		`  Filled: ${Number(filledSize) / Casting.Fixed.fixedOneN9} BTC (${filledPercent.toFixed(1)}%)`,
	);
	console.log(`  Remaining: ${remainingSize} BTC`);
	console.log(`  Collateral Needed: ${collateral.toFixed(2)} USDC`);

	return collateral;
}

// Usage
getRemainingCollateralNeeded(
	2000000000n, // 2 BTC
	500000000n, // 0.5 BTC filled
	5, // 5x leverage
);

// Validate sufficient collateral
function validateCollateral(
	orderData: PerpetualsOrderData,
	availableCollateral: number,
	leverage: number,
): { valid: boolean; required: number; available: number; error?: string } {
	const { collateral } = market.calcCollateralUsedForOrder({
		leverage,
		orderData,
		indexPrice: market.indexPrice,
		collateralPrice: market.collateralPrice,
	});

	if (collateral > availableCollateral) {
		return {
			valid: false,
			required: collateral,
			available: availableCollateral,
			error: `Insufficient collateral: need ${collateral.toFixed(2)}, have ${availableCollateral.toFixed(2)}`,
		};
	}

	return {
		valid: true,
		required: collateral,
		available: availableCollateral,
	};
}

// Calculate collateral efficiency
function calculateCollateralEfficiency(
	orderData: PerpetualsOrderData,
	leverage: number,
): number {
	const { collateral, collateralUsd } = market.calcCollateralUsedForOrder({
		leverage,
		orderData,
		indexPrice: market.indexPrice,
		collateralPrice: market.collateralPrice,
	});

	const remainingSize =
		Number(orderData.initialSize - orderData.filledSize) /
		Casting.Fixed.fixedOneN9;
	const positionValue = remainingSize * market.indexPrice;

	const efficiency = positionValue / collateralUsd;

	console.log(`Collateral Efficiency:`);
	console.log(`  Position Value: $${positionValue.toLocaleString()}`);
	console.log(`  Collateral: $${collateralUsd.toFixed(2)}`);
	console.log(`  Efficiency: ${efficiency.toFixed(2)}x`);

	return efficiency;
}

Use Cases:

1. Margin Calculation: Determine collateral requirements

2. Order Validation: Check if user has sufficient collateral

3. Partial Fill Handling: Calculate remaining collateral needed

4. Leverage Planning: Compare collateral across leverage levels

---

Market Parameter Accessors

lotSize

lotSize(): number

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

What This Returns:

The minimum increment for order sizes. All orders must be multiples of the lot size.

Returns:

• number: Lot size in base asset units

Example:

const lotSize = market.lotSize();
console.log(`Lot Size: ${lotSize} BTC`);

// Validate order size
function isValidOrderSize(size: number): boolean {
	const lot = market.lotSize();
	return size % lot === 0;
}

console.log(`Is 1.5 BTC valid? ${isValidOrderSize(1.5)}`);
console.log(`Is 1.3 BTC valid? ${isValidOrderSize(1.3)}`);

// Round to valid lot size
const orderSize = 1.37;
const lots = Math.round(orderSize / market.lotSize());
const validSize = lots * market.lotSize();

console.log(`Requested: ${orderSize} BTC`);
console.log(`Valid: ${validSize} BTC`);

Use Cases:

1. Order Validation: Check if size is valid

2. Size Rounding: Round sizes to valid increments

3. UI Constraints: Set input field step size

---

tickSize

tickSize(): number

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

What This Returns:

The minimum increment for limit prices. All limit prices must be multiples of the tick size.

Returns:

• number: Tick size in quote units (e.g., USD)

Example:

const tickSize = market.tickSize();
console.log(`Tick Size: $${tickSize}`);

// Validate limit price
function isValidPrice(price: number): boolean {
	const tick = market.tickSize();
	return price % tick === 0;
}

console.log(`Is $42000 valid? ${isValidPrice(42000)}`);
console.log(`Is $42000.5 valid? ${isValidPrice(42000.5)}`);

// Round to valid tick
const limitPrice = 42123.45;
const ticks = Math.round(limitPrice / market.tickSize());
const validPrice = ticks * market.tickSize();

console.log(`Requested: $${limitPrice}`);
console.log(`Valid: $${validPrice}`);

Use Cases:

1. Price Validation: Check if price is valid

2. Price Rounding: Round prices to valid ticks

3. UI Constraints: Set price input step size

---

maxLeverage

maxLeverage(): number

Get the maximum theoretical leverage for this market.

Formula:

1 / marginRatioInitial;

Returns:

• number: Maximum leverage

Example:

const maxLev = market.maxLeverage();
console.log(`Max Leverage: ${maxLev}x`);

// Validate leverage input
function validateLeverage(leverage: number): boolean {
	if (leverage < 1) {
		console.error("Leverage must be >= 1");
		return false;
	}

	if (leverage > market.maxLeverage()) {
		console.error(`Leverage exceeds maximum of ${market.maxLeverage()}x`);
		return false;
	}

	return true;
}

console.log(`Is 5x valid? ${validateLeverage(5)}`);
console.log(`Is 25x valid? ${validateLeverage(25)}`);

Use Cases:

1. Leverage Validation: Check if leverage is allowed

2. UI Constraints: Set maximum leverage slider value

3. Risk Warnings: Alert users approaching max leverage

---

initialMarginRatio

initialMarginRatio(): number

Get the initial margin ratio for this market.

What This Is:

The minimum margin required when opening a position, expressed as a fraction.

Formula:

initialMarginRatio = 1 / maxLeverage;

Returns:

• number: Initial margin ratio (fraction)

  • Example: 0.05 = 5% = 20x leverage

Example:

const imr = market.initialMarginRatio();
console.log(`Initial Margin Ratio: ${imr * 100}%`);

// Calculate required margin
const positionValue = 10000; // $10,000 position
const requiredMargin = positionValue * imr;

console.log(`Position: $${positionValue}`);
console.log(`Required Margin: $${requiredMargin}`);

Use Cases:

1. Margin Calculation: Calculate required initial margin

2. Position Sizing: Determine maximum position for capital

3. Risk Display: Show margin requirements to users

---

maintenanceMarginRatio

maintenanceMarginRatio(): number

Get the maintenance margin ratio for this market.

What This Is:

The minimum margin required to keep a position open. Falling below this triggers liquidation.

Returns:

• number: Maintenance margin ratio (fraction)

  • Always less than initial margin ratio

  • Example: 0.03 = 3%

Example:

const mmr = market.maintenanceMarginRatio();
console.log(`Maintenance Margin Ratio: ${mmr * 100}%`);

// Compare with initial margin
const imr = market.initialMarginRatio();
const buffer = imr - mmr;

console.log(`Initial Margin: ${imr * 100}%`);
console.log(`Maintenance Margin: ${mmr * 100}%`);
console.log(`Buffer: ${buffer * 100}%`);

// Check liquidation risk
function checkLiquidationRisk(
	positionValue: number,
	currentMargin: number,
): { safe: boolean; marginRatio: number } {
	const marginRatio = currentMargin / positionValue;
	const mmr = market.maintenanceMarginRatio();

	const safe = marginRatio > mmr;
	const buffer = marginRatio - mmr;

	console.log(`Position Value: $${positionValue}`);
	console.log(`Current Margin: $${currentMargin}`);
	console.log(`Margin Ratio: ${marginRatio * 100}%`);
	console.log(`Maintenance: ${mmr * 100}%`);

	if (safe) {
		console.log(`✓ Safe (${buffer * 100}% buffer)`);
	} else {
		console.log(`⚠️  At risk of liquidation!`);
	}

	return { safe, marginRatio };
}

// Usage
checkLiquidationRisk(10000, 400); // $10k position, $400 margin

Use Cases:

1. Liquidation Monitoring: Check if position is at risk

2. Margin Calls: Alert users when approaching maintenance

3. Risk Display: Show safety buffer to users

---

Rounding & Validation Methods

roundToValidPrice

roundToValidPrice(inputs: {
  price: number;
  floor?: boolean;
  ceil?: boolean;
}): number

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

Rounding Modes:

• floor: true - Round down

• ceil: true - Round up

• Neither - Round to nearest (default)

Parameters:

• price: number

  • Raw price to round

• floor (optional): boolean

  • If true, round down

• ceil (optional): boolean

  • If true, round up

Returns:

• number: Price snapped to valid tick

Example:

// Round to nearest
const price1 = 42123.45;
const rounded1 = market.roundToValidPrice({ price: price1 });
console.log(`${price1} → $${rounded1}`);

// Round down (floor)
const price2 = 42123.45;
const rounded2 = market.roundToValidPrice({ price: price2, floor: true });
console.log(`${price2} (floor) → $${rounded2}`);

// Round up (ceil)
const price3 = 42123.45;
const rounded3 = market.roundToValidPrice({ price: price3, ceil: true });
console.log(`${price3} (ceil) → $${rounded3}`);

// Use for limit orders
function prepareLimitPrice(price: number): number {
	// Always round limit prices down for bids, up for asks
	// to ensure favorable execution
	return market.roundToValidPrice({
		price,
		floor: true, // Conservative for buyers
	});
}

const limitPrice = prepareLimitPrice(42123.67);
console.log(`Limit order at: $${limitPrice}`);

Use Cases:

1. Order Validation: Ensure prices meet exchange requirements

2. UI Input: Round user input to valid prices

3. Slippage Calculation: Adjust limit prices with slippage

---

roundToValidPriceBigInt

roundToValidPriceBigInt(inputs: {
  price: number;
  floor?: boolean;
  ceil?: boolean;
}): bigint

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

What This Returns:

Same as roundToValidPrice but returns a bigint with 9 decimal precision, suitable for on-chain operations.

Parameters:

Same as roundToValidPrice

Returns:

• bigint: Tick-snapped price scaled by 1e9

Example:

const price = 42123.45;
const roundedBigInt = market.roundToValidPriceBigInt({ price });

console.log(`Price (bigint): ${roundedBigInt}`);
console.log(
	`Price (float): ${Number(roundedBigInt) / Casting.Fixed.fixedOneN9}`,
);

// Use in transaction building
function buildLimitOrderTx(price: number) {
	const priceBigInt = market.roundToValidPriceBigInt({ price });

	// Use priceBigInt in transaction
	console.log(`Transaction price: ${priceBigInt}`);
}

Use Cases:

1. Transaction Building: Prepare prices for blockchain

2. Precision Handling: Work with exact on-chain values

3. Order Submission: Format prices for contract calls

---

roundToValidSize

roundToValidSize(inputs: {
  size: number;
  floor?: boolean;
  ceil?: boolean;
}): number

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

Rounding Modes:

• floor: true - Round down

• ceil: true - Round up

• Neither - Round to nearest (default)

Parameters:

• size: number

  • Raw size to round

• floor (optional): boolean

  • If true, round down

• ceil (optional): boolean

  • If true, round up

Returns:

• number: Size snapped to valid lot

Example:

// Round to nearest
const size1 = 1.37;
const rounded1 = market.roundToValidSize({ size: size1 });
console.log(`${size1} BTC → ${rounded1} BTC`);

// Round down (floor)
const size2 = 1.37;
const rounded2 = market.roundToValidSize({ size: size2, floor: true });
console.log(`${size2} BTC (floor) → ${rounded2} BTC`);

// Round up (ceil)
const size3 = 1.37;
const rounded3 = market.roundToValidSize({ size: size3, ceil: true });
console.log(`${size3} BTC (ceil) → ${rounded3} BTC`);

// Validate and round user input
function validateAndRoundSize(userInput: number): number | null {
	if (userInput <= 0) {
		console.error("Size must be positive");
		return null;
	}

	const rounded = market.roundToValidSize({ size: userInput, floor: true });

	if (rounded === 0) {
		console.error(`Size too small (min lot: ${market.lotSize()})`);
		return null;
	}

	if (rounded !== userInput) {
		console.log(`Adjusted size from ${userInput} to ${rounded}`);
	}

	return rounded;
}

// Usage
const validSize = validateAndRoundSize(1.37);
console.log(`Valid size: ${validSize}`);

Use Cases:

1. Order Validation: Ensure sizes meet exchange requirements

2. UI Input: Round user input to valid sizes

3. Max Button: Round max size down for safety

---

roundToValidSizeBigInt

roundToValidSizeBigInt(inputs: {
  size: number;
  floor?: boolean;
  ceil?: boolean;
}): bigint

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

What This Returns:

Same as roundToValidSize but returns a bigint with 9 decimal precision.

Parameters:

Same as roundToValidSize

Returns:

• bigint: Lot-snapped size scaled by 1e9

Example:

const size = 1.37;
const roundedBigInt = market.roundToValidSizeBigInt({ size, floor: true });

console.log(`Size (bigint): ${roundedBigInt}`);
console.log(
	`Size (float): ${Number(roundedBigInt) / Casting.Fixed.fixedOneN9}`,
);

// Use in transaction building
function buildMarketOrderTx(size: number) {
	const sizeBigInt = market.roundToValidSizeBigInt({ size, floor: true });

	// Use sizeBigInt in transaction
	console.log(`Transaction size: ${sizeBigInt}`);
}

Use Cases:

1. Transaction Building: Prepare sizes for blockchain

2. Precision Handling: Work with exact on-chain values

3. Order Submission: Format sizes for contract calls

---

Helper Methods

emptyPosition

emptyPosition(): PerpetualsPosition

Construct an "empty" position object for this market.

What This Returns:

A zeroed-out position object that represents no open position in the market. Useful when:

• An account has no position in a market

• UI/calculations expect a position object

• Initializing position state

Returns:

• PerpetualsPosition: Empty position with:

  • marketId: This market's ID

  • baseAssetAmount: 0 (no position)

  • collateral: 0

  • All other fields zeroed or defaulted

  • cumFundingRateLong/Short: Current market funding rates

Example:

// Get empty position
const emptyPos = market.emptyPosition();

console.log(`=== Empty Position ===`);
console.log(`Market: ${emptyPos.marketId}`);
console.log(`Size: ${emptyPos.baseAssetAmount}`);
console.log(`Collateral: ${emptyPos.collateral}`);
console.log(`PnL: ${emptyPos.unrealizedPnlUsd}`);

// Use as default when no position exists
function getPosition(
	account: PerpetualsAccount,
	marketId: string,
): PerpetualsPosition {
	const position = account.account.positions.find(
		(p) => p.marketId === marketId,
	);

	return position || market.emptyPosition();
}

// Always returns a valid position object
const pos = getPosition(account, market.marketId);
console.log(`Position size: ${pos.baseAssetAmount}`);

// Initialize position tracking
class PositionTracker {
	private position: PerpetualsPosition;

	constructor() {
		this.position = market.emptyPosition();
	}

	updatePosition(newPosition: PerpetualsPosition) {
		this.position = newPosition;
	}

	hasPosition(): boolean {
		return this.position.baseAssetAmount !== 0;
	}

	getPosition(): PerpetualsPosition {
		return this.position;
	}
}

// Usage
const tracker = new PositionTracker();
console.log(`Has position: ${tracker.hasPosition()}`); // false

// UI component that always needs a position
function PositionDisplay() {
	const position = market.emptyPosition(); // Default

	return {
		size: position.baseAssetAmount,
		value: position.baseAssetAmount * market.indexPrice,
		pnl: position.unrealizedPnlUsd,
		leverage: position.leverage,
	};
}

// Compare empty vs actual position
function comparePositions(actualPosition?: PerpetualsPosition) {
	const empty = market.emptyPosition();
	const pos = actualPosition || empty;

	console.log(`Position exists: ${pos !== empty}`);
	console.log(`Has size: ${pos.baseAssetAmount !== 0}`);
	console.log(`Size: ${pos.baseAssetAmount}`);
}

// Funding rate initialization
const emptyPos2 = market.emptyPosition();
console.log(
	`Initial cumulative funding (long): ${emptyPos2.cumFundingRateLong}`,
);
console.log(
	`Initial cumulative funding (short): ${emptyPos2.cumFundingRateShort}`,
);

Use Cases:

1. Default Values: Provide default position when none exists

2. UI Initialization: Initialize position displays

3. State Management: Track position state over time

4. Null Handling: Avoid null checks in position logic

---

Complete Usage Examples

Example 1: Complete Order Placement Flow

import { Aftermath, PerpetualsOrderSide } from "aftermath-ts-sdk";

async function placeOrderFlow() {
	// Initialize SDK
	const afSdk = new Aftermath("MAINNET");
	await afSdk.init();

	const perps = afSdk.Perpetuals();

	// Get market
	const { market } = await perps.getMarket({
		marketId:
			"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
	});

	// 1. Check market conditions
	const fundingRate =
		market.indexPrice !== 0
			? market.marketState.premiumTwap / market.indexPrice
			: 0;
	console.log(`=== Market Check ===`);
	console.log(`Index Price: $${market.indexPrice}`);
	console.log(`Funding Rate: ${fundingRate * 100}%`);
	console.log(
		`Time to Funding: ${market.timeUntilNextFundingMs() / 60000} min`,
	);

	// 2. Get orderbook
	const { orderbook } = await market.getOrderbook();
	console.log(`\nBest Bid: $${orderbook.bids[0]?.price}`);
	console.log(`Best Ask: $${orderbook.asks[0]?.price}`);

	// 3. Calculate max order size
	const accountId = 123n;
	const { maxOrderSize } = await market.getMaxOrderSize({
		accountId,
		side: PerpetualsOrderSide.Bid,
		leverage: 5,
	});

	const maxSize = Number(maxOrderSize) / Casting.Fixed.fixedOneN9;
	console.log(`\nMax Order Size: ${maxSize} BTC`);

	// 4. Round to valid size
	const desiredSize = 1.37;
	const validSize = market.roundToValidSize({
		size: Math.min(desiredSize, maxSize),
		floor: true,
	});

	console.log(`Order Size: ${validSize} BTC`);

	// 5. Preview order
	const sizeBigInt = BigInt(Math.round(validSize * Casting.Fixed.fixedOneN9));
	const preview = await market.getPlaceMarketOrderPreview({
		side: PerpetualsOrderSide.Bid,
		size: sizeBigInt,
		leverage: 5,
		slippageTolerance: 0.01,
	});

	if ("error" in preview) {
		console.error(`Preview failed: ${preview.error}`);
		return;
	}

	console.log(`\n=== Order Preview ===`);
	console.log(`Execution Price: $${preview.executionPrice}`);
	console.log(`Slippage: ${preview.slippage * 100}%`);
	console.log(
		`Filled: ${Number(preview.filledSize) / Casting.Fixed.fixedOneN9} BTC`,
	);

	// 6. Check slippage tolerance
	if (preview.slippage > 0.01) {
		console.warn(`⚠️  Slippage exceeds 1% - consider limit order`);
		return;
	}

	// 7. Place order (using PerpetualsAccount)
	console.log(`\n✓ Ready to place order`);
	// const { tx } = await account.getPlaceMarketOrderTx({...});
	// await wallet.signAndExecuteTransaction({ transaction: tx });
}

Example 2: Market Monitoring Dashboard

class MarketDashboard {
	constructor(private market: PerpetualsMarket) {}

	async displayDashboard() {
		// Current prices
		const { basePrice, collateralPrice } = await this.market.getPrices();

		// 24h stats
		const stats = await this.market.get24hrStats();

		// Orderbook
		const { orderbook } = await this.market.getOrderbook();
		const { midPrice } = await this.market.getOrderbookMidPrice();

		// Funding
		const fundingRate =
			this.market.indexPrice !== 0
				? this.market.marketState.premiumTwap / this.market.indexPrice
				: 0;
		const timeToFunding = this.market.timeUntilNextFundingMs();

		console.log(`
Market Dashboard

Price: $${basePrice.toLocaleString()}
24h Change: ${stats.priceChange24h > 0 ? "+" : ""}${stats.priceChange24h.toFixed(2)}%
24h High: $${stats.high24h.toLocaleString()}
24h Low: $${stats.low24h.toLocaleString()}
24h Volume: $${(stats.volume24h / 1e6).toFixed(2)}M

Best Bid: $${orderbook.bids[0]?.price.toLocaleString()}
Best Ask: $${orderbook.asks[0]?.price.toLocaleString()}
Mid Price: $${midPrice?.toLocaleString()}

Funding Rate: ${(fundingRate * 100).toFixed(4)}%
Next Funding: ${Math.floor(timeToFunding / 60000)}m
Max Leverage: ${this.market.maxLeverage()}x
    `);
	}

	async startMonitoring(intervalMs: number = 30000) {
		await this.displayDashboard();

		setInterval(async () => {
			console.clear();
			await this.displayDashboard();
		}, intervalMs);
	}
}

// Usage
const dashboard = new MarketDashboard(market);
await dashboard.startMonitoring();

Example 3: Risk Management System

class RiskManager {
	constructor(
		private market: PerpetualsMarket,
		private accountId: bigint,
	) {}

	async checkPositionRisk(position: PerpetualsPosition) {
		const warnings: string[] = [];

		// 1. Check margin ratio
		const mmr = this.market.maintenanceMarginRatio();
		if (position.marginRatio < mmr * 1.2) {
			warnings.push(
				`⚠️  Margin ratio ${position.marginRatio * 100}% near maintenance (${mmr * 100}%)`,
			);
		}

		// 2. Check funding rate
		const fundingRate =
			this.market.indexPrice !== 0
				? this.market.marketState.premiumTwap / this.market.indexPrice
				: 0;
		if (Math.abs(fundingRate) > 0.05) {
			const cost = Math.abs(
				position.baseAssetAmount * this.market.indexPrice * fundingRate,
			);
			warnings.push(
				`⚠️  High funding rate: ${fundingRate * 100}% (cost: $${cost.toFixed(2)})`,
			);
		}

		// 3. Check position size vs max
		const { maxOrderSize } = await this.market.getMaxOrderSize({
			accountId: this.accountId,
			side:
				position.baseAssetAmount > 0
					? PerpetualsOrderSide.Bid
					: PerpetualsOrderSide.Ask,
			leverage: position.leverage,
		});

		const maxSize = Number(maxOrderSize) / Casting.Fixed.fixedOneN9;
		if (Math.abs(position.baseAssetAmount) > maxSize * 0.8) {
			warnings.push(
				`⚠️  Position size ${Math.abs(position.baseAssetAmount)} near max ${maxSize}`,
			);
		}

		// 4. Check unrealized PnL
		const pnlPercent =
			(position.unrealizedPnlUsd / position.collateralUsd) * 100;
		if (pnlPercent < -20) {
			warnings.push(
				`⚠️  Large unrealized loss: ${pnlPercent.toFixed(2)}%`,
			);
		}

		return warnings;
	}

	async suggestActions(position: PerpetualsPosition) {
		const warnings = await this.checkPositionRisk(position);

		if (warnings.length === 0) {
			console.log(`✓ Position is healthy`);
			return;
		}

		console.log(`\n=== Risk Warnings ===`);
		warnings.forEach((w) => console.log(w));

		console.log(`\n=== Suggested Actions ===`);

		// Suggest adding collateral
		if (position.marginRatio < this.market.maintenanceMarginRatio() * 1.5) {
			const neededCollateral =
				(position.baseAssetAmount * this.market.indexPrice * 0.1) /
				this.market.collateralPrice;
			console.log(
				`• Add ${neededCollateral.toFixed(2)} collateral to improve margin`,
			);
		}

		// Suggest reducing position
		if (Math.abs(position.baseAssetAmount) > 1) {
			const reduceSize = Math.abs(position.baseAssetAmount) * 0.3;
			console.log(
				`• Consider reducing position by ${reduceSize.toFixed(4)} BTC`,
			);
		}

		// Suggest stop loss
		const stopLossPrice =
			position.baseAssetAmount > 0
				? position.entryPrice * 0.95
				: position.entryPrice * 1.05;
		console.log(`• Set stop loss at $${stopLossPrice.toFixed(2)}`);
	}
}

// Usage
const riskMgr = new RiskManager(market, 123n);
await riskMgr.suggestActions(position);