<!-- tempo-docs-context -->
> Source: [/docs/earn/balances](https://tempo.xyz/developers/docs/earn/balances.md)
> Section: [Earn](https://tempo.xyz/developers/docs/earn.md). Choose a vault, deposit stablecoins, read positions, and withdraw. Earn is in beta; see the introduction for access.
> [Documentation index](https://tempo.xyz/developers/llms.txt) · [Docs skill](https://tempo.xyz/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.xyz/developers/llms.txt) and Markdown pages directly.

# Balances and earnings

Display the current asset value of each account's position as its earning balance. Keep share balance, earnings, available withdrawals, and pending withdrawals distinct.

## Read a position

Use `GET /v1/earn/addresses/{address}/positions` to list an account's positions, or `GET /v1/earn/vaults/{vaultId}/positions/{address}` for one vault. Keep `chainId` consistent with the network used for the deposit.

The API example starts with the [deposit demo’s vault](https://tempo.xyz/developers/docs/earn/integrate#try-a-deposit) on `testnet`. Replace `address` with your depositor address, or change both the vault and network to read another position. Use **Try** to read the position or switch the request’s code language to copy an example.

`GET /v1/earn/vaults/{vaultId}/positions/{address}`

Get account position

[API reference](https://tempo.xyz/developers/docs/api/earn#getearnvaultposition) — request parameters, authentication, and response schema. The examples below use editable sample values.

**cURL**

```bash
curl 'https://api.tempo.xyz/v1/earn/vaults/0x20147491b5701dea880263241c335caca9be326d/positions/0xbe058e1c4df8a4366a387bf595b284246a93039e?chainId=testnet'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/earn/vaults/0x20147491b5701dea880263241c335caca9be326d/positions/0xbe058e1c4df8a4366a387bf595b284246a93039e?chainId=testnet')
```

The single-position response includes `shareBalance`, `value`, and `valueToken`. Format the asset value using the token's decimals. Shares represent a position; their count is not an equal amount of stablecoins.

For public-chain data, these endpoints support anonymous reads. Use [API authentication](https://tempo.xyz/developers/docs/api/authentication) for dedicated quotas; an API key requires `data:read` access.

<span id="distinguish-earnings-from-balance-changes" />

## Calculate earnings

Use `GET /v1/earn/vaults/{vaultId}/earnings/{address}` for earnings over a selected period. Deposits, withdrawals, and share transfers change a balance without being earnings. When the response reports `status: incomplete_cost_basis`, show earnings as unavailable, rather than zero.

Choose the measurement window with the same account, vault, and network:

`GET /v1/earn/vaults/{vaultId}/earnings/{address}`

Get vault earnings

[API reference](https://tempo.xyz/developers/docs/api/earn#getearnvaultearnings) — request parameters, authentication, and response schema. The examples below use editable sample values.

**cURL**

```bash
curl 'https://api.tempo.xyz/v1/earn/vaults/0x20147491b5701dea880263241c335caca9be326d/earnings/0xbe058e1c4df8a4366a387bf595b284246a93039e?chainId=testnet'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/earn/vaults/0x20147491b5701dea880263241c335caca9be326d/earnings/0xbe058e1c4df8a4366a387bf595b284246a93039e?chainId=testnet')
```

<span id="show-rates-and-rewards-accurately" />

### Show rates and rewards

Vault responses can include an `apy` object with observed vault returns, reward information, and a measurement window. It can be `null` when no component is measurable. Display unavailable data as unavailable, rather than as zero.

Request account-specific APY from the [position endpoint](https://tempo.xyz/developers/docs/api/earn#getearnvaultposition) when showing an account's effective rate. Reward qualification can lag a new deposit or transfer, and an eligible boost does not mean the whole balance qualifies. Keep temporary reward terms separate from observed vault returns.

For charts, use the [share-price history endpoint](https://tempo.xyz/developers/docs/api/earn#getearnvaultshareprices) for vault share prices and the [earnings endpoint](https://tempo.xyz/developers/docs/api/earn#getearnvaultearnings) for an account's earnings. Label each chart for the metric it shows.

## Read private positions

Account position listing supports private Zones, but its optional earnings data is unavailable for those positions. Check endpoint support before reusing the public-account earnings view. See [private Earn tracking](https://tempo.xyz/developers/docs/earn/integrate#track-private-earn-activity).

For schema details, see the [Earn API](https://tempo.xyz/developers/docs/api/earn).