> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validationcloud.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance history

Returns a balance history for the specified XPUB or address.

This method will use `10` [Compute Units](/nodeapi/about/billing).

***

## **Reference:** [**Here**](https://github.com/trezor/blockbook/blob/master/docs/api.md#balance-history)

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
GET /api/v2/balancehistory/<XPUB | address>?from=<dateFrom>&to=<dateTo>[&fiatcurrency=<currency>&groupBy=<groupBySeconds>]
```

## **Parameters**

Required parameters

**`XPUB or address`**- string, required.

Example: `bc1q262qeyyhdakrje5qaux8m2a3r4z8sw8vu5mysh` (address)\
**`dateFrom`**- Unix timestamp, required.

Example: `1704067200`

**`dateTo`**- Unix timestamp, required.

Example: `1715160143`

Optional parameters

* ***`fiatcurrency`***: if specified, the response will contain secondary (fiat) rate at the time of transaction. If not, all available currencies will be returned.
* ***`groupBy`***: an interval in seconds, to group results by. Default is 3600 seconds.

## Returns

Example response (fiatcurrency=usd):

```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
[
	{
		"time": 1708239600,
		"txs": 9,
		"received": "2970",
		"sent": "0",
		"sentToSelf": "0",
		"rates": {
			"usd": 51518.35
		}
	},
	....
	{
		"time": 1715144400,
		"txs": 1,
		"received": "2310",
		"sent": "0",
		"sentToSelf": "0",
		"rates": {
			"usd": 62560.055
		}
	}
]
```

<CodeGroup>
  ```bash title="mainnet" theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE>/api/v2/balancehistory/bc1q262qeyyhdakrje5qaux8m2a3r4z8sw8vu5mysh?from=1704067200&to=1715160143&fiatcurrency=usd \
   -X GET \
   -H "Content-Type: application/json"
  ```

  ```bash title="testnet" theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE>/api/v2/balancehistory/bc1q262qeyyhdakrje5qaux8m2a3r4z8sw8vu5mysh?from=1704067200&to=1715160143&fiatcurrency=usd \
   -X GET \
   -H "Content-Type: application/json"
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.