Historical coldkey alpha shares per hotkey/subnet

Endpoint

GET /api/dtao/coldkey_alpha_shares/history/v1

Description

Returns historical snapshots of coldkey alpha-share holdings, broken out per (hotkey, subnet) position. Each row records the share count and equivalent alpha amount at a specific block, so you can reconstruct a stakeholder’s positions block-by-block.

Query a single point in time with block_number, or scan a window with block_start/block_end or timestamp_start/timestamp_end. Combine with coldkey, hotkey, and netuid filters to isolate a single position.

Parameters

Name	In	Type	Required	Description
coldkey	query	string		Filter by stakeholder coldkey (SS58 or hex).
hotkey	query	string		Filter by delegated hotkey (SS58 or hex).
netuid	query	integer		Subnet id.
block_number	query	integer		Return the snapshot at this exact block.
block_start	query	integer		Start of block range (inclusive).
block_end	query	integer		End of block range (inclusive).
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. block_number_desc, alpha_desc.

Responses

200 — Dtao coldkey alpha shares retrieved successfully

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "pagination",
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "block_number",
          "timestamp",
          "netuid",
          "coldkey",
          "hotkey",
          "shares",
          "alpha"
        ],
        "properties": {
          "alpha": {
            "type": "string"
          },
          "block_number": {
            "type": "integer",
            "format": "int32"
          },
          "coldkey": {
            "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"
              }
            }
          },
          "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"
              }
            }
          },
          "netuid": {
            "type": "integer",
            "format": "int32"
          },
          "shares": {
            "$ref": "#/components/schemas/BigDecimal"
          },
          "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 — Dtao coldkey alpha shares 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.