Reader

The Reader contract provides convenience functions for retrieving information such as markets, positions, and pricing data.

This page focuses on the most commonly used read helpers. For the full public surface, see Reader.sol.

Examples below assume you already have contract instances such as reader, dataStore, and referralStorage, plus any required market or price structs.

Market list

Use Reader.getMarkets to retrieve a paginated list of all markets. Each market is represented by a Market.Props struct.

Reader.getMarkets

function getMarkets(DataStore dataStore, uint256 start, uint256 end)
    external view returns (Market.Props[] memory)

Example (TypeScript / ethers):

const markets = await reader.getMarkets(dataStore.address, 0, 20);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
start	uint256	Start index for pagination
end	uint256	End index for pagination

Returns: Array of Market.Props.

Market.Props

Field	Type	Description
marketToken	address	Address of the GM token for this market
indexToken	address	Address of the index token (for example, ETH for the ETH/USD market)
longToken	address	Address of the long collateral token
shortToken	address	Address of the short collateral token

Detailed market list

Use Reader.getMarketInfoList to retrieve markets with additional runtime data including borrowing rates, funding rates, and whether the market is disabled.

Reader.getMarketInfoList

function getMarketInfoList(
    DataStore dataStore,
    MarketUtils.MarketPrices[] memory marketPricesList,
    uint256 start,
    uint256 end
) external view returns (ReaderUtils.MarketInfo[] memory)

Example (TypeScript / ethers):

const marketInfoList = await reader.getMarketInfoList(dataStore.address, marketPricesList, 0, 20);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
marketPricesList	MarketUtils.MarketPrices[]	Current prices for each market, in the same order as the markets being queried
start	uint256	Start index for pagination
end	uint256	End index for pagination

Returns: Array of ReaderUtils.MarketInfo, which includes the market props, borrowing rates, funding rates, and a flag indicating whether the market is disabled.

MarketUtils.MarketPrices

Field	Type	Description
indexTokenPrice	Price.Props	Current price range for the index token
longTokenPrice	Price.Props	Current price range for the long token
shortTokenPrice	Price.Props	Current price range for the short token

Price.Props

Field	Type	Description
min	uint256	Minimum (bid) price
max	uint256	Maximum (ask) price

Getting GM token price

Use Reader.getMarketTokenPrice to retrieve the current GM token price along with detailed pool information: pool value, PnL, token amounts, borrowing fees, and the impact pool.

Reader.getMarketTokenPrice

function getMarketTokenPrice(
    DataStore dataStore,
    Market.Props memory market,
    Price.Props memory indexTokenPrice,
    Price.Props memory longTokenPrice,
    Price.Props memory shortTokenPrice,
    bytes32 pnlFactorType,
    bool maximize
) external view returns (int256, MarketPoolValueInfo.Props memory)

Example (TypeScript / ethers):

const [gmPrice, poolInfo] = await reader.getMarketTokenPrice(
  dataStore.address,
  market,
  indexTokenPrice,
  longTokenPrice,
  shortTokenPrice,
  pnlFactorType,
  true
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	Market data struct (see Market list)
indexTokenPrice	Price.Props	Current price range for the index token
longTokenPrice	Price.Props	Current price range for the long token
shortTokenPrice	Price.Props	Current price range for the short token
pnlFactorType	bytes32	Which PnL factor cap to apply. Use Keys.MAX_PNL_FACTOR_FOR_TRADERS for trading contexts, Keys.MAX_PNL_FACTOR_FOR_DEPOSITS for deposit simulation, or Keys.MAX_PNL_FACTOR_FOR_WITHDRAWALS for withdrawal simulation.
maximize	bool	Pass true to use maximum prices (gives the higher GM token price), false to use minimum prices

Returns: A tuple of (int256 price, MarketPoolValueInfo.Props poolInfo) where price is the GM token price and poolInfo contains pool value, PnL, token amounts, borrowing fees, and the impact pool balance.

Position list

Use Reader.getAccountPositions to retrieve all open positions for a given account. The function returns raw position data without fee or pricing calculations.

Reader.getAccountPositions

function getAccountPositions(
    DataStore dataStore,
    address account,
    uint256 start,
    uint256 end
) external view returns (Position.Props[] memory)

Example (TypeScript / ethers):

const positions = await reader.getAccountPositions(dataStore.address, account.address, 0, 20);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
account	address	The account address to retrieve positions for
start	uint256	Start index for pagination
end	uint256	End index for pagination

Returns: Array of Position.Props, each containing the raw position state (size, collateral, entry price, and so on).

Detailed position list

Use Reader.getAccountPositionInfoList to retrieve all open positions for a given account with full fee and pricing context. This function uses the account address and market list directly rather than position keys.

note

Reader.getAccountPositionInfoList uses an account plus market list rather than explicit positionKeys. If you need to query specific keys directly, use Reader.getPositionInfoList.

Reader.getAccountPositionInfoList

function getAccountPositionInfoList(
    DataStore dataStore,
    IReferralStorage referralStorage,
    address account,
    address[] memory markets,
    MarketUtils.MarketPrices[] memory marketPrices,
    address uiFeeReceiver,
    uint256 start,
    uint256 end
) external view returns (ReaderPositionUtils.PositionInfo[] memory)

Example (TypeScript / ethers):

const positionInfoList = await reader.getAccountPositionInfoList(
  dataStore.address,
  referralStorage.address,
  account.address,
  markets,
  marketPrices,
  ethers.constants.AddressZero,
  0,
  20
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
referralStorage	address	Address of the ReferralStorage contract
account	address	The account address to retrieve positions for
markets	address[]	Array of perp market addresses covering every position you expect to retrieve. Must contain only perpetual markets (not swap-only markets).
marketPrices	MarketUtils.MarketPrices[]	Current prices for each market in the same order as markets. If a returned position's market is missing from this list, the call reverts.
uiFeeReceiver	address	Address of the UI fee receiver used in fee calculations. Pass the zero address if not applicable.
start	uint256	Start index for pagination
end	uint256	End index for pagination

Returns: Array of ReaderPositionUtils.PositionInfo, each including the position, fees, execution price, and PnL.

Position information

Use Reader.getPositionInfo to retrieve full details for a single position, including fees, execution price, and PnL.

Reader.getPositionInfo

function getPositionInfo(
    DataStore dataStore,
    IReferralStorage referralStorage,
    bytes32 positionKey,
    MarketUtils.MarketPrices memory prices,
    uint256 sizeDeltaUsd,
    address uiFeeReceiver,
    bool usePositionSizeAsSizeDeltaUsd
) public view returns (ReaderPositionUtils.PositionInfo memory)

Example (TypeScript / ethers):

const positionInfo = await reader.getPositionInfo(
  dataStore.address,
  referralStorage.address,
  positionKey,
  prices,
  0,
  ethers.constants.AddressZero,
  false
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
referralStorage	address	Address of the ReferralStorage contract
positionKey	bytes32	Key identifying the position
prices	MarketUtils.MarketPrices	Current prices for the index, long, and short tokens
sizeDeltaUsd	uint256	Used to calculate fees and execution price when simulating a position decrease. Pass 0 if not simulating a size change.
uiFeeReceiver	address	Address of the UI fee receiver for fee calculations. Pass the zero address if not applicable.
usePositionSizeAsSizeDeltaUsd	bool	Pass true to use the full position size as sizeDeltaUsd (for example, when simulating a full close)

Returns: ReaderPositionUtils.PositionInfo containing the position data, fees, execution price, and PnL.

Detailed position list by key

Use Reader.getPositionInfoList to retrieve detailed position data when you already have an array of position keys.

Reader.getPositionInfoList

function getPositionInfoList(
    DataStore dataStore,
    IReferralStorage referralStorage,
    bytes32[] memory positionKeys,
    MarketUtils.MarketPrices[] memory prices,
    address uiFeeReceiver
) external view returns (ReaderPositionUtils.PositionInfo[] memory)

Example (TypeScript / ethers):

const positionInfoList = await reader.getPositionInfoList(
  dataStore.address,
  referralStorage.address,
  positionKeys,
  prices,
  ethers.constants.AddressZero
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
referralStorage	address	Address of the ReferralStorage contract
positionKeys	bytes32[]	Position keys to query
prices	MarketUtils.MarketPrices[]	Current prices for the markets of the requested positions, in the same order as positionKeys
uiFeeReceiver	address	Address of the UI fee receiver used in fee calculations. Pass the zero address if not applicable.

Returns: Array of ReaderPositionUtils.PositionInfo values in the same order as positionKeys.

Execution price for increasing or decreasing a position

Use Reader.getExecutionPrice to estimate the execution price for increasing or decreasing a position, accounting for price impact.

Reader.getExecutionPrice

function getExecutionPrice(
    DataStore dataStore,
    address marketKey,
    MarketUtils.MarketPrices memory prices,
    uint256 positionSizeInUsd,
    uint256 positionSizeInTokens,
    int256 sizeDeltaUsd,
    int256 pendingImpactAmount,
    bool isLong
) external view returns (ReaderPricingUtils.ExecutionPriceResult memory)

Example (TypeScript / ethers):

const executionPriceResult = await reader.getExecutionPrice(
  dataStore.address,
  marketKey,
  prices,
  positionSizeInUsd,
  positionSizeInTokens,
  sizeDeltaUsd,
  pendingImpactAmount,
  true
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
marketKey	address	Address of the market
prices	MarketUtils.MarketPrices	Current prices for the index, long, and short tokens
positionSizeInUsd	uint256	Current size of the open position in USD. Pass 0 if there is no existing position.
positionSizeInTokens	uint256	Current size of the open position in index tokens. Pass 0 if there is no existing position.
sizeDeltaUsd	int256	Size change in USD. Positive to increase, negative to decrease.
pendingImpactAmount	int256	Pending price impact amount already accumulated for this position
isLong	bool	Pass true for a long position, false for short

Returns: ReaderPricingUtils.ExecutionPriceResult containing the execution price and price impact amounts.

Output amount for swaps

Use Reader.getSwapAmountOut to estimate how many tokens you receive for a swap, along with the price impact and swap fees.

Reader.getSwapAmountOut

function getSwapAmountOut(
    DataStore dataStore,
    Market.Props memory market,
    MarketUtils.MarketPrices memory prices,
    address tokenIn,
    uint256 amountIn,
    address uiFeeReceiver
) external view returns (uint256, int256, SwapPricingUtils.SwapFees memory fees)

Example (TypeScript / ethers):

const [amountOut, impactAmount, fees] = await reader.getSwapAmountOut(
  dataStore.address,
  market,
  prices,
  tokenIn,
  amountIn,
  ethers.constants.AddressZero
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	Market to route the swap through
prices	MarketUtils.MarketPrices	Current prices for the index, long, and short tokens
tokenIn	address	Address of the input token
amountIn	uint256	Amount of the input token
uiFeeReceiver	address	Address of the UI fee receiver. Pass the zero address if not applicable.

Returns: A tuple of (uint256 amountOut, int256 impactAmount, SwapPricingUtils.SwapFees fees) — the output token amount, price impact amount, and fee breakdown.

Output amount for deposits

Use Reader.getDepositAmountOut to estimate how many GM tokens you receive for a deposit.

Reader.getDepositAmountOut

function getDepositAmountOut(
    DataStore dataStore,
    Market.Props memory market,
    MarketUtils.MarketPrices memory prices,
    uint256 longTokenAmount,
    uint256 shortTokenAmount,
    address uiFeeReceiver,
    ISwapPricingUtils.SwapPricingType swapPricingType,
    bool includeVirtualInventoryImpact
) external view returns (uint256)

Example (TypeScript / ethers):

const marketTokensOut = await reader.getDepositAmountOut(
  dataStore.address,
  market,
  prices,
  longTokenAmount,
  shortTokenAmount,
  ethers.constants.AddressZero,
  swapPricingType,
  true
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	The market to deposit into
prices	MarketUtils.MarketPrices	Current prices for the index, long, and short tokens
longTokenAmount	uint256	Amount of the long token to deposit
shortTokenAmount	uint256	Amount of the short token to deposit
uiFeeReceiver	address	Address of the UI fee receiver. Pass the zero address if not applicable.
swapPricingType	ISwapPricingUtils.SwapPricingType	Pricing method to use for the internal swap component of the deposit
includeVirtualInventoryImpact	bool	Pass true to include virtual inventory impact in the price impact calculation

Returns: uint256 — the estimated number of GM tokens minted.

Output amount for withdrawals

Use Reader.getWithdrawalAmountOut to estimate how many long and short tokens you receive when withdrawing GM tokens.

Reader.getWithdrawalAmountOut

function getWithdrawalAmountOut(
    DataStore dataStore,
    Market.Props memory market,
    MarketUtils.MarketPrices memory prices,
    uint256 marketTokenAmount,
    address uiFeeReceiver,
    ISwapPricingUtils.SwapPricingType swapPricingType
) external view returns (uint256, uint256)

Example (TypeScript / ethers):

const [longTokenAmountOut, shortTokenAmountOut] = await reader.getWithdrawalAmountOut(
  dataStore.address,
  market,
  prices,
  marketTokenAmount,
  ethers.constants.AddressZero,
  swapPricingType
);

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	The market to withdraw from
prices	MarketUtils.MarketPrices	Current prices for the index, long, and short tokens
marketTokenAmount	uint256	Amount of GM tokens to burn
uiFeeReceiver	address	Address of the UI fee receiver. Pass the zero address if not applicable.
swapPricingType	ISwapPricingUtils.SwapPricingType	Pricing method to use for the internal swap component of the withdrawal

Returns: A tuple of (uint256 longTokenAmount, uint256 shortTokenAmount) — the estimated amounts of long and short tokens returned.

Direct lookups

Use these methods when you already have a key, salt, or account and want the raw stored value without additional pricing or fee calculations.

Reader.getMarket

function getMarket(DataStore dataStore, address key)
    external view returns (Market.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
key	address	Market token address used as the market key

Returns: Market.Props for the requested market.

Reader.getMarketBySalt

function getMarketBySalt(DataStore dataStore, bytes32 salt)
    external view returns (Market.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
salt	bytes32	Deterministic market deployment salt

Returns: Market.Props for the requested market.

Reader.getDeposit

function getDeposit(DataStore dataStore, bytes32 key)
    external view returns (Deposit.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
key	bytes32	Deposit request key

Returns: Raw Deposit.Props for the requested deposit.

Reader.getWithdrawal

function getWithdrawal(DataStore dataStore, bytes32 key)
    external view returns (Withdrawal.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
key	bytes32	Withdrawal request key

Returns: Raw Withdrawal.Props for the requested withdrawal.

Reader.getShift

function getShift(DataStore dataStore, bytes32 key)
    external view returns (Shift.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
key	bytes32	Shift request key

Returns: Raw Shift.Props for the requested shift.

Reader.getPosition

function getPosition(DataStore dataStore, bytes32 key)
    external view returns (Position.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
key	bytes32	Position key

Returns: Raw Position.Props for the requested position.

Reader.getOrder

function getOrder(DataStore dataStore, bytes32 key)
    external view returns (Order.Props memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
key	bytes32	Order key

Returns: Raw Order.Props for the requested order.

Account and position state helpers

Use these methods when you need raw account orders, PnL diagnostics, or liquidation checks rather than the higher-level position info helpers above.

Reader.getPositionPnlUsd

function getPositionPnlUsd(
    DataStore dataStore,
    Market.Props memory market,
    MarketUtils.MarketPrices memory prices,
    bytes32 positionKey,
    uint256 sizeDeltaUsd
) external view returns (int256, int256, uint256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	Market for the position
prices	MarketUtils.MarketPrices	Current prices for the market
positionKey	bytes32	Position key
sizeDeltaUsd	uint256	Position size delta to evaluate when computing PnL

Returns: A tuple of (positionPnlUsd, cappedPositionPnlUsd, sizeDeltaInTokens).

Reader.isPositionLiquidatable

function isPositionLiquidatable(
    DataStore dataStore,
    IReferralStorage referralStorage,
    bytes32 positionKey,
    Market.Props memory market,
    MarketUtils.MarketPrices memory prices,
    bool shouldValidateMinCollateralUsd,
    bool forLiquidation
) public view returns (bool, string memory, PositionUtils.IsPositionLiquidatableInfo memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
referralStorage	address	Address of the ReferralStorage contract
positionKey	bytes32	Position key
market	Market.Props	Market for the position
prices	MarketUtils.MarketPrices	Current prices for the market
shouldValidateMinCollateralUsd	bool	Whether to enforce the minimum collateral USD checks
forLiquidation	bool	Pass true when checking liquidation conditions, false for a soft check

Returns: A tuple of (isLiquidatable, reason, info) with the liquidation result, reason string, and detailed diagnostics.

Reader.getAccountOrders

function getAccountOrders(
    DataStore dataStore,
    address account,
    uint256 start,
    uint256 end
) external view returns (ReaderUtils.OrderInfo[] memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
account	address	Account to retrieve orders for
start	uint256	Start index for pagination
end	uint256	End index for pagination

Returns: Array of ReaderUtils.OrderInfo values for the account.

Market state and PnL helpers

Use these methods when you need one-market diagnostics without going through the paginated market list helpers.

Reader.getMarketInfo

function getMarketInfo(
    DataStore dataStore,
    MarketUtils.MarketPrices memory prices,
    address marketKey
) public view returns (ReaderUtils.MarketInfo memory)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
prices	MarketUtils.MarketPrices	Current prices for the market
marketKey	address	Market token address

Returns: ReaderUtils.MarketInfo for the requested market.

Reader.getPendingPositionImpactPoolDistributionAmount

function getPendingPositionImpactPoolDistributionAmount(
    DataStore dataStore,
    address market
) external view returns (uint256, uint256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	address	Market token address

Returns: A tuple of pending long-token and short-token impact pool distribution amounts.

Reader.getNetPnl

function getNetPnl(
    DataStore dataStore,
    Market.Props memory market,
    Price.Props memory indexTokenPrice,
    bool maximize
) external view returns (int256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	Market to evaluate
indexTokenPrice	Price.Props	Index token price range
maximize	bool	Whether to use the maximizing price path

Returns: Net market PnL as an int256.

Reader.getPnl

function getPnl(
    DataStore dataStore,
    Market.Props memory market,
    Price.Props memory indexTokenPrice,
    bool isLong,
    bool maximize
) external view returns (int256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	Market to evaluate
indexTokenPrice	Price.Props	Index token price range
isLong	bool	Pass true for long-side PnL
maximize	bool	Whether to use the maximizing price path

Returns: Long-side or short-side PnL as an int256.

Reader.getOpenInterestWithPnl

function getOpenInterestWithPnl(
    DataStore dataStore,
    Market.Props memory market,
    Price.Props memory indexTokenPrice,
    bool isLong,
    bool maximize
) external view returns (int256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	Market.Props	Market to evaluate
indexTokenPrice	Price.Props	Index token price range
isLong	bool	Pass true for long-side open interest
maximize	bool	Whether to use the maximizing price path

Returns: Open interest with PnL included, as an int256.

Reader.getPnlToPoolFactor

function getPnlToPoolFactor(
    DataStore dataStore,
    address marketAddress,
    MarketUtils.MarketPrices memory prices,
    bool isLong,
    bool maximize
) external view returns (int256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
marketAddress	address	Market token address
prices	MarketUtils.MarketPrices	Current prices for the market
isLong	bool	Pass true for the long side
maximize	bool	Whether to use the maximizing price path

Returns: Current PnL-to-pool factor as an int256.

Pricing and risk helpers

Use these methods when you need direct swap-impact or ADL diagnostics without calling the larger quote helpers.

Reader.getSwapPriceImpact

function getSwapPriceImpact(
    DataStore dataStore,
    address marketKey,
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    Price.Props memory tokenInPrice,
    Price.Props memory tokenOutPrice
) external view returns (int256, int256, int256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
marketKey	address	Market token address
tokenIn	address	Input token address
tokenOut	address	Output token address
amountIn	uint256	Input token amount
tokenInPrice	Price.Props	Input token price range
tokenOutPrice	Price.Props	Output token price range

Returns: A tuple of swap price impact values as signed integers.

Reader.getAdlState

function getAdlState(
    DataStore dataStore,
    address market,
    bool isLong,
    MarketUtils.MarketPrices memory prices
) external view returns (uint256, bool, int256, uint256)

Parameters:

Parameter	Type	Description
dataStore	address	Address of the DataStore contract
market	address	Market token address
isLong	bool	Pass true for the long side
prices	MarketUtils.MarketPrices	Current prices for the market

Returns: A tuple describing the ADL state, including the ADL phase, whether ADL is enabled, the PnL factor, and the minimum PnL factor for ADL.