# Token treasury health Source: https://docs.settlemint.com/docs/api-reference/tokens/token-treasury-health Read treasury funding readiness for maturity-redemption and fixed-treasury-yield features. The Platform API combines indexed allowance ceilings, an implementation classification for the treasury account, and a live ERC-20 balance read to return one green, yellow, or red badge. Use the badge to show whether a token's treasury is ready for its next redemption or yield obligation before your integration depends on that funding. Call this endpoint as an operational readiness check. It does not move funds, approve allowances, guarantee legal availability of treasury assets, or replace your funding and custody controls. ## Read treasury health [#read-treasury-health] Call the endpoint with the token address in the path: ```bash curl "https://your-platform.example.com/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/treasury/health" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" ``` A `green` response confirms that the configured treasury balance covers the projected next-period need and all applicable indexed allowance ceilings are satisfied. Example response: ```json { "data": { "approvals": [ { "kind": "maturity-redemption", "featureAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f", "treasury": "0x8ba1f109551bd432803012645ac136ddd64dba72", "denominationAsset": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "allowance": "1000.00", "required": "1000.00", "satisfied": true } ], "implementation": { "treasuryIsContract": false }, "availableBalance": "1250.00", "projectedNeed": "1000.00", "status": "green", "reason": null, "measuredAt": "2026-05-23T22:13:25Z" }, "links": { "self": "/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/treasury/health" } } ``` ## What the status means [#what-the-status-means] | Status | Meaning | What to do | | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `green` | Approval ceilings are satisfied, or they do not apply, and the live treasury balance covers the projected need. | Continue with the funding-dependent operation after your normal review checks. | | `yellow` | Approval ceilings are satisfied, or they do not apply, but the live balance is below the projected need. | Fund the treasury or update the expected redemption or yield setup before relying on the next payout. | | `red` | At least one applicable allowance row is below its required ceiling. | Update the ERC-20 allowance from the treasury to the feature contract before treating the treasury as ready. | Allowance rows apply to externally owned treasury wallets. Contract or vault treasuries, and treasuries that the indexer has not classified yet, fall through to the balance check instead of forcing a red status. ## Fields [#fields] | Field | Type | Notes | | ----------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `approvals[]` | array | One row for each maturity-redemption or fixed-treasury-yield feature that needs an allowance ceiling check. Empty when neither feature is attached. | | `approvals[].kind` | string | `maturity-redemption` or `fixed-treasury-yield`. | | `approvals[].featureAddress` | address | Feature contract that holds the allowance ceiling. | | `approvals[].treasury` | address | Treasury wallet measured for the feature. | | `approvals[].denominationAsset` | address | ERC-20 asset used for the allowance and balance check. | | `approvals[].allowance` | decimal string | Indexed treasury-to-feature ERC-20 allowance, expressed in denomination asset units (adjusted for decimals). | | `approvals[].required` | decimal string | Required allowance ceiling for the feature, expressed in denomination asset units (adjusted for decimals). | | `approvals[].satisfied` | boolean | `true` when the indexed allowance is greater than or equal to the required ceiling. | | `implementation.treasuryIsContract` | boolean or null | `true` for a contract treasury, `false` for an externally owned account, and `null` when the indexer has not classified the treasury yet. | | `availableBalance` | decimal string | Live `balanceOf(treasury)` for the resolved denomination asset. The only live on-chain read the endpoint performs. | | `projectedNeed` | decimal string | Projected next-period denomination need for the next scheduled redemption or unclaimed yield. | | `status` | string | `green`, `yellow`, or `red`. | | `reason` | string or null | Human-readable reason for a non-green result. `null` when the status is green. | | `measuredAt` | timestamp | Server timestamp captured immediately after the live balance read. | ## When to call it [#when-to-call-it] Call treasury health before your integration depends on redemption or yield funding being ready: 1. Read the token and its attached features. 2. Call `GET /api/v2/tokens/{tokenAddress}/treasury/health`. 3. If you receive a yellow response, fund the treasury before relying on the next payout. 4. If you receive a red response, update the treasury allowance for the feature contract and call the endpoint again. 5. Re-check the relevant token feature, holder, or event endpoint after your funding operation completes. For maturity-redemption setup and redemption events, see [maturity redemption](/docs/api-reference/token-features/maturity-redemption) and [token lifecycle](/docs/api-reference/tokens/token-lifecycle). For fixed treasury yield setup, see [fixed treasury yield](/docs/api-reference/token-features/fixed-treasury-yield). For broader feed-based valuation, see [token price resolution](/docs/api-reference/tokens/token-price-resolution). ## Failure cases [#failure-cases] The endpoint fails closed when a single badge would be misleading. Common setup failures include: | Condition | Result | Fix | | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The resolved treasury is the zero address. | The API returns an error instead of a green, yellow, or red badge. | Configure a non-zero treasury wallet for the bond or yield feature, then call the endpoint again. | | The live `balanceOf(treasury)` read fails. | The API returns an upstream dependency error. | Retry after the chain provider is reachable, then verify the RPC endpoint and denomination asset if the failure persists. | | The maturity-redemption feature is attached, but the redemption requirement for the bond has not been computed yet. | The API returns a retryable dependency error instead of a badge. | Wait for the bond's redemption requirement to become available, then call the endpoint again. A freshly deployed bond resolves this once the bond data is read in. | | Maturity-redemption and fixed-treasury-yield resolve to different treasury, denomination asset, or implementation values on the same token. | The API refuses to compose one treasury badge. | Reconcile the feature treasury configuration or read each feature's setup before presenting a combined status. | For the full error list, see the [Platform API error reference](/docs/api-reference/errors/platform-api-error-reference).