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

• Builder-code approvals and rebate tooling

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 = await Aftermath.create({ network: "MAINNET" });

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: Use "MAINNET" for Aftermath Perpetuals

    • 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 = await Aftermath.create({ network: "MAINNET" });
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) {
	const fundingRate =
		market.indexPrice !== 0
			? market.marketState.premiumTwap / market.indexPrice
			: 0;
	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 (premiumTwap/indexPrice): ${fundingRate * 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.indexPrice !== 0
		? market.marketState.premiumTwap / market.indexPrice
		: 0;
const timeToFunding = market.timeUntilNextFundingMs();
console.log(`Funding Rate (premiumTwap/indexPrice): ${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 production route returns marketDatas[], and the SDK constructs each PerpetualsMarket from marketDatas[].market. Static metadata is nullable, including displayName. The current OpenAPI response component for this route is stale and incorrectly describes orderbooks.

Parameters:

• marketIds: PerpetualsMarketId[]

  • Array of market object IDs to fetch

  • Can include any number of market IDs

  • Do not depend on input order; current market responses are sorted by symbol

Returns:

Object containing:

• markets: PerpetualsMarket[]

  • Array of wrapped market instances

  • Match returned markets by marketId, not array position

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

---

Dynamic Vault Configuration

getVaultsConfig

getVaultsConfig(abortSignal?: AbortSignal): Promise<PerpetualsVaultsConfig>

Fetches the current deployment-driven vault limits from POST /api/perpetuals/vaults/config. The request sends {}. Integer-like values return as JavaScript bigint; decimal limits remain numbers.

const config = await perps.getVaultsConfig();
console.log(config.maxLockPeriodMs, config.maxMarketsInVault);

Use this method instead of hard-coding lock periods, minimum deposits, market counts, or pending-order limits. PerpetualsVault.constants has been removed.

---

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

---

getAdminAccountCaps

async getAdminAccountCaps(
  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)

• getAdminAccountCaps: 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.getAdminAccountCaps({
	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.getAdminAccountCaps({
	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.getAdminAccountCaps({
			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

---

getOwnedVaultAssistantCaps

Fetches vault assistant capabilities owned by a wallet. These caps let an agent wallet construct supported vault-account transactions without receiving owner withdrawal authority.

---

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

• resolution: PerpetualsCandleResolution

  • Candle interval as a timeframe label

  • Supported values: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 3d, 1w, and 1mo

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;

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

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

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

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

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

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 recentHistory = await perps.getMarketCandleHistory({
  marketId: "0x1234...abcd",
  fromTimestamp: now - 3600000,
  toTimestamp: now,
  resolution: "1m",
});

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

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

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

const timeframes = ["1m", "5m", "1h", "1d"] as const;

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

  console.log(`${resolution} 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

---

getMarketFundingHistory

Fetch historical funding data for a market using the current market/funding-history endpoint. Funding and candle timestamps are milliseconds.

---

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

---

getGrantAgentWalletTx

Builds an account-level agent-wallet grant transaction. It accepts either an existing numeric accountId or the deferred arguments returned by getCreateAccountTx({ deferShare: true }).

getShareAccountTx

Finalizes deferred account creation by consuming accountArg, adminCapArg, sharePolicyArg, and collateralCoinType. Use it after composing any grant or cap-transfer commands into the same PTB.

---

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

---

Rebate Methods

getCurrentRebateRewards

Calculates current-epoch maker and taker reward allocations.

getCsvRebates

Returns a CSV rebate report and supports owner-level aggregation.

getReferralCsvRebates

Returns the referral rebate CSV.

---

Builder Code Integration Methods

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

1. Register once globally through the native API

2. Get users to approve them as integrators

3. Submit orders on behalf of users with integrator fees

Want to learn more about Builder Codes? Read more.

One-Time Integrator Registration

The v3 SDK does not expose a high-level registration method. Register through the native API:

POST /api/perpetuals/builder-codes/transactions/create-integrator-registration
Content-Type: application/json

{}

Registration is global rather than per market. The transaction sender is the integrator, and the protocol assigns a numeric integratorId.

---

getCreateBuilderCodeIntegratorConfigTx

async getCreateBuilderCodeIntegratorConfigTx(inputs: {
  accountId: PerpetualsAccountId;
  integratorId: number;
  maxIntegratorFee: 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 the maximum integrator fee that can be charged.

Parameters:

• accountId: User's numeric perpetuals account ID

• integratorId: Numeric ID assigned during global integrator registration

• maxIntegratorFee: Maximum additional fee the integrator can charge

  • Example: 0.0005 = 0.05% = 5 basis points

Example:

const { tx } = await perps.getCreateBuilderCodeIntegratorConfigTx({
  accountId: 123n,
  integratorId: 1,
  maxIntegratorFee: 0.0005,
});

The transaction must be signed by the account owner.

---

getRemoveBuilderCodeIntegratorConfigTx

async getRemoveBuilderCodeIntegratorConfigTx(inputs: {
  accountId: PerpetualsAccountId;
  integratorId: number;
}): Promise<SdkTransactionResponse>

Build a transaction to remove an integrator configuration. Once revoked, orders for that account can no longer charge a fee for that integratorId.

Example:

const { tx } = await perps.getRemoveBuilderCodeIntegratorConfigTx({
  accountId: 123n,
  integratorId: 1,
});

Only the account owner can remove an integrator approval.

---

getBuilderCodeIntegratorConfig

async getBuilderCodeIntegratorConfig(inputs: {
  accountId: PerpetualsAccountId;
  integratorId: number;
}): Promise<ApiPerpetualsBuilderCodesIntegratorConfigResponse>

Fetch integrator configuration for a specific account and integrator.

Returns:

• exists: Whether the integrator is approved

• maxIntegratorFee: Maximum fee if approved; otherwise null

Example:

const config = await perps.getBuilderCodeIntegratorConfig({
  accountId: 123n,
  integratorId: 1,
});

---

Adding Builder Codes to Orders

Supported native order builders accept:

builderCode: {
  integratorId: 1,
  integratorFee: 0.0005,
}

The per-order integratorFee cannot exceed the user's approved maxIntegratorFee. SL/TP and stop orders can carry their own builder code independently of the parent order.

The previous per-market integrator vaults and fee-claim flow have been removed. Do not use getCreateBuilderCodeIntegratorVaultTx, getClaimBuilderCodeIntegratorVaultFeesTx, or getBuilderCodeIntegratorVaults against the current service.

---

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.

For raw wire-level details, see the dedicated WebSockets page. For account and execution streams, prefer these SDK helpers over hand-rolled JSON because the helper methods encapsulate the current subscription payloads and optional auth material.

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

• topOfOrderbook: Bucketed top-of-book snapshots

• marketCandles: Live candles using timeframe labels

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 })

  • subscribeTopOfOrderbook({ marketId, priceBucketSize, bucketsNumber }) / matching unsubscribe

  • subscribeMarketCandles({ marketId, interval }) / matching unsubscribe

• close(): Close the WebSocket

Example:

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

		// Route on the top-level envelope key.
		const [streamType, payload] = Object.entries(message)[0] ?? [];
		if (!streamType) return;

		if ("market" in message) {
			console.log("Market update:", message.market);
		} else if ("orderbook" in message) {
			console.log("Orderbook delta:", message.orderbook);
		} else if ("oracle" in message) {
			console.log("Oracle update:", message.oracle);
		} else {
			console.log(`Other websocket update [${streamType}]:`, payload);
		}
	},

	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: "...", // Base64 of Aftermath Terms and Conditions
		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) {
		const [streamType, payload] = Object.entries(message)[0] ?? [];
		if (!streamType) return;

		if (streamType === "market") {
			this.latestPrice = payload.indexPrice;
			this.onPriceUpdate(this.latestPrice);
		} else if (streamType === "orderbook") {
			// Update orderbook with delta
			this.updateOrderbook(payload);
			this.onOrderbookUpdate(this.orderbook);
		} else {
			this.onAuxUpdate(streamType, payload);
		}
	}

	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
	}

	onAuxUpdate(streamType: string, payload: any) {
		console.log(`Aux update [${streamType}]:`, payload);
		// Handle oracle, execution, or account-scoped updates as needed.
	}

	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.objectId,
						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) {
			const fundingRate =
				typeof data.marketState?.premiumTwap === "number" &&
				typeof data.indexPrice === "number" &&
				data.indexPrice !== 0
					? data.marketState.premiumTwap / data.indexPrice
					: undefined;
			console.log(`${marketId}:`);
			console.log(`  Price: ${data.indexPrice}`);
			console.log(
				`  Funding (premiumTwap/indexPrice): ${fundingRate !== undefined ? `${(fundingRate * 100).toFixed(4)}%` : "n/a"}`,
			);
		}
	}

	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;
  interval: PerpetualsCandleResolution;
  onMessage: (msg: PerpetualsWsCandleResponseMessage) => void;
  onOpen?: (ev: Event) => void;
  onError?: (ev: Event) => void;
  onClose?: (ev: CloseEvent) => void;
}): WebSocketController

This helper connects to the unified /api/perpetuals/ws/updates socket and subscribes with marketCandles. The old dedicated /ws/market-candles/{market_id}/{interval_ms} route no longer exists.

const stream = perps.openMarketCandlesWebsocketStream({
  marketId: "0x...",
  interval: "1m",
  onMessage: ({ lastCandle }) => console.log(lastCandle),
});

Authenticated user subscriptions use the same reusable terms signature as stop-order and TWAP reads. User update payloads can include both stopOrders and twapOrders.

Use subscribeMarketCandles({ marketId, interval }) on the controller returned by openUpdatesWebsocketStream when you want candles multiplexed with other subscriptions.

---

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;
}