Get an offer
GET/api/market/offers/{id}
One offer by id, whatever its status.
Path parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The offer id (16 hex characters). |
Example request #
curl 'https://raresats.net/api/market/offers/dbf866a1e7e209e7'const response = await fetch('https://raresats.net/api/market/offers/dbf866a1e7e209e7');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/market/offers/dbf866a1e7e209e7").json()Response 200 #
| Field | Type | Description |
|---|---|---|
id | string | The offer id: 16 lowercase hex characters. |
kind | string | What the offer is on: item, one UTXO (the only kind so far). |
outpoint | string | The UTXO bid on, txid:vout. |
value | integer | The UTXO's own value in sats (it moves to the bidder whole). |
seller_address | string | The address that held the UTXO when the offer was made: it receives price, and only it can accept. |
price | integer | The offer price in sats: exactly what the seller receives (output 1). |
platform_fee | integer | The bidder's platform fee: 2.5% of price, at least 546 sats. |
fee_rate | number | The network fee rate in sat/vB, fixed by the bidder's signature. |
network_fee | integer | The network fee in sats. |
total | integer | What the bidder pays: price + platform_fee + network_fee. |
vsize | integer | The transaction's estimated virtual size. |
unit_price | number | (price - value) / count, to the hundredth of a sat, as listings. |
row | string | 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 | How many sats of row the UTXO holds (the "×N" of a bulk listing). |
rows | map of integer | Every row the UTXO's tracked sats count toward, with their counts (label rows included). |
types | array of TypeGroup | null | The UTXO's sats grouped by exact type combination, rarest first. |
sats | integer | null | Tracked sats in the UTXO (all rows). |
ranges | array of array of integer | null | The tracked sats as inclusive [first, last] ranges, ascending. |
years | map of integer | null | Tracked sats per mint year (UTC year of the block that mined them). |
bidder_payment_address | string | The bidder's payment address: it funds the offer and gets the change. |
bidder_ordinals_address | string | Where the bidder receives the UTXO (output 0). |
status | string | 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 | Unix seconds. |
updated_at | integer | Unix seconds of the last status change. |
expires_at | integer | null | Unix seconds after which it can no longer be accepted; null: no expiry (until cancelled, accepted or invalid). |
reason | string | null | 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 | The accepting transaction, while pending and once accepted; otherwise null. |
listing_id | string | null | The UTXO's live listing, if it is listed. |
acceptance_public | boolean | 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 | 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 | 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 | With in_bundle: how many sats of the row asked for the item holds. |
{
"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": "pending",
"created_at": 1790967012,
"updated_at": 1790967012,
"expires_at": 1791571812,
"reason": null,
"txid": "332f8cf83155e2532101454afe84ed45aedf9b2f98f8593b82ff38687cfee3be",
"listing_id": "5e1cb930f43354c3",
"acceptance_public": false
}Errors #
{error, code}; see Errors for every code.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_path | The path is not valid percent-encoding. |
| 404 | not_found | No such listing or offer. In chat: no such message. A display name to remove that does not exist. |
{"error": "no such offer", "code": "not_found"}Use it to follow an offer through its life: active, then pending with the accepting txid, then accepted; or cancelled, expired or invalid. See The Offer object.