API Reference

pnpm add @strobelabs/perpcity-sdk

import { PerpCityContext } from '@strobelabs/perpcity-sdk'

const context = new PerpCityContext({
  walletClient, // viem WalletClient
  rpcUrl: process.env.RPC_URL!,
  deployments: {
    perpManager: '0x...',
    usdc: '0x...',
    // Optional module addresses
    feesModule: '0x...',
    marginRatiosModule: '0x...',
    lockupPeriodModule: '0x...',
    sqrtPriceImpactLimitModule: '0x...'
  }
})

const config = await context.getPerpConfig('0x...')
console.log(config.fees) // Fees module address
console.log(config.marginRatios) // Margin ratios module address

const perpData = await context.getPerpData('0x...')
console.log(perpData.mark) // Current mark price
console.log(perpData.beacon) // Oracle address
console.log(perpData.tickSpacing)
console.log(perpData.bounds)
console.log(perpData.fees)

const userData = await context.getUserData('0x...', [
  { perpId: '0x...', positionId: 1n, isLong: true, isMaker: false },
  { perpId: '0x...', positionId: 2n, isLong: false, isMaker: false }
])

console.log(userData.usdcBalance)
console.log(userData.openPositions)

const positionData = await context.getOpenPositionData(
  '0x...', // perpId
  123n,    // positionId
  true,    // isLong
  false    // isMaker
)

console.log(positionData.liveDetails.pnl)
console.log(positionData.liveDetails.fundingPayment)
console.log(positionData.liveDetails.isLiquidatable)

const deployments = context.deployments()
console.log(deployments.perpManager)
console.log(deployments.usdc)

import { createPerp } from '@strobelabs/perpcity-sdk'

const perpId = await createPerp(context, {
  startingPrice: 3000,
  beacon: '0x...', // Oracle address
  // Optional module overrides
  fees: '0x...',
  marginRatios: '0x...',
  lockupPeriod: '0x...',
  sqrtPriceImpactLimit: '0x...'
})

import { openTakerPosition } from '@strobelabs/perpcity-sdk'

const position = await openTakerPosition(context, perpId, {
  isLong: true,
  margin: 1000,    // $1000 USDC
  leverage: 5,     // 5x leverage
  unspecifiedAmountLimit: 0
})

import { openMakerPosition } from '@strobelabs/perpcity-sdk'

const position = await openMakerPosition(context, perpId, {
  margin: 10000,
  priceLower: 2900,
  priceUpper: 3100,
  liquidity: 1000000n,
  maxAmt0In: 1000000,
  maxAmt1In: 1000000
})

import { closePosition } from '@strobelabs/perpcity-sdk'

const result = await closePosition(context, perpId, positionId, {
  minAmt0Out: 0,
  minAmt1Out: 0,
  maxAmt1In: 1000000
})

import { getPositionPnl } from '@strobelabs/perpcity-sdk'

const pnl = getPositionPnl(positionData)
console.log(`PnL: $${pnl}`)

import { getPositionFundingPayment } from '@strobelabs/perpcity-sdk'

const funding = getPositionFundingPayment(positionData)

import { getPositionEffectiveMargin } from '@strobelabs/perpcity-sdk'

const margin = getPositionEffectiveMargin(positionData)

import { getPositionIsLiquidatable } from '@strobelabs/perpcity-sdk'

const canLiquidate = getPositionIsLiquidatable(positionData)
if (canLiquidate) {
  console.warn('Position at risk!')
}

import { getPerpMark } from '@strobelabs/perpcity-sdk'

const mark = getPerpMark(perpData)

import { getPerpBeacon } from '@strobelabs/perpcity-sdk'

const beacon = getPerpBeacon(perpData)

import { getPerpTickSpacing } from '@strobelabs/perpcity-sdk'

const spacing = getPerpTickSpacing(perpData)

import { getPerpBounds } from '@strobelabs/perpcity-sdk'

const bounds = getPerpBounds(perpData)
console.log(bounds.minMargin)
console.log(bounds.minTakerLeverage)
console.log(bounds.maxTakerLeverage)

import { getPerpFees } from '@strobelabs/perpcity-sdk'

const fees = getPerpFees(perpData)
console.log(fees.creatorFee)
console.log(fees.insuranceFee)
console.log(fees.lpFee)
console.log(fees.liquidationFee)

import { getUserUsdcBalance } from '@strobelabs/perpcity-sdk'

const balance = getUserUsdcBalance(userData)

import { getUserOpenPositions } from '@strobelabs/perpcity-sdk'

const positions = getUserOpenPositions(userData)

import { getUserWalletAddress } from '@strobelabs/perpcity-sdk'

const address = getUserWalletAddress(userData)

type PerpData = {
  id: Hex
  mark: number
  beacon: Address
  tickSpacing: number
  bounds: Bounds
  fees: Fees
}

type Bounds = {
  minMargin: number
  minTakerLeverage: number
  maxTakerLeverage: number
  liquidationTakerRatio: number
}

type Fees = {
  creatorFee: number
  insuranceFee: number
  lpFee: number
  liquidationFee: number
}

type UserData = {
  walletAddress: Hex
  usdcBalance: number
  openPositions: OpenPositionData[]
}

type OpenPositionData = {
  perpId: Hex
  positionId: bigint
  isLong?: boolean    // Optional - populated when fetched
  isMaker?: boolean   // Optional - populated when fetched
  liveDetails: LiveDetails
}

type LiveDetails = {
  pnl: number
  fundingPayment: number
  effectiveMargin: number
  isLiquidatable: boolean
}

type PerpConfig = {
  key: {
    currency0: Address
    currency1: Address
    fee: number
    tickSpacing: number
    hooks: Address
  }
  creator: Address
  vault: Address
  beacon: Address
  fees: Address
  marginRatios: Address
  lockupPeriod: Address
  sqrtPriceImpactLimit: Address
}