# 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](https://staked.gitbook.io/staked/node-provisioning-api#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) |