Batch lookup: latest validator APY for many positions

Endpoint

POST /api/dtao/validator/yield/latest/v1

Description

Batch endpoint that returns the latest validator-yield snapshot for a list of (hotkey, netuid) positions supplied in the request body. Each returned row includes the validator’s current stake and its rolling 1-hour, 1-day, 7-day, and 30-day APYs, plus optional per-window epoch participation.

Pass up to limit positions in one call to avoid fanning out per-hotkey GETs against /api/dtao/validator/yield/history/v1; min_stake filters out low-stake positions and order controls the sort of the returned rows.

Parameters

No parameters.

Request body

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "positions"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "format": "int32"
    },
    "min_stake": {
      "type": "integer",
      "format": "int64",
      "nullable": true
    },
    "order": {
      "type": "string",
      "enum": [
        "netuid_asc",
        "netuid_desc",
        "name_asc",
        "name_desc",
        "stake_asc",
        "stake_desc",
        "one_hour_apy_asc",
        "one_hour_apy_desc",
        "one_day_apy_asc",
        "one_day_apy_desc",
        "seven_day_apy_asc",
        "seven_day_apy_desc",
        "thirty_day_apy_asc",
        "thirty_day_apy_desc"
      ]
    },
    "page": {
      "type": "integer",
      "format": "int32"
    },
    "positions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "hotkey",
          "netuid"
        ],
        "properties": {
          "hotkey": {
            "type": "string",
            "description": "SS58 or hex format"
          },
          "netuid": {
            "type": "integer",
            "format": "int32"
          }
        }
      }
    }
  }
}

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.