# The Listing object

A listing is one UTXO for sale at a fixed price. Every listing endpoint returns this object, and so does a sat's page (`listing`). The seller's signature is never part of it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The listing id: 16 lowercase hex characters. |
| `outpoint` | string | yes | The listed UTXO, `txid:vout`. |
| `value` | integer | yes | The UTXO's own value in sats (it moves to the buyer whole). |
| `price` | integer | yes | The listing price in sats: exactly what the seller receives. The buyer pays this plus the platform fee and the network fee. |
| `unit_price` | number | yes | Price per sat of the listing's own row: `(price - value) / count`, to the hundredth of a sat. Floors and the `unit` sort use it. |
| `row` | string | yes | The listing's own row (collection): the rarest market row holding every tracked sat of the UTXO, else the rarest market row present. Never a label row. |
| `count` | integer | yes | How many sats of `row` the UTXO holds (the "×N" of a bulk listing). |
| `rows` | map of integer | yes | Every row the UTXO's tracked sats count toward, with their counts (label rows included). |
| `types` | array of [TypeGroup](https://raresats.net/docs/listing-object.md) \| null | yes | The UTXO's sats grouped by exact type combination, rarest first. |
| `sats` | integer \| null | yes | Tracked sats in the UTXO (all rows). |
| `ranges` | array of array of integer \| null | yes | The tracked sats as inclusive `[first, last]` ranges, ascending. |
| `years` | map of integer \| null | yes | Tracked sats per mint year (UTC year of the block that mined them). |
| `seller_address` | string | yes | The address that holds the UTXO and signed the listing. |
| `payout_address` | string | yes | Where the price is paid (the seller's payment output). |
| `status` | string | yes | `active` (for sale), `pending` (a purchase is in the mempool), `sold`, `cancelled` (or replaced by a newer listing of the same UTXO), `moved` (spent elsewhere). A listing whose UTXO was sold through an accepted offer ends `sold` with `sold_via: "offer"`. |
| `created_at` | integer | yes | Unix seconds. |
| `updated_at` | integer | yes | Unix seconds of the last status change. |
| `txid` | string \| null | yes | The purchase transaction, while `pending` and once `sold`; otherwise `null`. |
| `signature_public` | boolean | yes | `true` once a broadcast purchase put the seller's signature on the network: the listing can then be bought at this price anywhere until the UTXO moves, even after a cancel here. |
| `sold_via` | string \| null | yes | `offer` when the listing ended `sold` through an accepted offer of its UTXO: `price` and `unit_price` are then the offer's (what was paid), `offer_id` names it. `null` otherwise. |
| `offer_id` | string \| null | yes | The accepted offer it was sold through (`sold_via: "offer"`), else `null`. |
| `best_offer` | [BestOffer](https://raresats.net/docs/offer-object.md) \| null | yes | The best active offer on the UTXO, or `null`. |
| `spent_by_pending` | object | no | A transaction still in the mempool that spends an output (`spent_by_pending`). Absent when nothing pending spends it. |
| `spent_by_pending.txid` | string | yes | The spending transaction. |
| `spent_by_pending.vin` | integer \| null | no | Its input that spends the output. |
| `spent_by_pending.first_seen` | integer \| null | yes | When the transaction was first seen in the mempool (bitcoind's entry time), unix seconds. |
| `spent_by_pending.fee_rate` | number \| null | yes | Its fee rate, sat/vB (one decimal). |
| `spent_by_pending.sale` | boolean | yes | Whether the spend sells this output (a pending sale with it as the seller's input). |
| `spent_by_pending.replaceable` | boolean | no | Always true (full RBF): the spend may still be replaced. |
| `in_bundle` | boolean | no | Only on a listing read for a row it holds some sats of among others (in bundle: `contains=1`'s `contains`, or a row's activity): `true`. Its `price` is the whole UTXO's and its `unit_price` its own row's, never the row asked for. |
| `contains_count` | integer \| null | no | With `in_bundle`: how many sats of the row asked for it holds. |

## Type groups

`types` holds the UTXO's sats grouped by their exact combination of sat types, rarest first: what the site draws as badges.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `types` | array of string | yes | The exact combination of sat types these sats share (e.g. `["block9", "nakamoto", "vintage"]`). |
| `count` | integer | yes | How many of the UTXO's (the sale's) tracked sats have exactly these types. |
| `sats` | array of integer | yes | Sample sat numbers of the group, ascending: its first 3 (an address's or a UTXO's page). A listing or an offer names up to 100: its first 3, then the first sat of each further run, so every special sat of a group of up to 100 (a whole range's run adds only its first sat). (0-100 items) |
| `inscribed` | integer | no | How many of them carry an inscription (absent when none). |

## Example

```json title="Listing"
{
  "id": "3324d08569806818",
  "outpoint": "8b09d6914ae17431940ce8b6cadae378a5d9b3c90c73c3a5b0b8c8e7edc9e86a:0",
  "value": 6280,
  "price": 94200,
  "unit_price": 14,
  "row": "block9",
  "count": 6280,
  "rows": {"block9": 6280, "block9_1st_tx": 6280},
  "types": [
    {
      "types": ["block9", "nakamoto", "vintage"],
      "count": 6280,
      "sats": [45100023043, 45100023044, 45100023045]
    }
  ],
  "sats": 6280,
  "ranges": [[45100023043, 45100029322]],
  "years": {"2009": 6280},
  "seller_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "payout_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "status": "active",
  "created_at": 1790952985,
  "updated_at": 1790952985,
  "txid": null,
  "signature_public": false,
  "sold_via": null,
  "offer_id": null,
  "best_offer": {
    "id": "dbf866a1e7e209e7",
    "price": 100000,
    "unit_price": 15.92,
    "bidder_payment_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "bidder_ordinals_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
    "created_at": 1790953585,
    "expires_at": 1791558385
  }
}
```

This UTXO holds 6,280 block 9 sats (2009, Nakamoto, vintage) in a 6,280-sat output, listed at 94,200 sats: `unit_price` = (94,200 − 6,280) / 6,280 = 14 sats per sat. The seller receives 94,200 sats; a buyer pays 94,200 + 2,355 (2.5%) + the network fee.

## Statuses

`active` → `pending` (a purchase in the mempool) → `sold`; or `cancelled` (by the seller, or replaced by a newer listing of the UTXO); or `moved` (spent without paying the listing). A listing whose UTXO the seller sold by accepting an [offer](https://raresats.net/docs/offer-object.md) is reserved (`pending`) while that transaction is in the mempool, then `sold` with `sold_via: "offer"`, the offer's `offer_id`, and the offer's `price` and `unit_price`: what was paid, not the ask. That sale's one activity event is the offer's `offer_accepted`. See [Concepts](https://raresats.net/docs/concepts.md#listing-statuses).