# Get Account

Gives most recent coldkey balance (from the database)

_Source: https://beta.taostats.io/docs/api-reference/account/get-account-latest_

_Last reviewed: 2026-09-18_

```http
GET https://api.taostats.io/api/account/latest/v1
```

Requires an API key in the `Authorization` header.

Gives most recent coldkey balance (from the database)

## Try it

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

### Examples

Get the current TAO balance breakdown (free, staked, total) for a single wallet

```text
https://api.taostats.io/api/account/latest/v1?address=5GH2aUTMRUh1RprCgH4x3tRyCaKeUi5BfmYCfs1NARA8R54n
```

List the top 10 accounts ranked by total TAO balance

```text
https://api.taostats.io/api/account/latest/v1?order=balance_total_desc&limit=10
```

Find accounts holding more than 10,000 TAO free balance (top 50)

```text
https://api.taostats.io/api/account/latest/v1?balance_free_min=10000000000000&order=balance_free_desc&limit=50
```

### Code samples

**cURL**

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/api/account/latest/v1?address=5GH2aUTMRUh1RprCgH4x3tRyCaKeUi5BfmYCfs1NARA8R54n"
```

**JavaScript**

```js
const response = await fetch('https://api.taostats.io/api/account/latest/v1?address=5GH2aUTMRUh1RprCgH4x3tRyCaKeUi5BfmYCfs1NARA8R54n', {
  headers: {
    Authorization: '<YOUR_API_KEY>',
  },
});
const data = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.taostats.io/api/account/latest/v1?address=5GH2aUTMRUh1RprCgH4x3tRyCaKeUi5BfmYCfs1NARA8R54n",
    headers={"Authorization": "<YOUR_API_KEY>"},
)
data = response.json()
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `address` | query | `string` |  | SS58 or hex format |
| `balance_free_min` | query | `string` |  | Min free balance in rao |
| `balance_free_max` | query | `string` |  | in rao |
| `balance_staked_min` | query | `string` |  | in rao |
| `balance_staked_max` | query | `string` |  | in rao |
| `balance_staked_root_min` | query | `string` |  |  |
| `balance_staked_root_max` | query | `string` |  |  |
| `balance_staked_alpha_as_tao_min` | query | `string` |  |  |
| `balance_staked_alpha_as_tao_max` | query | `string` |  |  |
| `balance_total_min` | query | `string` |  | in rao |
| `balance_total_max` | query | `string` |  | in rao |
| `rank` | query | `integer (int32)` |  |  |
| `created_on_network` | query | `string` |  | finney, nakamoto, kusanagi |
| `created_on_timestamp_start` | query | `integer (int64)` |  | Start of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive) |
| `created_on_timestamp_end` | query | `integer (int64)` |  | End of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive) |
| `page` | query | `integer (int32)` |  | Page of entries to retrieve. |
| `limit` | query | `integer (int32)` |  | Number of entries to return. Max value is 200. |
| `order` | query | `string` |  | One of `balance_free_asc`, `balance_free_desc`, `balance_staked_asc`, `balance_staked_desc`, `balance_staked_root_asc`, `balance_staked_root_desc`, `balance_staked_alpha_as_tao_asc`, `balance_staked_alpha_as_tao_desc`, `balance_total_asc`, `balance_total_desc`, `created_at_timestamp_asc`, `created_at_timestamp_desc`. |

## Responses

### `200` — Accounts retrieved successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `array` | Yes |  |
| `data[].address` | `object` | Yes |  |
| `data[].address.hex` | `string` | Yes | The hex format of the hot key |
| `data[].address.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].alpha_balances` | `array, nullable` |  |  |
| `data[].alpha_balances[].balance` | `string` | Yes |  |
| `data[].alpha_balances[].balance_as_tao` | `string` | Yes |  |
| `data[].alpha_balances[].coldkey` | `string` | Yes |  |
| `data[].alpha_balances[].hotkey` | `string` | Yes |  |
| `data[].alpha_balances[].netuid` | `integer (int32)` | Yes |  |
| `data[].alpha_balances_24hr_ago` | `array, nullable` |  |  |
| `data[].alpha_balances_24hr_ago[].balance` | `string` | Yes |  |
| `data[].alpha_balances_24hr_ago[].balance_as_tao` | `string` | Yes |  |
| `data[].alpha_balances_24hr_ago[].coldkey` | `string` | Yes |  |
| `data[].alpha_balances_24hr_ago[].hotkey` | `string` | Yes |  |
| `data[].alpha_balances_24hr_ago[].netuid` | `integer (int32)` | Yes |  |
| `data[].balance_free` | `string` | Yes |  |
| `data[].balance_free_24hr_ago` | `string, nullable` |  |  |
| `data[].balance_liquidity` | `string` | Yes |  |
| `data[].balance_liquidity_24hr_ago` | `string, nullable` |  |  |
| `data[].balance_reserved` | `string` | Yes |  |
| `data[].balance_reserved_24hr_ago` | `string, nullable` |  |  |
| `data[].balance_staked` | `string` | Yes |  |
| `data[].balance_staked_24hr_ago` | `string, nullable` |  |  |
| `data[].balance_staked_alpha_as_tao` | `string` | Yes |  |
| `data[].balance_staked_alpha_as_tao_24hr_ago` | `string, nullable` |  |  |
| `data[].balance_staked_root` | `string` | Yes |  |
| `data[].balance_staked_root_24hr_ago` | `string, nullable` |  |  |
| `data[].balance_total` | `string` | Yes |  |
| `data[].balance_total_24hr_ago` | `string, nullable` |  |  |
| `data[].block_number` | `integer (int32)` | Yes |  |
| `data[].coldkey_swap` | `object, nullable` |  |  |
| `data[].coldkey_swap.block_number` | `integer (int32)` | Yes |  |
| `data[].coldkey_swap.network` | `string` | Yes |  |
| `data[].coldkey_swap.new_coldkey` | `object` | Yes |  |
| `data[].coldkey_swap.new_coldkey.hex` | `string` | Yes | The hex format of the hot key |
| `data[].coldkey_swap.new_coldkey.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].coldkey_swap.old_coldkey` | `object` | Yes |  |
| `data[].coldkey_swap.old_coldkey.hex` | `string` | Yes | The hex format of the hot key |
| `data[].coldkey_swap.old_coldkey.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].coldkey_swap.timestamp` | `string (date-time)` | Yes |  |
| `data[].created_on_date` | `string (date)` | Yes |  |
| `data[].created_on_network` | `string` | Yes |  |
| `data[].network` | `string` | Yes |  |
| `data[].rank` | `integer (int32)` | Yes |  |
| `data[].root_basket_claimable_tao` | `string, nullable` |  | TAO currently claimable from this coldkey's root beta baskets. Only populated when a single `address` is requested; null otherwise and before the Root Reborn runtime is live. |
| `data[].root_claim_type` | `string, nullable` |  |  |
| `data[].timestamp` | `string (date-time)` | Yes |  |
| `pagination` | `object` | Yes |  |
| `pagination.current_page` | `integer (int32)` | Yes |  |
| `pagination.next_page` | `integer (int32), nullable` |  |  |
| `pagination.per_page` | `integer (int32)` | Yes |  |
| `pagination.prev_page` | `integer (int32), nullable` |  |  |
| `pagination.total_items` | `integer (int32)` | Yes |  |
| `pagination.total_pages` | `integer (int32)` | Yes |  |

**Example response**

```json
{
  "data": [
    {
      "address": {
        "hex": "0xb656ef6d8fa3ae7a7800906b6ea83a7c1320041290002c3ae7b1e4c68b1e4a67",
        "ss58": "5GBnPzvPghS8AuCoo6bfnK7JUFHuyUhWSFD4woBNsKnPiEUi"
      },
      "balance_free": "777150581296935",
      "balance_staked": "0",
      "balance_staked_alpha_as_tao": "0",
      "balance_staked_root": "0",
      "balance_total": "777150581296935",
      "block_number": 5011596,
      "coldkey_swap": null,
      "created_on_date": "2024-04-09",
      "created_on_network": "finney",
      "network": "finney",
      "rank": 1,
      "timestamp": "2025-02-26T13:52:48Z"
    },
    {
      "address": {
        "hex": "0x8aadfd659682487db6cb8e41e827056374743295cfad120270bc151e20883324",
        "ss58": "5FCY9iJYwghetXjE6xiYTj9g3HVW2K7E6JswWnR7PosJCRK9"
      },
      "balance_free": "1647950000",
      "balance_staked": "239843703109925",
      "balance_staked_alpha_as_tao": "0",
      "balance_staked_root": "239843703109925",
      "balance_total": "239845351059925",
      "block_number": 5011596,
      "coldkey_swap": null,
      "created_on_date": "2025-01-24",
      "created_on_network": "finney",
      "network": "finney",
      "rank": 2,
      "timestamp": "2025-02-26T13:52:48Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "per_page": 50,
    "prev_page": null,
    "total_items": 205362,
    "total_pages": 4108
  }
}
```

**Response details**

```text
{
      "address": {
        "ss58": "5Hd2ze5ug8n1bo3UCAcQsf66VNjKqGos8u6apNfzcU86pg4N",
        "hex": "0xf5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b"
      },
      "network": "finney",
      "block_number": 5451353b,
      "timestamp": "2025-04-28T15:44:12Z",
      "rank": 1,
      "balance_free": "658285656729475" free tao as rao,
      "balance_staked": "0" total tao staked as rao,
      "balance_staked_alpha_as_tao": "0"tao staked in alpha as rao,
      "balance_staked_root": "0" tao staked to root as rao,
      "balance_total": "658285656729475" total balance as rao,
      "balance_free_24hr_ago": nul  balance change 24 hours (only populated with address in query),
      "balance_staked_24hr_ago": null (only populated with address in query),
      "balance_staked_alpha_as_tao_24hr_ago": null (only populated with address in query),
      "balance_staked_root_24hr_ago": null (only populated with address in query), 
      "balance_total_24hr_ago": null (only populated with address in query),
      "created_on_date": "2025-02-26" wallet creation date,
      "created_on_network": "finney",
      "coldkey_swap": null
    },
```

### Other responses

| Status | Meaning |
| --- | --- |
| `400` | Bad request |
| `404` | Accounts not found |
| `500` | Internal server error |

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).