Watch addresses
Start watching BTC, LTC or BCH addresses so UTXOs, balances and webhooks are exact.
# Watch addresses
`POST https://api.rarebl.com/open/address/watch`
Starts tracking BTC, LTC or BCH addresses (their UTXOs and activity) so that UTXOs, balances and webhooks become exact.
**Rate class:** watch (30 per minute, 2,000 addresses per day, per IP). **Available since:** Open API v2.
## Request
Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.
Example: `curl -X POST "https://api.rarebl.com/open/address/watch" -H "Content-Type: application/json" -d '{"chain":"btc","addresses":["bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q","bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm"]}'`
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | BTC, LTC or BCH. One of: btc, ltc, bch. |
| `addresses` | array | Yes | Up to 100 addresses. At most 100 per call. |
## Responses
### API200 (HTTP 200): OK
Each address is `pending` until its bootstrap is done, then `active`.
```json
{
"status": 1,
"code": "API200",
"message": "success",
"data": {
"watches": [
{
"address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q",
"status": "pending",
"since": "2026-11-15T01:12:07Z"
},
{
"address": "bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm",
"status": "active",
"since": "2026-11-14T21:03:55Z"
}
]
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
| Field | Type | Description |
| --- | --- | --- |
| `data.watches[]` | object[] | `{address, status: "pending" \| "active", since}`. |
### API400 (HTTP 400): Bad Request
The chain is missing, or is not BTC, LTC or BCH (DASH and the account chains do not need a watch).
```json
{
"status": 0,
"code": "API400",
"message": "Unknown or missing chain.",
"data": {
"param": "chain"
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API429 (HTTP 429): Too Many Requests
Rate limited (watch class: 30 per minute, 2,000 addresses per day). `Retry-After` says how long to wait.
```json
{
"status": 0,
"code": "API429",
"message": "Too many requests. Please retry shortly.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
## Notes
- A UTXO-set bootstrap runs first; the address then follows new blocks and the mempool. The watch is `active` once the bootstrap is done. How long that takes depends on the deployment and the chain: poll this endpoint (or [address/utxos](https://docs.rarebl.com/api/address/utxos)) until the status is `active`.
- While an address is watched and active, [Address](https://docs.rarebl.com/api/address/balance) also returns an exact balance on BTC, LTC and BCH (`balanceStatus: "exact"`).
- Watches expire after 90 days without a query or webhook. Any read renews them.
- Not needed on DASH or the account chains. Address webhooks and WebSocket address channels on BTC/LTC/BCH watch the address automatically.