Historical validator APY snapshots

Endpoint

GET /api/dtao/validator/yield/history/v1

Description

Returns a historical series of validator-yield snapshots per (hotkey, subnet). Each row records the validator’s stake and its rolling 1-hour, 1-day, 7-day, and 30-day APYs at the sampled block, so you can chart how a validator’s returns have changed over time.

Filter with hotkey and netuid to isolate a validator on a subnet, use min_stake to skip low-stake noise, and bound the window with timestamp_start/timestamp_end. For a batch-latest lookup across many positions see POST /api/dtao/validator/yield/latest/v1.

Parameters

Name	In	Type	Required	Description
hotkey	query	string		Filter by validator hotkey (SS58 or hex).
netuid	query	integer		Subnet id.
min_stake	query	integer		Only return snapshots where the validator’s stake is at least this many rao.
timestamp_start	query	integer		Start of Unix timestamp range in seconds (inclusive).
timestamp_end	query	integer		End of Unix timestamp range in seconds (inclusive).
page	query	integer		1-based page number.
limit	query	integer		Page size (max 200).
order	query	—		Sort order, e.g. timestamp_desc, seven_day_apy_desc.

Responses

200 — Validators retrieved successfully

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "pagination",
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "hotkey",
          "netuid",
          "block_number",
          "timestamp",
          "stake",
          "one_hour_apy",
          "one_day_apy",
          "seven_day_apy",
          "thirty_day_apy"
        ],
        "properties": {
          "block_number": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "hotkey": {
            "type": "object",
            "required": [
              "ss58",
              "hex"
            ],
            "properties": {
              "hex": {
                "type": "string",
                "description": "The hex format of the hot key"
              },
              "ss58": {
                "type": "string",
                "description": "The SS58 format of the hot key"
              }
            }
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "netuid": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "one_day_apy": {
            "type": "number",
            "format": "double"
          },
          "one_day_epoch_participation": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "one_hour_apy": {
            "type": "number",
            "format": "double"
          },
          "seven_day_apy": {
            "type": "number",
            "format": "double"
          },
          "seven_day_epoch_participation": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "stake": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "thirty_day_apy": {
            "type": "number",
            "format": "double"
          },
          "thirty_day_epoch_participation": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "required": [
        "current_page",
        "per_page",
        "total_items",
        "total_pages"
      ],
      "properties": {
        "current_page": {
          "type": "integer",
          "format": "int32"
        },
        "next_page": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "per_page": {
          "type": "integer",
          "format": "int32"
        },
        "prev_page": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "total_items": {
          "type": "integer",
          "format": "int32"
        },
        "total_pages": {
          "type": "integer",
          "format": "int32"
        }
      }
    }
  }
}

400 — Bad request

404 — Validators not found

500 — Internal server error

Try it

Interactive request console coming soon. In the meantime you can use the OpenAPI spec with any client (Insomnia, Bruno, Scalar, curl).

Authentication

All Taostats API requests require an Authorization header containing your API key. See Getting Started.