Address UTXOs
List the UTXOs and balance of a UTXO-chain address (BTC/LTC/BCH need a watch).
# Address UTXOs
`GET https://api.rarebl.com/open/address/utxos`
The unspent outputs and balance of an address, for sweeps and payouts. BTC, LTC and BCH addresses must be watched and active; DASH uses its node index.
**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.
## 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/utxos?chain=dash&address=XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF"`
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | A UTXO chain. One of: btc, ltc, bch, dash. |
| `address` | string | Yes | The address. |
| `minConf` | integer | No | Minimum confirmations. Default 0. |
## Responses
### API200 (HTTP 200): OK
One unspent output (a real Dash reply).
```json
{
"status": 1,
"code": "API200",
"message": "success",
"data": {
"utxos": [
{
"txid": "1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c",
"vout": 1,
"value": "4.23877346",
"valueSats": 423877346,
"height": 2572425,
"confirmations": 2,
"scriptPubKey": "76a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac"
}
],
"balance": "4.23877346",
"balanceSats": 423877346
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
| Field | Type | Description |
| --- | --- | --- |
| `data.utxos[]` | object[] | `{txid, vout, value, valueSats, height \| null, confirmations, scriptPubKey}`. |
| `data.balance / balanceSats` | string | The sum of the returned UTXOs. |
### API409 (HTTP 409): Conflict
BTC, LTC or BCH: the address is not watched and active. `data.watch` names the call that starts one ([address/watch](https://docs.rarebl.com/api/address/watch)).
```json
{
"status": 0,
"code": "API409",
"message": "address is not watched yet: POST address/watch first",
"data": {
"reason": "not_watched",
"watch": {
"chain": "btc",
"address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q",
"endpoint": "address/watch"
}
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API400 (HTTP 400): Bad Request
ETH and TRON have no UTXOs: they answer API400.
```json
{
"status": 0,
"code": "API400",
"message": "UTXOs exist on UTXO chains only.",
"data": {
"param": "chain"
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API429 (HTTP 429): Too Many Requests
Rate limited (read class: 5 requests per second, burst 20, per IP). 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
- Spend them with [Build a transaction](https://docs.rarebl.com/api/tx/build) and `inputs`, or let the SDK pick them: see [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).