Margin

General

One can easily access any balance from the account using the following:

const balances = zoUser.balances

{
...
'SOL':new Num(1,9)
}

const solBalance = zoUser.balances['SOL'] //new Num(1,9)
const solBalanceNumber = zoUser.balances['SOL'].number // 1.0

Similarly, one can retrieve zero one positions from zoUser:

const positions = zoUser.positions
const synPosition = zoUser.positions['SYN-PERP']

{
    coins: new Num(0,6),
    pCoins: new Num(0,6),
    realizedPnL: new Num(0,6),
    fundingIndex: 1000.037713,
    marketKey: 'SYN-PERP',
    isLong: false
}

  coins - absolute size of the position [the real value is positive if long, negative otherwise]
  
  pCoins - usd balance of the position [the real value is negative if long, positive otherwise]
  
  realizedPnl - realizedPnl of the user, this value represent the pnl of the user, realized during event 
  consumption and is typically 0, because it's transferred to USD balance 
  of the user via cranking and other ixs
  
  fundingIndex - funding index at the last time that position was modified
  
  isLong - value representing if position is long or short

Funding

Funding accrued can be accessed as well, but it is transferred to USD balance on every transaction, so typically it does not represent total funding accrued in the market

const fundingAccruedInTotal = zoUser.funding
const solFundingAccruedInTotal = zoUser.positionFunding('SOL-PERP')

PnL

Total PnL of the position based on the index price.

const solPnL = zoUser.positionPnL('SOL-PERP')

Total PnL of the position based on the mark price.

const solPnLBasedOnMarkPrice = zoUser.positionPnLBasedOnMarkPrice('SOL-PERP')

Total unrealized PnL

const totalPnL = zoUser.cumulativeUnrealizedPnL

Positions

const totalPositionNotional = zoUser.totalPositionNotional
const totalOpenPositionNotional = zoUser.totalOpenPositionNotional
const longOrderSize = zoUser.longOrderSize
const shortOrderSize = zoUser.shortOrderSize
const openSize = zoUser.openSize

Collateral

You can learn more about margin fractions here: https://docs.01.xyz/margin/overview

const unweightedCollateralValue = zoUser.unweightedCollateralValue
const unweightedAccountValue = zoUser.unweightedAccountValue
const tiedCollateral = zoUser.tiedCollateral
const freeCollateralValue = zoUser.freeCollateralValue
const collateralWithdrawable = zoUser.collateralWithdrawable('SOL')
const collateralWithdrawableWithBorrow = zoUser.collateralWithdrawableWithBorrow('SOL')

Margin Fractions

const marginFraction = zoUser.marginFraction
const maintenanceMarginFraction = zoUser.maintenanceMarginFraction

Subscriptions

To simplify, the integration zoUser has a subscription which allows to subscribe to all the relevant updates, making sure that zoUser data is up to date.

await zoUser.subscribe()
await zoUser.unsubscribe()

It is also possible to listen to specific updates to respond to specific changes
 
zoUser.eventEmitter!.addListener(UpdateEvents.marginModified, () => {
    //DO: SOMETHING
})
zoUser.eventEmitter!.addListener(UpdateEvents.controlModified, () => {
    //DO: SOMETHING
})
zoUser.eventEmitter!.addListener(UpdateEvents.stateModified, () => {
    //DO: SOMETHING
})
// not recommended because it's updated every few seconds
zoUser.eventEmitter!.addListener(UpdateEvents._cacheModified, () => {
    //DO: SOMETHING
})

await sleep(100000000)

Place Order

symbol - market symbol
orderType - type of order
isLong - is a long order
price - price
size - size of the order
limit [optional]  - related to serum orderbook design
clientId [optional]  - if passed is used to assign a client id order which allows to cancel the order by clientId
maxTs [optional]  - timestamp after which order will not be accepted, helps preventing late order placement

const placeTxId = await zoUser.margin.placePerpOrder({
    symbol: 'SOL-PERP',
    orderType: OrderTypeName.Limit,
    isLong: false,
    price: 100.0,
    size: 1
})

Cancel Order

symbol  - market symbol
isLong [optional] - is a long order
orderId [optional]  - order id of the order
clientId [optional] - client id of the order
Note: you need to provide clientId or _orderId AND isLong_

const cancelTxId = await zoUser.margin.cancelPerpOrder({
    symbol: 'SOL-PERP',
    isLong: true,
    orderId: new BN(12312312321)
})

Close position

symbol  - market symbol

const closeTxId = await zoUser.margin.closePosition( 'SOL-PERP')

Deposit

mintOrSymbol - mint of the withdrawn collateral
size - size of the deposit
repayOnly - only repay borrows, dont deposit more than that
tokenAccountProvided - token account from where to deposit if not associated token account

const depositTxId = await zoUser.margin.deposit(
    'SOL',
    0.01,
    false
)

Withdraw

withdraws to the associated token account.

    mintOrSymbol - mint of the withdrawn collateral
    size - size of the withdrawal
    allowBorrow - should you be allowed to borrow assets to withdraw the required amount

const withdrawTxId = await zoUser.margin.withdraw(
    'USDC',
    1,
    true
)