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

• 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()}`);

---

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(() => {
			console.log(`⚠️  Funding payment in ${minutesBefore} minutes!`);
			console.log(
				`Current funding rate: ${market.estimatedFundingRate() * 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 estimated funding rate for this market.

What This Returns:

The current estimated funding rate as a percentage (fraction). Positive rates mean longs pay shorts; negative rates mean shorts pay longs.

Returns:

• Percentage (number): Funding rate as a fraction

  • Example: 0.01 = 1%

  • Example: -0.005 = -0.5%

Example:

// Get funding rate
const fundingRate = market.estimatedFundingRate();

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.estimatedFundingRate();
	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.estimatedFundingRate(),
		});
	}

	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() {
		console.log(`=== Funding Rate Statistics ===`);
		console.log(`Current: ${market.estimatedFundingRate() * 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.estimatedFundingRate();

	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
	console.log(`=== Market Check ===`);
	console.log(`Index Price: $${market.indexPrice}`);
	console.log(`Funding Rate: ${market.estimatedFundingRate() * 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.estimatedFundingRate();
		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.estimatedFundingRate();
		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);