# Fixed yield schedule read API Source: https://docs.settlemint.com/docs/api-reference/token-features/fixed-yield-schedule Read a fixed yield schedule by contract address, including its rate, interval, denomination asset, claimed and unclaimed totals, and every accrual period. Read one fixed yield schedule by its contract address. The endpoint returns the schedule configuration, the running yield totals, and every accrual period. Use it to show coupon status to your holders, reconcile claimed yield against accrued yield, and drive a holder claim flow. The endpoint reads indexed data and never funds, claims, or changes the schedule, so you can call it safely from dashboards, audit jobs, and pre-claim checks. Read this page when you hold a schedule address and need its current state. To configure a schedule on a token, fund it, or submit a claim, use the [fixed treasury yield feature API](/docs/api-reference/token-features/fixed-treasury-yield). For operator workflow guidance, see [Configure yield schedules](/docs/operators/system-addons/yield-schedule). ## Endpoint [#endpoint] ```http GET /api/v2/addons/fixed-yield-schedules/{scheduleAddress} ``` Set `scheduleAddress` to the EVM contract address of the yield schedule. The schedule must belong to a token in the active DALP tenant and system scope, otherwise the read reports the schedule as not found. ```bash curl "https://your-platform.example.com/api/v2/addons/fixed-yield-schedules/0x71c7656ec7ab88b098defb751b7401b5f6d8976f" \ -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" ``` ```json { "data": { "id": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f", "startDate": "2023-04-01T13:00:00.000Z", "endDate": "2024-03-31T13:00:00.000Z", "rate": "500", "interval": "2592000", "totalClaimed": "1000.0", "totalUnclaimedYield": "500.0", "totalYield": "1500.0", "denominationAsset": { "id": "0x2222222222222222222222222222222222222222", "decimals": 6, "symbol": "USDC" }, "currentPeriod": { "id": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f-period-2", "startDate": "2023-06-01T13:00:00.000Z", "endDate": "2023-07-01T13:00:00.000Z", "totalClaimed": "0", "totalUnclaimedYield": "500.0", "totalYield": "500.0", "completed": false }, "nextPeriod": null, "periods": [ { "id": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f-period-0", "startDate": "2023-04-01T13:00:00.000Z", "endDate": "2023-05-01T13:00:00.000Z", "totalClaimed": "500.0", "totalUnclaimedYield": "0", "totalYield": "500.0", "completed": true }, { "id": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f-period-1", "startDate": "2023-05-01T13:00:00.000Z", "endDate": "2023-06-01T13:00:00.000Z", "totalClaimed": "500.0", "totalUnclaimedYield": "0", "totalYield": "500.0", "completed": true }, { "id": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f-period-2", "startDate": "2023-06-01T13:00:00.000Z", "endDate": "2023-07-01T13:00:00.000Z", "totalClaimed": "0", "totalUnclaimedYield": "500.0", "totalYield": "500.0", "completed": false } ] }, "links": { "self": "/v2/addons/fixed-yield-schedules/0x71c7656ec7ab88b098defb751b7401b5f6d8976f" } } ``` ## Schedule fields [#schedule-fields] | Field | Type | Notes | | ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | | `id` | EVM address | The yield schedule contract address. | | `startDate` | ISO-8601 timestamp | When yield accrual begins. | | `endDate` | ISO-8601 timestamp | When yield accrual stops. | | `rate` | string | Yield rate in basis points. `500` means 5 percent. | | `interval` | string | Payment interval in seconds. `2592000` is 30 days. | | `totalClaimed` | decimal string | Yield already claimed across all periods, in display units that follow the denomination asset decimals. | | `totalUnclaimedYield` | decimal string | Accrued yield not yet claimed, in display units. Reported as `0` when claimed has caught up to accrued. | | `totalYield` | decimal string | Total yield generated across all periods, in display units. | | `denominationAsset.id` | EVM address | The asset paid out as yield. | | `denominationAsset.decimals` | number | Decimals of the denomination asset. All yield amounts follow these decimals. | | `denominationAsset.symbol` | string | Symbol of the denomination asset, for example `USDC`. | ## Periods [#periods] A schedule pays yield in discrete periods. The response reports every period in `periods`, plus two convenience pointers: `currentPeriod` for the period active at read time and `nextPeriod` for the first period that has not started yet. Both pointers are `null` when no period matches, for example after the schedule has ended. | Field | Type | Notes | | --------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- | | `id` | string | Period identifier in the form `{scheduleAddress}-period-{index}`, for example `0x71c7...8976f-period-0`. | | `startDate` | ISO-8601 timestamp | When the period starts. | | `endDate` | ISO-8601 timestamp | When the period ends. | | `totalClaimed` | decimal string | Yield claimed in this period, in denomination asset display units. | | `totalUnclaimedYield` | decimal string | Accrued yield not yet claimed in this period, in display units. | | `totalYield` | decimal string | Total yield generated in this period, in display units. | | `completed` | boolean | `true` once the period end time has passed. The platform computes this from the period end at read time. | The platform resolves `currentPeriod`, `nextPeriod`, and each `completed` flag against the current time when you call the endpoint, so the same schedule reports different period state as time passes even with no new on-chain activity. ## Yield amounts and units [#yield-amounts-and-units] The platform reports `rate` and `interval` as raw configuration: basis points and seconds. Every yield amount is a display-unit decimal string that follows the denomination asset decimals, so `1000.0` for a six-decimal asset means one thousand whole units. The platform derives unclaimed yield from total yield minus claimed yield and clamps it to zero, so unclaimed never reports a negative value. ## Errors [#errors] | Code | Status | Meaning | | --------- | ------ | ---------------------------------------------------------------------------------------------------------------- | | DALP-0074 | 404 | The active system has no record of this schedule address. Check the address, or retry after indexing catches up. | | DALP-0075 | 503 | The denomination asset metadata is still being indexed. Retry after indexing catches up. | Both states are retryable. A 404 most often means the schedule address is wrong or the indexer has not yet processed the creation event. A 503 means the schedule exists but its denomination asset metadata is still being indexed. See the [error reference](/docs/api-reference/errors/error-code-reference) for the full catalog. ## Related [#related] * [Fixed treasury yield feature API](/docs/api-reference/token-features/fixed-treasury-yield) to configure, fund, and claim yield. * [Yield coverage statistics](/docs/api-reference/tokens/yield-coverage-statistics) to check whether the treasury can cover accrued yield. * [Configure yield schedules](/docs/operators/system-addons/yield-schedule) for the operator workflow. * [Fixed yield schedule commands](/docs/developers/cli/command-reference#fixed-yield-schedule-commands) for the CLI.