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 \| 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 #

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

The Offer object

Example #

Statuses #

A public acceptance: acceptance_public #

The best offer of a listing #

A public acceptance: `acceptance_public` #