Perpetuals

Complete API Reference for the Perpetuals Class

Overview

The Perpetuals class is the main entry point for all perpetuals-related operations in the Aftermath Finance SDK. It provides a comprehensive interface for:

• Discovering and querying perpetual markets

• Managing trading accounts and vaults

• Fetching historical data and statistics

• Building transactions for on-chain operations

• Streaming real-time data via WebSocket

• Integrator fee management and collection

This class extends the Caller base class with the "perpetuals" route prefix, meaning all HTTP calls resolve under /perpetuals/... and WebSocket calls under /perpetuals/ws/....

Typical Usage:

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

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

const perps = afSdk.Perpetuals();

---

Constructor

constructor

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

Creates a new Perpetuals client instance.

Parameters:

• 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 used for transaction building

  • When provided, transaction builder methods can derive serialized txKind from Transaction objects

  • Enables the Provider.Transactions().fetchBase64TxKindFromTx() functionality

Remarks:

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

• HTTP calls resolve under /perpetuals/...

• WebSocket calls resolve under /perpetuals/ws/...

• Typically accessed via afSdk.Perpetuals() rather than direct construction

Example:

// Standard usage via Aftermath SDK
const afSdk = new Aftermath("MAINNET");
await afSdk.init();
const perps = afSdk.Perpetuals();

// Direct construction (advanced usage)
const customConfig = {
	network: "MAINNET" as SuiNetwork,
	accessToken: "your-token",
};
const customProvider = new AftermathApi(/* ... */);
const perps = new Perpetuals(customConfig, customProvider);

---

Static Properties

OrderUtils

public static readonly OrderUtils = PerpetualsOrderUtils;

Helper namespace for order-specific utilities such as parsing order IDs and extracting price information.

Available Methods:

• price(orderId: PerpetualsOrderId): PerpetualsOrderPrice - Extract the encoded price from an order ID

• isAsk(orderId: PerpetualsOrderId): boolean - Determine if an order is an ask (sell) order

• Additional order parsing utilities

Example:

const orderId = 12345678901234567890n;

// Extract price from order ID
const orderPrice = Perpetuals.OrderUtils.price(orderId);
console.log(`Encoded price: ${orderPrice}`);

// Check if it's an ask order
const isAsk = Perpetuals.OrderUtils.isAsk(orderId);
console.log(`Is ask order: ${isAsk}`);

// Convert to human-readable price
const price = Perpetuals.orderPriceToPrice({ orderPrice });
console.log(`Actual price: ${price}`);

---

Market Discovery Methods

getAllMarkets

async getAllMarkets(inputs: {
  collateralCoinType: CoinType;
}): Promise<{
  markets: PerpetualsMarket[];
}>

Fetch all perpetual markets for a given collateral coin type.

This method returns wrapped PerpetualsMarket instances, not raw market structs. Each instance provides additional helpers for pricing, margin calculations, and order parsing.

Parameters:

• collateralCoinType: CoinType

  • The coin type used as collateral (e.g., "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC")

  • Must be a fully qualified Move type identifier

  • All returned markets will use this collateral type

Returns:

Object containing:

• markets: PerpetualsMarket[]

  • Array of wrapped market instances

  • Each market contains market parameters, current state, and helper methods

Example:

// Fetch all SUI-collateralized markets
const { markets } = await perps.getAllMarkets({
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
});

console.log(`Found ${markets.length} markets`);

// Iterate through markets
for (const market of markets) {
	console.log(`Market ID: ${market.marketId}`);
	console.log(`Index Price: $${market.indexPrice}`);
	console.log(`Collateral Price: $${market.collateralPrice}`);
	console.log(`Lot Size: ${market.lotSize()}`);
	console.log(`Tick Size: ${market.tickSize()}`);
	console.log(`Max Leverage: ${market.maxLeverage()}x`);
	console.log(`Funding Rate: ${market.estimatedFundingRate() * 100}%`);
	console.log("---");
}

// Find a specific market by some criteria
const btcMarket = markets.find((m) =>
	m.marketData.baseCoinType.includes("BTC"),
);

// Get market with highest volume (requires additional data)
const { marketsStats } = await perps.getMarkets24hrStats({
	marketIds: markets.map((m) => m.marketId),
});

const highestVolumeMarket =
	markets[
		marketsStats.indexOf(
			marketsStats.reduce((max, stat) =>
				stat.volume24h > max.volume24h ? stat : max,
			),
		)
	];

Use Cases:

1. Market Discovery: List all available markets for a collateral type

2. Price Comparison: Compare prices across different markets

3. Market Selection: Let users choose which market to trade

4. Dashboard Display: Show market overview with key metrics

---

getMarket

async getMarket(inputs: {
  marketId: PerpetualsMarketId;
}): Promise<{
  market: PerpetualsMarket;
}>

Fetch a single market by its ID.

Internally calls getMarkets with a single-element array and returns the first entry.

Parameters:

• marketId: PerpetualsMarketId (which is ObjectId)

  • The market (clearing house) object ID on the Sui blockchain

  • This is the unique identifier for the market

  • Format: 32-byte hex string with 0x prefix

Returns:

Object containing:

• market: PerpetualsMarket

  • Single wrapped market instance

  • Contains all market parameters, state, and helper methods

Throws/Edge Cases:

• If the backend returns an empty list for the given marketId, this will still attempt to return markets[0] which would be undefined

• Callers should validate the result to ensure the market exists

Example:

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

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

// Use market parameters
console.log(`Lot Size: ${market.lotSize()}`);
console.log(`Tick Size: ${market.tickSize()}`);
console.log(`Initial Margin Ratio: ${market.initialMarginRatio()}`);
console.log(`Maintenance Margin Ratio: ${market.maintenanceMarginRatio()}`);

// Check funding
const fundingRate = market.estimatedFundingRate();
const timeToFunding = market.timeUntilNextFundingMs();
console.log(`Funding Rate: ${fundingRate * 100}%`);
console.log(`Next funding in: ${timeToFunding / 60000} minutes`);

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

// Validate market exists
if (!market || !market.marketId) {
	console.error("Market not found");
}

Use Cases:

1. Direct Market Access: When you know the exact market ID

2. Deep Linking: Navigate directly to a specific market

3. Market Refresh: Update data for a single market

4. Trading Interface: Display detailed market information

---

getMarkets

async getMarkets(inputs: {
  marketIds: PerpetualsMarketId[];
}): Promise<{
  markets: PerpetualsMarket[];
}>

Fetch multiple markets by their IDs in a single API call.

The API supports returning orderbooks along with market data. This SDK currently constructs PerpetualsMarket instances from the returned marketDatas[].market field.

Parameters:

• marketIds: PerpetualsMarketId[]

  • Array of market object IDs to fetch

  • Can include any number of market IDs

  • Order is preserved in the response

Returns:

Object containing:

• markets: PerpetualsMarket[]

  • Array of wrapped market instances

  • Returned in the same order as the input marketIds array

  • Each element corresponds to the market ID at the same index

Example:

// Fetch multiple specific markets
const marketIds = [
	"0x1234...abcd", // BTC market
	"0x5678...ef01", // ETH market
	"0x9abc...2345", // SUI market
];

const { markets } = await perps.getMarkets({
	marketIds,
});

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

// Process markets in order
markets.forEach((market, index) => {
	console.log(`Market ${index + 1}:`);
	console.log(`  ID: ${market.marketId}`);
	console.log(`  Index Price: $${market.indexPrice}`);
	console.log(`  Max Leverage: ${market.maxLeverage()}x`);
});

// Create a map for easy lookup
const marketMap = new Map(markets.map((m) => [m.marketId, m]));

// Access specific market from map
const btcMarket = marketMap.get(marketIds[0]);
if (btcMarket) {
	console.log(`BTC price: $${btcMarket.indexPrice}`);
}

// Batch process market data
const allPrices = markets.map((m) => ({
	marketId: m.marketId,
	indexPrice: m.indexPrice,
	collateralPrice: m.collateralPrice,
}));

// Fetch 24h stats for all markets
const stats = await perps.getMarkets24hrStats({
	marketIds: markets.map((m) => m.marketId),
});

// Combine market data with stats
const marketOverview = markets.map((market, i) => ({
	market,
	stats: stats.marketsStats[i],
}));

Use Cases:

1. Batch Fetching: Efficiently fetch multiple markets at once

2. Multi-Market Display: Show data for several markets simultaneously

3. Comparison Tools: Compare metrics across different markets

4. Portfolio View: Display all markets where user has positions

---

Vault Discovery Methods

getAllVaults

async getAllVaults(): Promise<{
  vaults: PerpetualsVault[];
}>

Fetch all vaults on the current network.

What are Vaults? Vaults are managed accounts that accept user deposits (LP tokens), trade across multiple markets, and support withdrawals via a request flow. LPs deposit collateral and receive LP coins representing their share of the vault. The vault manager (curator) trades on behalf of LPs and may charge a performance fee.

Parameters:

None - fetches all vaults regardless of collateral type or status.

Returns:

Object containing:

• vaults: PerpetualsVault[]

  • Array of all vaults on the network

  • Each vault instance provides access to vault parameters, trading account, and transaction builders

Example:

// Fetch all vaults
const { vaults } = await perps.getAllVaults();

console.log(`Total vaults: ${vaults.length}`);

// Display vault information
for (const vault of vaults) {
	const vaultObj = vault.vaultObject;

	console.log(`\nVault: ${vaultObj.objectId}`);
	console.log(`Performance Fee: ${vaultObj.performanceFeePercentage * 100}%`);
	console.log(
		`Lock Period: ${Number(vaultObj.lockPeriodMs) / 86400000} days`,
	);
	console.log(
		`Force Withdraw Delay: ${Number(vaultObj.forceWithdrawDelayMs) / 3600000} hours`,
	);
	console.log(`Collateral Type: ${vaultObj.collateralCoinType}`);
	console.log(`Total LP Supply: ${vaultObj.lpCoinSupply}`);
}

// Filter vaults by criteria
const suiVaults = vaults.filter(
	(v) =>
		v.vaultObject.collateralCoinType ===
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
);

console.log(`\nSUI collateral vaults: ${suiVaults.length}`);

// Find vaults with lowest fees
const lowFeeVaults = vaults
	.filter((v) => v.vaultObject.performanceFeePercentage <= 0.1) // 10% or less
	.sort(
		(a, b) =>
			a.vaultObject.performanceFeePercentage -
			b.vaultObject.performanceFeePercentage,
	);

console.log(`\nLow fee vaults (≤10%):`);
lowFeeVaults.forEach((v) => {
	console.log(
		`  ${v.vaultObject.objectId}: ${v.vaultObject.performanceFeePercentage * 100}%`,
	);
});

// Get LP coin prices for all vaults
const lpPrices = await perps.getLpCoinPrices({
	vaultIds: vaults.map((v) => v.vaultObject.objectId),
});

// Display vault performance
vaults.forEach((vault, index) => {
	const price = lpPrices.lpCoinPrices[index];
	console.log(
		`Vault ${index + 1} LP Price: ${price.priceInCollateral} collateral per LP token`,
	);
});

// Find best performing vault (highest LP price growth)
// Note: Would need historical data to calculate actual performance

Use Cases:

1. Vault Discovery: Browse all available vaults

2. Investment Research: Compare vault strategies and fees

3. LP Dashboard: Display vault metrics for liquidity providers

4. Curator Analytics: Analyze vault ecosystem

---

getVault

async getVault(inputs: {
  vaultId: ObjectId;
}): Promise<{
  vault: PerpetualsVault;
}>

Fetch a single vault by its object ID.

Internally calls getVaults with a single-element array and returns the first entry.

Parameters:

• vaultId: ObjectId

  • The vault's unique, onchain identifier

  • Format: 32-byte hex string with 0x prefix

Returns:

Object containing:

• vault: PerpetualsVault

  • Single wrapped vault instance

  • Provides access to vault configuration, trading account, and transaction builders

Example:

// Fetch a specific vault (note the parameter name)
const { vault } = await perps.getVault({
	marketId: "0xabcd...ef01", // This is actually a vault ID
});

// Access vault properties
const vaultObj = vault.vaultObject;
console.log(`Vault ID: ${vaultObj.objectId}`);
console.log(`Performance Fee: ${vaultObj.performanceFeePercentage * 100}%`);
console.log(`Lock Period: ${Number(vaultObj.lockPeriodMs) / 86400000} days`);
console.log(`Collateral Type: ${vaultObj.collateralCoinType}`);

// Get vault's trading account
const vaultAccount = await vault.getVaultAccount({});
console.log(`Vault has ${vaultAccount.account.positions.length} positions`);

// Check vault positions
for (const position of vaultAccount.account.positions) {
	console.log(`Market: ${position.marketId}`);
	console.log(`Size: ${position.baseAssetAmount}`);
	console.log(`Unrealized PnL: $${position.unrealizedPnlUsd}`);
}

// Get LP coin price
const { lpCoinPrices } = await perps.getLpCoinPrices({
	vaultIds: [vaultObj.objectId],
});
console.log(`LP Coin Price: ${lpCoinPrices[0].priceInCollateral}`);

// Check pending withdrawal requests
const { withdrawRequests } = await vault.getWithdrawRequests({});
console.log(`Pending withdrawals: ${withdrawRequests.length}`);

Use Cases:

1. Direct Vault Access: When you know the exact vault ID

2. Vault Detail Page: Display comprehensive vault information

3. LP Portfolio: Show vault details for deposited vaults

4. Curator Dashboard: Manage a specific vault

---

getVaults

async getVaults(inputs: {
  vaultIds: ObjectId[];
}): Promise<{
  vaults: PerpetualsVault[];
}>

Fetch multiple vaults by their IDs in a single API call.

Parameters:

• vaultIds: ObjectId[]

  • Unbounded array of vault object IDs to fetch

  • Order is preserved in the response

Returns:

Object containing:

• vaults: PerpetualsVault[]

  • Array of wrapped vault instances, returned in the same order as input vaultIds

Example:

// Fetch multiple vaults
const vaultIds = ["0xaaaa...1111", "0xbbbb...2222", "0xcccc...3333"];

const { vaults } = await perps.getVaults({
	vaultIds,
});

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

// Process vaults
vaults.forEach((vault, index) => {
	const vaultObj = vault.vaultObject;
	console.log(`\nVault ${index + 1}:`);
	console.log(`  ID: ${vaultObj.objectId}`);
	console.log(
		`  Performance Fee: ${vaultObj.performanceFeePercentage * 100}%`,
	);
	console.log(`  LP Supply: ${vaultObj.lpCoinSupply}`);
});

// Get LP prices for all vaults
const { lpCoinPrices } = await perps.getLpCoinPrices({
	vaultIds,
});

// Combine vault data with prices
const vaultOverview = vaults.map((vault, i) => ({
	vault,
	lpPrice: lpCoinPrices[i].priceInCollateral,
	totalValue:
		Number(vault.vaultObject.lpCoinSupply) *
		lpCoinPrices[i].priceInCollateral,
}));

// Sort by total value
vaultOverview.sort((a, b) => b.totalValue - a.totalValue);

console.log(`\nVaults by Total Value:`);
vaultOverview.forEach((item, i) => {
	console.log(
		`${i + 1}. ${item.vault.vaultObject.objectId}: $${item.totalValue.toFixed(2)}`,
	);
});

// Get trading accounts for all vaults
const vaultAccounts = await Promise.all(
	vaults.map((vault) => vault.getVaultAccount({})),
);

// Analyze vault positions
vaultAccounts.forEach((account, index) => {
	console.log(`\nVault ${index + 1} Positions:`);
	account.account.positions.forEach((pos) => {
		console.log(
			`  ${pos.marketId}: ${pos.baseAssetAmount} (PnL: $${pos.unrealizedPnlUsd})`,
		);
	});
});

Use Cases:

1. Batch Vault Fetching: Efficiently fetch multiple vaults

2. Portfolio Management: Display all vaults where user has deposits

3. Comparison Tools: Compare multiple vault strategies

4. Analytics Dashboard: Aggregate vault metrics

---

Account Management Methods

getAccount

async getAccount(inputs: {
  accountCap: PerpetualsAccountCap | PerpetualsPartialVaultCap;
  marketIds?: PerpetualsMarketId[];
}): Promise<{
  account: PerpetualsAccount;
}>

Convenience helper to fetch a single account (positions + account object) from an account cap.

What is an Account Cap? An account cap is an owned-object that represents control over a perpetuals account. It can be:

• PerpetualsAccountCap: Direct ownership of a personal trading account

• PerpetualsPartialVaultCap: Derived from a vault cap, representing the vault's trading account

Internally calls getAccounts with a single-element array and returns the first entry.

Parameters:

• accountCap: PerpetualsAccountCap | PerpetualsPartialVaultCap

  • Account cap or partial vault cap object to derive account metadata from

  • Contains: accountId, collateralCoinType, accountObjectId

  • Obtained from getOwnedAccountCaps() or vault operations

• marketIds (optional): PerpetualsMarketId[]

  • List of market IDs to filter positions by

  • If provided, only positions in these markets are returned

  • If omitted, all positions are returned

Returns:

Object containing:

• account: PerpetualsAccount

  • Wrapped account instance with:

    • Account snapshot (positions, balances, equity)

    • Ownership/cap metadata

    • Transaction builder methods

    • Helper functions

Example:

// Step 1: Get owned account caps
const { accounts: accountCaps } = await perps.getOwnedAccountCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
});

console.log(`Found ${accountCaps.length} account caps`);

if (accountCaps.length === 0) {
	console.log("No accounts found. Create one first.");
	// Create account...
}

// Step 2: Fetch full account data
const { account } = await perps.getAccount({
	accountCap: accountCaps[0],
});

// Access account information
console.log(`Account ID: ${account.accountId()}`);
console.log(`Owner: ${account.ownerAddress()}`);
console.log(`Available Collateral: ${account.collateral()}`);
console.log(`Total Positions: ${account.account.positions.length}`);
console.log(`Total Equity: ${account.account.totalEquity}`);

// View positions
for (const position of account.account.positions) {
	console.log(`\nPosition in ${position.marketId}:`);
	console.log(`  Size: ${position.baseAssetAmount}`);
	console.log(`  Entry Price: $${position.entryPrice}`);
	console.log(`  Leverage: ${position.leverage}x`);
	console.log(`  Unrealized PnL: $${position.unrealizedPnlUsd}`);
	console.log(`  Liquidation Price: $${position.liquidationPrice}`);
	console.log(`  Margin Ratio: ${position.marginRatio}`);
}

// Filter positions by specific markets
const { account: filteredAccount } = await perps.getAccount({
	accountCap: accountCaps[0],
	marketIds: ["0x1234...abcd", "0x5678...ef01"],
});

console.log(`Filtered positions: ${filteredAccount.account.positions.length}`);

// Use account for trading
const { tx } = await account.getPlaceMarketOrderTx({
	marketId: "0x1234...abcd",
	side: PerpetualsOrderSide.Bid,
	size: 1000000000n,
	collateralChange: 10,
	reduceOnly: false,
});

Use Cases:

1. Account Dashboard: Display user's account overview

2. Trading Interface: Access account for placing orders

3. Portfolio Management: View all positions and balances

4. Position Monitoring: Check margin ratios and PnL

---

getAccounts

async getAccounts(inputs: {
  accountCaps: (PerpetualsAccountCap | PerpetualsPartialVaultCap)[];
  marketIds?: PerpetualsMarketId[];
}): Promise<{
  accounts: PerpetualsAccount[];
}>

Fetch one or more accounts (positions + account objects) from account caps.

How it Works:

1. Calls getAccountObjects() to fetch raw account data by account IDs

2. Locally pairs returned account objects with input accountCaps

3. Constructs PerpetualsAccount instances wrapping both data and metadata

The returned PerpetualsAccount instances encapsulate:

• Account snapshot (positions, balances, equity)

• Ownership/cap metadata (accountId, collateral type, vaultId)

• Transaction builder methods

• Helper functions

Parameters:

• accountCaps: (PerpetualsAccountCap | PerpetualsPartialVaultCap)[]

  • Array of account caps or partial vault cap objects

  • Each cap contains ownership and identification data

  • Can mix direct account caps and vault caps

• marketIds (optional): PerpetualsMarketId[]

  • List of market IDs to filter positions by

  • Applies to all accounts in the request

  • Useful for focused portfolio views

Returns:

Object containing:

• accounts: PerpetualsAccount[]

  • Array of wrapped account instances

  • Returned in the same order as input accountCaps

  • Each element corresponds to the cap at the same index

Example:

// Fetch all account caps for a wallet
const { accounts: accountCaps } = await perps.getOwnedAccountCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinTypes: [
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	],
});

console.log(`Found ${accountCaps.length} accounts`);

// Fetch full account data for all caps
const { accounts } = await perps.getAccounts({
	accountCaps,
});

// Process all accounts
accounts.forEach((account, index) => {
	console.log(`\nAccount ${index + 1}:`);
	console.log(`  ID: ${account.accountId()}`);
	console.log(`  Collateral: ${account.collateral()}`);
	console.log(`  Equity: ${account.account.totalEquity}`);
	console.log(`  Positions: ${account.account.positions.length}`);

	// Show positions
	account.account.positions.forEach((pos) => {
		console.log(
			`    - ${pos.marketId}: ${pos.baseAssetAmount} (PnL: $${pos.unrealizedPnlUsd})`,
		);
	});
});

// Filter by specific markets across all accounts
const btcEthMarkets = ["0x1234...btc", "0x5678...eth"];
const { accounts: filteredAccounts } = await perps.getAccounts({
	accountCaps,
	marketIds: btcEthMarkets,
});

console.log(`\nBTC/ETH Positions Across All Accounts:`);
filteredAccounts.forEach((account) => {
	if (account.account.positions.length > 0) {
		console.log(`Account ${account.accountId()}:`);
		account.account.positions.forEach((pos) => {
			console.log(`  ${pos.marketId}: ${pos.baseAssetAmount}`);
		});
	}
});

// Calculate total portfolio value
const totalEquity = accounts.reduce(
	(sum, account) => sum + account.account.totalEquity,
	0,
);
console.log(`\nTotal Portfolio Equity: $${totalEquity.toFixed(2)}`);

// Find account with highest equity
const richestAccount = accounts.reduce((max, account) =>
	account.account.totalEquity > max.account.totalEquity ? account : max,
);
console.log(`Highest equity account: ${richestAccount.accountId()}`);

// Empty case handling
if (accountCaps.length === 0) {
	console.log("No account caps provided");
	const { accounts: emptyAccounts } = await perps.getAccounts({
		accountCaps: [],
	});
	console.log(`Empty result: ${emptyAccounts.length} accounts`); // 0
}

Use Cases:

1. Multi-Account Dashboard: Display all user accounts

2. Portfolio Aggregation: Calculate total portfolio metrics

3. Account Comparison: Compare performance across accounts

4. Bulk Operations: Prepare multiple accounts for batch processing

---

getAccountObjects

async getAccountObjects(
  inputs: ApiPerpetualsAccountPositionsBody
): Promise<ApiPerpetualsAccountPositionsResponse>

Fetch raw account objects (including positions) for one or more account IDs. This is the lower-level primitive used by getAccounts.

Difference from getAccounts:

• getAccountObjects: Takes account IDs, returns raw data structures

• getAccounts: Takes account caps, returns wrapped PerpetualsAccount instances

When to use:

• When you only have account IDs (not caps)

• When you need raw data without the wrapper layer

• For custom processing or integration

Parameters:

• accountIds: PerpetualsAccountId[]

  • List of numeric account IDs to query (bigint values)

  • Each ID uniquely identifies an account

  • Example: [123n, 456n, 789n]

• marketIds (optional): PerpetualsMarketId[]

  • List of market IDs to filter positions by

  • If provided, only positions in these markets are included

  • Applies to all accounts in the request

Returns:

ApiPerpetualsAccountPositionsResponse containing:

• accounts: PerpetualsAccountObject[]

  • Array of raw account objects

  • Each object contains:

    • accountId: The account ID

    • positions: Array of position data

    • availableCollateral: Free collateral amount

    • totalEquity: Total account equity

    • Other account state fields

Edge Cases:

• If accountIds is empty, returns { accounts: [] } without making an API call

Example:

// Fetch raw account objects by ID
const accountIds = [123n, 456n, 789n];

const response = await perps.getAccountObjects({
	accountIds,
});

console.log(`Fetched ${response.accounts.length} account objects`);

// Process raw account data
for (const accountObj of response.accounts) {
	console.log(`\nAccount ID: ${accountObj.accountId}`);
	console.log(`Available Collateral: ${accountObj.availableCollateral}`);
	console.log(`Total Equity: ${accountObj.totalEquity}`);
	console.log(`Positions: ${accountObj.positions.length}`);

	// Access positions directly
	for (const position of accountObj.positions) {
		console.log(`  Market: ${position.marketId}`);
		console.log(`  Size: ${position.baseAssetAmount}`);
		console.log(`  PnL: $${position.unrealizedPnlUsd}`);
	}
}

// Filter by markets
const btcMarket = "0x1234...btc";
const filteredResponse = await perps.getAccountObjects({
	accountIds,
	marketIds: [btcMarket],
});

console.log(
	`\nBTC positions across ${filteredResponse.accounts.length} accounts:`,
);
for (const accountObj of filteredResponse.accounts) {
	if (accountObj.positions.length > 0) {
		const btcPosition = accountObj.positions[0];
		console.log(
			`Account ${accountObj.accountId}: ${btcPosition.baseAssetAmount} BTC`,
		);
	}
}

// Empty case
const emptyResponse = await perps.getAccountObjects({
	accountIds: [],
	marketIds: undefined,
});
console.log(`Empty request: ${emptyResponse.accounts.length} accounts`); // 0

// Custom processing example: Calculate total collateral across accounts
const totalCollateral = response.accounts.reduce(
	(sum, account) => sum + account.availableCollateral,
	0,
);
console.log(`Total available collateral: ${totalCollateral}`);

// Find accounts with negative PnL
const accountsInLoss = response.accounts.filter((account) =>
	account.positions.some((pos) => pos.unrealizedPnlUsd < 0),
);
console.log(`Accounts with losses: ${accountsInLoss.length}`);

Use Cases:

1. Low-Level Data Access: When you need raw account data

2. Custom Integrations: Building custom account wrappers

3. Analytics: Processing account data for reports

4. Bulk Queries: Efficiently fetch many accounts by ID

---

Ownership Query Methods

getOwnedAccountCaps

async getOwnedAccountCaps(
  inputs: ApiPerpetualsOwnedAccountCapsBody
): Promise<ApiPerpetualsOwnedAccountCapsResponse>

Fetch all account caps (perpetuals accounts) owned by a wallet, optionally filtered by collateral coin types.

What are Account Caps? Account caps are ownership objects that represent control over perpetuals trading accounts. They contain:

• Account ID (numeric identifier)

• Account Object ID (on-chain object)

• Collateral coin type

• Owner wallet address

Returned values are Account Caps, not a snapshot of the full account. To fetch account positions and balances, use getAccount() or getAccounts().

Parameters:

• walletAddress: SuiAddress

  • Owner wallet address to query

  • Must be a valid Sui address (32-byte hex with 0x prefix)

  • Returns caps owned by this address

• collateralCoinTypes (optional): CoinType[]

  • Optional list of collateral coin types to filter by

  • Only returns caps for accounts using these collateral types

  • Example: ["0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC", "0x...::usdc::USDC"]

  • If omitted, returns caps for all collateral types

Returns:

ApiPerpetualsOwnedAccountCapsResponse containing:

• accounts: PerpetualsAccountCap[]

  • Array of account cap objects

  • Each cap contains:

    • objectId: Cap object ID

    • accountId: Numeric account ID

    • accountObjectId: Account object ID

    • collateralCoinType: Collateral type

    • walletAddress: Owner address

Example:

// Fetch all account caps for a wallet
const { accounts } = await perps.getOwnedAccountCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
});

console.log(`Found ${accounts.length} account caps`);

if (accounts.length === 0) {
	console.log("No accounts found. User needs to create an account first.");
}

// Display account caps
accounts.forEach((cap, index) => {
	console.log(`\nAccount ${index + 1}:`);
	console.log(`  Cap Object ID: ${cap.objectId}`);
	console.log(`  Account ID: ${cap.accountId}`);
	console.log(`  Account Object ID: ${cap.accountObjectId}`);
	console.log(`  Collateral Type: ${cap.collateralCoinType}`);
	console.log(`  Owner: ${cap.walletAddress}`);
});

// Filter by collateral type
const { accounts: suiAccounts } = await perps.getOwnedAccountCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinTypes: [
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	],
});

console.log(`\nSUI collateral accounts: ${suiAccounts.length}`);

// Multiple collateral types
const { accounts: multiCollateralAccounts } = await perps.getOwnedAccountCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinTypes: [
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC", // USDC
		"0x2::sui::SUI",
	],
});

console.log(`Multi-collateral accounts: ${multiCollateralAccounts.length}`);

// Use caps to fetch full account data
if (accounts.length > 0) {
	const { account } = await perps.getAccount({
		accountCap: accounts[0],
	});

	console.log(`\nFirst account details:`);
	console.log(`  Collateral: ${account.collateral()}`);
	console.log(`  Positions: ${account.account.positions.length}`);
}

// Group caps by collateral type
const capsByCollateral = accounts.reduce(
	(groups, cap) => {
		const type = cap.collateralCoinType;
		if (!groups[type]) groups[type] = [];
		groups[type].push(cap);
		return groups;
	},
	{} as Record<string, typeof accounts>,
);

console.log(`\nAccounts by collateral type:`);
for (const [collateral, caps] of Object.entries(capsByCollateral)) {
	console.log(`  ${collateral}: ${caps.length} accounts`);
}

Use Cases:

1. Account Discovery: Find all accounts owned by a user

2. Wallet Integration: List user's trading accounts

3. Multi-Account Management: Display account switcher

4. Onboarding: Check if user has an account before trading

---

getOwnedVaultCaps

async getOwnedVaultCaps(
  inputs: ApiPerpetualsOwnedVaultCapsBody
): Promise<ApiPerpetualsOwnedVaultCapsResponse>

Fetch all vault caps owned by a wallet.

What are Vault Caps? Vault caps represent ownership/administrative authority over a vault. Holders of a vault cap can:

• Update vault parameters (fees, lock periods)

• Process user withdrawals

• Withdraw performance fees

• Manage vault positions

Parameters:

• walletAddress: SuiAddress

  • Owner wallet address to query

  • Must be a valid Sui address

  • Returns vault caps owned by this address

Returns:

ApiPerpetualsOwnedVaultCapsResponse containing:

• vaultCaps: PerpetualsVaultCap[]

  • Array of vault cap objects

  • Each cap contains:

    • objectId: Cap object ID

    • vaultId: Vault object ID

    • accountId: Vault's trading account ID

    • accountObjectId: Account object ID

    • collateralCoinType: Vault's collateral type

    • ownerAddress: Vault owner address

Example:

// Fetch all vault caps for a wallet
const response = await perps.getOwnedVaultCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
});

console.log(`Found ${response.vaultCaps.length} vault caps`);

if (response.vaultCaps.length === 0) {
	console.log("User doesn't own any vaults");
}

// Display vault caps
for (const cap of response.vaultCaps) {
	console.log(`\nVault Cap:`);
	console.log(`  Cap Object ID: ${cap.objectId}`);
	console.log(`  Vault ID: ${cap.vaultId}`);
	console.log(`  Account ID: ${cap.accountId}`);
	console.log(`  Collateral Type: ${cap.collateralCoinType}`);
	console.log(`  Owner: ${cap.ownerAddress}`);
}

// Fetch full vault data for each cap
const vaults = await Promise.all(
	response.vaultCaps.map(
		(cap) => perps.getVault({ marketId: cap.vaultId }), // Note: marketId parameter
	),
);

// Display vault details
vaults.forEach((result, index) => {
	const vault = result.vault;
	const vaultObj = vault.vaultObject;

	console.log(`\nVault ${index + 1}:`);
	console.log(`  ID: ${vaultObj.objectId}`);
	console.log(
		`  Performance Fee: ${vaultObj.performanceFeePercentage * 100}%`,
	);
	console.log(
		`  Lock Period: ${Number(vaultObj.lockPeriodMs) / 86400000} days`,
	);
	console.log(`  LP Supply: ${vaultObj.lpCoinSupply}`);
});

// Get vault trading accounts
for (const cap of response.vaultCaps) {
	const { vault } = await perps.getVault({ marketId: cap.vaultId });
	const vaultAccount = await vault.getVaultAccount({ vaultCapData: cap });

	console.log(`\nVault ${cap.vaultId} Trading Account:`);
	console.log(`  Collateral: ${vaultAccount.collateral()}`);
	console.log(`  Equity: ${vaultAccount.account.totalEquity}`);
	console.log(`  Positions: ${vaultAccount.account.positions.length}`);

	// Show positions
	vaultAccount.account.positions.forEach((pos) => {
		console.log(
			`    ${pos.marketId}: ${pos.baseAssetAmount} (PnL: $${pos.unrealizedPnlUsd})`,
		);
	});
}

// Calculate total managed assets
let totalManagedValue = 0;
for (const cap of response.vaultCaps) {
	const { vault } = await perps.getVault({ marketId: cap.vaultId });
	const vaultAccount = await vault.getVaultAccount({ vaultCapData: cap });
	totalManagedValue += vaultAccount.account.totalEquity;
}

console.log(`\nTotal Managed Assets: $${totalManagedValue.toFixed(2)}`);

// Check if user can manage vaults (has any caps)
const canManageVaults = response.vaultCaps.length > 0;
console.log(`Can manage vaults: ${canManageVaults}`);

Use Cases:

1. Vault Management: Find vaults owned/managed by a curator

2. Curator Dashboard: Display all managed vaults

3. Administrative Access: Verify vault ownership before operations

4. Portfolio Management: Track performance across managed vaults

---

getOwnedVaultWithdrawRequests

async getOwnedVaultWithdrawRequests(
  inputs: ApiPerpetualsVaultOwnedWithdrawRequestsBody
): Promise<ApiPerpetualsVaultOwnedWithdrawRequestsResponse>

Fetch all pending vault withdrawal requests created by a given wallet.

What are Withdrawal Requests? When LPs want to exit a vault, they create a withdrawal request. These requests:

• Are subject to lock periods (preventing immediate withdrawal)

• May be processed by the vault owner in batches

• Can be cancelled before processing

• Have slippage protection (minimum collateral out)

Parameters:

• walletAddress: SuiAddress

  • Wallet address that created the withdrawal requests

  • Returns all pending requests for this address

  • Must be a valid Sui address

Returns:

ApiPerpetualsVaultOwnedWithdrawRequestsResponse containing:

• withdrawRequests: PerpetualsVaultWithdrawRequest[]

  • Array of pending withdrawal request objects

  • Each request contains:

    • objectId: Request object ID

    • vaultId: Vault being withdrawn from

    • lpCoinAmount: Amount of LP coins to burn

    • minCollateralAmountOut: Minimum collateral to receive

    • createdAt: Timestamp when request was created

    • userAddress: User who created the request

Example:

// Fetch all withdrawal requests for a user
const response = await perps.getOwnedVaultWithdrawRequests({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
});

console.log(
	`Found ${response.withdrawRequests.length} pending withdrawal requests`,
);

if (response.withdrawRequests.length === 0) {
	console.log("No pending withdrawal requests");
}

// Display withdrawal requests
for (const request of response.withdrawRequests) {
	console.log(`\nWithdrawal Request:`);
	console.log(`  Request ID: ${request.objectId}`);
	console.log(`  Vault ID: ${request.vaultId}`);
	console.log(`  LP Coins: ${request.lpCoinAmount}`);
	console.log(`  Min Collateral Out: ${request.minCollateralAmountOut}`);
	console.log(`  Created: ${new Date(request.createdAt).toLocaleString()}`);
	console.log(`  User: ${request.userAddress}`);
}

// Group requests by vault
const requestsByVault = response.withdrawRequests.reduce(
	(groups, req) => {
		if (!groups[req.vaultId]) groups[req.vaultId] = [];
		groups[req.vaultId].push(req);
		return groups;
	},
	{} as Record<string, typeof response.withdrawRequests>,
);

console.log(`\nRequests by vault:`);
for (const [vaultId, requests] of Object.entries(requestsByVault)) {
	const totalLpCoins = requests.reduce(
		(sum, req) => sum + Number(req.lpCoinAmount),
		0,
	);
	console.log(`  Vault ${vaultId}:`);
	console.log(`    ${requests.length} requests`);
	console.log(`    ${totalLpCoins} total LP coins`);
}

// Calculate expected collateral for each request
const { lpCoinPrices } = await perps.getLpCoinPrices({
	vaultIds: [...new Set(response.withdrawRequests.map((r) => r.vaultId))],
});

const priceMap = new Map(
	lpCoinPrices.map((price, i) => [
		response.withdrawRequests[i].vaultId,
		price.priceInCollateral,
	]),
);

console.log(`\nExpected Collateral Output:`);
for (const request of response.withdrawRequests) {
	const lpPrice = priceMap.get(request.vaultId);
	if (lpPrice) {
		const expectedCollateral = Number(request.lpCoinAmount) * lpPrice;
		const slippage =
			((expectedCollateral - Number(request.minCollateralAmountOut)) /
				expectedCollateral) *
			100;

		console.log(`  Request ${request.objectId}:`);
		console.log(
			`    Expected: ${expectedCollateral.toFixed(2)} collateral`,
		);
		console.log(
			`    Minimum: ${request.minCollateralAmountOut} collateral`,
		);
		console.log(`    Slippage tolerance: ${slippage.toFixed(2)}%`);
	}
}

// Find requests ready to process (past lock period)
const now = Date.now();
const { vaults } = await perps.getVaults({
	vaultIds: [...new Set(response.withdrawRequests.map((r) => r.vaultId))],
});

const readyRequests = response.withdrawRequests.filter((request) => {
	const vault = vaults.find(
		(v) => v.vaultObject.objectId === request.vaultId,
	);
	if (!vault) return false;

	const lockPeriod = Number(vault.vaultObject.lockPeriodMs);
	const timeElapsed = now - request.createdAt;

	return timeElapsed >= lockPeriod;
});

console.log(`\nRequests ready to process: ${readyRequests.length}`);

// User actions on requests
if (response.withdrawRequests.length > 0) {
	const firstRequest = response.withdrawRequests[0];
	const { vault } = await perps.getVault({ marketId: firstRequest.vaultId });

	// Option 1: Update slippage
	const { tx: updateTx } = await vault.getUpdateWithdrawRequestSlippageTx({
		minCollateralAmountOut:
			(BigInt(firstRequest.minCollateralAmountOut) * 95n) / 100n, // 5% more tolerance
	});

	// Option 2: Cancel request
	const { tx: cancelTx } = await vault.getCancelWithdrawRequestTx({
		walletAddress: firstRequest.userAddress,
	});

	console.log("Transaction builders created for request management");
}

Use Cases:

1. Withdrawal Tracking: Monitor pending vault withdrawals

2. User Dashboard: Display withdrawal request status

3. Request Management: Update or cancel pending requests

4. Liquidity Planning: Understand pending outflows for vault managers

---

getOwnedVaultLpCoins

async getOwnedVaultLpCoins(
  inputs: ApiPerpetualsVaultOwnedLpCoinsBody
): Promise<ApiPerpetualsVaultOwnedLpCoinsResponse>

Fetch all Perpetuals vault LP coins owned by a wallet.

What are LP Coins? When users deposit collateral into a vault, they receive LP (Liquidity Provider) coins representing their share of the vault. These coins:

• Represent proportional ownership of vault assets

• Can be burned to withdraw collateral (via withdrawal request)

• Appreciate/depreciate based on vault performance

• Are transferable (can be sent to other addresses)

• Are owned directly by end users

Parameters:

• walletAddress: SuiAddress

  • Owner wallet address to query

  • Returns LP coins owned by this address

  • Must be a valid Sui address

• vaultIds (optional): ObjectId[]

  • Optional list of vault IDs to filter by

  • Only returns LP coins for these specific vaults

  • If omitted, returns LP coins for all vaults

Returns:

ApiPerpetualsVaultOwnedLpCoinsResponse containing:

• lpCoins: PerpetualsVaultLpCoin[]

  • Array of LP coin objects

  • Each coin contains:

    • objectId: Coin object ID

    • vaultId: Vault the coin belongs to

    • balance: Amount of LP coins

    • coinType: Full coin type (includes vault ID)

Example:

// Fetch all LP coins for a wallet
const response = await perps.getOwnedVaultLpCoins({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
});

console.log(`Found ${response.lpCoins.length} LP coin objects`);

if (response.lpCoins.length === 0) {
	console.log("No LP coin holdings found");
}

// Display LP coins
for (const lpCoin of response.lpCoins) {
	console.log(`\nLP Coin:`);
	console.log(`  Object ID: ${lpCoin.objectId}`);
	console.log(`  Vault ID: ${lpCoin.vaultId}`);
	console.log(`  Balance: ${lpCoin.balance}`);
	console.log(`  Coin Type: ${lpCoin.coinType}`);
}

// Filter by specific vaults
const vaultIds = ["0xaaaa...1111", "0xbbbb...2222"];
const filteredResponse = await perps.getOwnedVaultLpCoins({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	vaultIds,
});

console.log(
	`\nLP coins for specified vaults: ${filteredResponse.lpCoins.length}`,
);

// Calculate total LP holdings per vault
const lpByVault = response.lpCoins.reduce((totals, coin) => {
	const current = totals.get(coin.vaultId) || 0n;
	totals.set(coin.vaultId, current + BigInt(coin.balance));
	return totals;
}, new Map<string, bigint>());

console.log(`\nTotal LP holdings by vault:`);
for (const [vaultId, total] of lpByVault) {
	console.log(`  ${vaultId}: ${total} LP tokens`);
}

// Get LP coin prices to calculate USD value
const uniqueVaultIds = [...lpByVault.keys()];
const { lpCoinPrices } = await perps.getLpCoinPrices({
	vaultIds: uniqueVaultIds,
});

// Calculate total value
console.log(`\nLP Holdings Value:`);
let totalValue = 0;

uniqueVaultIds.forEach((vaultId, index) => {
	const lpAmount = Number(lpByVault.get(vaultId) || 0n);
	const pricePerLp = lpCoinPrices[index].priceInCollateral;
	const value = lpAmount * pricePerLp;

	console.log(`  Vault ${vaultId}:`);
	console.log(`    LP Amount: ${lpAmount}`);
	console.log(`    Price per LP: ${pricePerLp}`);
	console.log(`    Total Value: ${value} collateral`);

	totalValue += value;
});

console.log(`\nTotal Portfolio Value: ${totalValue} collateral units`);

// Find vault with largest position
const largestPosition = [...lpByVault.entries()].reduce(
	(max, [vaultId, amount]) =>
		amount > max.amount ? { vaultId, amount } : max,
	{ vaultId: "", amount: 0n },
);

console.log(`\nLargest LP position:`);
console.log(`  Vault: ${largestPosition.vaultId}`);
console.log(`  Amount: ${largestPosition.amount} LP tokens`);

// Prepare withdrawal for a specific vault
if (response.lpCoins.length > 0) {
	const firstCoin = response.lpCoins[0];
	const { vault } = await perps.getVault({ marketId: firstCoin.vaultId });

	// Create withdrawal request
	const { tx } = await vault.getCreateWithdrawRequestTx({
		walletAddress:
			"0x0000000000000000000000000000000000000000000000000000000000000123",
		lpCoinAmount: BigInt(firstCoin.balance),
		minCollateralAmountOut: (BigInt(firstCoin.balance) * 95n) / 100n, // 5% slippage
	});

	console.log("Withdrawal request transaction prepared");
}

// Group coins by vault and sum balances
const consolidatedHoldings = response.lpCoins.reduce(
	(holdings, coin) => {
		if (!holdings[coin.vaultId]) {
			holdings[coin.vaultId] = {
				vaultId: coin.vaultId,
				totalBalance: 0n,
				coinCount: 0,
				coinIds: [],
			};
		}

		holdings[coin.vaultId].totalBalance += BigInt(coin.balance);
		holdings[coin.vaultId].coinCount++;
		holdings[coin.vaultId].coinIds.push(coin.objectId);

		return holdings;
	},
	{} as Record<string, any>,
);

console.log(`\nConsolidated Holdings:`);
for (const holding of Object.values(consolidatedHoldings)) {
	console.log(`  Vault: ${holding.vaultId}`);
	console.log(`    Total: ${holding.totalBalance} LP`);
	console.log(`    Coins: ${holding.coinCount} separate objects`);
}

Use Cases:

1. Portfolio Display: Show user's vault investments

2. Withdrawal Planning: Determine available LP coins for withdrawal

3. Performance Tracking: Calculate investment value over time

4. Asset Management: Monitor vault allocations

---

getAccountCaps

async getAccountCaps(
  inputs: ApiPerpetualsAccountCapsBody
): Promise<ApiPerpetualsAccountCapsResponse>

Fetch account caps by their cap object IDs.

Difference from getOwnedAccountCaps:

• getOwnedAccountCaps: Queries by wallet address (finds all caps owned by an address)

• getAccountCaps: Queries by cap object IDs (direct lookup)

When to use:

• When you have specific cap object IDs

• For direct cap lookup without knowing the owner

• For cached/stored cap references

Parameters:

• accountCapIds: ObjectId[]

  • List of account cap object IDs to fetch

  • Each ID uniquely identifies a cap on-chain

  • Must be valid 32-byte hex strings with 0x prefix

Returns:

ApiPerpetualsAccountCapsResponse containing:

• accountCaps: PerpetualsAccountCap[]

  • Array of account cap objects

  • Returned in the same order as input accountCapIds

  • Each cap contains full ownership and metadata

Example:

// Fetch specific account caps by ID
const capIds = [
	"0xaaaa111122223333444455556666777788889999aaaabbbbccccddddeeeeffff",
	"0xbbbb222233334444555566667777888899990000aaaabbbbccccddddeeee1111",
];

const response = await perps.getAccountCaps({
	accountCapIds: capIds,
});

console.log(`Fetched ${response.accountCaps.length} account caps`);

// Display cap information
for (const cap of response.accountCaps) {
	console.log(`\nAccount Cap:`);
	console.log(`  Cap Object ID: ${cap.objectId}`);
	console.log(`  Account ID: ${cap.accountId}`);
	console.log(`  Account Object ID: ${cap.accountObjectId}`);
	console.log(`  Collateral Type: ${cap.collateralCoinType}`);
	console.log(`  Owner: ${cap.walletAddress}`);
}

// Use caps to fetch full account data
const { accounts } = await perps.getAccounts({
	accountCaps: response.accountCaps,
});

accounts.forEach((account, index) => {
	console.log(`\nAccount ${index + 1}:`);
	console.log(`  Collateral: ${account.collateral()}`);
	console.log(`  Equity: ${account.account.totalEquity}`);
	console.log(`  Positions: ${account.account.positions.length}`);
});

// Verify cap ownership
const expectedOwner =
	"0x0000000000000000000000000000000000000000000000000000000000000123";
const isOwner = response.accountCaps.every(
	(cap) => cap.walletAddress === expectedOwner,
);
console.log(`\nAll caps owned by ${expectedOwner}: ${isOwner}`);

// Lookup single cap
const singleCapResponse = await perps.getAccountCaps({
	accountCapIds: [capIds[0]],
});

const cap = singleCapResponse.accountCaps[0];
console.log(`\nSingle cap lookup:`);
console.log(`  Account ID: ${cap.accountId}`);
console.log(`  Collateral: ${cap.collateralCoinType}`);

// Cache use case: Store cap IDs, fetch when needed
class AccountCapCache {
	private capIds: string[] = [];

	async store(capId: string) {
		this.capIds.push(capId);
	}

	async fetchAll(perps: Perpetuals) {
		if (this.capIds.length === 0) return [];

		const response = await perps.getAccountCaps({
			accountCapIds: this.capIds,
		});

		return response.accountCaps;
	}
}

const cache = new AccountCapCache();
await cache.store(capIds[0]);
const cachedCaps = await cache.fetchAll(perps);
console.log(`Fetched ${cachedCaps.length} caps from cache`);

Use Cases:

1. Direct Cap Lookup: When you have stored cap IDs

2. Deep Linking: Navigate to account from cap ID in URL

3. Cached References: Fetch caps from persistent storage

4. Permission Verification: Check cap ownership

---

Historical Data & Statistics Methods

getMarketCandleHistory

getMarketCandleHistory(
  inputs: ApiPerpetualsMarketCandleHistoryBody
): Promise<ApiPerpetualsMarketCandleHistoryResponse>

Fetch historical OHLCV (Open, High, Low, Close, Volume) candle data for a single market.

Parameters:

• marketId: PerpetualsMarketId

  • Market ID to query candle history for

  • Must be a valid market object ID

• fromTimestamp: Timestamp

  • Start timestamp in milliseconds (inclusive)

  • Unix epoch time (e.g., Date.now())

  • Data begins from this time

• toTimestamp: Timestamp

  • End timestamp in milliseconds (exclusive)

  • Unix epoch time

  • Data ends before this time

• intervalMs: number

  • Candle interval in milliseconds

  • Common intervals:

    • 60000 = 1 minute

    • 300000 = 5 minutes

    • 900000 = 15 minutes

    • 3600000 = 1 hour

    • 14400000 = 4 hours

    • 86400000 = 1 day

Returns:

ApiPerpetualsMarketCandleHistoryResponse containing:

• candles: PerpetualsMarketCandleDataPoint[]

  • Array of candle data points

  • Each candle contains:

    • timestamp: Candle start time

    • open: Opening price

    • high: Highest price

    • low: Lowest price

    • close: Closing price

    • volume: Trading volume

  • Sorted chronologically (oldest to newest)

Example:

// Fetch 1-hour candles for the last 24 hours
const now = Date.now();
const oneDayAgo = now - 86400000; // 24 hours in milliseconds

const history = await perps.getMarketCandleHistory({
	marketId: "0x1234...abcd",
	fromTimestamp: oneDayAgo,
	toTimestamp: now,
	intervalMs: 3600000, // 1 hour
});

console.log(`Fetched ${history.candles.length} candles`);

// Display candle data
for (const candle of history.candles) {
	const date = new Date(candle.timestamp);
	console.log(`${date.toISOString()}:`);
	console.log(`  Open: $${candle.open}`);
	console.log(`  High: $${candle.high}`);
	console.log(`  Low: $${candle.low}`);
	console.log(`  Close: $${candle.close}`);
	console.log(`  Volume: ${candle.volume}`);
}

// Calculate price change
if (history.candles.length >= 2) {
	const firstCandle = history.candles[0];
	const lastCandle = history.candles[history.candles.length - 1];
	const priceChange =
		((lastCandle.close - firstCandle.open) / firstCandle.open) * 100;

	console.log(`\n24h Price Change: ${priceChange.toFixed(2)}%`);
	console.log(`Open: $${firstCandle.open}`);
	console.log(`Close: $${lastCandle.close}`);
}

// Find highest and lowest prices
const allPrices = history.candles.flatMap((c) => [c.high, c.low]);
const highest = Math.max(...allPrices);
const lowest = Math.min(...allPrices);

console.log(`\n24h High: $${highest}`);
console.log(`24h Low: $${lowest}`);
console.log(`24h Range: $${highest - lowest}`);

// Calculate total volume
const totalVolume = history.candles.reduce((sum, c) => sum + c.volume, 0);
console.log(`24h Volume: ${totalVolume}`);

// Fetch 1-minute candles for the last hour
const oneHourAgo = now - 3600000;

const recentHistory = await perps.getMarketCandleHistory({
	marketId: "0x1234...abcd",
	fromTimestamp: oneHourAgo,
	toTimestamp: now,
	intervalMs: 60000, // 1 minute
});

console.log(`\nRecent 1-minute candles: ${recentHistory.candles.length}`);

// Chart visualization preparation
const chartData = history.candles.map((candle) => ({
	x: new Date(candle.timestamp),
	y: [candle.open, candle.high, candle.low, candle.close],
	volume: candle.volume,
}));

// Technical analysis: Simple Moving Average
function calculateSMA(
	candles: typeof history.candles,
	period: number,
): number[] {
	const sma: number[] = [];

	for (let i = period - 1; i < candles.length; i++) {
		const slice = candles.slice(i - period + 1, i + 1);
		const average = slice.reduce((sum, c) => sum + c.close, 0) / period;
		sma.push(average);
	}

	return sma;
}

const sma20 = calculateSMA(history.candles, 20);
console.log(`\n20-period SMA: ${sma20[sma20.length - 1]?.toFixed(2)}`);

// Fetch multiple timeframes
const timeframes = [
	{ interval: 60000, label: "1m" },
	{ interval: 300000, label: "5m" },
	{ interval: 3600000, label: "1h" },
	{ interval: 86400000, label: "1d" },
];

for (const timeframe of timeframes) {
	const data = await perps.getMarketCandleHistory({
		marketId: "0x1234...abcd",
		fromTimestamp: now - 86400000 * 7, // Last 7 days
		toTimestamp: now,
		intervalMs: timeframe.interval,
	});

	console.log(`${timeframe.label} candles: ${data.candles.length}`);
}

Use Cases:

1. Chart Visualization: Display price charts with OHLC data

2. Technical Analysis: Calculate indicators (SMA, EMA, RSI, etc.)

3. Historical Performance: Analyze price movements over time

4. Backtesting: Test trading strategies on historical data

---

getMarkets24hrStats

getMarkets24hrStats(inputs: {
  marketIds: PerpetualsMarketId[];
}): Promise<ApiPerpetualsMarkets24hrStatsResponse>

Fetch 24-hour statistics for multiple markets.

What's Included:

• 24-hour volume

• Price change (absolute and percentage)

• High/low prices

• Open/close prices

• Number of trades

Parameters:

• marketIds: PerpetualsMarketId[]

  • Array of market IDs to query statistics for

  • Can query multiple markets simultaneously

  • Stats returned in corresponding order

Returns:

ApiPerpetualsMarkets24hrStatsResponse containing:

• marketsStats: PerpetualsMarket24hrStats[]

  • Array of 24-hour statistics

  • One entry per input market ID

  • Each stat object contains:

    • marketId: Market identifier

    • volume24h: Trading volume in last 24h

    • priceChange24h: Price change percentage

    • priceChangeAbsolute24h: Absolute price change

    • high24h: Highest price

    • low24h: Lowest price

    • open24h: Opening price

    • close24h: Closing price (most recent)

    • trades24h: Number of trades

Example:

// Fetch stats for multiple markets
const marketIds = ["0x1111...btc", "0x2222...eth", "0x3333...sui"];

const stats = await perps.getMarkets24hrStats({
	marketIds,
});

console.log(`Fetched stats for ${stats.marketsStats.length} markets`);

// Display stats for each market
stats.marketsStats.forEach((stat, index) => {
	console.log(`\nMarket ${index + 1}: ${stat.marketId}`);
	console.log(`  24h Volume: $${stat.volume24h.toFixed(2)}`);
	console.log(
		`  24h Change: ${stat.priceChange24h > 0 ? "+" : ""}${stat.priceChange24h.toFixed(2)}%`,
	);
	console.log(`  24h High: $${stat.high24h}`);
	console.log(`  24h Low: $${stat.low24h}`);
	console.log(`  Current Price: $${stat.close24h}`);
	console.log(`  Trades: ${stat.trades24h}`);
});

// Find market with highest volume
const highestVolumeMarket = stats.marketsStats.reduce((max, stat) =>
	stat.volume24h > max.volume24h ? stat : max,
);

console.log(`\nHighest Volume Market:`);
console.log(`  ID: ${highestVolumeMarket.marketId}`);
console.log(`  Volume: $${highestVolumeMarket.volume24h.toFixed(2)}`);

// Find biggest gainers and losers
const sortedByChange = [...stats.marketsStats].sort(
	(a, b) => b.priceChange24h - a.priceChange24h,
);

const biggestGainer = sortedByChange[0];
const biggestLoser = sortedByChange[sortedByChange.length - 1];

console.log(`\nBiggest Gainer:`);
console.log(`  ID: ${biggestGainer.marketId}`);
console.log(`  Change: +${biggestGainer.priceChange24h.toFixed(2)}%`);

console.log(`\nBiggest Loser:`);
console.log(`  ID: ${biggestLoser.marketId}`);
console.log(`  Change: ${biggestLoser.priceChange24h.toFixed(2)}%`);

// Calculate portfolio statistics
const totalVolume = stats.marketsStats.reduce(
	(sum, stat) => sum + stat.volume24h,
	0,
);
console.log(`\nTotal 24h Volume: $${totalVolume.toFixed(2)}`);

// Display market heatmap data
console.log(`\nMarket Heatmap:`);
stats.marketsStats.forEach((stat) => {
	const color =
		stat.priceChange24h > 0 ? "🟢" : stat.priceChange24h < 0 ? "🔴" : "⚪";
	const intensity = Math.abs(stat.priceChange24h);
	const bars = "█".repeat(Math.ceil(intensity));

	console.log(
		`${color} ${stat.marketId}: ${stat.priceChange24h.toFixed(2)}% ${bars}`,
	);
});

// Combine with current market data
const { markets } = await perps.getMarkets({
	marketIds,
});

const combinedData = markets.map((market, index) => ({
	market,
	stats: stats.marketsStats[index],
	currentPrice: market.indexPrice,
	priceVsOpen:
		((market.indexPrice - stats.marketsStats[index].open24h) /
			stats.marketsStats[index].open24h) *
		100,
}));

console.log(`\nCombined Market Data:`);
combinedData.forEach((data) => {
	console.log(`\nMarket: ${data.market.marketId}`);
	console.log(`  Current: $${data.currentPrice}`);
	console.log(`  24h Open: $${data.stats.open24h}`);
	console.log(`  Change vs Open: ${data.priceVsOpen.toFixed(2)}%`);
	console.log(`  Volume: $${data.stats.volume24h.toFixed(2)}`);
});

// Volatility analysis
const volatilityRankings = stats.marketsStats
	.map((stat) => ({
		marketId: stat.marketId,
		range: stat.high24h - stat.low24h,
		rangePercentage: ((stat.high24h - stat.low24h) / stat.low24h) * 100,
	}))
	.sort((a, b) => b.rangePercentage - a.rangePercentage);

console.log(`\nVolatility Rankings (by 24h range %):`);
volatilityRankings.forEach((item, index) => {
	console.log(
		`${index + 1}. ${item.marketId}: ${item.rangePercentage.toFixed(2)}%`,
	);
});

// Trading activity analysis
const avgTradesPerMarket =
	stats.marketsStats.reduce((sum, stat) => sum + stat.trades24h, 0) /
	stats.marketsStats.length;

console.log(`\nAverage trades per market: ${avgTradesPerMarket.toFixed(0)}`);

const mostActiveMarket = stats.marketsStats.reduce((max, stat) =>
	stat.trades24h > max.trades24h ? stat : max,
);

console.log(
	`Most active market: ${mostActiveMarket.marketId} (${mostActiveMarket.trades24h} trades)`,
);

Use Cases:

1. Market Overview Dashboard: Display 24h performance metrics

2. Top Movers: Show biggest gainers/losers

3. Volume Analysis: Identify most liquid markets

4. Performance Tracking: Monitor market activity

---

Pricing Methods

getPrices

async getPrices(inputs: {
  marketIds: ObjectId[];
}): Promise<ApiPerpetualsMarketsPricesResponse>

Fetch the latest oracle prices (base asset and collateral) for one or more markets.

What Prices are Returned:

• Base Price: Current oracle price of the underlying asset (e.g., BTC, ETH)

• Collateral Price: Current price of the collateral asset (e.g., USD value of SUI)

These prices are used for:

• Position valuation

• PnL calculations

• Margin requirements

• Liquidation price determination

Parameters:

• marketIds: ObjectId[]

  • List of market IDs to query prices for

  • Can request prices for multiple markets simultaneously

  • Prices returned in corresponding order

Returns:

ApiPerpetualsMarketsPricesResponse containing:

• marketsPrices: Array of price objects

  • One entry per input market ID

  • Each object contains:

    • marketId: Market identifier

    • basePrice: Oracle price of base asset

    • collateralPrice: Price of collateral asset

Example:

// Fetch prices for multiple markets
const marketIds = ["0x1111...btc", "0x2222...eth", "0x3333...sui"];

const prices = await perps.getPrices({
	marketIds,
});

console.log(`Fetched prices for ${prices.marketsPrices.length} markets`);

// Display prices
for (const price of prices.marketsPrices) {
	console.log(`\nMarket: ${price.marketId}`);
	console.log(`  Base Price: $${price.basePrice.toFixed(2)}`);
	console.log(`  Collateral Price: $${price.collateralPrice.toFixed(6)}`);
}

// Empty array handling
const emptyPrices = await perps.getPrices({
	marketIds: [],
});
console.log(`Empty request: ${emptyPrices.marketsPrices.length} prices`); // 0

// Single market price
const singlePrice = await perps.getPrices({
	marketIds: ["0x1111...btc"],
});

const btcPrice = singlePrice.marketsPrices[0];
console.log(`\nBTC Oracle Price: $${btcPrice.basePrice}`);

// Compare with market data
const { markets } = await perps.getMarkets({ marketIds });

markets.forEach((market, index) => {
	const price = prices.marketsPrices[index];
	const marketPrice = market.indexPrice;
	const oraclePrice = price.basePrice;

	const difference = Math.abs(marketPrice - oraclePrice);
	const differencePercent = (difference / oraclePrice) * 100;

	console.log(`\nMarket ${index + 1}:`);
	console.log(`  Market Index Price: $${marketPrice}`);
	console.log(`  Oracle Price: $${oraclePrice}`);
	console.log(
		`  Difference: $${difference.toFixed(2)} (${differencePercent.toFixed(4)}%)`,
	);
});

// Calculate position values using oracle prices
interface Position {
	marketId: string;
	baseAssetAmount: number;
	entryPrice: number;
}

const positions: Position[] = [
	{ marketId: "0x1111...btc", baseAssetAmount: 0.5, entryPrice: 45000 },
	{ marketId: "0x2222...eth", baseAssetAmount: 10, entryPrice: 3000 },
];

positions.forEach((position) => {
	const price = prices.marketsPrices.find(
		(p) => p.marketId === position.marketId,
	);

	if (price) {
		const currentValue = position.baseAssetAmount * price.basePrice;
		const entryValue = position.baseAssetAmount * position.entryPrice;
		const pnl = currentValue - entryValue;
		const pnlPercent = (pnl / entryValue) * 100;

		console.log(`\nPosition: ${position.marketId}`);
		console.log(`  Size: ${position.baseAssetAmount}`);
		console.log(`  Entry: $${position.entryPrice}`);
		console.log(`  Current: $${price.basePrice}`);
		console.log(`  Value: $${currentValue.toFixed(2)}`);
		console.log(`  PnL: $${pnl.toFixed(2)} (${pnlPercent.toFixed(2)}%)`);
	}
});

// Monitor price changes
let previousPrices = await perps.getPrices({ marketIds });

setInterval(async () => {
	const currentPrices = await perps.getPrices({ marketIds });

	currentPrices.marketsPrices.forEach((current, index) => {
		const previous = previousPrices.marketsPrices[index];

		if (previous) {
			const change = current.basePrice - previous.basePrice;
			const changePercent = (change / previous.basePrice) * 100;

			if (Math.abs(changePercent) > 0.1) {
				// Alert on >0.1% change
				console.log(`Price Alert: ${current.marketId}`);
				console.log(
					`  Changed ${changePercent > 0 ? "+" : ""}${changePercent.toFixed(2)}%`,
				);
				console.log(`  ${previous.basePrice} → ${current.basePrice}`);
			}
		}
	});

	previousPrices = currentPrices;
}, 5000); // Check every 5 seconds

// Collateral value tracking
const collateralPrices = prices.marketsPrices.map((p) => p.collateralPrice);
const uniqueCollateralPrices = [...new Set(collateralPrices)];

console.log(`\nUnique collateral prices: ${uniqueCollateralPrices.length}`);
uniqueCollateralPrices.forEach((price, index) => {
	console.log(`  Collateral ${index + 1}: $${price.toFixed(6)}`);
});

Use Cases:

1. Position Valuation: Calculate current position values

2. PnL Calculation: Determine unrealized profits/losses

3. Price Monitoring: Track oracle price movements

4. Liquidation Checks: Compare prices to liquidation thresholds

---

getLpCoinPrices

async getLpCoinPrices(
  inputs: ApiPerpetualsVaultLpCoinPricesBody
): Promise<ApiPerpetualsVaultLpCoinPricesResponse>

Fetch LP coin prices (in collateral units) for a set of vaults.

What is LP Coin Price? The LP coin price represents how much collateral one LP token is worth. This price:

• Changes based on vault performance (trading PnL)

• Increases when vault makes profits

• Decreases when vault has losses

• Accounts for performance fees

Formula:

LP Coin Price = (Total Vault Equity - Accrued Fees) / Total LP Supply

Parameters:

• vaultIds: ObjectId[]

  • List of vault IDs to query LP prices for

  • Can request prices for multiple vaults simultaneously

  • Prices returned in corresponding order

Returns:

ApiPerpetualsVaultLpCoinPricesResponse containing:

• lpCoinPrices: Array of LP price objects

  • One entry per input vault ID

  • Each object contains:

    • vaultId: Vault identifier

    • priceInCollateral: Price of one LP coin in collateral units

    • timestamp: When price was calculated

Example:

// Fetch LP prices for multiple vaults
const vaultIds = ["0xaaaa...vault1", "0xbbbb...vault2", "0xcccc...vault3"];

const prices = await perps.getLpCoinPrices({
	vaultIds,
});

console.log(`Fetched LP prices for ${prices.lpCoinPrices.length} vaults`);

// Display LP prices
for (const price of prices.lpCoinPrices) {
	console.log(`\nVault: ${price.vaultId}`);
	console.log(
		`  LP Coin Price: ${price.priceInCollateral} collateral per token`,
	);
	console.log(`  Updated: ${new Date(price.timestamp).toLocaleString()}`);
}

// Empty array handling
const emptyPrices = await perps.getLpCoinPrices({
	vaultIds: [],
});
console.log(`Empty request: ${emptyPrices.lpCoinPrices.length} prices`); // 0

// Calculate user's vault holdings value
const userLpHoldings = [
	{ vaultId: "0xaaaa...vault1", lpAmount: 1000 },
	{ vaultId: "0xbbbb...vault2", lpAmount: 500 },
];

const userVaultIds = userLpHoldings.map((h) => h.vaultId);
const userPrices = await perps.getLpCoinPrices({
	vaultIds: userVaultIds,
});

let totalValue = 0;

console.log(`\nUser Vault Holdings:`);
userLpHoldings.forEach((holding, index) => {
	const price = userPrices.lpCoinPrices[index];
	const value = holding.lpAmount * price.priceInCollateral;
	totalValue += value;

	console.log(`\nVault ${index + 1}:`);
	console.log(`  LP Amount: ${holding.lpAmount}`);
	console.log(`  Price per LP: ${price.priceInCollateral}`);
	console.log(`  Total Value: ${value} collateral`);
});

console.log(`\nTotal Portfolio Value: ${totalValue} collateral`);

// Track LP price performance over time
interface LpPriceSnapshot {
	timestamp: number;
	prices: Map<string, number>;
}

const priceHistory: LpPriceSnapshot[] = [];

async function recordPriceSnapshot() {
	const currentPrices = await perps.getLpCoinPrices({ vaultIds });

	const snapshot: LpPriceSnapshot = {
		timestamp: Date.now(),
		prices: new Map(
			currentPrices.lpCoinPrices.map((p) => [
				p.vaultId,
				p.priceInCollateral,
			]),
		),
	};

	priceHistory.push(snapshot);

	// Calculate performance since first snapshot
	if (priceHistory.length > 1) {
		const first = priceHistory[0];
		const current = snapshot;

		console.log(`\nVault Performance:`);
		for (const [vaultId, currentPrice] of current.prices) {
			const initialPrice = first.prices.get(vaultId);
			if (initialPrice) {
				const change =
					((currentPrice - initialPrice) / initialPrice) * 100;
				console.log(
					`  ${vaultId}: ${change > 0 ? "+" : ""}${change.toFixed(2)}%`,
				);
			}
		}
	}
}

// Record snapshot every hour
setInterval(recordPriceSnapshot, 3600000);

// Compare vault performances
const performances = prices.lpCoinPrices
	.map((price, index) => ({
		vaultId: price.vaultId,
		lpPrice: price.priceInCollateral,
		index,
	}))
	.sort((a, b) => b.lpPrice - a.lpPrice);

console.log(`\nVaults by LP Price (descending):`);
performances.forEach((perf, rank) => {
	console.log(`${rank + 1}. ${perf.vaultId}: ${perf.lpPrice} collateral/LP`);
});

// Fetch vault objects to calculate total value locked (TVL)
const { vaults } = await perps.getVaults({ vaultIds });

const vaultTVLs = vaults
	.map((result, index) => {
		const vault = result.vaultObject;
		const lpPrice = prices.lpCoinPrices[index].priceInCollateral;
		const lpSupply = Number(vault.lpCoinSupply);
		const tvl = lpSupply * lpPrice;

		return {
			vaultId: vault.objectId,
			lpSupply,
			lpPrice,
			tvl,
		};
	})
	.sort((a, b) => b.tvl - a.tvl);

console.log(`\nVaults by TVL:`);
vaultTVLs.forEach((item, rank) => {
	console.log(`${rank + 1}. ${item.vaultId}:`);
	console.log(`   LP Supply: ${item.lpSupply}`);
	console.log(`   LP Price: ${item.lpPrice}`);
	console.log(`   TVL: ${item.tvl.toFixed(2)} collateral`);
});

// Calculate expected withdrawal amount
function calculateWithdrawalAmount(
	lpCoinsToRedeem: number,
	lpPrice: number,
	slippageTolerance: number = 0.01,
): { expectedCollateral: number; minCollateral: number } {
	const expectedCollateral = lpCoinsToRedeem * lpPrice;
	const minCollateral = expectedCollateral * (1 - slippageTolerance);

	return { expectedCollateral, minCollateral };
}

const withdrawalCalc = calculateWithdrawalAmount(
	500, // LP coins to redeem
	prices.lpCoinPrices[0].priceInCollateral,
	0.01, // 1% slippage
);

console.log(`\nWithdrawal Calculation:`);
console.log(`  LP Coins: 500`);
console.log(`  Expected Collateral: ${withdrawalCalc.expectedCollateral}`);
console.log(`  Min Collateral (1% slippage): ${withdrawalCalc.minCollateral}`);

Use Cases:

1. Portfolio Valuation: Calculate total vault investment value

2. Performance Tracking: Monitor vault returns over time

3. Withdrawal Planning: Estimate collateral received when withdrawing

4. Vault Comparison: Compare LP prices across vaults

---

Transaction Builder Methods

getCreateAccountTx

async getCreateAccountTx(inputs: {
  walletAddress: SuiAddress;
  collateralCoinType: CoinType;
  tx?: Transaction;
}): Promise<SdkTransactionResponse>

Build a create-account transaction for Aftermath Perpetuals.

What This Does: Creates a new perpetuals trading account for a user. The account:

• Is owned by the specified wallet address

• Uses the specified collateral type

• Can be used to trade in markets with matching collateral

• Receives an account cap NFT representing ownership

This transaction must be signed and executed by the wallet. The account cap will be minted to the wallet address.

Parameters:

• walletAddress: SuiAddress

  • Wallet address that will own the new account

  • This address will receive the account cap NFT

  • Must be a valid Sui address (32-byte hex with 0x prefix)

• collateralCoinType: CoinType

  • Collateral coin type the account will use

  • Must be a supported collateral type (e.g., "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC")

  • Account can only trade in markets using this collateral

  • Cannot be changed after account creation

• tx (optional): Transaction

  • Optional existing transaction to extend

  • If provided, create-account commands are appended to this transaction

  • Useful for batching multiple operations

Returns:

SdkTransactionResponse containing:

• tx: Transaction

  • Transaction object ready to be signed and executed

  • Contains the create-account command

  • Can be further modified before signing

Example:

// Basic account creation
const { tx } = await perps.getCreateAccountTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
});

// Sign and execute with your wallet
// const result = await wallet.signAndExecuteTransaction({
//   transaction: tx,
// });

console.log("Account creation transaction built");

// Create multiple accounts with different collateral types
const collateralTypes = [
	"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC", // USDC
	"0x2::sui::SUI",
];

for (const collateralType of collateralTypes) {
	const { tx } = await perps.getCreateAccountTx({
		walletAddress:
			"0x0000000000000000000000000000000000000000000000000000000000000123",
		collateralCoinType: collateralType,
	});

	// Execute transaction for each collateral type
	// await wallet.signAndExecuteTransaction({ transaction: tx });

	console.log(`Created account for ${collateralType}`);
}

// Extend existing transaction
const existingTx = new Transaction();
// ... add other operations to existingTx

const { tx: extendedTx } = await perps.getCreateAccountTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	tx: existingTx,
});

// extendedTx now contains both the original operations and account creation

// Check if user already has an account before creating
const { accounts } = await perps.getOwnedAccountCaps({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinTypes: [
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	],
});

if (accounts.length === 0) {
	console.log("No SUI account found, creating one...");

	const { tx } = await perps.getCreateAccountTx({
		walletAddress:
			"0x0000000000000000000000000000000000000000000000000000000000000123",
		collateralCoinType:
			"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	});

	// Execute transaction
	// const result = await wallet.signAndExecuteTransaction({ transaction: tx });
} else {
	console.log("Account already exists");
}

// Onboarding flow
async function onboardUser(walletAddress: SuiAddress) {
	// Check for existing accounts
	const { accounts } = await perps.getOwnedAccountCaps({
		walletAddress,
	});

	if (accounts.length > 0) {
		console.log(`User has ${accounts.length} existing accounts`);
		return accounts;
	}

	// Create new account
	console.log("Creating new account for user...");
	const { tx } = await perps.getCreateAccountTx({
		walletAddress,
		collateralCoinType:
			"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC", // Default to SUI
	});

	// Return transaction for user to sign
	return tx;
}

Use Cases:

1. User Onboarding: Create first trading account for new users

2. Multi-Collateral Setup: Create accounts for different collateral types

3. Wallet Integration: Build account creation flow in dApp

4. Batch Operations: Combine account creation with other transactions

---

getCreateVaultCapTx

async getCreateVaultCapTx(
  inputs: ApiPerpetualsCreateVaultCapBody
): Promise<SdkTransactionResponse>

Build a create-vault-cap transaction.

What This Does: Creates a vault cap, which is an ownership/admin object for interacting with vault management flows. This is a prerequisite step before creating the actual vault. The transaction returns:

• A coin metadata object ID

• A treasury cap object ID

These IDs are needed as inputs for getCreateVaultTx.

This is step 1 of 2 for vault creation. After executing this transaction, use the returned object IDs to call getCreateVaultTx.

Parameters:

• walletAddress: SuiAddress

  • Vault owner/curator address

  • Will receive the vault cap NFT

  • Must be a valid Sui address

• collateralCoinType: CoinType

  • Collateral coin type for the vault

  • Vault will only accept this collateral type

  • Example: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"

Returns:

SdkTransactionResponse containing:

• tx: Transaction

  • Transaction object ready to sign and execute

  • After execution, extract coinMetadataId and treasuryCapId from transaction effects

Example:

// Step 1: Create vault cap
const { tx: vaultCapTx } = await perps.getCreateVaultCapTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
});

// Execute the transaction
// const result = await wallet.signAndExecuteTransaction({
//   transaction: vaultCapTx,
// });

// Extract the created object IDs from transaction effects
// const coinMetadataId = result.effects.created[0].reference.objectId;
// const treasuryCapId = result.effects.created[1].reference.objectId;

// Step 2: Use these IDs to create the vault (see getCreateVaultTx)
// const { tx: vaultTx } = await perps.getCreateVaultTx({
//   walletAddress: "0x0000000000000000000000000000000000000000000000000000000000000123",
//   coinMetadataId,
//   treasuryCapId,
//   // ... other parameters
// });

console.log("Vault cap transaction built");

// Complete vault creation flow
async function createVault(
	walletAddress: SuiAddress,
	collateralCoinType: CoinType,
) {
	// Step 1: Create vault cap
	console.log("Step 1: Creating vault cap...");
	const { tx: capTx } = await perps.getCreateVaultCapTx({
		walletAddress,
		collateralCoinType,
	});

	// Execute and get created object IDs
	// const capResult = await wallet.signAndExecuteTransaction({
	//   transaction: capTx,
	// });

	// const coinMetadataId = extractObjectId(capResult, 0);
	// const treasuryCapId = extractObjectId(capResult, 1);

	// console.log("Vault cap created successfully");
	// console.log(`Coin Metadata ID: ${coinMetadataId}`);
	// console.log(`Treasury Cap ID: ${treasuryCapId}`);

	// Step 2: Create the vault
	// console.log("Step 2: Creating vault...");
	// const { tx: vaultTx } = await perps.getCreateVaultTx({
	//   walletAddress,
	//   metadata: {
	//     name: "My Trading Vault",
	//     description: "Automated perpetuals trading",
	//   },
	//   coinMetadataId,
	//   treasuryCapId,
	//   collateralCoinType,
	//   lockPeriodMs: 2592000000n, // 30 days
	//   performanceFeePercentage: 0.1, // 10%
	//   forceWithdrawDelayMs: 86400000n, // 1 day
	//   initialDepositAmount: 1000000000n, // 1 SUI
	// });

	// const vaultResult = await wallet.signAndExecuteTransaction({
	//   transaction: vaultTx,
	// });

	// console.log("Vault created successfully");
	// return vaultResult;
}

Use Cases:

1. Vault Creation: First step in creating a new vault

2. Curator Onboarding: Set up new vault managers

3. Multi-Vault Management: Create multiple vaults for different strategies

---

getCreateVaultTx

async getCreateVaultTx(inputs: {
  walletAddress: SuiAddress;
  metadata: {
    name: string;
    description: string;
    curatorName?: string;
    curatorUrl?: string;
    curatorLogoUrl?: string;
    extraFields?: Record<string, string>;
  };
  coinMetadataId: ObjectId;
  treasuryCapId: ObjectId;
  collateralCoinType: CoinType;
  lockPeriodMs: bigint;
  performanceFeePercentage: Percentage;
  forceWithdrawDelayMs: bigint;
  tx?: Transaction;
  isSponsoredTx?: boolean;
} & (
  | { initialDepositAmount: Balance }
  | { initialDepositCoinArg: TransactionObjectArgument }
)): Promise<SdkTransactionResponse>

Build a create-vault transaction.

What This Does: Creates a new vault with:

• On-chain metadata (name, description, curator info)

• Initial LP supply seeded by the initial deposit

• Configurable parameters (lock period, fees, delays)

Prerequisites:

• Must have executed getCreateVaultCapTx first

• Need coinMetadataId and treasuryCapId from that transaction

Parameters:

• walletAddress: SuiAddress

  • Vault owner/curator address

  • Must match the address used in getCreateVaultCapTx

• metadata: Object containing:

  • name: string - Human-readable vault name

  • description: string - Verbose vault description

  • curatorName (optional): string - Curator's name

  • curatorUrl (optional): string - Curator's website

  • curatorLogoUrl (optional): string - Curator's logo image URL

  • extraFields (optional): Record<string, string> - Additional metadata

    • Recommended keys: twitter_url, discord_url, telegram_url

• coinMetadataId: ObjectId

  • Coin metadata object ID from getCreateVaultCapTx transaction

• treasuryCapId: ObjectId

  • Treasury cap object ID from getCreateVaultCapTx transaction

• collateralCoinType: CoinType

  • Collateral coin type (must match vault cap)

• lockPeriodMs: bigint

  • Lock-in period for deposits in milliseconds

  • Depositors must wait this long before withdrawing

  • Maximum: 2 months (5,184,000,000 ms)

• performanceFeePercentage: Percentage

  • Fraction of profits taken as curator fee (0 to 0.2)

  • Example: 0.1 = 10%

  • Maximum: 20% (0.2)

• forceWithdrawDelayMs: bigint

  • Delay before forced withdrawals can be processed

  • In milliseconds

  • Maximum: 1 day (86,400,000 ms)

• tx (optional): Transaction

  • Optional existing transaction to extend

• isSponsoredTx (optional): boolean

  • Whether this transaction is gas-sponsored

• Initial Deposit (choose one):

  • initialDepositAmount: Balance

    • Deposit amount in base units

    • API will select/merge coins as needed

  • initialDepositCoinArg: TransactionObjectArgument

    • Transaction object argument for deposit coin

    • Use when you have a coin arg from previous tx commands

Returns:

SdkTransactionResponse containing:

• tx: Transaction - Transaction ready to sign and execute

Example:

// Complete vault creation example
// (Assumes you have coinMetadataId and treasuryCapId from getCreateVaultCapTx)

const { tx } = await perps.getCreateVaultTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",

	// Vault metadata
	metadata: {
		name: "Algorithmic Trading Vault",
		description: "High-frequency trading strategies for perpetuals markets",
		curatorName: "Quantum Trading LLC",
		curatorUrl: "https://quantumtrading.example",
		curatorLogoUrl: "https://quantumtrading.example/logo.png",
		extraFields: {
			twitter_url: "https://twitter.com/quantumtrading",
			discord_url: "https://discord.gg/quantumtrading",
			strategy: "momentum_arbitrage",
		},
	},

	// Object IDs from vault cap transaction
	coinMetadataId:
		"0xaaaa111122223333444455556666777788889999aaaabbbbccccddddeeeeffff",
	treasuryCapId:
		"0xbbbb222233334444555566667777888899990000aaaabbbbccccddddeeee1111",

	// Configuration
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	lockPeriodMs: 2592000000n, // 30 days
	performanceFeePercentage: 0.15, // 15%
	forceWithdrawDelayMs: 86400000n, // 1 day

	// Initial deposit
	initialDepositAmount: 10000000000n, // 10 SUI
});

// Execute transaction
// const result = await wallet.signAndExecuteTransaction({ transaction: tx });

console.log("Vault creation transaction built");

// Conservative vault configuration
const conservativeVault = await perps.getCreateVaultTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	metadata: {
		name: "Conservative Growth Vault",
		description: "Low-risk, steady returns with minimal leverage",
	},
	coinMetadataId: "0x...",
	treasuryCapId: "0x...",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	lockPeriodMs: 5184000000n, // 60 days (max)
	performanceFeePercentage: 0.05, // 5% (low fee)
	forceWithdrawDelayMs: 43200000n, // 12 hours
	initialDepositAmount: 5000000000n, // 5 SUI
});

// Aggressive vault configuration
const aggressiveVault = await perps.getCreateVaultTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	metadata: {
		name: "High Yield Vault",
		description: "Maximum returns through leveraged strategies",
	},
	coinMetadataId: "0x...",
	treasuryCapId: "0x...",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	lockPeriodMs: 604800000n, // 7 days (short lock)
	performanceFeePercentage: 0.2, // 20% (max fee)
	forceWithdrawDelayMs: 3600000n, // 1 hour
	initialDepositAmount: 20000000000n, // 20 SUI
});

// Using coin argument from previous transaction
const coinTx = new Transaction();
const [coin] = coinTx.splitCoins(coinTx.gas, [10000000000n]);

const { tx: vaultTxWithCoin } = await perps.getCreateVaultTx({
	walletAddress:
		"0x0000000000000000000000000000000000000000000000000000000000000123",
	metadata: {
		name: "My Vault",
		description: "Trading vault",
	},
	coinMetadataId: "0x...",
	treasuryCapId: "0x...",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	lockPeriodMs: 2592000000n,
	performanceFeePercentage: 0.1,
	forceWithdrawDelayMs: 86400000n,
	initialDepositCoinArg: coin,
	tx: coinTx, // Extend the existing transaction
});

// Validation helper
function validateVaultParams(params: {
	lockPeriodMs: bigint;
	performanceFeePercentage: number;
	forceWithdrawDelayMs: bigint;
}) {
	const MAX_LOCK_PERIOD = 5184000000n; // 60 days
	const MAX_PERFORMANCE_FEE = 0.2; // 20%
	const MAX_FORCE_WITHDRAW_DELAY = 86400000n; // 1 day

	if (params.lockPeriodMs > MAX_LOCK_PERIOD) {
		throw new Error(`Lock period exceeds maximum of ${MAX_LOCK_PERIOD}ms`);
	}

	if (params.performanceFeePercentage > MAX_PERFORMANCE_FEE) {
		throw new Error(
			`Performance fee exceeds maximum of ${MAX_PERFORMANCE_FEE * 100}%`,
		);
	}

	if (params.forceWithdrawDelayMs > MAX_FORCE_WITHDRAW_DELAY) {
		throw new Error(
			`Force withdraw delay exceeds maximum of ${MAX_FORCE_WITHDRAW_DELAY}ms`,
		);
	}

	return true;
}

// Validate before creating
validateVaultParams({
	lockPeriodMs: 2592000000n,
	performanceFeePercentage: 0.15,
	forceWithdrawDelayMs: 86400000n,
});

Use Cases:

1. Vault Deployment: Launch new trading vaults

2. Strategy Diversification: Create vaults with different risk profiles

3. Curator Platform: Enable users to become vault managers

4. Institutional Offering: Deploy managed trading products

---

getTransferCapTx

async getTransferCapTx(inputs: {
  recipientAddress: SuiAddress;
  capObjectId: ObjectId;
  tx?: Transaction;
}): Promise<{ tx: Transaction }>

Build a transfer-cap transaction that transfers a Perpetuals capability object to another wallet.

What This Does:

Transfers ownership of a perpetuals capability (account cap or vault cap) to a different wallet address. This changes the controlling wallet for the account or vault.

This action is irreversible without access to the recipientAddress. Triple check the recipientAddress before executing.

Important:

• Transaction must be signed by the current cap owner

• Can transfer both account caps and vault caps

• Recipient immediately gains full control over the account/vault

• Original owner loses all access after transfer

• Transfer is permanent and cannot be undone

Parameters:

• recipientAddress: SuiAddress

  • Wallet address that should receive the capability

  • This wallet will become the new owner

• capObjectId: ObjectId

  • Object ID of the capability to transfer

  • Can be an account cap ID or vault cap ID

• tx (optional): Transaction

  • Existing transaction to extend

Returns:

Object containing:

• tx: Transaction - Transaction ready to sign and execute

Example:

// Transfer account cap to another wallet
const { tx } = await perps.getTransferCapTx({
	recipientAddress: "0xNEW_OWNER_ADDRESS",
	capObjectId: "0xACCOUNT_CAP_OBJECT_ID",
});

// Sign and execute with CURRENT owner wallet
// await currentOwnerWallet.signAndExecuteTransaction({ transaction: tx });

console.log("Account cap transferred to new owner");

// Transfer vault cap
const { tx: vaultTx } = await perps.getTransferCapTx({
	recipientAddress: "0xNEW_VAULT_OWNER",
	capObjectId: "0xVAULT_CAP_OBJECT_ID",
});

// Transfer with confirmation
async function transferCapWithConfirmation(
	recipientAddress: string,
	capObjectId: string,
	capType: "account" | "vault",
): Promise<Transaction | null> {
	console.log(`⚠️  WARNING: Transferring ${capType} cap`);
	console.log(`   Cap Object ID: ${capObjectId}`);
	console.log(`   New Owner: ${recipientAddress}`);
	console.log(`   Current owner will LOSE ALL ACCESS`);
	console.log(`   This action CANNOT BE UNDONE`);

	// In a real application, you'd prompt for user confirmation here
	const confirmed = true; // Replace with actual confirmation logic

	if (!confirmed) {
		console.log("Transfer cancelled");
		return null;
	}

	try {
		const { tx } = await perps.getTransferCapTx({
			recipientAddress,
			capObjectId,
		});

		console.log(`✓ Transfer transaction prepared`);
		return tx;
	} catch (error) {
		console.error("Failed to prepare transfer:", error);
		return null;
	}
}

// Transfer account to new owner
async function transferAccountOwnership(
	accountCapId: string,
	newOwnerAddress: string,
) {
	console.log("Initiating account ownership transfer...");

	// Validate new owner address
	if (!newOwnerAddress.startsWith("0x") || newOwnerAddress.length !== 66) {
		throw new Error("Invalid recipient address format");
	}

	// Build transfer transaction
	const { tx } = await perps.getTransferCapTx({
		recipientAddress: newOwnerAddress,
		capObjectId: accountCapId,
	});

	console.log("\n⚠️  IMPORTANT:");
	console.log("  After this transaction:");
	console.log(`  - ${newOwnerAddress} will control the account`);
	console.log("  - Current owner will have NO access");
	console.log("  - All positions and collateral transfer with ownership");

	return tx;
}

// Bulk transfer multiple accounts
async function bulkTransferAccounts(
	transfers: Array<{
		capObjectId: string;
		recipientAddress: string;
	}>,
) {
	console.log(`Transferring ${transfers.length} accounts...`);

	const transactions: Transaction[] = [];

	for (const { capObjectId, recipientAddress } of transfers) {
		const { tx } = await perps.getTransferCapTx({
			recipientAddress,
			capObjectId,
		});

		transactions.push(tx);
		console.log(
			`  Prepared transfer: ${capObjectId} → ${recipientAddress}`,
		);
	}

	console.log(`\n${transactions.length} transfer transactions ready`);
	return transactions;
}

// Transfer vault to new manager
async function transferVaultToNewManager(
	vaultCapId: string,
	newManagerAddress: string,
) {
	console.log("Transferring vault to new manager...");

	// Build transfer transaction
	const { tx } = await perps.getTransferCapTx({
		recipientAddress: newManagerAddress,
		capObjectId: vaultCapId,
	});

	console.log("\nVault ownership transfer prepared:");
	console.log(`  New Manager: ${newManagerAddress}`);
	console.log("\nNew manager will be able to:");
	console.log("  ✓ Trade across all vault markets");
	console.log("  ✓ Process user withdrawals");
	console.log("  ✓ Update vault parameters");
	console.log("  ✓ Withdraw performance fees");
	console.log("\nCurrent manager will lose all access");

	return tx;
}

// Safe transfer with state snapshot
async function safeTransferWithSnapshot(
	capObjectId: string,
	recipientAddress: string,
) {
	// Get account state before transfer
	const { accounts: caps } = await perps.getOwnedAccountCaps({
		walletAddress: currentOwnerAddress,
	});

	const cap = caps.find((c) => c.objectId === capObjectId);
	if (!cap) {
		throw new Error("Account cap not found");
	}

	const { account } = await perps.getAccount({ accountCap: cap });

	// Create snapshot
	const snapshot = {
		timestamp: Date.now(),
		accountId: account.accountId(),
		positions: account.account.positions.length,
		totalEquity: account.account.totalEquity,
		availableCollateral: account.account.availableCollateral,
		newOwner: recipientAddress,
	};

	console.log("Account snapshot before transfer:");
	console.log(JSON.stringify(snapshot, null, 2));

	// Build transfer
	const { tx } = await perps.getTransferCapTx({
		recipientAddress,
		capObjectId,
	});

	// You might want to save this snapshot to a database
	// await saveTransferSnapshot(snapshot);

	return { tx, snapshot };
}

// Transfer with notification
async function transferWithNotification(
	capObjectId: string,
	recipientAddress: string,
	notificationEmail?: string,
) {
	const { tx } = await perps.getTransferCapTx({
		recipientAddress,
		capObjectId,
	});

	// In a real application, send notification
	if (notificationEmail) {
		console.log(`📧 Sending notification to ${notificationEmail}`);
		console.log(`   Subject: Perpetuals Account Transferred`);
		console.log(
			`   Message: You have received ownership of account ${capObjectId}`,
		);
		// await sendEmail(notificationEmail, subject, message);
	}

	return tx;
}

// Validate transfer before execution
async function validateTransfer(
	capObjectId: string,
	recipientAddress: string,
): Promise<{
	valid: boolean;
	issues: string[];
}> {
	const issues: string[] = [];

	// Validate recipient address format
	if (!recipientAddress.startsWith("0x")) {
		issues.push("Recipient address must start with 0x");
	}

	if (recipientAddress.length !== 66) {
		issues.push("Recipient address must be 66 characters");
	}

	// Validate cap object ID
	if (!capObjectId.startsWith("0x")) {
		issues.push("Cap object ID must start with 0x");
	}

	// Check if transferring to self
	const { accounts: caps } = await perps.getOwnedAccountCaps({
		walletAddress: recipientAddress,
	});

	if (caps.some((c) => c.objectId === capObjectId)) {
		issues.push("Cannot transfer to current owner");
	}

	return {
		valid: issues.length === 0,
		issues,
	};
}

// Usage with validation
const validation = await validateTransfer(
	"0xCAP_OBJECT_ID",
	"0xRECIPIENT_ADDRESS",
);

if (!validation.valid) {
	console.error("Transfer validation failed:");
	validation.issues.forEach((issue) => console.error(`  - ${issue}`));
} else {
	const { tx } = await perps.getTransferCapTx({
		recipientAddress: "0xRECIPIENT_ADDRESS",
		capObjectId: "0xCAP_OBJECT_ID",
	});

	// Execute transfer
	await currentOwnerWallet.signAndExecuteTransaction({ transaction: tx });
	console.log("✓ Transfer completed successfully");
}

// Error handling
try {
	const { tx } = await perps.getTransferCapTx({
		recipientAddress: "0xNEW_OWNER",
		capObjectId: "0xCAP_ID",
	});

	await wallet.signAndExecuteTransaction({ transaction: tx });
} catch (error) {
	console.error("Transfer failed:", error);

	// Common error cases
	if (error.message.includes("not found")) {
		console.error("Capability object not found - check the cap object ID");
	} else if (error.message.includes("permission")) {
		console.error("Only the current owner can transfer the capability");
	} else {
		console.error("Unexpected error during transfer");
	}
}

Use Cases:

1. Account Migration: Move accounts between wallets

2. Ownership Transfer: Transfer account/vault to new owner

3. Organization Changes: Transfer to new team member or entity

4. Estate Planning: Transfer assets to designated recipients

5. Account Consolidation: Move multiple accounts to single wallet

6. Vault Handoff: Transfer vault management to new manager

---

Builder Code Integration Methods

These methods support protocol integrators who want to earn fees on user orders. Integrators can:

1. Get users to approve them as integrators

2. Submit orders on behalf of users with integrator fees

3. Collect accumulated fees from vaults

Want to learn more about Builder Codes? Read more.

getCreateBuilderCodeIntegratorConfigTx

async getCreateBuilderCodeIntegratorConfigTx(inputs: {
  accountId: PerpetualsAccountId;
  integratorAddress: SuiAddress;
  maxTakerFee: Percentage;
}): Promise<SdkTransactionResponse>

Build a transaction to create an integrator configuration.

What This Does: Allows a user to grant permission to an integrator to receive fees on orders placed on their behalf. The user specifies a maximum taker fee that the integrator can charge.

Workflow:

1. User executes this transaction to approve an integrator

2. Integrator can then place orders for the user (via API or other means)

3. When placing orders, integrator includes their address and fee (up to max)

4. Integrator earns fees proportional to taker volume generated

The transaction must be signed by the account owner.

Parameters:

• accountId: PerpetualsAccountId

  • User's perpetuals account ID (bigint)

  • The account that will grant integrator permission

• integratorAddress: SuiAddress

  • Integrator's wallet address

  • Address that will receive accumulated fees

• maxTakerFee: Percentage

  • Maximum taker fee the integrator can charge (as a fraction)

  • Example: 0.001 = 0.1% = 10 basis points

  • Integrator cannot charge more than this amount

Returns:

SdkTransactionResponse containing:

• tx: Transaction - Transaction ready for user to sign

Example:

// User approves an integrator
const { tx } = await perps.getCreateBuilderCodeIntegratorConfigTx({
	accountId: 123n,
	integratorAddress:
		"0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
	maxTakerFee: 0.001, // 0.1% max fee
});

// User signs and executes
// const result = await wallet.signAndExecuteTransaction({ transaction: tx });

console.log("Integrator approval transaction built");

// Different fee tiers
const feeConfigs = [
	{ tier: "Basic", maxFee: 0.0005 }, // 0.05% (5 bps)
	{ tier: "Standard", maxFee: 0.001 }, // 0.1% (10 bps)
	{ tier: "Premium", maxFee: 0.002 }, // 0.2% (20 bps)
];

for (const config of feeConfigs) {
	const { tx } = await perps.getCreateBuilderCodeIntegratorConfigTx({
		accountId: 123n,
		integratorAddress: "0x...",
		maxTakerFee: config.maxFee,
	});

	console.log(`${config.tier} tier: ${config.maxFee * 100}% max fee`);
}

// Approve multiple integrators for same account
const integrators = [
	{ address: "0xaaaa...", maxFee: 0.001 },
	{ address: "0xbbbb...", maxFee: 0.0015 },
	{ address: "0xcccc...", maxFee: 0.0008 },
];

for (const integrator of integrators) {
	const { tx } = await perps.getCreateBuilderCodeIntegratorConfigTx({
		accountId: 123n,
		integratorAddress: integrator.address,
		maxTakerFee: integrator.maxFee,
	});

	// Execute each approval
	// await wallet.signAndExecuteTransaction({ transaction: tx });
}

// Verify integrator config after approval
async function verifyIntegratorApproval(
	accountId: PerpetualsAccountId,
	integratorAddress: SuiAddress,
) {
	const config = await perps.getBuilderCodeIntegratorConfig({
		accountId,
		integratorAddress,
	});

	if (config.exists) {
		console.log(`Integrator approved with max fee: ${config.maxTakerFee}`);
		return true;
	} else {
		console.log("Integrator not approved");
		return false;
	}
}

// Integrator onboarding flow
async function onboardUserForIntegrator(
	accountId: PerpetualsAccountId,
	integratorAddress: SuiAddress,
	proposedMaxFee: number,
) {
	// Check if already approved
	const existing = await perps.getBuilderCodeIntegratorConfig({
		accountId,
		integratorAddress,
	});

	if (existing.exists) {
		console.log(`Already approved with max fee: ${existing.maxTakerFee}`);

		if (existing.maxTakerFee >= proposedMaxFee) {
			console.log("Existing approval is sufficient");
			return null;
		}

		console.log("Need to update to higher max fee");
		// Note: User would need to remove and re-add
	}

	// Build approval transaction
	const { tx } = await perps.getCreateBuilderCodeIntegratorConfigTx({
		accountId,
		integratorAddress,
		maxTakerFee: proposedMaxFee,
	});

	return tx;
}

Use Cases:

1. Trading Platform Integration: Allow platforms to charge fees

2. Referral Programs: Enable fee-sharing with referrers

3. White-Label Solutions: Build branded trading interfaces with revenue share

4. API Access: Grant programmatic trading access with fee collection

---

getRemoveBuilderCodeIntegratorConfigTx

async getRemoveBuilderCodeIntegratorConfigTx(inputs: {
  accountId: PerpetualsAccountId;
  integratorAddress: SuiAddress;
}): Promise<SdkTransactionResponse>

Build a transaction to remove an integrator configuration.

What This Does: Removes an integrator's approval to collect fees on orders placed on behalf of the user. Once revoked:

• Integrator can no longer submit orders with integrator fees

• User can re-approve the integrator later if desired

• Existing accumulated fees can still be claimed by integrator

The transaction must be signed by the account owner.

Parameters:

• accountId: PerpetualsAccountId

  • User's perpetuals account ID

  • Account to remove integrator approval from

• integratorAddress: SuiAddress

  • Integrator's wallet address to revoke

Returns:

SdkTransactionResponse containing:

• tx: Transaction - Transaction ready for user to sign

Example:

// Revoke integrator approval
const { tx } = await perps.getRemoveBuilderCodeIntegratorConfigTx({
	accountId: 123n,
	integratorAddress:
		"0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
});

// User signs and executes
// const result = await wallet.signAndExecuteTransaction({ transaction: tx });

console.log("Integrator revocation transaction built");

// Verify removal
async function verifyIntegratorRemoval(
	accountId: PerpetualsAccountId,
	integratorAddress: SuiAddress,
) {
	const config = await perps.getBuilderCodeIntegratorConfig({
		accountId,
		integratorAddress,
	});

	if (!config.exists) {
		console.log("Integrator successfully removed");
		return true;
	} else {
		console.log("Integrator still has approval");
		return false;
	}
}

// Remove multiple integrators
const integratorsToRemove = ["0xaaaa...", "0xbbbb...", "0xcccc..."];

for (const integratorAddress of integratorsToRemove) {
	const { tx } = await perps.getRemoveBuilderCodeIntegratorConfigTx({
		accountId: 123n,
		integratorAddress,
	});

	// Execute each removal
	// await wallet.signAndExecuteTransaction({ transaction: tx });
	console.log(`Removed integrator: ${integratorAddress}`);
}

// Integrator management class
class IntegratorManager {
	constructor(
		private perps: Perpetuals,
		private accountId: PerpetualsAccountId,
	) {}

	async listApprovedIntegrators(): Promise<
		Array<{
			address: SuiAddress;
			maxTakerFee: number;
		}>
	> {
		// Note: Would need to track approved integrators separately
		// or query on-chain data
		return [];
	}

	async approveIntegrator(
		address: SuiAddress,
		maxFee: number,
	): Promise<Transaction> {
		const { tx } = await this.perps.getCreateBuilderCodeIntegratorConfigTx({
			accountId: this.accountId,
			integratorAddress: address,
			maxTakerFee: maxFee,
		});
		return tx;
	}

	async revokeIntegrator(address: SuiAddress): Promise<Transaction> {
		const { tx } = await this.perps.getRemoveBuilderCodeIntegratorConfigTx({
			accountId: this.accountId,
			integratorAddress: address,
		});
		return tx;
	}

	async revokeAllIntegrators(
		integrators: SuiAddress[],
	): Promise<Transaction[]> {
		const txs: Transaction[] = [];

		for (const address of integrators) {
			const { tx } =
				await this.perps.getRemoveBuilderCodeIntegratorConfigTx({
					accountId: this.accountId,
					integratorAddress: address,
				});
			txs.push(tx);
		}

		return txs;
	}
}

// Usage
const manager = new IntegratorManager(perps, 123n);
// const revokeTx = await manager.revokeIntegrator("0x...");

Use Cases:

1. Permission Management: Revoke untrusted integrators

2. Platform Migration: Remove old platform approvals

3. Security: Revoke access if integrator is compromised

4. Fee Negotiation: Remove to renegotiate terms

---

getCreateBuilderCodeIntegratorVaultTx

async getCreateBuilderCodeIntegratorVaultTx(inputs: {
  marketId: PerpetualsMarketId;
  integratorAddress: SuiAddress;
}): Promise<SdkTransactionResponse>

Build a transaction to initialize an integrator fee vault for a specific market.

What This Does: Creates a vault where an integrator's fees will accumulate for a specific market (clearing house). This is a one-time setup operation that must be performed before the integrator can claim fees from that market.

Workflow:

1. Integrator executes this transaction (once per market)

2. Vault is created on-chain for that market

3. As integrator submits orders, fees accumulate in the vault

4. Integrator can later claim fees using getClaimBuilderCodeIntegratorVaultFeesTx

The transaction must be signed by the integrator.

Parameters:

• marketId: PerpetualsMarketId

  • Market (clearing house) to create vault for

  • One vault needed per market

• integratorAddress: SuiAddress

  • Integrator's wallet address

  • Owner of the fee vault

Returns:

SdkTransactionResponse containing:

• tx: Transaction - Transaction ready for integrator to sign

Example:

// Create fee vault for a market
const { tx } = await perps.getCreateBuilderCodeIntegratorVaultTx({
	marketId: "0x1234...btcmarket",
	integratorAddress: "0x9876...integrator",
});

// Integrator signs and executes
// const result = await wallet.signAndExecuteTransaction({ transaction: tx });

console.log("Integrator vault creation transaction built");

// Create vaults for multiple markets
const markets = ["0x1111...btc", "0x2222...eth", "0x3333...sui"];

const integratorAddress = "0x9876...integrator";

for (const marketId of markets) {
	const { tx } = await perps.getCreateBuilderCodeIntegratorVaultTx({
		marketId,
		integratorAddress,
	});

	// Execute for each market
	// await wallet.signAndExecuteTransaction({ transaction: tx });
	console.log(`Created vault for market: ${marketId}`);
}

// Check if vault exists before creating
async function ensureIntegratorVault(
	marketId: PerpetualsMarketId,
	integratorAddress: SuiAddress,
) {
	try {
		// Try to fetch vault fees
		const vaults = await perps.getBuilderCodeIntegratorVaults({
			marketIds: [marketId],
			integratorAddress,
		});

		if (vaults.integratorVaults.length > 0) {
			console.log("Vault already exists");
			return null;
		}
	} catch (error) {
		// Vault doesn't exist, create it
	}

	const { tx } = await perps.getCreateBuilderCodeIntegratorVaultTx({
		marketId,
		integratorAddress,
	});

	return tx;
}

// Integrator setup workflow
async function setupIntegratorForMarkets(
	markets: PerpetualsMarketId[],
	integratorAddress: SuiAddress,
) {
	console.log(`Setting up integrator for ${markets.length} markets...`);

	const vaultTxs: Transaction[] = [];

	for (const marketId of markets) {
		const tx = await ensureIntegratorVault(marketId, integratorAddress);
		if (tx) {
			vaultTxs.push(tx);
		}
	}

	if (vaultTxs.length > 0) {
		console.log(`Need to create ${vaultTxs.length} vaults`);
		// Execute vault creation transactions
		// for (const tx of vaultTxs) {
		//   await wallet.signAndExecuteTransaction({ transaction: tx });
		// }
	} else {
		console.log("All vaults already exist");
	}
}

// Integrator onboarding helper
class IntegratorOnboarding {
	constructor(
		private perps: Perpetuals,
		private integratorAddress: SuiAddress,
	) {}

	async setupForAllMarkets(
		collateralCoinType: CoinType,
	): Promise<Transaction[]> {
		// Get all markets for collateral type
		const { markets } = await this.perps.getAllMarkets({
			collateralCoinType,
		});

		console.log(`Found ${markets.length} markets`);

		// Create vault for each market
		const txs: Transaction[] = [];
		for (const market of markets) {
			const { tx } =
				await this.perps.getCreateBuilderCodeIntegratorVaultTx({
					marketId: market.marketId,
					integratorAddress: this.integratorAddress,
				});
			txs.push(tx);
		}

		return txs;
	}
}

// Usage
const onboarding = new IntegratorOnboarding(perps, "0x9876...integrator");
// const setupTxs = await onboarding.setupForAllMarkets("0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC");

Use Cases:

1. Integrator Onboarding: Initialize fee collection infrastructure

2. Multi-Market Setup: Create vaults for all active markets

3. New Market Support: Add vault when new market launches

4. Platform Expansion: Enable fee collection across markets

---

getClaimBuilderCodeIntegratorVaultFeesTx

async getClaimBuilderCodeIntegratorVaultFeesTx(inputs: {
  marketId: PerpetualsMarketId;
  integratorAddress: SuiAddress;
  recipientAddress?: SuiAddress;
}): Promise<ApiPerpetualsBuilderCodesClaimIntegratorVaultFeesTxResponse>

Build a transaction to claim accumulated integrator fees from a vault.

What This Does: Allows an integrator to claim the fees they have earned from orders placed on behalf of users. Fees accumulate in a vault specific to each market and can be claimed at any time.

How Fees Work:

• Fees are proportional to taker volume generated by users' orders

• Integrator specifies fee when submitting orders (up to user-approved max)

• Fees accumulate automatically in the vault

• Can be claimed at any time by the integrator

Parameters:

• marketId: PerpetualsMarketId

  • Market to claim fees from

  • Must have a vault created via getCreateBuilderCodeIntegratorVaultTx

• integratorAddress: SuiAddress

  • Integrator's wallet address

  • Must be the vault owner

• recipientAddress (optional): SuiAddress

  • Address to receive claimed fees

  • If provided: fees automatically transferred to recipient

  • If omitted: coin output exposed as transaction argument for further use

Returns:

ApiPerpetualsBuilderCodesClaimIntegratorVaultFeesTxResponse containing:

• txKind: Transaction kind

• coinOutArg (optional): Transaction argument for the claimed coin

  • Only present if recipientAddress not provided

  • Can be used in subsequent transaction commands

Example:

// Claim fees with automatic transfer
const { tx } = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
	marketId: "0x1234...btcmarket",
	integratorAddress: "0x9876...integrator",
	recipientAddress: "0x5555...recipient",
});

// Integrator signs and executes
// const result = await wallet.signAndExecuteTransaction({ transaction: tx });

console.log("Fee claim transaction built with transfer");

// Claim fees as coin output for further use
const response = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
	marketId: "0x1234...btcmarket",
	integratorAddress: "0x9876...integrator",
	// No recipientAddress
});

// Use the coin in subsequent commands
const tx = response.tx;
if (response.coinOutArg) {
	// Can now use response.coinOutArg in transaction
	// tx.transferObjects([response.coinOutArg], recipientAddr);
	// or split, merge, etc.
}

// Claim from multiple markets
const markets = ["0x1111...btc", "0x2222...eth", "0x3333...sui"];
const integratorAddress = "0x9876...integrator";
const recipientAddress = "0x5555...recipient";

for (const marketId of markets) {
	// Check accumulated fees first
	const vaults = await perps.getBuilderCodeIntegratorVaults({
		marketIds: [marketId],
		integratorAddress,
	});

	const vault = vaults.integratorVaults[0];
	if (vault && vault.fees > 0) {
		console.log(`Claiming ${vault.fees} from ${marketId}...`);

		const { tx } = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
			marketId,
			integratorAddress,
			recipientAddress,
		});

		// Execute claim
		// await wallet.signAndExecuteTransaction({ transaction: tx });
	} else {
		console.log(`No fees to claim from ${marketId}`);
	}
}

// Automated fee claiming
async function claimAllFees(
	markets: PerpetualsMarketId[],
	integratorAddress: SuiAddress,
	recipientAddress: SuiAddress,
): Promise<{ claimed: number; total: number }> {
	// Get fee totals
	const vaults = await perps.getBuilderCodeIntegratorVaults({
		marketIds: markets,
		integratorAddress,
	});

	let totalFees = 0;
	let claimedCount = 0;

	for (const vault of vaults.integratorVaults) {
		totalFees += vault.fees;

		if (vault.fees > 0) {
			const { tx } = await perps.getClaimBuilderCodeIntegratorVaultFeesTx(
				{
					marketId: vault.marketId,
					integratorAddress,
					recipientAddress,
				},
			);

			// Execute claim
			// await wallet.signAndExecuteTransaction({ transaction: tx });
			claimedCount++;
		}
	}

	console.log(`Claimed fees from ${claimedCount} markets`);
	console.log(`Total fees: ${totalFees} collateral units`);

	return { claimed: claimedCount, total: totalFees };
}

// Compound fees (reinvest into vault)
async function compoundFeesToVault(
	marketId: PerpetualsMarketId,
	integratorAddress: SuiAddress,
	vaultId: ObjectId,
) {
	// Claim fees as coin output
	const { tx, coinOutArg } =
		await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
			marketId,
			integratorAddress,
			// No recipient - get coin output
		});

	if (!coinOutArg) {
		throw new Error("No coin output returned");
	}

	// Get vault for deposit
	const { vault } = await perps.getVault({ marketId: vaultId });

	// Add deposit command to same transaction
	const depositTx = await vault.getDepositTx({
		walletAddress: integratorAddress,
		depositCoinArg: coinOutArg,
		minLpAmountOut: 0n, // Accept any amount
		tx, // Extend the claim transaction
	});

	return depositTx;
}

// Fee claiming with threshold
async function claimFeesIfAboveThreshold(
	marketId: PerpetualsMarketId,
	integratorAddress: SuiAddress,
	recipientAddress: SuiAddress,
	minThreshold: number,
): Promise<boolean> {
	// Check accumulated fees
	const vaults = await perps.getBuilderCodeIntegratorVaults({
		marketIds: [marketId],
		integratorAddress,
	});

	const vault = vaults.integratorVaults[0];
	if (!vault || vault.fees < minThreshold) {
		console.log(
			`Fees (${vault?.fees || 0}) below threshold (${minThreshold})`,
		);
		return false;
	}

	console.log(`Claiming ${vault.fees} (above threshold ${minThreshold})`);

	const { tx } = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
		marketId,
		integratorAddress,
		recipientAddress,
	});

	// Execute claim
	// await wallet.signAndExecuteTransaction({ transaction: tx });

	return true;
}

Use Cases:

1. Revenue Collection: Claim earned fees from trading volume

2. Automated Claiming: Set up scheduled fee collection

3. Multi-Market Claiming: Collect fees across all markets

4. Fee Compounding: Reinvest fees into other protocols

---

getBuilderCodeIntegratorConfig

async getBuilderCodeIntegratorConfig(inputs: {
  accountId: PerpetualsAccountId;
  integratorAddress: SuiAddress;
}): Promise<ApiPerpetualsBuilderCodesIntegratorConfigResponse>

Fetch integrator configuration for a specific account and integrator.

What This Queries: Whether an integrator has been approved by an account to collect fees on orders placed on behalf of the account. If approved, returns the maximum taker fee the integrator is authorized to charge.

Use Cases:

• Verify integrator permissions before placing orders

• Display authorized integrators in UIs

• Validate requested fees don't exceed approved maximum

Parameters:

• accountId: PerpetualsAccountId

  • Account ID to check integrator approval for

• integratorAddress: SuiAddress

  • Integrator address to check

Returns:

ApiPerpetualsBuilderCodesIntegratorConfigResponse containing:

• exists: boolean - Whether integrator is approved

• maxTakerFee: number - Maximum fee if approved (otherwise may be 0 or undefined)

Example:

// Check if integrator is approved
const config = await perps.getBuilderCodeIntegratorConfig({
	accountId: 123n,
	integratorAddress: "0x9876...integrator",
});

if (config.exists) {
	console.log(`Integrator is approved`);
	console.log(`Max taker fee: ${config.maxTakerFee * 100}%`);
	console.log(`Max taker fee (bps): ${config.maxTakerFee * 10000}`);
} else {
	console.log("Integrator is not approved for this account");
}

// Validate fee before placing order
async function validateIntegratorFee(
	accountId: PerpetualsAccountId,
	integratorAddress: SuiAddress,
	requestedFee: number,
): Promise<boolean> {
	const config = await perps.getBuilderCodeIntegratorConfig({
		accountId,
		integratorAddress,
	});

	if (!config.exists) {
		console.error("Integrator not approved");
		return false;
	}

	if (requestedFee > config.maxTakerFee) {
		console.error(`Fee ${requestedFee} exceeds max ${config.maxTakerFee}`);
		return false;
	}

	console.log("Fee validation passed");
	return true;
}

// List all approved integrators for an account
// Note: Would need to track approved integrators separately
async function checkMultipleIntegrators(
	accountId: PerpetualsAccountId,
	integrators: SuiAddress[],
): Promise<
	Array<{
		address: SuiAddress;
		approved: boolean;
		maxFee?: number;
	}>
> {
	const results = [];

	for (const address of integrators) {
		const config = await perps.getBuilderCodeIntegratorConfig({
			accountId,
			integratorAddress: address,
		});

		results.push({
			address,
			approved: config.exists,
			maxFee: config.exists ? config.maxTakerFee : undefined,
		});
	}

	return results;
}

// Usage
const integrators = ["0xaaaa...", "0xbbbb...", "0xcccc..."];
const approvals = await checkMultipleIntegrators(123n, integrators);

console.log("Integrator Approvals:");
approvals.forEach((approval) => {
	if (approval.approved) {
		console.log(`  ✓ ${approval.address}: ${approval.maxFee! * 100}%`);
	} else {
		console.log(`  ✗ ${approval.address}: Not approved`);
	}
});

// Integrator dashboard helper
async function getIntegratorDashboard(
	accountIds: PerpetualsAccountId[],
	integratorAddress: SuiAddress,
) {
	const approvedAccounts = [];

	for (const accountId of accountIds) {
		const config = await perps.getBuilderCodeIntegratorConfig({
			accountId,
			integratorAddress,
		});

		if (config.exists) {
			approvedAccounts.push({
				accountId,
				maxFee: config.maxTakerFee,
			});
		}
	}

	console.log(`Integrator ${integratorAddress}:`);
	console.log(
		`  Approved accounts: ${approvedAccounts.length}/${accountIds.length}`,
	);

	if (approvedAccounts.length > 0) {
		const avgMaxFee =
			approvedAccounts.reduce((sum, acc) => sum + acc.maxFee, 0) /
			approvedAccounts.length;
		console.log(`  Average max fee: ${avgMaxFee * 100}%`);
	}

	return approvedAccounts;
}

Use Cases:

1. Permission Verification: Check approval before submitting orders

2. UI Display: Show approved integrators and their fee caps

3. Fee Validation: Ensure requested fees don't exceed approved max

4. Integrator Dashboard: Display approval status across accounts

---

getBuilderCodeIntegratorVaults

async getBuilderCodeIntegratorVaults(inputs: {
  marketIds: PerpetualsMarketId[];
  integratorAddress: SuiAddress;
}): Promise<ApiPerpetualsBuilderCodesIntegratorVaultsResponse>

Fetch accumulated integrator vault fees across multiple markets.

What This Queries: The total fees an integrator has earned and accumulated in their vaults across one or more markets. Integrators earn fees proportional to the taker volume generated by orders they submit on behalf of users.

How Fees Accumulate:

1. Integrator submits orders for users (who have approved them)

2. Orders execute and generate taker volume

3. Fees (percentage of volume) accumulate in per-market vaults

4. Integrator can claim anytime using getClaimBuilderCodeIntegratorVaultFeesTx

Parameters:

• marketIds: PerpetualsMarketId[]

  • Markets to query fees for

  • One vault exists per market

• integratorAddress: SuiAddress

  • Integrator's wallet address

Returns:

ApiPerpetualsBuilderCodesIntegratorVaultsResponse containing:

• integratorVaults: Array of vault data objects

  • One entry per market

  • Each object contains:

    • marketId: Market identifier

    • fees: Accumulated fees in collateral units

    • Other vault metadata

Example:

// Get fees across multiple markets
const vaultFees = await perps.getBuilderCodeIntegratorVaults({
	marketIds: ["0x1111...btc", "0x2222...eth", "0x3333...sui"],
	integratorAddress: "0x9876...integrator",
});

console.log(`Vault data for ${vaultFees.integratorVaults.length} markets:`);

for (const vault of vaultFees.integratorVaults) {
	console.log(`\nMarket: ${vault.marketId}`);
	console.log(`  Accumulated Fees: ${vault.fees} collateral units`);
}

// Calculate total claimable fees
const totalFees = vaultFees.integratorVaults.reduce(
	(sum, vault) => sum + vault.fees,
	0,
);

console.log(`\nTotal Claimable: ${totalFees} collateral units`);

// Find markets with claimable fees
const claimableVaults = vaultFees.integratorVaults.filter(
	(vault) => vault.fees > 0,
);

console.log(
	`\nMarkets with fees: ${claimableVaults.length}/${vaultFees.integratorVaults.length}`,
);

// Sort by fee amount
const sortedByFees = [...vaultFees.integratorVaults].sort(
	(a, b) => b.fees - a.fees,
);

console.log(`\nTop markets by fees:`);
sortedByFees.slice(0, 5).forEach((vault, index) => {
	console.log(`  ${index + 1}. ${vault.marketId}: ${vault.fees}`);
});

// Check all markets for an integrator
async function getAllIntegratorFees(
	collateralCoinType: CoinType,
	integratorAddress: SuiAddress,
) {
	// Get all markets
	const { markets } = await perps.getAllMarkets({
		collateralCoinType,
	});

	const marketIds = markets.map((m) => m.marketId);

	// Get fees for all markets
	const vaultFees = await perps.getBuilderCodeIntegratorVaults({
		marketIds,
		integratorAddress,
	});

	const totalFees = vaultFees.integratorVaults.reduce(
		(sum, vault) => sum + vault.fees,
		0,
	);

	const marketsWithFees = vaultFees.integratorVaults.filter(
		(v) => v.fees > 0,
	).length;

	return {
		totalFees,
		totalMarkets: markets.length,
		marketsWithFees,
		vaults: vaultFees.integratorVaults,
	};
}

// Usage
const allFees = await getAllIntegratorFees(
	"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
	"0x9876...integrator",
);

console.log(`Total fees across all markets: ${allFees.totalFees}`);
console.log(
	`Markets with fees: ${allFees.marketsWithFees}/${allFees.totalMarkets}`,
);

// Fee claiming strategy
async function claimFeesAboveThreshold(
	marketIds: PerpetualsMarketId[],
	integratorAddress: SuiAddress,
	recipientAddress: SuiAddress,
	minFeeThreshold: number,
) {
	const vaultFees = await perps.getBuilderCodeIntegratorVaults({
		marketIds,
		integratorAddress,
	});

	const claimableVaults = vaultFees.integratorVaults.filter(
		(v) => v.fees >= minFeeThreshold,
	);

	console.log(`Found ${claimableVaults.length} vaults above threshold`);

	for (const vault of claimableVaults) {
		console.log(`Claiming ${vault.fees} from ${vault.marketId}...`);

		const { tx } = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
			marketId: vault.marketId,
			integratorAddress,
			recipientAddress,
		});

		// Execute claim
		// await wallet.signAndExecuteTransaction({ transaction: tx });
	}

	const totalClaimed = claimableVaults.reduce((sum, v) => sum + v.fees, 0);

	return totalClaimed;
}

// Revenue analytics
async function getIntegratorRevenueAnalytics(
	marketIds: PerpetualsMarketId[],
	integratorAddress: SuiAddress,
) {
	const vaultFees = await perps.getBuilderCodeIntegratorVaults({
		marketIds,
		integratorAddress,
	});

	const stats = {
		totalFees: 0,
		totalVaults: vaultFees.integratorVaults.length,
		vaultsWithFees: 0,
		averageFeePerVault: 0,
		highestFeeVault: { marketId: "", fees: 0 },
	};

	for (const vault of vaultFees.integratorVaults) {
		stats.totalFees += vault.fees;
		if (vault.fees > 0) stats.vaultsWithFees++;
		if (vault.fees > stats.highestFeeVault.fees) {
			stats.highestFeeVault = {
				marketId: vault.marketId,
				fees: vault.fees,
			};
		}
	}

	stats.averageFeePerVault = stats.totalFees / stats.totalVaults;

	console.log("Revenue Analytics:");
	console.log(`  Total Fees: ${stats.totalFees}`);
	console.log(`  Vaults: ${stats.totalVaults}`);
	console.log(`  Vaults with Fees: ${stats.vaultsWithFees}`);
	console.log(`  Average per Vault: ${stats.averageFeePerVault.toFixed(2)}`);
	console.log(
		`  Highest Fee: ${stats.highestFeeVault.fees} (${stats.highestFeeVault.marketId})`,
	);

	return stats;
}

Use Cases:

1. Revenue Tracking: Monitor total earned fees

2. Fee Dashboard: Display claimable fees per market

3. Claiming Strategy: Identify which markets to claim from

4. Performance Analysis: Analyze fee generation across markets

---

WebSocket Methods

openUpdatesWebsocketStream

openUpdatesWebsocketStream(args: {
  onMessage: (env: PerpetualsWsUpdatesResponseMessage) => void;
  onOpen?: (ev: Event) => void;
  onError?: (ev: Event) => void;
  onClose?: (ev: CloseEvent) => void;
}): WebSocketController

Open the main updates websocket for real-time perpetuals data: /perpetuals/ws/updates.

What This Provides: A WebSocket stream that emits PerpetualsWsUpdatesResponseMessage envelopes and supports multiple subscription types. Returns a controller with convenience subscribe/unsubscribe functions.

Supported Subscription Types:

• market: Market state updates (prices, funding rates)

• user: User account updates (optionally including stop orders)

• oracle: Oracle price updates

• orderbook: Orderbook deltas (bids/asks changes)

• marketOrders: Public market trades/orders

• userOrders: User-specific trade/order events

• userCollateralChanges: User collateral change events

Parameters:

• onMessage: (env: PerpetualsWsUpdatesResponseMessage) => void

  • Handler for parsed messages from the websocket

  • Called whenever a message is received

  • Message type varies based on subscriptions

• onOpen (optional): (ev: Event) => void

  • Handler for the open event

  • Called when WebSocket connection establishes

• onError (optional): (ev: Event) => void

  • Handler for the error event

  • Called on WebSocket errors

• onClose (optional): (ev: CloseEvent) => void

  • Handler for the close event

  • Called when WebSocket closes

Returns:

WebSocketController object containing:

• ws: Underlying WebSocket instance

• Subscription helpers (all methods):

  • subscribeMarket({ marketId }) / unsubscribeMarket({ marketId })

  • subscribeUser({ accountId, withStopOrders }) / unsubscribeUser({ accountId, withStopOrders })

  • subscribeOracle({ marketId }) / unsubscribeOracle({ marketId })

  • subscribeOrderbook({ marketId }) / unsubscribeOrderbook({ marketId })

  • subscribeMarketOrders({ marketId }) / unsubscribeMarketOrders({ marketId })

  • subscribeUserOrders({ accountId }) / unsubscribeUserOrders({ accountId })

  • subscribeUserCollateralChanges({ accountId }) / unsubscribeUserCollateralChanges({ accountId })

• close(): Close the WebSocket

Example:

// Open WebSocket stream
const stream = perps.openUpdatesWebsocketStream({
	onMessage: (message) => {
		console.log("Received message:", message);

		// Handle different message types
		if ("market" in message) {
			console.log("Market update:", message.market);
		} else if ("orderbook" in message) {
			console.log("Orderbook delta:", message.orderbook);
		} else if ("trade" in message) {
			console.log("New trade:", message.trade);
		} else if ("user" in message) {
			console.log("User account update:", message.user);
		}
	},

	onOpen: () => {
		console.log("WebSocket connected!");
	},

	onError: (error) => {
		console.error("WebSocket error:", error);
	},

	onClose: (event) => {
		console.log("WebSocket closed:", event.code, event.reason);
	},
});

// Subscribe to market updates
const marketId = "0x1234...";
stream.subscribeMarket({ marketId });

// Subscribe to orderbook
stream.subscribeOrderbook({ marketId });

// Subscribe to public trades
stream.subscribeMarketOrders({ marketId });

// Subscribe to oracle prices
stream.subscribeOracle({ marketId });

// Subscribe to user account (with stop orders)
const accountId = 123n;
stream.subscribeUser({
	accountId,
	withStopOrders: {
		walletAddress:
			"0x0000000000000000000000000000000000000000000000000000000000000123",
		bytes: "...", // Signed message bytes
		signature: "...", // Signature
	},
});

// Subscribe to user orders only
stream.subscribeUserOrders({ accountId });

// Subscribe to user collateral changes
stream.subscribeUserCollateralChanges({ accountId });

// Unsubscribe when no longer needed
stream.unsubscribeMarket({ marketId });
stream.unsubscribeOrderbook({ marketId });

// Close connection
stream.close();

// Complete trading interface example
class RealtimeMarketData {
	private stream: any;
	private latestPrice: number = 0;
	private orderbook: any = { bids: [], asks: [] };

	constructor(
		private perps: Perpetuals,
		private marketId: PerpetualsMarketId,
	) {}

	connect() {
		this.stream = this.perps.openUpdatesWebsocketStream({
			onMessage: (message) => {
				this.handleMessage(message);
			},
			onOpen: () => {
				console.log("Connected to real-time data");
				// Subscribe to needed data
				this.stream.subscribeMarket({ marketId: this.marketId });
				this.stream.subscribeOrderbook({ marketId: this.marketId });
				this.stream.subscribeMarketOrders({ marketId: this.marketId });
			},
			onError: (error) => {
				console.error("WebSocket error:", error);
				// Implement reconnection logic
			},
			onClose: () => {
				console.log("Disconnected from real-time data");
				// Implement reconnection logic
			},
		});
	}

	handleMessage(message: any) {
		if ("market" in message) {
			this.latestPrice = message.market.indexPrice;
			this.onPriceUpdate(this.latestPrice);
		} else if ("orderbook" in message) {
			// Update orderbook with delta
			this.updateOrderbook(message.orderbook);
			this.onOrderbookUpdate(this.orderbook);
		} else if ("trade" in message) {
			this.onNewTrade(message.trade);
		}
	}

	updateOrderbook(delta: any) {
		// Apply orderbook delta
		// Implementation depends on delta format
	}

	onPriceUpdate(price: number) {
		console.log(`Price update: ${price}`);
		// Update UI
	}

	onOrderbookUpdate(orderbook: any) {
		console.log("Orderbook updated");
		// Update UI
	}

	onNewTrade(trade: any) {
		console.log("New trade:", trade);
		// Update trade history UI
	}

	disconnect() {
		if (this.stream) {
			this.stream.close();
		}
	}
}

// Multi-market monitoring
class MultiMarketMonitor {
	private stream: any;
	private marketData: Map<string, any> = new Map();

	constructor(
		private perps: Perpetuals,
		private marketIds: PerpetualsMarketId[],
	) {}

	start() {
		this.stream = this.perps.openUpdatesWebsocketStream({
			onMessage: (message) => {
				if ("market" in message) {
					this.marketData.set(
						message.market.marketId,
						message.market,
					);
					this.displayMarkets();
				}
			},
			onOpen: () => {
				// Subscribe to all markets
				for (const marketId of this.marketIds) {
					this.stream.subscribeMarket({ marketId });
				}
			},
		});
	}

	displayMarkets() {
		console.clear();
		console.log("=== Market Monitor ===");
		for (const [marketId, data] of this.marketData) {
			console.log(`${marketId}:`);
			console.log(`  Price: ${data.indexPrice}`);
			console.log(`  Funding: ${data.fundingRate}`);
		}
	}

	stop() {
		this.stream?.close();
	}
}

// Reconnection logic
function createRobustWebSocket(perps: Perpetuals) {
	let stream: any;
	let reconnectAttempts = 0;
	const MAX_RECONNECT_ATTEMPTS = 5;
	const RECONNECT_DELAY = 5000; // 5 seconds

	function connect() {
		stream = perps.openUpdatesWebsocketStream({
			onMessage: (message) => {
				// Reset reconnect counter on successful message
				reconnectAttempts = 0;
				// Handle message
			},
			onOpen: () => {
				console.log("WebSocket connected");
				reconnectAttempts = 0;
				// Subscribe to channels
			},
			onError: (error) => {
				console.error("WebSocket error:", error);
			},
			onClose: (event) => {
				console.log("WebSocket closed");

				if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
					reconnectAttempts++;
					console.log(
						`Reconnecting in ${RECONNECT_DELAY}ms (attempt ${reconnectAttempts})`,
					);
					setTimeout(connect, RECONNECT_DELAY);
				} else {
					console.error("Max reconnection attempts reached");
				}
			},
		});
	}

	connect();

	return {
		stream,
		close: () => stream?.close(),
	};
}

Use Cases:

1. Live Trading Interface: Real-time price and orderbook updates

2. Market Monitoring: Track multiple markets simultaneously

3. Trading Bots: Receive order and position updates

4. Analytics Dashboard: Real-time market data visualization

---

openMarketCandlesWebsocketStream

openMarketCandlesWebsocketStream(args: {
  marketId: PerpetualsMarketId;
  intervalMs: number;
  onMessage: (msg: PerpetualsWsCandleResponseMessage) => void;
  onOpen?: (ev: Event) => void;
  onError?: (ev: Event) => void;
  onClose?: (ev: CloseEvent) => void;
}): WebSocketController

Open a market-candles websocket stream for a single market/interval: /perpetuals/ws/market-candles/{market_id}/{interval_ms}.

What This Provides: A WebSocket stream that emits PerpetualsWsCandleResponseMessage messages, typically containing the latest candle for the specified interval.

Parameters:

• marketId: PerpetualsMarketId

  • Market ID to subscribe to

  • Only candles for this market are emitted

• intervalMs: number

  • Candle interval in milliseconds

  • Common intervals:

    • 60000 = 1 minute

    • 300000 = 5 minutes

    • 900000 = 15 minutes

    • 3600000 = 1 hour

    • 86400000 = 1 day

• onMessage: (msg: PerpetualsWsCandleResponseMessage) => void

  • Handler for incoming candle updates

  • Called when a new candle is available

• onOpen (optional): (ev: Event) => void

  • Handler for the open event

• onError (optional): (ev: Event) => void

  • Handler for the error event

• onClose (optional): (ev: CloseEvent) => void

  • Handler for the close event

Returns:

WebSocketController object containing:

• ws: Underlying WebSocket instance

• close(): Close the WebSocket

Example:

// Stream 1-minute candles
const stream = perps.openMarketCandlesWebsocketStream({
	marketId: "0x1234...",
	intervalMs: 60000, // 1 minute
	onMessage: ({ lastCandle }) => {
		console.log("New candle:", lastCandle);
		console.log(`  Time: ${new Date(lastCandle.timestamp)}`);
		console.log(`  Open: ${lastCandle.open}`);
		console.log(`  High: ${lastCandle.high}`);
		console.log(`  Low: ${lastCandle.low}`);
		console.log(`  Close: ${lastCandle.close}`);
		console.log(`  Volume: ${lastCandle.volume}`);
	},
	onOpen: () => {
		console.log("Candle stream connected");
	},
	onError: (error) => {
		console.error("Candle stream error:", error);
	},
	onClose: () => {
		console.log("Candle stream closed");
	},
});

// Close when done
// stream.close();

// Live chart updater
class LiveChart {
	private stream: any;
	private candles: any[] = [];

	constructor(
		private perps: Perpetuals,
		private marketId: PerpetualsMarketId,
		private intervalMs: number,
	) {}

	start() {
		// Fetch historical candles first
		this.loadHistoricalCandles();

		// Then start live stream
		this.stream = this.perps.openMarketCandlesWebsocketStream({
			marketId: this.marketId,
			intervalMs: this.intervalMs,
			onMessage: ({ lastCandle }) => {
				this.updateCandle(lastCandle);
				this.renderChart();
			},
			onOpen: () => {
				console.log("Live chart connected");
			},
		});
	}

	async loadHistoricalCandles() {
		const now = Date.now();
		const oneDayAgo = now - 86400000;

		const history = await this.perps.getMarketCandleHistory({
			marketId: this.marketId,
			fromTimestamp: oneDayAgo,
			toTimestamp: now,
			intervalMs: this.intervalMs,
		});

		this.candles = history.candles;
		this.renderChart();
	}

	updateCandle(newCandle: any) {
		const lastCandle = this.candles[this.candles.length - 1];

		if (lastCandle && lastCandle.timestamp === newCandle.timestamp) {
			// Update existing candle
			this.candles[this.candles.length - 1] = newCandle;
		} else {
			// New candle
			this.candles.push(newCandle);

			// Keep only last 100 candles
			if (this.candles.length > 100) {
				this.candles.shift();
			}
		}
	}

	renderChart() {
		// Update chart visualization
		console.log(`Chart updated: ${this.candles.length} candles`);
	}

	stop() {
		this.stream?.close();
	}
}

// Usage
const chart = new LiveChart(perps, "0x1234...", 300000); // 5-min candles
chart.start();

// Multiple timeframe monitoring
const timeframes = [
	{ interval: 60000, label: "1m" },
	{ interval: 300000, label: "5m" },
	{ interval: 3600000, label: "1h" },
];

const streams = timeframes.map((tf) => {
	return perps.openMarketCandlesWebsocketStream({
		marketId: "0x1234...",
		intervalMs: tf.interval,
		onMessage: ({ lastCandle }) => {
			console.log(`[${tf.label}] ${lastCandle.close}`);
		},
	});
});

// Close all streams
// streams.forEach(s => s.close());

// Price alert system
class PriceAlertSystem {
	private stream: any;
	private alerts: Array<{
		price: number;
		condition: "above" | "below";
		triggered: boolean;
	}> = [];

	constructor(
		private perps: Perpetuals,
		private marketId: PerpetualsMarketId,
	) {}

	addAlert(price: number, condition: "above" | "below") {
		this.alerts.push({ price, condition, triggered: false });
		console.log(`Alert added: ${condition} ${price}`);
	}

	start() {
		this.stream = this.perps.openMarketCandlesWebsocketStream({
			marketId: this.marketId,
			intervalMs: 60000, // Check every minute
			onMessage: ({ lastCandle }) => {
				this.checkAlerts(lastCandle.close);
			},
		});
	}

	checkAlerts(currentPrice: number) {
		for (const alert of this.alerts) {
			if (alert.triggered) continue;

			const triggered =
				(alert.condition === "above" && currentPrice > alert.price) ||
				(alert.condition === "below" && currentPrice < alert.price);

			if (triggered) {
				alert.triggered = true;
				this.onAlertTriggered(alert, currentPrice);
			}
		}
	}

	onAlertTriggered(alert: any, currentPrice: number) {
		console.log(
			`🚨 ALERT: Price ${currentPrice} is ${alert.condition} ${alert.price}`,
		);
		// Send notification, email, etc.
	}

	stop() {
		this.stream?.close();
	}
}

// Usage
const alertSystem = new PriceAlertSystem(perps, "0x1234...");
alertSystem.addAlert(100, "above");
alertSystem.addAlert(95, "below");
alertSystem.start();

Use Cases:

1. Live Charts: Real-time price chart updates

2. Price Alerts: Trigger notifications on price movements

3. Multi-Timeframe Analysis: Monitor multiple intervals simultaneously

4. Trading Bots: React to candle closes for strategy execution

---

Static Helper Methods

These methods provide utility functions for price/size conversion and order parsing.

positionSide

static positionSide(inputs: {
  baseAssetAmount: number;
}): PerpetualsOrderSide

Determine the logical order side (Bid/Ask) from a signed base asset amount.

Logic:

• Positive or zero amount = Bid (long position)

• Negative amount = Ask (short position)

Parameters:

• baseAssetAmount: number

  • Position base size (signed)

  • Positive = long, Negative = short

Returns:

• PerpetualsOrderSide.Bid for long positions

• PerpetualsOrderSide.Ask for short positions

Example:

// Long position
const longSide = Perpetuals.positionSide({ baseAssetAmount: 100 });
console.log(longSide); // PerpetualsOrderSide.Bid

// Short position
const shortSide = Perpetuals.positionSide({ baseAssetAmount: -50 });
console.log(shortSide); // PerpetualsOrderSide.Ask

// Zero (neutral)
const neutralSide = Perpetuals.positionSide({ baseAssetAmount: 0 });
console.log(neutralSide); // PerpetualsOrderSide.Bid

// Use in trading logic
function getClosingSide(position: {
	baseAssetAmount: number;
}): PerpetualsOrderSide {
	const currentSide = Perpetuals.positionSide({
		baseAssetAmount: position.baseAssetAmount,
	});

	// To close, trade opposite side
	return currentSide === PerpetualsOrderSide.Bid
		? PerpetualsOrderSide.Ask
		: PerpetualsOrderSide.Bid;
}

---

orderPriceFromEvent

static orderPriceFromEvent(inputs: {
  orderEvent: FilledTakerOrderEvent;
}): number

Compute the effective trade price from a FilledTakerOrderEvent.

Formula:

price = quoteAssetDelta / baseAssetDelta

Parameters:

• orderEvent: FilledTakerOrderEvent

  • Filled taker order event containing deltas

Returns:

• Trade price as a number

Example:

const orderEvent = {
	baseAssetDelta: 1.5,
	quoteAssetDelta: 150,
	// ... other fields
};

const price = Perpetuals.orderPriceFromEvent({ orderEvent });
console.log(`Order filled at: $${price}`); // $100

// Calculate slippage
const expectedPrice = 99.5;
const actualPrice = Perpetuals.orderPriceFromEvent({ orderEvent });
const slippage = ((actualPrice - expectedPrice) / expectedPrice) * 100;
console.log(`Slippage: ${slippage.toFixed(2)}%`);

---

orderPriceFromOrderId

static orderPriceFromOrderId(inputs: {
  orderId: PerpetualsOrderId;
}): number

Extract the floating-point price from an encoded order ID.

Implementation:

• Uses PerpetualsOrderUtils.price() to extract fixed-point price

• Converts to float using orderPriceToPrice()

Parameters:

• orderId: PerpetualsOrderId

  • Encoded order ID (bigint)

Returns:

• Price as a floating-point number

Example:

const orderId = 123456789012345678n;

const price = Perpetuals.orderPriceFromOrderId({ orderId });
console.log(`Order price: $${price}`);

// Parse multiple orders
const orderIds = [123n, 456n, 789n];
const prices = orderIds.map((orderId) =>
	Perpetuals.orderPriceFromOrderId({ orderId }),
);
console.log("Order prices:", prices);

---

priceToOrderPrice

static priceToOrderPrice(inputs: {
  price: number;
}): PerpetualsOrderPrice

Convert a floating-point price to fixed-point order price using 9 decimal places of precision.

Precision: 9 decimals (multiply by 1e9)

Parameters:

• price: number

  • Price as a float

Returns:

• Fixed-point order price (bigint)

Example:

const price = 100.5;
const orderPrice = Perpetuals.priceToOrderPrice({ price });
console.log(orderPrice); // 100500000000n

// Round trip
const backToFloat = Perpetuals.orderPriceToPrice({ orderPrice });
console.log(backToFloat); // 100.5

// Precision example
const precisePrice = 100.123456789;
const orderPrice2 = Perpetuals.priceToOrderPrice({ price: precisePrice });
console.log(orderPrice2); // 100123456789n

---

orderPriceToPrice

static orderPriceToPrice(inputs: {
  orderPrice: PerpetualsOrderPrice;
}): number

Convert a fixed-point order price to floating-point.

Parameters:

• orderPrice: PerpetualsOrderPrice

  • Fixed-point order price (bigint with 9 decimals)

Returns:

• Price as a float

Example:

const orderPrice = 100500000000n;
const price = Perpetuals.orderPriceToPrice({ orderPrice });
console.log(price); // 100.5

// Convert array of order prices
const orderPrices = [100500000000n, 99500000000n, 101000000000n];
const prices = orderPrices.map((op) =>
	Perpetuals.orderPriceToPrice({ orderPrice: op }),
);
console.log(prices); // [100.5, 99.5, 101]

---

lotOrTickSizeToNumber

static lotOrTickSizeToNumber(lotOrTickSize: bigint): number

Convert fixed-point lot/tick size (9 decimals) to a number.

Parameters:

• lotOrTickSize: bigint

  • Fixed-point size (9 decimal precision)

Returns:

• Floating-point size

Example:

const lotSize = 1000000000n; // 1.0
const size = Perpetuals.lotOrTickSizeToNumber(lotSize);
console.log(size); // 1

const tickSize = 500000000n; // 0.5
const tick = Perpetuals.lotOrTickSizeToNumber(tickSize);
console.log(tick); // 0.5

---

lotOrTickSizeToBigInt

static lotOrTickSizeToBigInt(lotOrTickSize: number): bigint

Convert floating-point lot/tick size to fixed-point representation (9 decimals).

Parameters:

• lotOrTickSize: number

  • Floating-point size

Returns:

• Fixed-point size (bigint)

Example:

const size = 1.5;
const lotSize = Perpetuals.lotOrTickSizeToBigInt(size);
console.log(lotSize); // 1500000000n

// Round trip
const backToFloat = Perpetuals.lotOrTickSizeToNumber(lotSize);
console.log(backToFloat); // 1.5

---

orderIdToSide

static orderIdToSide(orderId: PerpetualsOrderId): PerpetualsOrderSide

Infer the order side from an encoded order ID.

Implementation: Uses PerpetualsOrderUtils.isAsk() to determine side.

Parameters:

• orderId: PerpetualsOrderId

  • Encoded order ID

Returns:

• PerpetualsOrderSide.Ask if ask order

• PerpetualsOrderSide.Bid if bid order

Example:

const orderId = 123456789n;
const side = Perpetuals.orderIdToSide(orderId);

if (side === PerpetualsOrderSide.Bid) {
	console.log("Buy order");
} else {
	console.log("Sell order");
}

// Parse multiple orders
const orders = [123n, 456n, 789n];
const sides = orders.map((id) => Perpetuals.orderIdToSide(id));

---

eventTypeForCollateral

static eventTypeForCollateral(inputs: {
  eventType: string;
  collateralCoinType: CoinType;
}): string

Construct a collateral-specialized Move event type string.

What This Does: Many Move events are generic over a collateral coin type. This helper appends <collateralCoinType> to a base eventType.

Parameters:

• eventType: string

  • Base event type without type parameters

• collateralCoinType: CoinType

  • Collateral coin type

Returns:

• Fully-qualified event type string

Example:

const eventType = Perpetuals.eventTypeForCollateral({
	eventType: "0x123::perpetuals::OrderFilled",
	collateralCoinType:
		"0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
});

console.log(eventType);
// "0x123::perpetuals::OrderFilled<0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC>"

// Use in event filtering
async function fetchOrderFilledEvents(
	marketId: PerpetualsMarketId,
	collateralCoinType: CoinType,
) {
	const eventType = Perpetuals.eventTypeForCollateral({
		eventType: "0xPACKAGE::perpetuals::OrderFilled",
		collateralCoinType,
	});

	// Use eventType to query events from Sui
	// const events = await provider.queryEvents({ MoveEventType: eventType });

	return eventType;
}