Positions Response Fields

This page describes the fields of the response provided by the User DeFi Positions API

Positions per DeFi Protocol

List of objects - one object per DeFi Protocol -, containing a list of DeFi Positions for each Protocol. One object contains:

Parameter	Type	Description
chain	string	Chain or network name: blockchain identification, corresponds to the 'id' parameter returned by the 'getAllSupportedChains' endpoint
name	string	Protocol name, corresponds to the 'name" parameter returned by the 'getSupportedProtocolsList" endpoint
commonName	string	Protocol display name
logo	string	URL of the protocol logo
site	string	URL of the protocol website
fullCoverage	boolean	Flag to indicate Merlin P&L analytics coverage for the given protocol
portfolio	array of objects	List of Positions in a user's portfolio for the given Protocol & Chain: list of open positions for endpoints without P&L list of open & closed positions for endpoints with P&L "...WithPnl"
--module	string	Name of the DeFi Protocol's module, like: farm, stake, pool etc. To characterize the type of Position. Possible values: Liquidity Pool, Yield, Deposit, Staked, Locked, Farming, Leveraged Farming, Lending, Vesting, Rewards, Airdrop, Investment, Governance, Perpetuals, NFT Staked, NFT Liquidity Pool, NFT Lending, NFT Fraction, NFT P2P Borrower, NFT P2P Lender, Options Seller, Options Buyer, Insurance Seller, Insurance Buyer
--proxy	string	Name of the proxy wallet (smart wallet), if applicable (if Position managed via proxy wallet)
--total	object	Overall balances per Position
--/--		Parameters details here
--detailed	object	Detailed balances per Position
--/--...		Parameters details here
--yieldAndPnl	object	Detailed Yield and P&L analytics per Position - for "...WithPnl" endpoints only, and for P&L supported protocols only
--/--...		Parameters details here
--poolData	object	Detailed DEX LP Position analytics - for "...WithPnl" endpoints only, and for Uniswap V3 only
--/--...		Parameters details here

Merlin P&L supported protocols here.

Position > Total balances

Overall balances per Position:

Parameter	Type	Description
total	object	Overall balances per Position
--supplyUSD	number	Value in USD deposited by the user
--debtUSD	number	Debt amount in USD to be repaid by the user
--txFeeUSD	number	Transaction fees in USD, to date
--navUSD	number	Net asset value amount in USD
--active	boolean	Active Position indicator; true: means the Position is still yielding (generating yield)

Position > Detailed balances

Detailed balances per Position:

Parameter	Type	Description
detailed	object	Detailed balances per Position
--supply	array of objects	List of tokens deposited in the Position
--/--id	string	Token internal Merlin ID
--/--tokenAddress	string	Deposited token address
--/--tokenDecimals	number	Number of decimals for deposited token balance
--/--tokenName	string	Deposited token name
--/--tokenSymbol	string	Deposited token symbol
--/--usdRate	number	Deposited token USD price
--/--balance	number	Deposited token amount; apply number of decimals for precise value
--/--logo	string	URL of the token logo
--/--balanceDecimal	number	Deposited token amount considering decimals
--borrow	array of objects	List of tokens borrowed ; applies for Lending & Borrowing protocols
--/--id	number	Token internal Merlin ID
--/--tokenAddress	string	Borrowed token address
--/--tokenDecimals	number	Number of decimals for borrowed token balance
--/--tokenName	string	Borrowed token name
--/--tokenSymbol	string	Borrowed token symbol
--/--usdRate	number	Borrowed token USD price
--/--balance	number	Borrowed token amount; apply number of decimals for precise value
--/--logo	string	URL of the token logo
--/--balanceDecimal	number	Borrowed token amount considering decimals
--rewards	array of objects	List of reward tokens
--/--id	number	Token internal Merlin ID
--/--tokenAddress	string	Reward token address
--/--tokenDecimals	number	Number of decimals for reward token balance
--/--tokenName	string	Reward token name
--/--tokenSymbol	string	Reward token symbol
--/--usdRate	number	Reward token USD price
--/--balance	number	Reward token amount; apply number of decimals for precise value
--/--logo	string	URL of the token logo
--/--balanceDecimal	number	Reward token amount considering decimals
--lpToken*	array of objects	For DEX LP open Positions, details about the associated LP Token Applies for Uniswap V2&V3, Convex, Curve and SushiSwap
--/--id*	number	Token internal Merlin ID
--/--tokenAddress*	string	LP token address
--/--tokenDecimals*	number	Number of decimals for LP token token balance
--/--tokenName*	string	LP token name
--/--tokenSymbol*	string	LP token symbol
--/--usdRate*	number	LP token USD price
--/--balance*	number	LP token amount; apply number of decimals for precise value
--/--logo*	string	URL of the token logo
--/--balanceDecimal*	number	LP token amount considering decimals
--lpTokenAddress	string	LP token address For DeFi Position endpoints (without P&L): value provided for ERC20 contract pools only; no limitations for DeFi Positions with P&L endpoints
--poolAddress	string	Pool address, for Positions other than DEX LP For DeFi Position endpoints (without P&L): value provided for ERC20 contract pools only; no limitations for DeFi Positions with P&L endpoints
--poolTokenName	string	Pool token name, for DEX LP and other Positions, when lpTokenAddress or poolAddress are provided
--poolTokenSymbol	string	Pool token symbol, for DEX LP and other Positions, when lpTokenAddress or poolAddress are provided
--poolApy*	number	Internal Merlin data
--balanceOf*	number	Internal Merlin data
--totalSupply*	number	Internal Merlin data
--unlock	number	Unlock time, Unix timestamp format. Applies for active Lock positions

*Data provided by "...WithPnl" endpoints only, and for P&L supported protocols only. Check Merlin supported protocols here.

Position > Yield and P&L

Yield and P&L analytics per Position. Data provided by "...WithPnl" endpoints only, and for P&L supported protocols only. Check Merlin supported protocols here.

Parameter	Type	Description
yieldAndPnl	object	Yield and P&L analytics per Position
--id	string	Internal Merlin ID of the Position; to be used as input parameter for the endpoints returning Position dedicated info
--address	number	Internal Merlin Position address
--name	string	Name of the Position tokens
--symbol	string	Symbol of the Position tokens
--decimals	number	Number of decimals for Yield token balance
--currentYields	array of objects	Array of Yields in tokens generated after the last transaction (Unrealized Yields measured in tokens)
--/--address		Yield token address
--/--balance		Raw Yield token balance without taking into account decimals; apply above decimals info to obtain precise value
--pnlUSD	number	Overall P&L (Realized and Unrealized), valued in USD, of the Position, considering Yield, Transaction Fees and underlying asset(s) Price Fluctuation. More details about P&L computations here.
--txCount	number	Number of associated transactions for this Position
--txFeeUSD	number	Transaction Fees, valued in USD, related to this Position
--yieldUSD	number	Generated Yield (Realized and Unrealized) generated by this Position
--pnlUSDRealised	number	Historical realized P&L, for closed Position, considering Yield, Transactions Fees and underlying asset(s) Price Fluctuation
--pnlUSDRealised	number	Historical realized Yield, for closed Position
--deFiEvents	array of objects	Position movements (associated transactions), last 20 transactions; for Merlin internal use

Position > Pool Data

Detailed DEX LP open Position analytics. Data provided by "...WithPnl" endpoints only, and for Uniswap V3 only.

Parameter	Type	Description
poolData	object	Detailed DEX LP open Position analytics, for Uniswap V3 only
--position	string	Position address: NFT address
--chain	string	Blockchain short name
--token0USDPrice	number	Transaction fees in USD, to date
--token1USDPrice	number	Net asset value amount in USD
--token0	object	Details about token0: is, symbol, display name, balance decimals
--token1	object	Details about token1: is, symbol, display name, balance decimals
--unclaimedFees	object	Details about unclaimed Yield, breakdown between token0 and token1 balances, USD valuation and overall USD valuation
--claimedFees	object	Details about claimed Yield, breakdown between token0 and token1 balances, USD valuation and overall USD valuation
--liquidity	object	Details about current Liquidity available in the Pool, breakdown between token0 and token1 balances, USD valuation and overall USD valuation
--impermanentLoss	object	Details about current Impermanent Loss, breakdown between token0 and token1 balances, USD valuation and overall USD valuation
--maxPrice	number	Max price according to the Position range
--minPrice	number	Min price according to the Position range
--feeTier	number	Fee Tier applicable to the Position
--supplied	object	UNI-V3 LP Token details: NFT address, USD valuation, underlying token details (balance, USD valuation, entry price)
--inRange	boolean	Position in range flag