# Address

`GET /api/address/{address}`

An address's UTXOs that hold tracked sats, as its address page lists them: totals, the types it holds, and one page of UTXOs. Cacheable 30 s. A UTXO a pending transaction spends carries `spent_by_pending`; `pending_outputs` lists the outputs pending transactions send it.

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | yes | A mainnet address. |

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `offset` | integer | no | UTXOs to skip. Default: `0`. (min 0) |
| `limit` | integer | no | Page size, at most 5,000. Default: `500`. (min 1, max 5000) |
| `sort` | string | no | A column, `-` first for descending: `rare`, `range`, `year`, `quantity`, `utxo`, `size`, `received`. Default: `range`. |
| `types` | string | no | Comma-separated sat types; a UTXO must hold every one. |

#### Example request

```bash title="cURL"
curl 'https://raresats.net/api/address/bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr'
```
```js title="JavaScript"
const response = await fetch('https://raresats.net/api/address/bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr');
const data = await response.json();
```
```python title="Python"
import requests

data = requests.get("https://raresats.net/api/address/bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr").json()
```

#### Response `200`

| Field | Type | Description |
| --- | --- | --- |
| `address` | string | The address. |
| `script_pubkey` | string | Its script, hex. |
| `chain` | string | Network. |
| `explorer` | string \| null | Block explorer base URL. |
| `as_of` | object \| null | `{height, hash, time}` of the index. |
| `totals` | object |  |
| `totals.utxos` | integer | UTXOs with tracked sats. |
| `totals.sats` | integer | Tracked sats. |
| `totals.value` | integer | Their value in sats. |
| `rows` | map of integer | Row counts over every UTXO. |
| `types` | array of object | Every type the address holds. |
| `types[].type` | string | Sat type. |
| `types[].utxos` | integer | UTXOs holding it. |
| `types[].ranges` | integer | Contiguous runs. |
| `types[].sats` | integer | Sats. |
| `page` | object |  |
| `page.offset` | integer | Offset. |
| `page.limit` | integer | Limit. |
| `page.total` | integer | UTXOs matching `types`. |
| `page.sort` | string | Sort. |
| `page.types` | array of string | Type filter. |
| `outputs` | array of object | One page of UTXOs. |
| `outputs[].outpoint` | string | `txid:vout`. |
| `outputs[].txid` | string | Transaction. |
| `outputs[].vout` | integer | Output index. |
| `outputs[].value` | integer \| null | Value in sats. |
| `outputs[].kind` | string | `spendable` and so on. |
| `outputs[].created_height` | integer \| null | The block that created it. |
| `outputs[].created_time` | integer \| null | Its time. |
| `outputs[].extracted` | boolean | Extracted (isolated rare sats). |
| `outputs[].inscribed_sats` | array of integer | Inscribed tracked sats. |
| `outputs[].quantity` | integer | Tracked sats. |
| `outputs[].first` | integer \| null | Lowest tracked sat. |
| `outputs[].last` | integer \| null | Highest tracked sat. |
| `outputs[].ranges` | array of array of integer | Inclusive ranges. |
| `outputs[].groups` | array of [TypeGroup](https://raresats.net/docs/listing-object.md) | Sats by exact type combination, rarest first. |
| `outputs[].years` | map of integer | Sats per mint year. |
| `outputs[].year` | integer \| null | The year holding the most sats. |
| `outputs[].rows` | map of integer | Row counts. |
| `outputs[].spent_by_pending` | object | A transaction still in the mempool that spends an output (`spent_by_pending`). Absent when nothing pending spends it. |
| `outputs[].spent_by_pending.txid` | string | The spending transaction. |
| `outputs[].spent_by_pending.vin` | integer \| null | Its input that spends the output. |
| `outputs[].spent_by_pending.first_seen` | integer \| null | When the transaction was first seen in the mempool (bitcoind's entry time), unix seconds. |
| `outputs[].spent_by_pending.fee_rate` | number \| null | Its fee rate, sat/vB (one decimal). |
| `outputs[].spent_by_pending.sale` | boolean | Whether the spend sells this output (a pending sale with it as the seller's input). |
| `outputs[].spent_by_pending.replaceable` | boolean | Always true (full RBF): the spend may still be replaced. |
| `outputs[].split_counts` | map of integer | The sats an extract's `split` may cut, per exact type combination (types sorted, joined with `+`): the row's sats as `groups` counts them, without the tracked pieces that touch block 9 or 450x (a split leaves those whole). |
| `pending_outputs` | array of object | Outputs pending transactions send it, newest first (rare sats being received); only while the index serves its mempool overlay. A UTXO being sent away carries `spent_by_pending`. `totals`, `rows` and `types` stay confirmed-only. |
| `pending_outputs[].outpoint` | string | `txid:vout`. |
| `pending_outputs[].txid` | string | Transaction. |
| `pending_outputs[].vout` | integer | Output index. |
| `pending_outputs[].value` | integer \| null | Value in sats. |
| `pending_outputs[].kind` | string | `spendable` and so on. |
| `pending_outputs[].created_height` | integer \| null | The block that created it. |
| `pending_outputs[].created_time` | integer \| null | Its time. |
| `pending_outputs[].extracted` | boolean | Extracted (isolated rare sats). |
| `pending_outputs[].inscribed_sats` | array of integer | Inscribed tracked sats. |
| `pending_outputs[].quantity` | integer | Tracked sats. |
| `pending_outputs[].first` | integer \| null | Lowest tracked sat. |
| `pending_outputs[].last` | integer \| null | Highest tracked sat. |
| `pending_outputs[].ranges` | array of array of integer | Inclusive ranges. |
| `pending_outputs[].groups` | array of [TypeGroup](https://raresats.net/docs/listing-object.md) | Sats by exact type combination, rarest first. |
| `pending_outputs[].years` | map of integer | Sats per mint year. |
| `pending_outputs[].year` | integer \| null | The year holding the most sats. |
| `pending_outputs[].rows` | map of integer | Row counts. |
| `pending_outputs[].pending` | `true` |  |
| `pending_outputs[].first_seen` | integer \| null | When the transaction was first seen in the mempool (bitcoind's entry time), unix seconds. |
| `pending_outputs[].fee_rate` | number \| null | Its fee rate, sat/vB (one decimal). |
| `pending_outputs[].address` | string \| null | Who receives it. |
| `pending_outputs[].spent_by_pending` | object | A transaction still in the mempool that spends an output (`spent_by_pending`). Absent when nothing pending spends it. |
| `pending_outputs[].spent_by_pending.txid` | string | The spending transaction. |
| `pending_outputs[].spent_by_pending.vin` | integer \| null | Its input that spends the output. |
| `pending_outputs[].spent_by_pending.first_seen` | integer \| null | When the transaction was first seen in the mempool (bitcoind's entry time), unix seconds. |
| `pending_outputs[].spent_by_pending.fee_rate` | number \| null | Its fee rate, sat/vB (one decimal). |
| `pending_outputs[].spent_by_pending.sale` | boolean | Whether the spend sells this output (a pending sale with it as the seller's input). |
| `pending_outputs[].spent_by_pending.replaceable` | boolean | Always true (full RBF): the spend may still be replaced. |
| `pending_outputs[].split_counts` | map of integer | The sats an extract's `split` may cut, per exact type combination (types sorted, joined with `+`): the row's sats as `groups` counts them, without the tracked pieces that touch block 9 or 450x (a split leaves those whole). |

#### Errors

`{error}` (a message, no code):

| Status | When |
| --- | --- |
| 400 | Not an address, or a malformed parameter. |
| 503 | The index is unavailable or busy. |

A page holds 500 UTXOs by default (`limit` up to 5,000); `page.total` says how many match. `sort` and `types` sort and filter on the server. To see which of the address's UTXOs are listed, pass their outpoints to [the batch lookup](https://raresats.net/docs/get-listing-by-outpoint.md).

While the index watches the mempool, a UTXO a pending transaction is spending carries `spent_by_pending` (`{txid, vin, first_seen, fee_rate, sale, replaceable}`: rare sats being sent), and `pending_outputs` lists the outputs pending transactions send the address (rare sats being received), described as UTXOs with `pending: true`. `totals`, `rows` and `types` stay confirmed-only.