# Yield coverage statistics

Source: https://docs.settlemint.com/docs/developers/api-integration/yield-coverage-statistics
Read indexed yield funding, consumed-interest, and allowance coverage for a fixed-treasury-yield token through the DALP API.



Yield coverage statistics show whether a token's configured schedule has enough denomination asset balance and wallet allowance for holder claims. Use the endpoint to power monitoring dashboards, approval prompts, and treasury checks for fixed treasury yield programmes.

The endpoint reads indexed state only. Check the empty and indexing states below before asking an operator to act.

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

Call the token statistics endpoint with the token address in the path. The response uses the single-resource envelope and preserves token amounts as 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 locale-independent decimal strings. Preserve them as strings or decimal-safe values in clients 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 has not indexed yet, 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 allowance.

## 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. DALP calculates that adjusted value by converting holder-level consumed interest into denomination units and subtracting it.

`requiredAllowance` uses the same adjusted amount plus one period of headroom. This keeps approval prompts from overstating what a wallet treasury needs after conversions have already consumed part of the yield.

`allowanceCoveredPercentage` compares the indexed allowance with `requiredAllowance` and caps the percentage at full coverage, while still returning the actual allowance amount.

## Related [#related]

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