Coldkey stake portfolio with cost basis and P&L

Endpoint

GET /api/dtao/stake_balance/portfolio/v1

Description

Returns a full dTao stake portfolio for a coldkey, grouped by (hotkey, subnet). Every row shows the current alpha balance and its TAO value, cumulative buy/sell/transfer volumes, average entry and exit prices, and realised versus unrealised P&L in both TAO and USD.

Use days to restrict period-based aggregates (buys, sells, average prices) to a rolling window; leave it off for lifetime totals. Optional hotkey and netuid filters narrow to specific positions, and the balance / balance_as_tao bounds are handy for skipping dust rows.

Parameters

Name	In	Type	Required	Description
coldkey	query	string	✅	Portfolio owner coldkey (SS58 or hex).
hotkey	query	string		Restrict to a single delegated hotkey (SS58 or hex).
netuid	query	integer		Restrict to a single subnet.
days	query	integer		Rolling window in days for period aggregates; omit for lifetime totals.
balance_min	query	string		Minimum current alpha balance (in rao).
balance_max	query	string		Maximum current alpha balance (in rao).
balance_as_tao_min	query	string		Minimum current balance valued in TAO.
balance_as_tao_max	query	string		Maximum current balance valued in TAO.
page	query	integer		1-based page number.
limit	query	integer		Page size (max 200).
order	query	—		Sort order, e.g. balance_as_tao_desc, unrealised_profit_tao_desc.

Responses

200 — Stake balance portfolios retrieved successfully

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "pagination",
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "hotkey",
          "coldkey",
          "netuid",
          "balance",
          "balance_as_tao",
          "total_bought_alpha",
          "total_bought_alpha_as_tao",
          "total_bought_alpha_as_usd",
          "total_sold_alpha",
          "total_sold_alpha_as_tao",
          "total_sold_alpha_as_usd",
          "total_transferred_in_alpha",
          "total_transferred_in_alpha_as_tao",
          "total_transferred_in_alpha_as_usd",
          "total_transferred_out_alpha",
          "total_transferred_out_alpha_as_tao",
          "total_transferred_out_alpha_as_usd",
          "total_buys",
          "total_sells",
          "total_transfers_in",
          "total_transfers_out",
          "current_market_price_usd",
          "current_market_price_tao",
          "average_purchase_price_tao",
          "average_sale_price_tao",
          "average_purchase_price_usd",
          "average_sale_price_usd",
          "total_earned_alpha",
          "total_earned_alpha_as_tao",
          "total_earned_alpha_as_usd",
          "realised_profit_usd",
          "unrealised_profit_usd",
          "realised_profit_tao",
          "unrealised_profit_tao"
        ],
        "properties": {
          "average_purchase_price_tao": {
            "type": "string"
          },
          "average_purchase_price_usd": {
            "type": "string"
          },
          "average_sale_price_tao": {
            "type": "string"
          },
          "average_sale_price_usd": {
            "type": "string"
          },
          "balance": {
            "type": "string"
          },
          "balance_as_tao": {
            "type": "string"
          },
          "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"
              }
            }
          },
          "current_market_price_tao": {
            "type": "string"
          },
          "current_market_price_usd": {
            "type": "string"
          },
          "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"
              }
            }
          },
          "hotkey_name": {
            "type": "string",
            "nullable": true
          },
          "netuid": {
            "type": "integer",
            "format": "int32"
          },
          "period_start_alpha": {
            "type": "string",
            "nullable": true
          },
          "period_start_alpha_cost_in_usd": {
            "type": "string",
            "nullable": true
          },
          "period_start_alpha_price_in_tao": {
            "type": "string",
            "nullable": true
          },
          "period_start_tao_price_in_usd": {
            "type": "string",
            "nullable": true
          },
          "realised_profit_tao": {
            "type": "string"
          },
          "realised_profit_usd": {
            "type": "string"
          },
          "subnet_rank": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "subnet_total_holders": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "total_bought_alpha": {
            "type": "string"
          },
          "total_bought_alpha_as_tao": {
            "type": "string"
          },
          "total_bought_alpha_as_usd": {
            "type": "string"
          },
          "total_buys": {
            "type": "integer",
            "format": "int32"
          },
          "total_earned_alpha": {
            "type": "string"
          },
          "total_earned_alpha_as_tao": {
            "type": "string"
          },
          "total_earned_alpha_as_usd": {
            "type": "string"
          },
          "total_sells": {
            "type": "integer",
            "format": "int32"
          },
          "total_sold_alpha": {
            "type": "string"
          },
          "total_sold_alpha_as_tao": {
            "type": "string"
          },
          "total_sold_alpha_as_usd": {
            "type": "string"
          },
          "total_transferred_in_alpha": {
            "type": "string"
          },
          "total_transferred_in_alpha_as_tao": {
            "type": "string"
          },
          "total_transferred_in_alpha_as_usd": {
            "type": "string"
          },
          "total_transferred_out_alpha": {
            "type": "string"
          },
          "total_transferred_out_alpha_as_tao": {
            "type": "string"
          },
          "total_transferred_out_alpha_as_usd": {
            "type": "string"
          },
          "total_transfers_in": {
            "type": "integer",
            "format": "int32"
          },
          "total_transfers_out": {
            "type": "integer",
            "format": "int32"
          },
          "unrealised_profit_tao": {
            "type": "string"
          },
          "unrealised_profit_usd": {
            "type": "string"
          }
        }
      }
    },
    "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 — Stake balance portfolios 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.