Skip to main content
Portfolio Wallets earn yield from multiple sources with different accrual mechanics. This guide explains how yield is computed and how to use the yield endpoint for detailed reporting.

​
How yield accrues

Yield sources fall into two categories: These tokens appreciate in value over time. When you deposit USDC, it is converted into the yield token at the current exchange rate. As the protocol earns yield, the token’s NAV (net asset value) per share increases, making your tokens worth more USDC. The wallet’s balance.totalUsd reflects the current market value of all positions, so NAV appreciation is automatically captured in the balance.

​
Fixed-rate tokens (USDz)

USDz accrues yield at a fixed annual rate (currently visible via the yield endpoint’s apyBps field). Unlike NAV tokens, USDz maintains a 1:1 USDC peg onchain — yield is accrued virtually and settled when you withdraw. The wallet’s balance.totalUsd includes the accrued virtual yield for USDz positions, so the balance grows linearly even though the onchain token balance stays flat.

​
Wallet-level earnings

Yield is reported at the wallet level, not per position. This is because rebalances move funds between positions over time, making per-position attribution misleading. The formula is: 
earnedUsd = currentBalance + totalWithdrawn - totalDeposited
This captures all yield regardless of which position generated it.

​
The yield endpoint

Use GET /v2/wallets/:id/yield for a detailed yield breakdown: 
curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/yield" \
  -H "Authorization: Bearer $API_TOKEN"

{
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "earnedUsd": "250.000000",
  "currentBalanceUsd": "82500.000000",
  "totalDepositedUsd": "80000.000000",
  "totalWithdrawnUsd": "0.000000",
  "yieldSources": [
    {
      "yieldSourceId": "usdz",
      "name": "Anzen USDz",
      "type": "fixed",
      "apyBps": 330,
      "allocationPct": 60
    },
    {
      "yieldSourceId": "syrup-usdc",
      "name": "Maple Syrup USDC",
      "type": "variable",
      "apyBps": 650,
      "allocationPct": 40
    }
  ]
}

​
Response fields

FieldDescription
earnedUsdCumulative yield earned (same as balance.earnedUsd on the wallet)
currentBalanceUsdCurrent total wallet balance
totalDepositedUsdSum of all completed deposits
totalWithdrawnUsdSum of all completed withdrawals
yieldSourcesPer-source APY and allocation breakdown

​
Yield source fields

FieldDescription
yieldSourceIdIdentifier for the yield source
nameDisplay name
type"fixed" (e.g. USDz) or "variable" (e.g. Syrup, Resolv LP)
apyBpsCurrent annualized yield in basis points (100 bps = 1%). null if unavailable.
allocationPctTarget allocation percentage for this source in the wallet’s strategy

​
Displaying yield to users

  1. Total earned — use balance.earnedUsd from the wallet response or earnedUsd from the yield endpoint
  2. Current APY — compute a blended APY from the yield endpoint’s yieldSources array: 
    blendedApyBps = sum(source.apyBps * source.allocationPct / 100) for each source
  3. Yield breakdown — show each yield source’s name, type, apyBps, and allocationPct from the yield endpoint

​
Important notes

  • earnedUsd is always >= 0. It will never go negative even if market conditions temporarily reduce a NAV token’s value below cost basis.
  • type: "fixed" sources accrue at a predictable rate. type: "variable" sources fluctuate based on market conditions.
  • apyBps reflects the current rate and may change over time. It is not a guaranteed return.
  • Balances may briefly lag deposits or withdrawals due to caching. See Balances and Yield for valuation notes.