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 #

cURL

curl 'https://raresats.net/api/address/bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr'

JavaScript

const response = await fetch('https://raresats.net/api/address/bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr');
const data = await response.json();

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	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	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.

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.