@strobelabs/perpcity-sdk 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1388,17 +1388,13 @@ declare const PERP_MANAGER_ABI: readonly [{
1388
1388
  readonly name: "funding";
1389
1389
  readonly type: "int256";
1390
1390
  }, {
1391
- readonly internalType: "int256";
1391
+ readonly internalType: "uint256";
1392
1392
  readonly name: "netMargin";
1393
- readonly type: "int256";
1393
+ readonly type: "uint256";
1394
1394
  }, {
1395
1395
  readonly internalType: "bool";
1396
1396
  readonly name: "wasLiquidated";
1397
1397
  readonly type: "bool";
1398
- }, {
1399
- readonly internalType: "uint256";
1400
- readonly name: "notional";
1401
- readonly type: "uint256";
1402
1398
  }];
1403
1399
  readonly stateMutability: "nonpayable";
1404
1400
  readonly type: "function";
@@ -1865,6 +1861,11 @@ type MarginRatios = {
1865
1861
  max: number;
1866
1862
  liq: number;
1867
1863
  };
1864
+ type MakerDetails = {
1865
+ unlockTimestamp: number;
1866
+ tickLower: number;
1867
+ tickUpper: number;
1868
+ };
1868
1869
  type PositionRawData = {
1869
1870
  perpId: Hex;
1870
1871
  positionId: bigint;
@@ -1872,6 +1873,18 @@ type PositionRawData = {
1872
1873
  entryPerpDelta: bigint;
1873
1874
  entryUsdDelta: bigint;
1874
1875
  marginRatios: MarginRatios;
1876
+ makerDetails: MakerDetails | null;
1877
+ };
1878
+ type QuoteTakerPositionResult = {
1879
+ perpDelta: bigint;
1880
+ usdDelta: bigint;
1881
+ fillPrice: number;
1882
+ };
1883
+ type QuoteClosePositionResult = {
1884
+ pnl: number;
1885
+ funding: number;
1886
+ netMargin: number;
1887
+ wasLiquidated: boolean;
1875
1888
  };
1876
1889
  type CacheConfig = {
1877
1890
  ttl: number;
@@ -6376,6 +6389,13 @@ declare function getPerpBeacon(perpData: PerpData): string;
6376
6389
  declare function getPerpBounds(perpData: PerpData): Bounds;
6377
6390
  declare function getPerpFees(perpData: PerpData): Fees;
6378
6391
  declare function getPerpTickSpacing(perpData: PerpData): number;
6392
+ declare function getFundingRate(context: PerpCityContext, perpId: Hex): Promise<{
6393
+ ratePerDay: number;
6394
+ ratePerMinute: number;
6395
+ rawX96: bigint;
6396
+ }>;
6397
+ declare function getIndexValue(context: PerpCityContext, perpId: Hex): Promise<bigint>;
6398
+ declare function getIndexTWAP(context: PerpCityContext, perpId: Hex, secondsAgo: number): Promise<bigint>;
6379
6399
 
6380
6400
  declare function createPerp(context: PerpCityContext, params: CreatePerpParams): Promise<Hex>;
6381
6401
  declare function openTakerPosition(context: PerpCityContext, perpId: Hex, params: OpenTakerPositionParams): Promise<OpenPosition>;
@@ -6383,8 +6403,37 @@ declare function calculateAlignedTicks(priceLower: number, priceUpper: number, t
6383
6403
  alignedTickLower: number;
6384
6404
  alignedTickUpper: number;
6385
6405
  };
6406
+ declare const DEFAULT_MAKER_SLIPPAGE_TOLERANCE = 0.01;
6407
+ declare const MAX_UINT128: bigint;
6386
6408
  declare function quoteOpenMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<QuoteOpenMakerPositionResult>;
6409
+ /**
6410
+ * Computes maxAmtIn slippage limit from a quote delta.
6411
+ *
6412
+ * When delta < 0 (tokens need to go in), applies slippage tolerance to the
6413
+ * absolute amount. When delta >= 0 (quote says no tokens needed), uses
6414
+ * `fallbackRef` as a reference to compute a small buffer — this prevents
6415
+ * reverts when price moves between quote and execution, shifting the token
6416
+ * split so some amount of this token is now required.
6417
+ *
6418
+ * Note: `fallbackRef` is intentionally the *other* leg's delta (cross-unit).
6419
+ * It is only used as a rough magnitude reference for sizing a small buffer,
6420
+ * not as a precise same-unit value. For maker positions the two legs are
6421
+ * correlated in magnitude, so this heuristic produces a reasonable buffer.
6422
+ */
6423
+ declare function applySlippage(delta: bigint, slippageTolerance: number, fallbackRef?: bigint): bigint;
6387
6424
  declare function openMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<OpenPosition>;
6425
+ declare function quoteTakerPosition(context: PerpCityContext, perpId: Hex, params: {
6426
+ holder: Address;
6427
+ isLong: boolean;
6428
+ margin: number;
6429
+ leverage: number;
6430
+ }): Promise<QuoteTakerPositionResult>;
6431
+ declare function adjustMargin(context: PerpCityContext, positionId: bigint, marginDelta: bigint): Promise<{
6432
+ txHash: Hex;
6433
+ }>;
6434
+ declare function adjustNotional(context: PerpCityContext, positionId: bigint, usdDelta: bigint, perpLimit: bigint): Promise<{
6435
+ txHash: Hex;
6436
+ }>;
6388
6437
 
6389
6438
  declare function getPositionPerpId(positionData: OpenPositionData): Hex;
6390
6439
  declare function getPositionId(positionData: OpenPositionData): bigint;
@@ -6395,6 +6444,10 @@ declare function getPositionPnl(positionData: OpenPositionData): number;
6395
6444
  declare function getPositionFundingPayment(positionData: OpenPositionData): number;
6396
6445
  declare function getPositionEffectiveMargin(positionData: OpenPositionData): number;
6397
6446
  declare function getPositionIsLiquidatable(positionData: OpenPositionData): boolean;
6447
+ declare function quoteClosePosition(context: PerpCityContext, positionId: bigint): Promise<QuoteClosePositionResult>;
6448
+ declare function closePositionWithQuote(context: PerpCityContext, _perpId: Hex, positionId: bigint,
6449
+ /** Slippage as a fraction, e.g. 0.01 = 1%. Compare with calculateClosePositionParams which uses percentage form (1 = 1%). */
6450
+ slippageTolerance?: number): Promise<ClosePositionResult>;
6398
6451
  declare function closePosition(context: PerpCityContext, perpId: Hex, positionId: bigint, params: ClosePositionParams): Promise<ClosePositionResult>;
6399
6452
  declare function getPositionLiveDetailsFromContract(context: PerpCityContext, _perpId: Hex, positionId: bigint): Promise<LiveDetails>;
6400
6453
  /**
@@ -6437,11 +6490,35 @@ declare function calculateLeverage(positionValue: number, effectiveMargin: numbe
6437
6490
  * @returns Liquidation price in USD, or null if cannot be calculated
6438
6491
  */
6439
6492
  declare function calculateLiquidationPrice(rawData: PositionRawData, isLong: boolean): number | null;
6493
+ declare function calculatePnlPercentage(pnl: number, funding: number, margin: number): number;
6494
+ /**
6495
+ * Calculates ClosePositionParams for a position close, handling the difference
6496
+ * between taker and maker positions.
6497
+ *
6498
+ * For taker positions, the contract checks minAmt1Out (for longs) or maxAmt1In
6499
+ * (for shorts) against the raw USD swap delta — NOT netMargin. The swap amount
6500
+ * corresponds to the position's notional value at current price, so slippage
6501
+ * limits must be based on `notional`, not `expectedReturn`.
6502
+ *
6503
+ * For maker positions, the contract checks minAmt0Out and minAmt1Out against
6504
+ * the raw token amounts from Uniswap liquidity removal. The split between
6505
+ * perp tokens and USDC depends on where the current price sits in the LP range,
6506
+ * and quoteClosePosition only returns the aggregate netMargin. Since we cannot
6507
+ * predict the individual token amounts, both minimums are set to 0.
6508
+ */
6509
+ declare function calculateClosePositionParams(opts: {
6510
+ isMaker: boolean;
6511
+ isLong?: boolean;
6512
+ notional: number;
6513
+ /** Slippage as a percentage, e.g. 1 = 1%. Compare with closePositionWithQuote which uses fractional form (0.01 = 1%). */
6514
+ slippagePercent: number;
6515
+ }): ClosePositionParams;
6440
6516
 
6441
6517
  declare function getUserUsdcBalance(userData: UserData): number;
6442
6518
  declare function getUserOpenPositions(userData: UserData): OpenPositionData[];
6443
6519
  declare function getUserWalletAddress(userData: UserData): Hex;
6444
6520
 
6521
+ declare function getUsdcAllowance(context: PerpCityContext, owner: Address): Promise<bigint>;
6445
6522
  declare function approveUsdc(context: PerpCityContext, amount: bigint, confirmations?: number): Promise<void>;
6446
6523
 
6447
6524
  declare const NUMBER_1E6: number;
@@ -6451,6 +6528,8 @@ declare const MIN_TICK = -887272;
6451
6528
  declare const MAX_TICK = 887272;
6452
6529
  declare const MIN_PRICE = 0.000001;
6453
6530
  declare const MAX_PRICE = 1000000;
6531
+ declare const UINT256_MAX: bigint;
6532
+ declare const INT256_THRESHOLD: bigint;
6454
6533
 
6455
6534
  declare function priceToSqrtPriceX96(price: number): bigint;
6456
6535
  /**
@@ -6463,6 +6542,12 @@ declare function scaleToX96(amount: number): bigint;
6463
6542
  declare function scaleFromX96(valueX96: bigint): number;
6464
6543
  declare function priceToTick(price: number, roundDown: boolean): number;
6465
6544
  declare function tickToPrice(tick: number): number;
6545
+ /**
6546
+ * Interprets a uint256 as int256 if it exceeds 2^255 (unsigned underflow).
6547
+ * The contract returns netMargin as uint256, but it can underflow when
6548
+ * the effective margin is negative (position is underwater).
6549
+ */
6550
+ declare function uint256ToInt256(value: bigint): bigint;
6466
6551
  declare function sqrtPriceX96ToPrice(sqrtPriceX96: bigint): number;
6467
6552
  declare function marginRatioToLeverage(marginRatio: number): number;
6468
6553
  declare function scaleFrom6Decimals(value: number): number;
@@ -6544,6 +6629,14 @@ declare function parseContractError(error: unknown): PerpCityError;
6544
6629
  */
6545
6630
  declare function withErrorHandling<T>(fn: () => Promise<T>, context: string): Promise<T>;
6546
6631
 
6632
+ /**
6633
+ * Convert a funding diff (over `interval` seconds) to a percentage for `period` seconds.
6634
+ * Defers the interval division until after scaling to avoid truncating small differentials.
6635
+ */
6636
+ declare function convertFundingDiffX96ToPercentPerPeriod(fundingDiffX96: bigint, interval: bigint, periodSeconds: bigint): number;
6637
+ declare function convertFundingPerSecondX96ToPercentPerMinute(fundingPerSecondX96: bigint): number;
6638
+ declare function convertFundingPerSecondX96ToPercentPerDay(fundingPerSecondX96: bigint): number;
6639
+
6547
6640
  /**
6548
6641
  * Calculate liquidity from USDC amount (amount1) using Uniswap v3 formula
6549
6642
  * liquidity = amount1 / (sqrt(priceUpper) - sqrt(priceLower))
@@ -6605,4 +6698,4 @@ interface RpcConfig {
6605
6698
  */
6606
6699
  declare function getRpcUrl(config?: RpcConfig): string;
6607
6700
 
6608
- export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, InsufficientFundsError, type LiveDetails, MAX_PRICE, MAX_TICK, MIN_PRICE, MIN_TICK, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, type QuoteOpenMakerPositionResult, RPCError, type RpcConfig, TransactionRejectedError, type UserData, ValidationError, approveUsdc, calculateAlignedTicks, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePositionSize, calculatePositionValue, closePosition, createPerp, estimateLiquidity, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, quoteOpenMakerPosition, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, withErrorHandling };
6701
+ export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, DEFAULT_MAKER_SLIPPAGE_TOLERANCE, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, INT256_THRESHOLD, InsufficientFundsError, type LiveDetails, MAX_PRICE, MAX_TICK, MAX_UINT128, MIN_PRICE, MIN_TICK, type MakerDetails, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, type QuoteClosePositionResult, type QuoteOpenMakerPositionResult, type QuoteTakerPositionResult, RPCError, type RpcConfig, TransactionRejectedError, UINT256_MAX, type UserData, ValidationError, adjustMargin, adjustNotional, applySlippage, approveUsdc, calculateAlignedTicks, calculateClosePositionParams, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePnlPercentage, calculatePositionSize, calculatePositionValue, closePosition, closePositionWithQuote, convertFundingDiffX96ToPercentPerPeriod, convertFundingPerSecondX96ToPercentPerDay, convertFundingPerSecondX96ToPercentPerMinute, createPerp, estimateLiquidity, getFundingRate, getIndexTWAP, getIndexValue, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUsdcAllowance, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, quoteClosePosition, quoteOpenMakerPosition, quoteTakerPosition, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, uint256ToInt256, withErrorHandling };
package/dist/index.d.ts CHANGED
@@ -1388,17 +1388,13 @@ declare const PERP_MANAGER_ABI: readonly [{
1388
1388
  readonly name: "funding";
1389
1389
  readonly type: "int256";
1390
1390
  }, {
1391
- readonly internalType: "int256";
1391
+ readonly internalType: "uint256";
1392
1392
  readonly name: "netMargin";
1393
- readonly type: "int256";
1393
+ readonly type: "uint256";
1394
1394
  }, {
1395
1395
  readonly internalType: "bool";
1396
1396
  readonly name: "wasLiquidated";
1397
1397
  readonly type: "bool";
1398
- }, {
1399
- readonly internalType: "uint256";
1400
- readonly name: "notional";
1401
- readonly type: "uint256";
1402
1398
  }];
1403
1399
  readonly stateMutability: "nonpayable";
1404
1400
  readonly type: "function";
@@ -1865,6 +1861,11 @@ type MarginRatios = {
1865
1861
  max: number;
1866
1862
  liq: number;
1867
1863
  };
1864
+ type MakerDetails = {
1865
+ unlockTimestamp: number;
1866
+ tickLower: number;
1867
+ tickUpper: number;
1868
+ };
1868
1869
  type PositionRawData = {
1869
1870
  perpId: Hex;
1870
1871
  positionId: bigint;
@@ -1872,6 +1873,18 @@ type PositionRawData = {
1872
1873
  entryPerpDelta: bigint;
1873
1874
  entryUsdDelta: bigint;
1874
1875
  marginRatios: MarginRatios;
1876
+ makerDetails: MakerDetails | null;
1877
+ };
1878
+ type QuoteTakerPositionResult = {
1879
+ perpDelta: bigint;
1880
+ usdDelta: bigint;
1881
+ fillPrice: number;
1882
+ };
1883
+ type QuoteClosePositionResult = {
1884
+ pnl: number;
1885
+ funding: number;
1886
+ netMargin: number;
1887
+ wasLiquidated: boolean;
1875
1888
  };
1876
1889
  type CacheConfig = {
1877
1890
  ttl: number;
@@ -6376,6 +6389,13 @@ declare function getPerpBeacon(perpData: PerpData): string;
6376
6389
  declare function getPerpBounds(perpData: PerpData): Bounds;
6377
6390
  declare function getPerpFees(perpData: PerpData): Fees;
6378
6391
  declare function getPerpTickSpacing(perpData: PerpData): number;
6392
+ declare function getFundingRate(context: PerpCityContext, perpId: Hex): Promise<{
6393
+ ratePerDay: number;
6394
+ ratePerMinute: number;
6395
+ rawX96: bigint;
6396
+ }>;
6397
+ declare function getIndexValue(context: PerpCityContext, perpId: Hex): Promise<bigint>;
6398
+ declare function getIndexTWAP(context: PerpCityContext, perpId: Hex, secondsAgo: number): Promise<bigint>;
6379
6399
 
6380
6400
  declare function createPerp(context: PerpCityContext, params: CreatePerpParams): Promise<Hex>;
6381
6401
  declare function openTakerPosition(context: PerpCityContext, perpId: Hex, params: OpenTakerPositionParams): Promise<OpenPosition>;
@@ -6383,8 +6403,37 @@ declare function calculateAlignedTicks(priceLower: number, priceUpper: number, t
6383
6403
  alignedTickLower: number;
6384
6404
  alignedTickUpper: number;
6385
6405
  };
6406
+ declare const DEFAULT_MAKER_SLIPPAGE_TOLERANCE = 0.01;
6407
+ declare const MAX_UINT128: bigint;
6386
6408
  declare function quoteOpenMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<QuoteOpenMakerPositionResult>;
6409
+ /**
6410
+ * Computes maxAmtIn slippage limit from a quote delta.
6411
+ *
6412
+ * When delta < 0 (tokens need to go in), applies slippage tolerance to the
6413
+ * absolute amount. When delta >= 0 (quote says no tokens needed), uses
6414
+ * `fallbackRef` as a reference to compute a small buffer — this prevents
6415
+ * reverts when price moves between quote and execution, shifting the token
6416
+ * split so some amount of this token is now required.
6417
+ *
6418
+ * Note: `fallbackRef` is intentionally the *other* leg's delta (cross-unit).
6419
+ * It is only used as a rough magnitude reference for sizing a small buffer,
6420
+ * not as a precise same-unit value. For maker positions the two legs are
6421
+ * correlated in magnitude, so this heuristic produces a reasonable buffer.
6422
+ */
6423
+ declare function applySlippage(delta: bigint, slippageTolerance: number, fallbackRef?: bigint): bigint;
6387
6424
  declare function openMakerPosition(context: PerpCityContext, perpId: Hex, params: OpenMakerPositionParams): Promise<OpenPosition>;
6425
+ declare function quoteTakerPosition(context: PerpCityContext, perpId: Hex, params: {
6426
+ holder: Address;
6427
+ isLong: boolean;
6428
+ margin: number;
6429
+ leverage: number;
6430
+ }): Promise<QuoteTakerPositionResult>;
6431
+ declare function adjustMargin(context: PerpCityContext, positionId: bigint, marginDelta: bigint): Promise<{
6432
+ txHash: Hex;
6433
+ }>;
6434
+ declare function adjustNotional(context: PerpCityContext, positionId: bigint, usdDelta: bigint, perpLimit: bigint): Promise<{
6435
+ txHash: Hex;
6436
+ }>;
6388
6437
 
6389
6438
  declare function getPositionPerpId(positionData: OpenPositionData): Hex;
6390
6439
  declare function getPositionId(positionData: OpenPositionData): bigint;
@@ -6395,6 +6444,10 @@ declare function getPositionPnl(positionData: OpenPositionData): number;
6395
6444
  declare function getPositionFundingPayment(positionData: OpenPositionData): number;
6396
6445
  declare function getPositionEffectiveMargin(positionData: OpenPositionData): number;
6397
6446
  declare function getPositionIsLiquidatable(positionData: OpenPositionData): boolean;
6447
+ declare function quoteClosePosition(context: PerpCityContext, positionId: bigint): Promise<QuoteClosePositionResult>;
6448
+ declare function closePositionWithQuote(context: PerpCityContext, _perpId: Hex, positionId: bigint,
6449
+ /** Slippage as a fraction, e.g. 0.01 = 1%. Compare with calculateClosePositionParams which uses percentage form (1 = 1%). */
6450
+ slippageTolerance?: number): Promise<ClosePositionResult>;
6398
6451
  declare function closePosition(context: PerpCityContext, perpId: Hex, positionId: bigint, params: ClosePositionParams): Promise<ClosePositionResult>;
6399
6452
  declare function getPositionLiveDetailsFromContract(context: PerpCityContext, _perpId: Hex, positionId: bigint): Promise<LiveDetails>;
6400
6453
  /**
@@ -6437,11 +6490,35 @@ declare function calculateLeverage(positionValue: number, effectiveMargin: numbe
6437
6490
  * @returns Liquidation price in USD, or null if cannot be calculated
6438
6491
  */
6439
6492
  declare function calculateLiquidationPrice(rawData: PositionRawData, isLong: boolean): number | null;
6493
+ declare function calculatePnlPercentage(pnl: number, funding: number, margin: number): number;
6494
+ /**
6495
+ * Calculates ClosePositionParams for a position close, handling the difference
6496
+ * between taker and maker positions.
6497
+ *
6498
+ * For taker positions, the contract checks minAmt1Out (for longs) or maxAmt1In
6499
+ * (for shorts) against the raw USD swap delta — NOT netMargin. The swap amount
6500
+ * corresponds to the position's notional value at current price, so slippage
6501
+ * limits must be based on `notional`, not `expectedReturn`.
6502
+ *
6503
+ * For maker positions, the contract checks minAmt0Out and minAmt1Out against
6504
+ * the raw token amounts from Uniswap liquidity removal. The split between
6505
+ * perp tokens and USDC depends on where the current price sits in the LP range,
6506
+ * and quoteClosePosition only returns the aggregate netMargin. Since we cannot
6507
+ * predict the individual token amounts, both minimums are set to 0.
6508
+ */
6509
+ declare function calculateClosePositionParams(opts: {
6510
+ isMaker: boolean;
6511
+ isLong?: boolean;
6512
+ notional: number;
6513
+ /** Slippage as a percentage, e.g. 1 = 1%. Compare with closePositionWithQuote which uses fractional form (0.01 = 1%). */
6514
+ slippagePercent: number;
6515
+ }): ClosePositionParams;
6440
6516
 
6441
6517
  declare function getUserUsdcBalance(userData: UserData): number;
6442
6518
  declare function getUserOpenPositions(userData: UserData): OpenPositionData[];
6443
6519
  declare function getUserWalletAddress(userData: UserData): Hex;
6444
6520
 
6521
+ declare function getUsdcAllowance(context: PerpCityContext, owner: Address): Promise<bigint>;
6445
6522
  declare function approveUsdc(context: PerpCityContext, amount: bigint, confirmations?: number): Promise<void>;
6446
6523
 
6447
6524
  declare const NUMBER_1E6: number;
@@ -6451,6 +6528,8 @@ declare const MIN_TICK = -887272;
6451
6528
  declare const MAX_TICK = 887272;
6452
6529
  declare const MIN_PRICE = 0.000001;
6453
6530
  declare const MAX_PRICE = 1000000;
6531
+ declare const UINT256_MAX: bigint;
6532
+ declare const INT256_THRESHOLD: bigint;
6454
6533
 
6455
6534
  declare function priceToSqrtPriceX96(price: number): bigint;
6456
6535
  /**
@@ -6463,6 +6542,12 @@ declare function scaleToX96(amount: number): bigint;
6463
6542
  declare function scaleFromX96(valueX96: bigint): number;
6464
6543
  declare function priceToTick(price: number, roundDown: boolean): number;
6465
6544
  declare function tickToPrice(tick: number): number;
6545
+ /**
6546
+ * Interprets a uint256 as int256 if it exceeds 2^255 (unsigned underflow).
6547
+ * The contract returns netMargin as uint256, but it can underflow when
6548
+ * the effective margin is negative (position is underwater).
6549
+ */
6550
+ declare function uint256ToInt256(value: bigint): bigint;
6466
6551
  declare function sqrtPriceX96ToPrice(sqrtPriceX96: bigint): number;
6467
6552
  declare function marginRatioToLeverage(marginRatio: number): number;
6468
6553
  declare function scaleFrom6Decimals(value: number): number;
@@ -6544,6 +6629,14 @@ declare function parseContractError(error: unknown): PerpCityError;
6544
6629
  */
6545
6630
  declare function withErrorHandling<T>(fn: () => Promise<T>, context: string): Promise<T>;
6546
6631
 
6632
+ /**
6633
+ * Convert a funding diff (over `interval` seconds) to a percentage for `period` seconds.
6634
+ * Defers the interval division until after scaling to avoid truncating small differentials.
6635
+ */
6636
+ declare function convertFundingDiffX96ToPercentPerPeriod(fundingDiffX96: bigint, interval: bigint, periodSeconds: bigint): number;
6637
+ declare function convertFundingPerSecondX96ToPercentPerMinute(fundingPerSecondX96: bigint): number;
6638
+ declare function convertFundingPerSecondX96ToPercentPerDay(fundingPerSecondX96: bigint): number;
6639
+
6547
6640
  /**
6548
6641
  * Calculate liquidity from USDC amount (amount1) using Uniswap v3 formula
6549
6642
  * liquidity = amount1 / (sqrt(priceUpper) - sqrt(priceLower))
@@ -6605,4 +6698,4 @@ interface RpcConfig {
6605
6698
  */
6606
6699
  declare function getRpcUrl(config?: RpcConfig): string;
6607
6700
 
6608
- export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, InsufficientFundsError, type LiveDetails, MAX_PRICE, MAX_TICK, MIN_PRICE, MIN_TICK, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, type QuoteOpenMakerPositionResult, RPCError, type RpcConfig, TransactionRejectedError, type UserData, ValidationError, approveUsdc, calculateAlignedTicks, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePositionSize, calculatePositionValue, closePosition, createPerp, estimateLiquidity, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, quoteOpenMakerPosition, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, withErrorHandling };
6701
+ export { BEACON_ABI, BIGINT_1E6, type Bounds, type CacheConfig, type ClosePositionParams, type ClosePositionResult, ContractError, type CreatePerpParams, DEFAULT_MAKER_SLIPPAGE_TOLERANCE, ErrorCategory, type ErrorDebugInfo, ErrorSource, type Fees, INT256_THRESHOLD, InsufficientFundsError, type LiveDetails, MAX_PRICE, MAX_TICK, MAX_UINT128, MIN_PRICE, MIN_TICK, type MakerDetails, type MarginRatios, NUMBER_1E6, type OpenMakerPositionParams, OpenPosition, type OpenPositionData, type OpenTakerPositionParams, PERP_MANAGER_ABI, PerpCityContext, type PerpCityContextConfig, type PerpCityDeployments, PerpCityError, type PerpConfig, type PerpData, type PositionRawData, Q96, type QuoteClosePositionResult, type QuoteOpenMakerPositionResult, type QuoteTakerPositionResult, RPCError, type RpcConfig, TransactionRejectedError, UINT256_MAX, type UserData, ValidationError, adjustMargin, adjustNotional, applySlippage, approveUsdc, calculateAlignedTicks, calculateClosePositionParams, calculateEntryPrice, calculateLeverage, calculateLiquidationPrice, calculateLiquidityForTargetRatio, calculatePnlPercentage, calculatePositionSize, calculatePositionValue, closePosition, closePositionWithQuote, convertFundingDiffX96ToPercentPerPeriod, convertFundingPerSecondX96ToPercentPerDay, convertFundingPerSecondX96ToPercentPerMinute, createPerp, estimateLiquidity, getFundingRate, getIndexTWAP, getIndexValue, getPerpBeacon, getPerpBounds, getPerpFees, getPerpMark, getPerpTickSpacing, getPositionEffectiveMargin, getPositionFundingPayment, getPositionId, getPositionIsLiquidatable, getPositionIsLong, getPositionIsMaker, getPositionLiveDetails, getPositionLiveDetailsFromContract, getPositionPerpId, getPositionPnl, getRpcUrl, getUsdcAllowance, getUserOpenPositions, getUserUsdcBalance, getUserWalletAddress, marginRatioToLeverage, openMakerPosition, openTakerPosition, parseContractError, priceToSqrtPriceX96, priceToTick, quoteClosePosition, quoteOpenMakerPosition, quoteTakerPosition, scale6Decimals, scaleFrom6Decimals, scaleFromX96, scaleToX96, sqrtPriceX96ToPrice, tickToPrice, uint256ToInt256, withErrorHandling };