User

User account management and position tracking for Drift Protocol v2

User

The User class provides methods for managing individual user accounts, tracking positions, calculating margins, and analyzing account health.

Constructor

new User(config: UserConfig)

config · UserConfig · required

Configuration object for initializing the User

Show properties

driftClient · DriftClient · required

DriftClient instance

userAccountPublicKey · PublicKey · required

Public key of the user account

accountSubscription · UserSubscriptionConfig

Account subscription configuration

Subscription Methods

subscribe

Subscribes to user account state updates.

await user.subscribe(userAccount?: UserAccount): Promise<boolean>

userAccount · UserAccount

Optional pre-fetched user account data

return · Promise<boolean>

Returns true if subscription was successful

unsubscribe

Unsubscribes from user account updates.

await user.unsubscribe(): Promise<void>

fetchAccounts

Forces a fetch of fresh account data from RPC.

await user.fetchAccounts(): Promise<void>

Account Data Methods

getUserAccount

Returns the current user account data.

user.getUserAccount(): UserAccount

return · UserAccount

User account containing positions, orders, and settings

getUserAccountAndSlot

Returns user account data with the slot number.

user.getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined

return · DataAndSlot<UserAccount> | undefined

User account data with slot information

exists

Checks if the user account exists on-chain.

await user.exists(): Promise<boolean>

return · Promise<boolean>

Returns true if the account exists

Position Methods

getPerpPosition

Returns the user’s position for a specific perpetual market.

user.getPerpPosition(marketIndex: number): PerpPosition | undefined

marketIndex · number · required

Perpetual market index

return · PerpPosition | undefined

Perpetual position data or undefined if no position exists

getSpotPosition

Returns the user’s position for a specific spot market.

user.getSpotPosition(marketIndex: number): SpotPosition | undefined

marketIndex · number · required

Spot market index

return · SpotPosition | undefined

Spot position data or undefined if no position exists

getActivePerpPositions

Returns all active perpetual positions.

user.getActivePerpPositions(): PerpPosition[]

return · PerpPosition[]

Array of active perpetual positions

getActiveSpotPositions

Returns all active spot positions.

user.getActiveSpotPositions(): SpotPosition[]

return · SpotPosition[]

Array of active spot positions

getTokenAmount

Returns the token amount for a spot market position in the token’s native precision.

user.getTokenAmount(marketIndex: number): BN

marketIndex · number · required

Spot market index

return · BN

Token amount (positive for deposits, negative for borrows)

Order Methods

getOrder

Returns an order by its order ID.

user.getOrder(orderId: number): Order | undefined

orderId · number · required

Order ID to retrieve

return · Order | undefined

Order data or undefined if not found

getOrderByUserOrderId

Returns an order by its user-defined order ID.

user.getOrderByUserOrderId(userOrderId: number): Order | undefined

userOrderId · number · required

User-defined order ID

return · Order | undefined

Order data or undefined if not found

getOpenOrders

Returns all open orders.

user.getOpenOrders(): Order[]

return · Order[]

Array of open orders

Margin & Collateral Methods

getFreeCollateral

Calculates free collateral available for trading.

user.getFreeCollateral(
  marginCategory?: MarginCategory,
  enterHighLeverageMode?: boolean,
  perpMarketIndex?: number
): BN

marginCategory · MarginCategory · default: "Initial"

Margin category: ‘Initial’ or ‘Maintenance’

enterHighLeverageMode · boolean · default: false

Whether to calculate for high leverage mode

perpMarketIndex · number

Specific perp market index for isolated margin calculation

return · BN

Free collateral in USDC precision (1e6)

getTotalCollateral

Calculates total collateral including unrealized PnL.

user.getTotalCollateral(
  marginCategory?: MarginCategory,
  strict?: boolean,
  includeOpenOrders?: boolean,
  liquidationBuffer?: BN,
  perpMarketIndex?: number
): BN

marginCategory · MarginCategory · default: "Initial"

Margin category: ‘Initial’ or ‘Maintenance’

strict · boolean · default: false

Whether to use strict oracle prices

includeOpenOrders · boolean · default: true

Whether to include open orders in calculation

liquidationBuffer · BN

Liquidation buffer to apply

perpMarketIndex · number

Specific perp market for isolated margin

return · BN

Total collateral in USDC precision (1e6)

getMarginRequirement

Calculates the margin requirement for the account.

user.getMarginRequirement(
  marginCategory: MarginCategory,
  liquidationBuffer?: BN,
  strict?: boolean,
  includeOpenOrders?: boolean,
  enteringHighLeverage?: boolean,
  perpMarketIndex?: number
): BN

marginCategory · MarginCategory · required

Margin category: ‘Initial’ or ‘Maintenance’

liquidationBuffer · BN

Additional buffer for liquidation calculations

strict · boolean

Whether to use strict pricing

includeOpenOrders · boolean

Whether to include open orders

enteringHighLeverage · boolean

Whether entering high leverage mode

perpMarketIndex · number

Specific perp market for isolated margin

return · BN

Margin requirement in USDC precision (1e6)

getInitialMarginRequirement

Calculates the initial margin requirement.

user.getInitialMarginRequirement(
  enterHighLeverageMode?: boolean,
  perpMarketIndex?: number
): BN

enterHighLeverageMode · boolean · default: false

Whether to calculate for high leverage mode

perpMarketIndex · number

Specific perp market for isolated margin

return · BN

Initial margin requirement in USDC precision (1e6)

getMaintenanceMarginRequirement

Calculates the maintenance margin requirement.

user.getMaintenanceMarginRequirement(
  liquidationBuffer?: BN,
  perpMarketIndex?: number
): BN

liquidationBuffer · BN

Liquidation buffer to apply

perpMarketIndex · number

Specific perp market for isolated margin

return · BN

Maintenance margin requirement in USDC precision (1e6)

PnL & Value Methods

getUnrealizedPNL

Calculates unrealized profit and loss.

user.getUnrealizedPNL(
  withFunding?: boolean,
  marketIndex?: number,
  withWeightMarginCategory?: MarginCategory,
  strict?: boolean,
  liquidationBuffer?: BN
): BN

withFunding · boolean

Whether to include funding payments

marketIndex · number

Specific market index (or all markets if undefined)

withWeightMarginCategory · MarginCategory

Apply margin category weights to PnL

strict · boolean

Use strict oracle pricing

liquidationBuffer · BN

Liquidation buffer to apply

return · BN

Unrealized PnL in USDC precision (1e6)

getUnrealizedFundingPNL

Calculates unrealized funding payment PnL.

user.getUnrealizedFundingPNL(marketIndex?: number): BN

marketIndex · number

Specific market index (or all markets if undefined)

return · BN

Unrealized funding PnL in USDC precision (1e6)

getNetUsdValue

Calculates the net USD value of the account.

user.getNetUsdValue(): BN

return · BN

Net USD value in USDC precision (1e6)

getTotalAllTimePnl

Calculates all-time profit and loss.

user.getTotalAllTimePnl(): BN

return · BN

All-time PnL in USDC precision (1e6)

Leverage & Risk Methods

getLeverage

Calculates current account leverage.

user.getLeverage(
  includeOpenOrders?: boolean,
  perpMarketIndex?: number
): BN

includeOpenOrders · boolean · default: true

Whether to include open orders

perpMarketIndex · number

Specific perp market for isolated position

return · BN

Leverage with precision TEN_THOUSAND (1e4)

getMarginRatio

Calculates the margin ratio (inverse of leverage).

user.getMarginRatio(): BN

return · BN

Margin ratio with precision TEN_THOUSAND (1e4)

getHealth

Calculates account health as a percentage.

user.getHealth(perpMarketIndex?: number): number

perpMarketIndex · number

Specific perp market for isolated position health

return · number

Health percentage from 0-100 (0 = liquidatable, 100 = max health)

canBeLiquidated

Checks if the account can be liquidated.

user.canBeLiquidated(): AccountLiquidatableStatus & {
  isolatedPositions: Map<number, AccountLiquidatableStatus>
}

return · object

Liquidation status for cross margin and isolated positions

Show properties

canBeLiquidated · boolean

Whether the account can be liquidated

marginRequirement · BN

Current margin requirement

totalCollateral · BN

Current total collateral

isolatedPositions · Map<number, AccountLiquidatableStatus>

Liquidation status for each isolated position by market index

liquidationPrice

Calculates the liquidation price for a perpetual position.

user.liquidationPrice(
  marketIndex: number,
  positionBaseSizeChange?: BN,
  estimatedEntryPrice?: BN,
  marginCategory?: MarginCategory,
  includeOpenOrders?: boolean,
  offsetCollateral?: BN,
  enteringHighLeverage?: boolean,
  marginType?: MarginType
): BN

marketIndex · number · required

Perpetual market index

positionBaseSizeChange · BN · default: "ZERO"

Change in position size to calculate for

estimatedEntryPrice · BN · default: "ZERO"

Estimated entry price for the trade

marginCategory · MarginCategory · default: "Maintenance"

Margin category to use

includeOpenOrders · boolean · default: false

Whether to include open orders

offsetCollateral · BN · default: "ZERO"

Additional collateral to add

enteringHighLeverage · boolean · default: false

Whether entering high leverage mode

marginType · MarginType

‘Cross’ or ‘Isolated’

return · BN

Liquidation price in PRICE_PRECISION (1e6), or -1 if position won’t liquidate

Properties

driftClient · DriftClient

Reference to the DriftClient instance

userAccountPublicKey · PublicKey

Public key of the user account

isSubscribed · boolean

Whether the user is subscribed to account updates

Usage Example

import { User } from '@drift-labs/sdk';

// Get user from DriftClient
const user = driftClient.getUser();

// Subscribe to user account updates
await user.subscribe();

// Get account data
const userAccount = user.getUserAccount();
console.log('Authority:', userAccount.authority.toBase58());

// Get positions
const perpPositions = user.getActivePerpPositions();
console.log('Active perp positions:', perpPositions.length);

// Calculate account metrics
const freeCollateral = user.getFreeCollateral();
const leverage = user.getLeverage();
const health = user.getHealth();

console.log('Free Collateral:', freeCollateral.toString());
console.log('Leverage:', leverage.toNumber() / 10000); // Convert from precision
console.log('Health:', health, '%');

// Check specific position
const solPerpPosition = user.getPerpPosition(0); // SOL-PERP
if (solPerpPosition) {
  console.log('SOL-PERP base amount:', solPerpPosition.baseAssetAmount.toString());
  
  // Calculate liquidation price
  const liqPrice = user.liquidationPrice(0);
  console.log('Liquidation price:', liqPrice.toNumber() / 1e6);
}

// Unsubscribe when done
await user.unsubscribe();