List active listings

GET/api/market/listings

Active listings, one page at a time, filtered by row and seller and sorted by unit price, price or age. Read-only, no rate limit beyond the edge's.

Query parameters #

Example request #

curl 'https://raresats.net/api/market/listings?row=black_rare&sort=unit&order=asc&limit=2'

const response = await fetch('https://raresats.net/api/market/listings?row=black_rare&sort=unit&order=asc&limit=2');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/market/listings", params={"row": "black_rare", "sort": "unit", "order": "asc", "limit": 2}).json()

Response 200 #

{
  "listings": [
    {
      "id": "1031931af1592e1c",
      "outpoint": "2fb6fb60ece3672924a373d7479d144d9ce4d3591185bfb5a00e62aedd53d3a9:0",
      "value": 546,
      "price": 60546,
      "unit_price": 60000,
      "row": "black_rare",
      "count": 1,
      "rows": {"black_rare": 1},
      "types": [
        {
          "types": ["black_rare", "omega"],
          "count": 1,
          "sats": [1657319999999999]
        }
      ],
      "sats": 1,
      "ranges": [[1657319999999999, 1657319999999999]],
      "years": {"2017": 1},
      "seller_address": "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu",
      "payout_address": "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu",
      "status": "active",
      "created_at": 1790952985,
      "updated_at": 1790952985,
      "txid": null,
      "signature_public": false,
      "sold_via": null,
      "offer_id": null,
      "best_offer": null
    }
  ],
  "total": 1,
  "as_of": {"height": 969001, "checked_at": 1790952985}
}

Errors #

{error, code}; see Errors for every code.

{"error": "sort must be unit, price or new", "code": "bad_sort"}

Sorting and paging #

• sort=unit (the default) orders by unit_price, the price per sat of the listing's own row: the way to find a collection's cheapest sats. sort=price orders by the listing price, sort=new by creation time.
• order defaults to asc, except desc for sort=new (newest first). Equal values come newest first, then by id, so pages are stable.
• Page with limit (1-200) and offset; total counts every match. Listings can sell or move between two pages; re-read the first page when it matters.

Filters #

• row filters by a listing's own row. With sub=1 it also lists the row's rarer sub-categories (listings whose sats the row holds whole). A label row such as block9_1st_tx lists every listing lying in it.
• contains=1 (with row) adds, apart, the listings that hold only some sats of the row among others (in bundle: a 330-sat Block 9 chunk holding one Block 9 palindrome, under block9_palindrome) as contains, the first limit by total price, with contains_total. Each is marked in_bundle: true with contains_count, its sats of the row. They are priced as the whole UTXO: their unit_price is their own row's, so they are never in listings, total or the row's floor. contains=only answers them alone as listings and total, paged by limit and offset.
• seller lists one seller's active listings (the site's "My listings").
• Only active listings are listed. A pending, sold, cancelled or moved listing is still readable by id (Get a listing).

To filter listings by mint year, mint day, birthday (month-day) or one rarer sub-category, use Query listings; see Filtering & birthday sats.