> ## Documentation Index
> Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# getYieldEarnings

# getYieldEarnings

Gets a wallet's [Earn](/docs/earn/overview) earnings across every vault it holds on one chain: aggregate USD totals plus a per-vault breakdown.

The values are indexed by Morpho rather than read on-chain, so they trail the chain head by a short delay. [`getYieldPosition`](/docs/javascript/reference/client/get-yield-position) stays the source of truth for what a position is worth right now; use this function for earnings and PNL. Morpho aggregates per chain, so `chainId` is required and Vault V1 positions are not covered.

Aggregate totals come back in USD only, because per-vault earnings are denominated in different underlying assets and are not additive. A vault with no USD price is skipped from the totals, not counted as zero.

Positions in vaults the environment does not offer are still included, with `vaultId` set to `null` for those entries.

## Usage

```javascript theme={"system"}
import { getYieldEarnings } from '@dynamic-labs-sdk/client';

const earnings = await getYieldEarnings({
  chainId: 8453, // Base
  walletAccount,
});

console.log(earnings.totalPnlUsd); // aggregate PNL in USD
console.log(earnings.vaults.length); // per-vault breakdown
```

## Parameters

| Parameter       | Type                       | Description                                                                        |
| --------------- | -------------------------- | ---------------------------------------------------------------------------------- |
| `chainId`       | `number`                   | EVM chain ID on which the wallet's earnings are aggregated (e.g. `8453` for Base). |
| `walletAccount` | `WalletAccount`            | The wallet account whose earnings are being read.                                  |
| `client`        | `DynamicClient` (optional) | The Dynamic client instance. Only required when using multiple Dynamic clients.    |

## Returns

`Promise<YieldEarnings>` - The wallet's aggregate USD totals and per-vault earnings.

| Field            | Type                   | Description                                    |
| ---------------- | ---------------------- | ---------------------------------------------- |
| `chainId`        | `number`               | The chain the earnings were aggregated on.     |
| `ownerAddress`   | `string`               | The wallet address the earnings were read for. |
| `totalAssetsUsd` | `number`               | Total position value across vaults, in USD.    |
| `totalPnlUsd`    | `number`               | Total profit or loss across vaults, in USD.    |
| `vaults`         | `YieldVaultEarnings[]` | Per-vault earnings entries.                    |

Each entry in `vaults`:

| Field          | Type             | Description                                                                                     |
| -------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `vaultId`      | `string \| null` | Opaque vault identifier, or `null` for vaults the environment does not offer.                   |
| `vaultAddress` | `string`         | Contract address of the vault.                                                                  |
| `assets`       | `string`         | Current position value in raw underlying-token units. Divide by `assetDecimals` before display. |
| `assetsUsd`    | `number \| null` | Position value in USD, or `null` when the vault has no USD price.                               |
| `pnl`          | `string \| null` | Profit or loss in raw underlying-token units, or `null` when unavailable.                       |
| `pnlUsd`       | `number \| null` | Profit or loss in USD, or `null` when the vault has no USD price.                               |
| `roe`          | `number \| null` | Time-weighted, non-annualized return as a decimal. `null` when there is too little history.     |

## Examples

### List per-vault earnings

```javascript theme={"system"}
import { getYieldDetails, getYieldEarnings } from '@dynamic-labs-sdk/client';
import { formatUnits } from 'viem';

const earnings = await getYieldEarnings({ chainId: 8453, walletAccount });

for (const vault of earnings.vaults) {
  if (vault.vaultId === null || vault.pnl === null) {
    continue; // vault not offered here, or no PNL available
  }

  // `pnl` is a raw string in the vault's underlying-token units, like `assets`
  // from getYieldPosition, so format it with the vault's `assetDecimals`.
  const details = await getYieldDetails({ vaultId: vault.vaultId });
  const pnl = formatUnits(BigInt(vault.pnl), details.assetDecimals);
  console.log(`${details.assetSymbol}: ${pnl} (${vault.pnlUsd ?? 'n/a'} USD)`);
}
```

## React

`useGetYieldEarnings` is a query hook that stays disabled until `walletAccount` is defined, safe to render before a wallet is connected.

```tsx theme={"system"}
import { useGetYieldEarnings } from '@dynamic-labs-sdk/react-hooks';
import type { WalletAccount } from '@dynamic-labs-sdk/client';

function TotalEarnings({
  chainId,
  walletAccount,
}: {
  chainId: number;
  walletAccount: WalletAccount | undefined;
}) {
  const { data: earnings, isLoading } = useGetYieldEarnings({
    chainId,
    walletAccount,
  });

  if (isLoading) {
    return <p>Loading earnings...</p>;
  }

  return <p>Total PNL: ${earnings?.totalPnlUsd.toFixed(2) ?? '0.00'}</p>;
}
```

## Related

* [`getYieldPerformance`](/docs/javascript/reference/client/get-yield-performance) - The wallet's earnings in a single vault
* [`getYieldPosition`](/docs/javascript/reference/client/get-yield-position) - The wallet's current balance in a vault
* [`listYieldVaults`](/docs/javascript/reference/client/list-yield-vaults) - The vaults available to the environment