# Yield coverage statistics

Source: https://docs.settlemint.com/docs/api-reference/tokens/yield-coverage-statistics
Monitor funding gaps for fixed-treasury-yield tokens before they affect payouts, with schedule status, consumed interest, and allowance coverage in one call.



Operators running fixed treasury yield programmes need to know whether the treasury holds enough denomination asset, and whether the wallet allowance covers outstanding claims, before a payout gap reaches holders. This resource exposes that data in one call, so you can build monitoring dashboards, drive approval prompts, and run treasury checks without assembling the figures yourself.

This endpoint reads indexed state only. Before you ask an operator to act, check the empty and indexing states described below.

## Read yield coverage [#read-yield-coverage]

Call the token statistics endpoint with the token address in the path. You receive a single-resource envelope; amount fields are decimal strings.

```bash
curl "https://your-platform.example.com/api/v2/tokens/0xTOKEN/stats/yield-coverage" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```

```json
{
  "data": {
    "yieldCoverage": 150,
    "hasYieldSchedule": true,
    "isRunning": true,
    "totalUnclaimedYield": "500.000000000000000000",
    "denominationAssetBalance": "750.000000000000000000",
    "denominationAssetTreasuryAllowance": "2000.000000000000000000",
    "allowanceCoveredPercentage": "100",
    "requiredAllowance": "2000.000000000000000000",
    "treasuryIsContract": false,
    "treasuryAddress": "0x1111111111111111111111111111111111111111",
    "scheduleAddress": "0x2222222222222222222222222222222222222222"
  },
  "links": {
    "self": "/v2/tokens/0xTOKEN/stats/yield-coverage"
  }
}
```

## Fields [#fields]

| Field                                | Type            | Notes                                                                                                                                                                       |
| ------------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenAddress`                       | path string     | Token contract address.                                                                                                                                                     |
| `yieldCoverage`                      | number          | Percentage of adjusted unclaimed yield covered by the available denomination asset balance. Values can exceed 100 when the treasury holds more than the outstanding amount. |
| `hasYieldSchedule`                   | boolean         | Whether DALP has indexed a yield schedule for the token.                                                                                                                    |
| `isRunning`                          | boolean         | Whether the current time falls within the indexed schedule start and end dates.                                                                                             |
| `totalUnclaimedYield`                | decimal string  | Indexed outstanding yield after DALP subtracts holder-level consumed interest that conversion flows already used but claims have not settled.                               |
| `denominationAssetBalance`           | decimal string  | Available denomination asset balance used for the yield coverage calculation.                                                                                               |
| `denominationAssetTreasuryAllowance` | decimal string  | ERC-20 allowance granted by the treasury wallet to the yield schedule contract.                                                                                             |
| `allowanceCoveredPercentage`         | decimal string  | Percentage of `requiredAllowance` covered by `denominationAssetTreasuryAllowance`. DALP caps the percentage at full coverage.                                               |
| `requiredAllowance`                  | decimal string  | Suggested allowance for keeping holder claims unblocked. DALP sizes it as indexed unclaimed yield plus one period of headroom.                                              |
| `treasuryIsContract`                 | boolean or null | `true` for a contract treasury, `false` for a wallet treasury, and `null` while indexing has not classified the treasury.                                                   |
| `treasuryAddress`                    | address or null | Configured yield treasury address, or `null` when DALP has no indexed fixed-treasury-yield feature row.                                                                     |
| `scheduleAddress`                    | address or null | Yield schedule contract address. For wallet treasuries, this is the spender that needs the denomination asset allowance.                                                    |

DALP serializes amount fields as decimal strings with no locale formatting. Preserve them as strings or decimal-safe values in your client so large token amounts do not lose precision.

## Empty and indexing states [#empty-and-indexing-states]

If the token has no indexed yield schedule, DALP returns `hasYieldSchedule: false`, zero balance and allowance fields, and `null` treasury and schedule addresses.

If the schedule exists but the treasury feature row is still indexing, DALP can return `hasYieldSchedule: true` and a `scheduleAddress` while `treasuryAddress` and `treasuryIsContract` are `null`. Treat that as an indexing catch-up state and retry later instead of prompting for approval.

## Wallet allowance guidance [#wallet-allowance-guidance]

Only prompt for an allowance transaction when `treasuryIsContract` is `false` and the allowance is below the required amount. Prefer the direct amount comparison:

* `denominationAssetTreasuryAllowance` is lower than `requiredAllowance`

You can also use `allowanceCoveredPercentage` for display, but only treat it as undercovered when `requiredAllowance` is greater than zero.

Do not ask a contract treasury to approve wallet allowance. When `treasuryIsContract` is `true`, contract-specific treasury logic supplies the payout path. When `treasuryIsContract` is `null`, wait for indexing to classify the treasury before deciding which prompt to show.

## Calculation model [#calculation-model]

The statistic is indexer-backed. DALP reads the indexed yield schedule, unclaimed yield totals, denomination asset balance, fixed-treasury-yield feature row, holder consumed-interest rows, and ERC-20 allowance row for the active chain.

`yieldCoverage` compares the available denomination asset balance with adjusted unclaimed yield. To get that adjusted value, DALP converts each holder's consumed interest into denomination units and subtracts the total. Conversions consume interest before a claim settles, so the raw unclaimed figure overstates what the treasury still needs to cover.

`requiredAllowance` adds one period of headroom to the same adjusted amount, preventing your approval prompts from overstating what a wallet treasury needs.

`allowanceCoveredPercentage` compares the indexed allowance with `requiredAllowance`. The platform caps the percentage at full coverage while still returning the actual allowance amount in `denominationAssetTreasuryAllowance`.

## Related [#related]

* [Fixed Treasury Yield](/docs/architects/components/token-features/fixed-treasury-yield)
* [Token volume statistics](/docs/api-reference/tokens/token-volume-statistics)
* [Token holders and transfers](/docs/api-reference/tokens/token-holders-transfers)
* [Asset decimals](/docs/api-reference/reference/asset-decimals)