List offers
GET/api/market/offers
Offers filtered by UTXO, seller, bidder, row and status, sorted by price, unit price, age or expiry, paged. Without status, only active offers. A wallet's "offers made" are bidder=<address>, its "offers received" seller=<address>.
Query parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
outpoint | string | no | Only offers on this UTXO (txid:vout). |
seller | string | no | Only offers to this address (that held the UTXO when the offer was made). |
bidder | string | no | Only offers made by this address (the bidder's payment or ordinals address). |
row | string | no | Only offers whose own row is this one (as always); with sub=1 also those on UTXOs the row holds whole (marked sub), and with contains those on bundles holding some of its sats, apart. |
sub | string | no | With row: 1 also answers the offers on UTXOs the row holds whole, as a rarer sub-category or a label (marked sub). One of: 0, 1. Default: 0. |
contains | string | no | With row: 1 also answers, apart, the offers on UTXOs holding only some sats of the row among others (in bundle) as contains (the first limit) and contains_total, each marked in_bundle with contains_count; only answers those alone as offers/total. Their unit price is their own row's, so sort=unit orders them by price. One of: 0, 1, only. Default: 0. |
status | string | no | all, or a comma-separated list of active, pending, accepted, cancelled, expired, invalid. Default: active. |
sort | string | no | price (the default), unit (unit price), new (creation time) or expiry (offers with no expiry last). One of: price, unit, new, expiry. Default: price. |
order | string | no | desc (the default; asc for expiry) or asc. One of: asc, desc. |
limit | integer | no | Offers per page, 1-200. Default: 50. (min 1, max 200) |
offset | integer | no | Offers to skip. Default: 0. (min 0) |
Example request #
curl 'https://raresats.net/api/market/offers?outpoint=24b3eedfdc210f4a5baa96a6c99db5a51d3b1286ab2f58cb0b16fc607e54107f:0&seller=bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr&bidder=bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh&row=decasat_alpha&status=active,pending&limit=20'const response = await fetch('https://raresats.net/api/market/offers?outpoint=24b3eedfdc210f4a5baa96a6c99db5a51d3b1286ab2f58cb0b16fc607e54107f:0&seller=bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr&bidder=bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh&row=decasat_alpha&status=active,pending&limit=20');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/market/offers", params={"outpoint": "24b3eedfdc210f4a5baa96a6c99db5a51d3b1286ab2f58cb0b16fc607e54107f:0", "seller": "bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr", "bidder": "bc1p4qhjn9zdvkux4e44uhx8tc55attvtyu358kutcqkudyccelu0was9fqzwh", "row": "decasat_alpha", "status": "active,pending", "limit": 20}).json()Response 200 #
| Field | Type | Description |
|---|---|---|
offers | array of Offer | One page of offers. |
total | integer | All offers matching the query. |
{
"offers": [
{
"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
},
{
"id": "9ab58f471cc625be",
"kind": "item",
"outpoint": "24b3eedfdc210f4a5baa96a6c99db5a51d3b1286ab2f58cb0b16fc607e54107f:0",
"value": 10000,
"seller_address": "bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr",
"price": 100000,
"platform_fee": 2500,
"fee_rate": 3,
"network_fee": 921,
"total": 103421,
"vsize": 307,
"unit_price": 90000,
"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": "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu",
"bidder_ordinals_address": "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu",
"status": "active",
"created_at": 1790967012,
"updated_at": 1790967012,
"expires_at": null,
"reason": null,
"txid": null,
"listing_id": "5e1cb930f43354c3",
"acceptance_public": false
}
],
"total": 2
}Errors #
{error, code}; see Errors for every code.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_address | An address is not a mainnet address (or not one at all). |
| 400 | bad_order | order is not asc or desc. |
| 400 | bad_outpoint | Not an outpoint (txid:vout). |
| 400 | bad_paging | limit or offset out of range. |
| 400 | bad_row | row is not a row id. |
| 400 | bad_sort | sort is not unit, price or new. |
| 400 | bad_status | status is not all or a comma-separated list of offer statuses, or (wallet transfers) not pending or all. |
| 404 | retired_row | row is a row the site retired (uncommon_2009, rare_2009): its listings are its parent row's. retired names the row and the parent and years to ask for. |
{
"error": "status must be all, or a comma-separated list of active, pending, accepted, cancelled, expired, invalid",
"code": "bad_status"
}A wallet page's two offer tabs are two queries: offers made is ?bidder=<address>&status=all, offers received is ?seller=<address>&status=all. A UTXO's offers, best first, are ?outpoint=<txid:vout>. See The Offer object and Make, accept and cancel offers.