Address
Get the balance and summary of an address on any chain (BTC, LTC and BCH balances pending the history index).
# Address
`GET https://api.rarebl.com/open/address/balance` or `POST https://api.rarebl.com/open/address/balance`
Balance and summary of an address: validity, type, balance, totals received and sent, transaction count and chain-specific details.
**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.
## Request
Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.
Example: `curl "https://api.rarebl.com/open/address/balance?chain=btc&address=XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT"`
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `address` | string | Yes | The address to look up. A valid address for the chain. BCH accepts CashAddr (with or without prefix) and legacy. |
## Responses
### API200 (HTTP 200): OK
Balance of a Dash address (exact).
```json
{
"status": 1,
"code": "API200",
"message": "success",
"data": {
"address": {
"chain": "dash",
"address": "XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT",
"valid": true,
"type": "p2pkh",
"balance": "10.0001",
"balanceStatus": "exact",
"received": "10.0001",
"sent": "0",
"txCount": 1,
"tokens": [],
"isContract": null,
"history": {
"available": true,
"reason": null
},
"details": [
{
"key": "immature",
"label": "Immature balance",
"value": "0",
"kind": "amount",
"unit": "DASH"
},
{
"key": "utxos",
"label": "Unspent outputs",
"value": 1,
"kind": "number"
}
]
}
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
| Field | Type | Description |
| --- | --- | --- |
| `data.address.valid` | boolean | Whether the address is well formed for the chain. |
| `data.address.type` | string \| null | p2pkh, p2sh, p2wpkh, p2tr, cashaddr, eoa, contract, tron-account and so on. |
| `data.address.balance` | string \| null | Native balance. Null until the history index exists on BTC, LTC and BCH. |
| `data.address.balanceStatus` | string | `exact`, or `index_pending` for BTC, LTC and BCH until the history index exists. |
| `data.address.received / sent / txCount` | string \| null | Lifetime totals, when known. |
| `data.address.tokens[]` | object[] | Known tokens held (ETH and TRON). |
| `data.address.history` | object | `{available, reason}`: whether address history can be listed. |
| `data.address.details` | DetailRow[] | ETH nonce; TRON energy, bandwidth and frozen resources; Dash unspent output count. |
### API200 (HTTP 200): OK (index pending)
A Bitcoin address: the balance is not available until the history index exists.
```json
{
"status": 1,
"code": "API200",
"message": "success",
"data": {
"address": {
"chain": "btc",
"address": "1K6KoYC69NnafWJ7YgtrpwJxBLiijWqwa6",
"valid": true,
"type": "p2pkh",
"balance": null,
"balanceStatus": "index_pending",
"received": null,
"sent": null,
"txCount": null,
"tokens": [],
"isContract": null,
"history": {
"available": false,
"reason": "index_pending"
},
"details": []
}
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API400 (HTTP 400): Bad Request
A parameter is missing or malformed. `data.param` names it (here `address`).
```json
{
"status": 0,
"code": "API400",
"message": "Invalid BTC address.",
"data": {
"param": "address"
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API429 (HTTP 429): Too Many Requests
Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.
```json
{
"status": 0,
"code": "API429",
"message": "Too many requests. Please retry shortly.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API502 (HTTP 502): Bad Gateway
The node is unavailable, still syncing or timed out. Retry later with a short back-off.
```json
{
"status": 0,
"code": "API502",
"message": "The node is unavailable or timed out. Please try again.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
## Notes
- Today the balance is exact on DASH, ETH and TRON. On BTC, LTC and BCH it is `null` with `balanceStatus: "index_pending"` until the history index is built. Treat that as "unknown", not zero.
- Never display `null` as `0`. See [Coverage and limits](https://docs.rarebl.com/limits-today).