# Reporting API

## Get Balance Of All Provisioned Nodes

<mark style="color:blue;">`GET`</mark> `https://mainnet.staked.cloud/api/reports/:chain/balance`

Get the balance of all nodes provisioned through the [Node Provisioning API](/staked/staking-api/node-provisioning-api.md#what-is-the-node-provisioning-api).

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| chain<mark style="color:red;">\*</mark> | String | Chain Name  |

#### Request Headers

| Name                                        | Type   | Description                                                                                   |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | Your API key (preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name                                       | Type   | Description                                                                                                                                                                       |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong></p><p></p><p>Your API key</p> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "total_balance": 32000000000000000000,
    "balances": [
        { // active validator
            "balance": 32000000000000000000,
            "block": 62421,
            "timestamp": "2021-09-15T22:25:25.737607",
            "address": "validator public key",
            "currency": "ETH2.0",
            "conversion_factor_power": 18,
            "attributes": {
                "status": "ACTIVE",
            }
        },
        { // validator provisioned but not deposited into
            "balance": null,
            "block": null,
            "timestamp": "2021-09-15T22:25:25.737607",
            "address": "validator public key",
            "currency": "ETH2.0",
            "conversion_factor_power": 18,
            "attributes": {}
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get Balance Of Address

<mark style="color:blue;">`GET`</mark> `https://mainnet.staked.cloud/api/reports/:chain/delegator/:address/balance`

Get the balance of an address that has delegated to Staked.&#x20;

#### Path Parameters

| Name                                      | Type   | Description                |
| ----------------------------------------- | ------ | -------------------------- |
| chain<mark style="color:red;">\*</mark>   | string | Chain Name                 |
| address<mark style="color:red;">\*</mark> | string | Address to get balance for |

#### Request Headers

| Name                                        | Type   | Description                                                                                   |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | Your API key (preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name                                       | Type   | Description                                                                                                                                                                       |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | string | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong></p><p></p><p>Your API key</p> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "balance": 5000000,
  "timestamp": "2019-07-08T17:09:08.753866",
  "address": "KT1W4Rda7pHrqmbDk4xDZ97YpgqAVHE5hndr"
}

```

{% endtab %}
{% endtabs %}

**Balance Object Schema**

| Field                     | Description                                             | Type   |
| ------------------------- | ------------------------------------------------------- | ------ |
| balance                   | Staking balance                                         | Number |
| block                     | Block of latest snapshot                                | Number |
| timestamp                 | Timestamp at latest snapshot                            | String |
| address                   | Address queried                                         | String |
| conversion\_factor\_power | Decimals used in Number values (used to keep precision) | Number |
| attributes                | Extra information depending on the chain                | Object |

{% tabs %}
{% tab title="React w/ Axios" %}

```javascript
import axios from "axios";

const api_key = 'YOUR API KEY';
const chain = 'TEZOS';
const address = 'KT1W4Rda7pHrqmbDk4xDZ97YpgqAVHE5hndr';

var api = axios.create({
  baseURL: "https://mainnet.staked.cloud/api",
  timeout: 1000000,
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": api_key
  }
});

api.get(`/reports/${chain}/delegator/${address}/balance`).then(response => {
  console.log(res);
})
```

{% endtab %}

{% tab title="jQuery" %}

```javascript
const api_key = 'YOUR API KEY';
const chain = 'TEZOS';
const address = 'KT1W4Rda7pHrqmbDk4xDZ97YpgqAVHE5hndr';

var request = {
  "url": `https://mainnet.staked.cloud/api/reports/${chain}/delegator/${address}/balance`,
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "X-Api-Key": api_key
  }
};

$.ajax(request).done(function (response) {
  console.log(response);
});
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
var http = require('http');

const api_key = 'YOUR API KEY';
const chain = 'TEZOS';
const address = 'KT1W4Rda7pHrqmbDk4xDZ97YpgqAVHE5hndr';

var options = {
  'method': 'GET',
  'hostname': 'mainnet.staked.cloud',
  'path': `/api/reports/${chain}/delegator/${address}/balance`,
  'headers': {
    'Content-Type': 'application/json',
    'X-Api-Key': api_key
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();
```

{% endtab %}

{% tab title="Swift" %}

```swift
import Alamofire

let api_key = 'YOUR API KEY';
let chain = 'TEZOS';
let address = 'KT1W4Rda7pHrqmbDk4xDZ97YpgqAVHE5hndr';

let headers: HTTPHeaders = [
    "Content-Type": "application/json",
    "X-Api-Key": api_key
]

AF.request("https://mainnet.staked.cloud/api/reports/\(chain)/delegator/\(address)/balance", headers: headers).response { response in
    debugPrint(response)
}
```

{% endtab %}
{% endtabs %}

## Get Detailed Balance of Address

<mark style="color:blue;">`GET`</mark> `https://mainnet.staked.cloud/api/reports/:chain/delegator/:address/detailed_balance`

Get the detailed balance (summary view of rewards and the staked balance) of an address. The detail param is used to describe the results - "monthly" returns an array of detailed balance objects aggregated by month, "by\_period" returns an array of detailed balance objects for each state change (delegation or reward).

#### Path Parameters

| Name                                      | Type   | Description                         |
| ----------------------------------------- | ------ | ----------------------------------- |
| chain<mark style="color:red;">\*</mark>   | string | Chain Name                          |
| address<mark style="color:red;">\*</mark> | string | Address to get detailed balance for |

#### Request Headers

| Name                                        | Type   | Description                                                                                   |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | Your API key (preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name                                       | Type   | Description                                                                                                                                                                       |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | string | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong></p><p></p><p>Your API Key</p> |
| detail                                     | string | "by\_period" or "monthly"                                                                                                                                                         |

{% tabs %}
{% tab title="200 " %}

```
{
    "results": [
        {
            "timestamp": "2020-08-27T14:12:31.722731",
            "block": null,
            "total_delegation": 3874585409425.0,
            "delegation": 3876252281981.0,
            "balance": 3897899084922.0,
            "total_reward_and_fees": 23313675497.0,
            "reward_and_fees": 23313675497.0,
            "total_reward": 23304218223.0,
            "reward": 23304218223.0,
            "total_fees": 9457274.0,
            "fees": 9457274.0,
            "total_gross_return": 0.006681130527750926,
            "gross_return": 0.006681130527750926,
            "annualized_gross_return": 0.016456788919817385,
            "block_explorer_url": null,
            "kind": null,
            "conversion_factor_power": 6,
            "currency": "Tezos"
        }
    ],
    "page": 1,
    "pages": 1,
    "per_page": 10,
    "total": 1
}
```

{% endtab %}
{% endtabs %}

**Response** **Object** **Schema**

| Field     | Description                       | Type   |
| --------- | --------------------------------- | ------ |
| results   | Array of Detailed Balance Objects | Array  |
| page      | Current page of results           | Number |
| pages     | Total number of pages             | Number |
| per\_page | Results per page                  | Number |
| total     | Total number of results           | Number |

**Detailed** **Balance** **Object** **Schema**

Detailed balance objects are returned for every state change of an account (stake, reward, unstake).

| **Field**                 | Description                                             | Type   |
| ------------------------- | ------------------------------------------------------- | ------ |
| timestamp                 | Timestamp of snapshot                                   | String |
| block                     | Block of snapshot                                       | Number |
| total\_delegation         | Total amount delegated                                  | Number |
| delegation                | Delegated amount in state change                        | Number |
| balance                   | Staking balance at snapshot                             | Number |
| total\_reward\_and\_fees  | Total accumulated reward and fees up to snapshot        | Number |
| reward\_and\_fees         | Reward and fees earned in state change                  | Number |
| total\_reward             | Total accumulated reward up to snapshot                 | Number |
| reward                    | Reward earned in state change                           | Number |
| total\_fees               | Total fees accumulated up to snapshot                   | Number |
| fees                      | Fees in state change                                    | Number |
| total\_gross\_return      | Total gross return up to snapshot                       | Number |
| gross\_return             | Gross return from state change                          | Number |
| annualized\_gross\_return | Annualized gross return                                 | Number |
| block\_explorer\_url      | Block Explorer URL for state change                     | String |
| kind                      | Kind of state change ("Delegation" or "Reward")         | String |
| conversion\_factor\_power | Decimals used in Number values (used to keep precision) | Number |
| currency                  | Name of currency                                        | String |

## Get Transactions (and rewards) of All Provisioned Nodes

<mark style="color:blue;">`GET`</mark> `https://mainnet.staked.cloud/api/reports/:chain/txns`

Get the transactions for all nodes provisioned through the Staked API associated with your API key. Use the kind parameter to specify which type of transactions to query.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| chain<mark style="color:red;">\*</mark> | String | Chain Name  |

#### Request Headers

| Name                                        | Type   | Description                                                                                   |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | Your API key (preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name                                       | Type   | Description                                                                                                                                                                       |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong></p><p></p><p>Your API Key</p> |
| kind                                       | String | Transaction kind                                                                                                                                                                  |
| start                                      | String | Start date. Format: YYYY-MM-DD                                                                                                                                                    |
| end                                        | String | End date. Format: YYYY-MM-DD                                                                                                                                                      |
| page                                       | String | Page number for paginated results.                                                                                                                                                |
| per\_page                                  | String | Number of items per page for paginated results.                                                                                                                                   |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "id": id,
        "kind": Transaction Kind,
        "transaction_time": Transaction Time,
        "transaction_address": Transaction Address,
        "holding_address": Holding Address,
        "amount": Amount,
        "reward": Reward,
        "fees": Fees,
        "total": Total,
        "denom": Denomination,
        "block_reference": Block Reference
    }
]
```

{% endtab %}
{% endtabs %}

## Get Transactions (and rewards) of Address&#x20;

<mark style="color:blue;">`GET`</mark> `https://mainnet.staked.cloud/api/reports/:chain/delegator/:address/txns`

Get the transactions for an address that has delegated to Staked. Use the kind parameter to specify which type of transactions to query.

#### Path Parameters

| Name                                      | Type   | Description                         |
| ----------------------------------------- | ------ | ----------------------------------- |
| chain<mark style="color:red;">\*</mark>   | string | Chain Name                          |
| address<mark style="color:red;">\*</mark> | string | Address to get transaction data for |

#### Request Headers

| Name                                        | Type   | Description                                                                                   |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | Your API key (preferred method of passing api key is now in headers rather than query params) |

#### Query Parameters

| Name                                       | Type   | Description                                                                                                                                                                       |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | string | <p><strong>\[Deprecated since March '25</strong> (preferred method of passing api key is now in headers rather than query params)<strong>]</strong></p><p></p><p>Your API Key</p> |
| kind                                       | string | Transaction kind                                                                                                                                                                  |
| start                                      | string | Start date. Format: YYYY-MM-DD                                                                                                                                                    |
| end                                        | string | End date. Format: YYYY-MM-DD                                                                                                                                                      |

{% tabs %}
{% tab title="200 " %}

```
[
    {
        "id": id,
        "kind": Transaction Kind,
        "transaction_time": Transaction Time,
        "transaction_address": Transaction Address,
        "holding_address": Holding Address,
        "amount": Amount,
        "reward": Reward,
        "fees": Fees,
        "total": Total,
        "denom": Denomination,
        "block_reference": Block Reference
    }
]
```

{% endtab %}
{% endtabs %}

**Transaction Object Schema**

| Field                     | Description                                             | Type                  |
| ------------------------- | ------------------------------------------------------- | --------------------- |
| id                        | Transaction identifier                                  | String                |
| kind                      | Kind of transaction                                     | Transaction Kind Enum |
| transaction\_time         | Timestamp of transaction                                | String                |
| transaction\_address      | Hash or identifier of transaction on blockchain         | String                |
| holding\_address          | Address queried                                         | String                |
| Amount                    | Amount of value in transaction                          | Number                |
| Reward                    | Reward in transaction                                   | Number                |
| Fees                      | Fees in transaction                                     | Number                |
| Total                     | Net value in transaction                                | Number                |
| conversion\_factor\_power | Decimals used in Number values (used to keep precision) | Number                |
| denom                     | Denomination                                            | Number                |
| block\_reference          | Block the transaction was included in                   | Number                |

**Transaction Kind Enum**

| Value |                    Meaning                   |
| :---: | :------------------------------------------: |
|  STK  |            Delegation Transactions           |
| UNSTK |           Undelegation Transactions          |
|  SCH  |           Scheduled Future Rewards           |
|  PEND |           Rewards in Frozen Period           |
|  PYBL |         Rewards Pending Distribution         |
|  PAID |                Earned Rewards                |
|  XFER | Transfers (includes withdrawals in Ethereum) |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://staked.gitbook.io/staked/staking-api/staking-reporting-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.