> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/docs/earn/core-concepts/position.md). # Position A user's deposit into a strategy, tracked over its full history – balance, performance, and every event that shaped it. A position is a specific wallet's history with a specific [strategy](/docs/earn/core-concepts/strategy.md): every deposit and withdrawal, the current balance, and performance calculated from that full history. A position is identified by the combination of a **wallet address** and a **`strategy_id`**. History defaults to the position's **full lifetime** – from the strategy's first block through the latest indexed one – since performance calculations need the complete history to be accurate. Results are paginated with `limit`/`offset`. ### Response shape A position response has four parts: | Section | Contains | | ---------- | --------------------------------------- | | `meta` | Wallet, strategy, chain, and status | | `tokens` | The tokens involved, classified by role | | `pnl` | Aggregated performance for the position | | `events[]` | The full deposit/withdraw history | #### `meta` Identifies the position and its current state: `wallet`, `strategy_id`, `chain_id`, `status` (whether the position is currently open or has been fully closed), and `opened_at` (when the first deposit happened). #### `tokens` Every token touched by this position, grouped by role: | Category | What it is | Example | | ------------ | ------------------------------------------ | ------------------- | | `underlying` | The base asset deposited or received back | WETH, USDC | | `share` | The strategy's own receipt token | aEthWETH, syrupUSDC | | `reward` | Protocol reward tokens, if any | – | | `gas` | The network's gas token, for cost tracking | ETH (on Ethereum) | ### Events `events[]` is the deposit/withdraw history behind the position, in chronological order. Each event has a direction, not a fixed token type: * **`deposit`** – `sent` is the underlying token, `received` is the share token. * **`withdraw`** – `sent` is the share token, `received` is the underlying token. Each side carries both a gross and a net amount: ```json "sent": { "token_id": "ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "amount_usd": "1.588000", "amount_gross": "0.001000", "amount_net": "0.000997" } ``` `amount_gross` and `amount_net` differ only on the side a fee was actually taken from. `balance_after` is a snapshot of the share balance right after the event, useful for charting a position's balance over time without replaying the whole history yourself. ### How PnL is calculated The core question a position answers: **how much has this deposit actually earned?** That splits into two numbers: * **Realized PnL** – profit that's locked in. It only appears on a `withdraw`: the user got underlying tokens back, and the gain relative to what they originally cost is fixed and won't change afterward. * **Unrealized PnL** – paper profit on whatever's still deposited. Calculated once, from the current value of the remaining balance versus what was paid for it. #### Why order matters (weighted-average cost) If a wallet deposits more than once at different rates, a withdrawal needs to know the *average* cost of the shares it's consuming – not just the total ever deposited. YiFi walks through a position's events in chronological order, maintaining a running weighted-average cost, and recalculates it at each withdrawal using only what had happened up to that point. A simplified example (USDC lending, rate rising over time): | # | Type | Rate | Amount | Avg. cost | Realized this step | | - | -------- | ---- | ------ | --------- | ------------------ | | 1 | Deposit | 1.00 | +1,000 | — | — | | 2 | Deposit | 1.05 | +500 | — | — | | 3 | Withdraw | 1.10 | −220 | 1.0161 | **+16.77** | | 4 | Deposit | 1.12 | +300 | — | — | | 5 | Withdraw | 1.15 | −115 | 1.0341 | **+11.59** | Realized PnL for each withdrawal, once calculated, never changes. Unrealized PnL is computed a single time at the end, from whatever balance remains. #### Rebasing vs. appreciating tokens Different protocols express yield differently, and a position handles both correctly: * **Appreciating.** The number of share tokens stays fixed; each one becomes worth more over time (most ERC-4626 vaults, wstETH). Yield shows up as a rising exchange rate. * **Rebasing.** The exchange rate stays pegged near 1:1; the *balance* of share tokens itself grows (Aave's aTokens, stETH). Yield shows up as more tokens appearing in the wallet, not a changing price. For example, an Aave USDC position might show `aEthUSDC` balance growing from 2,987.80 to 2,994.17 over three weeks, with the token's price sitting steady near $1 the whole time — that balance growth **is** the yield. YiFi detects which behavior a given strategy's share token follows and computes unrealized PnL accordingly, so both types report accurate performance rather than a false loss or gain. #### Settle token (multi-input strategies) Some strategies accept more than one input token (for example, a strategy that takes ETH, WETH, or eETH and issues the same share token). Since those aren't directly comparable amounts, PnL in token terms is expressed relative to one chosen **settle token** – by default, the first input token used in the position's history, overridable via `?settle_token=`. Conversion between input tokens uses the **current** exchange rate, not the rate at the time of each deposit — this keeps the strategy's own performance cleanly separated from any price movement between the input assets themselves. #### Gross vs. net, and USD PnL is reported in three parallel views: * **`gross`** – performance before fees. * **`net`** – performance after the zap fee is factored in at each step. * **`_usd` fields** – the same calculation expressed in USD. This can diverge meaningfully from the settle-token percentage for volatile assets – both numbers are correct, they just answer different questions ("how did my tokens grow" vs. "how did my dollar value grow"). ### Example – position summary ```json { "success": true, "data": { "meta": { "wallet": "0x053806E0642F6A6aAFE6176bd264cbbE446C8c92", "strategy_id": "eth-eth-lending-aave", "chain_id": "ethereum", "status": "active", "opened_at": 1774528679 }, "tokens": { "underlying": [{ "symbol": "WETH", "token_id": "ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "decimals": 18 }], "share": [{ "symbol": "aEthWETH", "token_id": "ethereum:0x4d5f47fa6a74757f35c14fd3a6ef8e3c9bc514e8", "decimals": 18 }], "reward": [], "gas": [{ "symbol": "ETH" }] }, "pnl": { "settle_token": { "token_id": "ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "symbol": "WETH" }, "gross": { "realized_pnl_settle": "0.000210", "unrealized_pnl_settle": "0.000045", "pnl_settle_pct": "3.84", "pnl_usd_pct": "4.12" }, "net": { "realized_pnl_settle": "0.000195", "unrealized_pnl_settle": "0.000042", "pnl_settle_pct": "3.55" } }, "events": [ { "type": "deposit", "tx_hash": "0x...", "sent": { "token_id": "ethereum:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "amount_gross": "0.001000", "amount_net": "0.000997", "amount_usd": "1.588000" }, "received": { "token_id": "ethereum:0x4d5f47fa6a74757f35c14fd3a6ef8e3c9bc514e8", "amount_gross": "0.000997", "amount_net": "0.000997", "amount_usd": "1.690081" }, "balance_after": { "share_balance": "0.000997", "share_balance_usd": "1.690081" } } ], "pagination": { "limit": 20, "offset": 0 } }, "error": null } ``` ### Relationship to Strategy A position is what a [strategy](/docs/earn/core-concepts/strategy.md) becomes once a specific wallet deposits into it.