# The Offer object

An offer is a bid of a fixed price on one UTXO, listed or not. Every offer endpoint returns this object. The bidder's signatures are never part of it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The offer id: 16 lowercase hex characters. |
| `kind` | string | yes | What the offer is on: `item`, one UTXO (the only kind so far). |
| `outpoint` | string | yes | The UTXO bid on, `txid:vout`. |
| `value` | integer | yes | The UTXO's own value in sats (it moves to the bidder whole). |
| `seller_address` | string | yes | The address that held the UTXO when the offer was made: it receives `price`, and only it can accept. |
| `price` | integer | yes | The offer price in sats: exactly what the seller receives (output 1). |
| `platform_fee` | integer | yes | The bidder's platform fee: 2.5% of `price`, at least 546 sats. |
| `fee_rate` | number | yes | The network fee rate in sat/vB, fixed by the bidder's signature. |
| `network_fee` | integer | yes | The network fee in sats. |
| `total` | integer | yes | What the bidder pays: `price + platform_fee + network_fee`. |
| `vsize` | integer | yes | The transaction's estimated virtual size. |
| `unit_price` | number | yes | `(price - value) / count`, to the hundredth of a sat, as listings. |
| `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). |
| `bidder_payment_address` | string | yes | The bidder's payment address: it funds the offer and gets the change. |
| `bidder_ordinals_address` | string | yes | Where the bidder receives the UTXO (output 0). |
| `status` | string | yes | `active` (can be accepted), `pending` (accepted, in the mempool), `accepted` (confirmed), `cancelled` (by the bidder), `expired`, `invalid` (the UTXO moved or the bidder's funds were spent). |
| `created_at` | integer | yes | Unix seconds. |
| `updated_at` | integer | yes | Unix seconds of the last status change. |
| `expires_at` | integer \| null | yes | Unix seconds after which it can no longer be accepted; `null`: no expiry (until cancelled, accepted or invalid). |
| `reason` | string \| null | yes | Why an `invalid` offer is: `utxo_spent` (the UTXO was sold here otherwise: its listing bought, or another offer accepted), `utxo_moved` (spent elsewhere), `funding_spent` (a UTXO funding it was spent), `config_changed` (the marketplace's fee settings changed since it was made). `null` in every other status. |
| `txid` | string \| null | yes | The accepting transaction, while `pending` and once `accepted`; otherwise `null`. |
| `listing_id` | string \| null | yes | The UTXO's live listing, if it is listed. |
| `acceptance_public` | boolean | yes | `true` once an acceptance the server broadcast left the mempool unconfirmed: that fully signed transaction is public and can still confirm, even after a cancel or expiry here (the offer then ends `accepted`), until the bidder spends a funding UTXO or the UTXO moves. Back to `false` once it no longer can. |
| `sub` | boolean | no | Only on an offer read for a row (`row=`) that is not its own row but holds every tracked sat of the item (a sub-category or a label row): `true`. |
| `in_bundle` | boolean | no | Only on an offer read for a row (`row=`) whose UTXO holds some sats of that row among others (in bundle): `true`. Its unit price is its own `row`'s. |
| `contains_count` | integer \| null | no | With `in_bundle`: how many sats of the row asked for the item holds. |

## Example

```json title="Offer"
{
  "id": "dbf866a1e7e209e7",
  "kind": "item",
  "outpoint": "24b3eedfdc210f4a5baa96a6c99db5a51d3b1286ab2f58cb0b16fc607e54107f:0",
  "value": 10000,
  "seller_address": "bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr",
  "price": 110000,
  "platform_fee": 2750,
  "fee_rate": 3,
  "network_fee": 963,
  "total": 113713,
  "vsize": 321,
  "unit_price": 100000,
  "row": "decasat_alpha",
  "count": 1,
  "rows": {"uncommon": 1, "alpha_uncommon": 1, "decasat_alpha": 1},
  "types": [
    {
      "types": ["uncommon", "decasat_alpha", "alpha"],
      "count": 1,
      "sats": [441000000000000]
    }
  ],
  "sats": 1,
  "ranges": [[441000000000000, 441000000000000]],
  "years": {"2010": 1},
  "bidder_payment_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "bidder_ordinals_address": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh",
  "status": "active",
  "created_at": 1790967012,
  "updated_at": 1790967012,
  "expires_at": 1791571812,
  "reason": null,
  "txid": null,
  "listing_id": "5e1cb930f43354c3",
  "acceptance_public": false
}
```

The bidder offers 110,000 sats for a 10,000-sat UTXO holding one sat of its row: `unit_price` = (110,000 − 10,000) / 1 = 100,000 sats per sat. If the holder accepts, they receive 110,000 sats; the bidder pays 110,000 + 2,750 (2.5%) + the network fee.

## Statuses

`active` → `pending` (accepted, in the mempool) → `accepted` (confirmed); or `cancelled` (by the bidder), `expired` (past `expires_at`; never when it is `null`), `invalid`. Leaving `active` or `pending` deletes the bidder's signatures from the server.

An `invalid` offer says why in `reason`:

| `reason` | |
| --- | --- |
| `utxo_spent` | The UTXO was sold here otherwise: its listing was bought, or another offer on it accepted. |
| `utxo_moved` | The UTXO was spent elsewhere (its holder moved it). |
| `funding_spent` | A UTXO funding the offer was spent: by the bidder, or by another of their offers sharing it that was accepted. |
| `config_changed` | The marketplace's fee settings changed since the offer was made: the signed fee no longer matches. |

## A public acceptance: `acceptance_public`

Once accepted, the transaction carries every signature it needs. If it leaves the mempool unconfirmed, the offer goes back to `active` with **`acceptance_public: true`**: anyone holding that transaction can broadcast it again, as long as everything it spends is unspent. Cancelling or expiry here then ends the offer here but cannot recall it; should it confirm, the offer ends `accepted` all the same. **Spend a funding UTXO to be certain.** `acceptance_public` goes back to `false` once the transaction can no longer confirm.

## The best offer of a listing

A [Listing](https://raresats.net/docs/listing-object.md) shows the best active offer on its UTXO as `best_offer`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The offer id. |
| `price` | integer | yes | What the seller would receive, in sats. |
| `unit_price` | number | yes | `(price - value) / count` of the UTXO's own row, to the hundredth of a sat. |
| `bidder_payment_address` | string | yes | The bidder's payment address. |
| `bidder_ordinals_address` | string | yes | Where the bidder receives the UTXO. |
| `created_at` | integer | yes | Unix seconds. |
| `expires_at` | integer \| null | yes | Unix seconds; `null`: no expiry. |