# Get Alpha Portfolio

Coldkey alpha portfolio + trading aggregates.

_Source: https://beta.taostats.io/docs/new/alpha/get-alpha-portfolio_

_Last reviewed: 2026-10-07_

```http
GET https://api.taostats.io/v1/alpha/portfolio
```

Requires an API key in the `Authorization` header.

Coldkey alpha portfolio + trading aggregates.

## Try it

Try this request in the browser on the HTML version of this page, or use the code samples below.

### Code samples

**cURL**

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/v1/alpha/portfolio"
```

**JavaScript**

```js
const response = await fetch('https://api.taostats.io/v1/alpha/portfolio', {
  headers: {
    Authorization: '<YOUR_API_KEY>',
  },
});
const data = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.taostats.io/v1/alpha/portfolio",
    headers={"Authorization": "<YOUR_API_KEY>"},
)
data = response.json()
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `coldkey` | query | `string` | Yes | Staker coldkey (SS58 or 0x-hex; normalized to SS58). Required. |
| `hotkey` | query | `string` |  | Filter to one validator hotkey (SS58 or 0x-hex; normalized to SS58). |
| `netuid` | query | `integer (int32)` |  | Filter to one subnet UID. |
| `days` | query | `integer (int32)` |  | Aggregate over the last N days only (omit for all-time). Must be \> 0. When set, `period_start_*` fields are populated. |

## Responses

### `200` — Coldkey alpha portfolio positions

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `array` | Yes |  |
| `data[].average_purchase_price_tao` | `string` | Yes | Volume-weighted average buy price in TAO. |
| `data[].average_purchase_price_usd` | `string, nullable` | Yes | Average buy price in USD. `null` — pending oracle. |
| `data[].average_sale_price_tao` | `string` | Yes | Volume-weighted average sell price in TAO. |
| `data[].average_sale_price_usd` | `string, nullable` | Yes | Average sell price in USD. `null` — pending oracle. |
| `data[].balance` | `string` | Yes | Current alpha balance (RAO). |
| `data[].balance_as_tao` | `string` | Yes | Current alpha as TAO equivalent (RAO). |
| `data[].block_number` | `integer (int32)` | Yes | The block every figure in this row is true at, except `hotkey_name`, `subnet_rank` and `subnet_total_holders`: the head block the balance and the alpha price were read from the chain at, the newest finalized block the indexes have reached. Trades, transfers and moves are counted up to and including it, and TAO/USD is the rate in force at its time. The same for every row of a response. |
| `data[].coldkey` | `string` | Yes | Staker coldkey, SS58. |
| `data[].current_market_price_tao` | `string` | Yes | Current alpha price in TAO. |
| `data[].current_market_price_usd` | `string, nullable` | Yes | Current alpha price in USD. `null` — pending oracle. |
| `data[].hotkey` | `string` | Yes | Validator hotkey, SS58. |
| `data[].hotkey_name` | `string, nullable` | Yes | The hotkey's current identity name: the on-chain identity of the coldkey the chain records as its owner today (`SubtensorModule::Owner`), the same name `/v1/validators` serves for a validator. Validator or not (#1314). `null` when the hotkey holds no stake at the current snapshot (so no stored owner) or its owner has no identity. |
| `data[].netuid` | `integer (int32)` | Yes | Subnet UID. |
| `data[].period_start_alpha` | `string, nullable` | Yes | Alpha balance at period start (RAO). Only when `days` is set. The balance at the last block before the window starts, as the OLD API serves it: for `days >= 8` the end-of-day snapshot in `stake_balance_history_v1` (`build_start_sql`), for `days < 8` the chain at the last block before the hour (`fetch_chain_start_rows`). |
| `data[].period_start_alpha_cost_in_usd` | `string, nullable` | Yes | Alpha cost in USD at period start. `null` — pending oracle. |
| `data[].period_start_alpha_price_in_tao` | `string, nullable` | Yes | Alpha price in TAO at period start. Only when `days` is set. |
| `data[].period_start_tao_price_in_usd` | `string, nullable` | Yes | TAO price in USD at period start. `null` (only set when `days`, and pending oracle). |
| `data[].realised_profit_tao` | `string` | Yes | Realised profit in TAO (RAO). |
| `data[].realised_profit_usd` | `string, nullable` | Yes | Realised profit in USD. `null` — pending oracle. |
| `data[].subnet_rank` | `integer (int32), nullable` | Yes | Rank within the subnet by balance, from the newest stake-balance snapshot (about hourly), not from `block_number`. `null` for positions with no current balance (traded-out within the window), and for one opened since that snapshot. |
| `data[].subnet_total_holders` | `integer (int32), nullable` | Yes | Number of holders in the subnet. `null` as for `subnet_rank`. |
| `data[].timestamp` | `string` | Yes | That block's time, ISO 8601 with millisecond precision. |
| `data[].total_bought_alpha` | `string` | Yes | Total alpha bought (RAO). |
| `data[].total_bought_alpha_as_tao` | `string` | Yes | Total bought, as TAO paid (RAO). |
| `data[].total_bought_alpha_as_usd` | `string, nullable` | Yes | Total bought, as USD. `null` — pending oracle. |
| `data[].total_buys` | `integer (int32)` | Yes | Number of buy transactions. |
| `data[].total_earned_alpha` | `string` | Yes | Total alpha earned (emissions etc.): balance − bought − start − in + sold + out, where in and out also hold stake moved by a coldkey swap (RAO; may be negative). |
| `data[].total_earned_alpha_as_tao` | `string` | Yes | Earned, as TAO at the current price (RAO). |
| `data[].total_earned_alpha_as_usd` | `string, nullable` | Yes | Earned, as USD. `null` — pending oracle. |
| `data[].total_sells` | `integer (int32)` | Yes | Number of sell transactions. |
| `data[].total_sold_alpha` | `string` | Yes | Total alpha sold (RAO). |
| `data[].total_sold_alpha_as_tao` | `string` | Yes | Total sold, as TAO received (RAO). |
| `data[].total_sold_alpha_as_usd` | `string, nullable` | Yes | Total sold, as USD. `null` — pending oracle. |
| `data[].total_transferred_in_alpha` | `string` | Yes | Total alpha transferred in (RAO). |
| `data[].total_transferred_in_alpha_as_tao` | `string` | Yes | Transferred in, as TAO (RAO). |
| `data[].total_transferred_in_alpha_as_usd` | `string, nullable` | Yes | Transferred in, as USD. `null` — pending oracle. |
| `data[].total_transferred_out_alpha` | `string` | Yes | Total alpha transferred out (RAO). |
| `data[].total_transferred_out_alpha_as_tao` | `string` | Yes | Transferred out, as TAO (RAO). |
| `data[].total_transferred_out_alpha_as_usd` | `string, nullable` | Yes | Transferred out, as USD. `null` — pending oracle. |
| `data[].total_transfers_in` | `integer (int32)` | Yes | Number of inbound transfers. |
| `data[].total_transfers_out` | `integer (int32)` | Yes | Number of outbound transfers. |
| `data[].unrealised_profit_tao` | `string` | Yes | Unrealised profit in TAO (RAO). |
| `data[].unrealised_profit_usd` | `string, nullable` | Yes | Unrealised profit in USD. `null` — pending oracle. |

### `400` — Invalid query parameter

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes | Plain-english message describing the failure from the caller's perspective. |
| `status_code` | `integer (int32)` | Yes | HTTP status code (mirrored in the response status line for convenience). |

### `500` — Internal server error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes | Plain-english message describing the failure from the caller's perspective. |
| `status_code` | `integer (int32)` | Yes | HTTP status code (mirrored in the response status line for convenience). |

Every request needs an `Authorization` header holding your API key — see [Getting started with the Taostats API](https://beta.taostats.io/docs/start-here/getting-started-with-taostats-api).