Fixed yield schedule read API

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. For operator workflow guidance, see Configure yield schedules.

Endpoint

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.

curl "https://your-platform.example.com/api/v2/addons/fixed-yield-schedules/0x71c7656ec7ab88b098defb751b7401b5f6d8976f" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

{
  "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

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.

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

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

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 for the full catalog.

Related

• Fixed treasury yield feature API to configure, fund, and claim yield.
• Yield coverage statistics to check whether the treasury can cover accrued yield.
• Configure yield schedules for the operator workflow.
• Fixed yield schedule commands for the CLI.