Skip to main content

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

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

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();

Build docs developers (and LLMs) love