Sales

GET/api/sales

Every sale of tracked sats the index found, on every marketplace, oldest first, as compact columns (gzip when accepted). Follow new sales with after=<seq>. Addresses are left out: ask /api/sales/parties. Cacheable 30 s. With years, month or luck, only the sales that pass (the filter echoed as filter); 501 on a server without the filters, 503 (retry: true) while the mint days or the luck are still being read, 429 (retry: true, with Retry-After) past your network's budget of new filtered answers (a cached one is always served). Sales still in the mempool come apart, in pending (newest first, marked pending: true with first_seen and fee_rate); they never enter the columns, stats or markets.

Query parameters #

Example request #

curl 'https://raresats.net/api/sales?row=uncommon&years=2009&month=2017-12&blocks=1000-5000&luck=10'

const response = await fetch('https://raresats.net/api/sales?row=uncommon&years=2009&month=2017-12&blocks=1000-5000&luck=10');
const data = await response.json();

import requests

data = requests.get("https://raresats.net/api/sales", params={"row": "uncommon", "years": "2009", "month": "2017-12", "blocks": "1000-5000", "luck": "10"}).json()

Response 200 #

Errors #

{error} (a message, no code):

Reading the columns #

The answer is column-oriented: entry i of every column is sale i, oldest first. Decode it like this:

const data = await (await fetch('https://raresats.net/api/sales?row=uncommon')).json();
let time = 0;
let seq = data.after;
let w = 0; // the next item of `w`
const pairs = list => Object.fromEntries(list.flatMap((v, j) => (j % 2 ? [] : [[data.rows[v], list[j + 1]]])));
const kind = list => list.flatMap((v, j) => (j % 2 ? [] : [{ types: data.type_sets[v], sats: list[j + 1] }]));
const sales = data.t.map((dt, i) => {
  time += dt;
  seq += data.q[i];
  return {
    seq,
    time,                               // unix seconds
    row: data.rows[data.r[i]],          // the row it is shown as
    unit_price: data.u[i],              // premium per sat of that row
    price: data.p[i],                   // sats
    count: data.c[i],                   // sats of the row sold
    marketplace: data.markets[data.m[i]],
    inscribed: (data.f[i] & 1) !== 0,
    outlier: (data.f[i] & 2) !== 0,
    sub_category: (data.f[i] & 4) !== 0,
    led: (data.f[i] & 8) !== 0,         // led by another row (with led=1)
    median: data.md[i],                 // the row's rolling median at the time
    first_sat: data.s[i],
    mined_height: data.sh[i],
    sats_sold: data.n[i],
    txid_short: data.x[i],              // first 8 + last 4 hex digits
    // The rows of the other sats it sold, primary-first ({black_omega: 1}).
    secondary: (data.f[i] & 16) ? pairs(data.w[w++]) : {},
    // The sats it sold by exact type combination ([{types: ['uncommon', 'alpha'], sats: 1}]).
    types: kind(data.kinds[data.k[i]])
  };
});

• Follow new sales: keep seq and ask ?after=<seq> (same row/group) on the next block; append what comes back. If generation changes (a reorg), reload from after=0. A cursor more than 5,000 sales behind the newest is answered whole: the answer's after is then 0, and replaces what you hold. One past the newest is answered as the newest (nothing new).
• Secondary rows: a bundle is shown as its primary row (the primary-sat rule); a sale flagged 16 sold sats of other rows too, named by its item in w. With led=1, a row's view also lists the sales led by another row that it is a secondary row of, flagged 8 (with their own row in o), never in its median or market.
• Exact types: a row's sales are not all alike (an alpha uncommon sold with a plain uncommon is an Uncommon sale). k names the type combinations each sale sold, its own row's first, through the small kinds and type_sets tables.
• Addresses are not in the columns: ask Sale parties for the rows you show.
• The full txid is a redirect away: /api/sales/{seq}/tx (to the transaction page; {txid, href} with accept: application/json).
• A sale's price is the marketplace's: on Magisat the listing price; elsewhere the seller's payment plus attributable marketplace fees. Its unit price is the premium (price less the sold output's value) per sat of its row.

To filter by mint year, mint day, birthday (month-day) or a rarer sub-category, newest first and paged, use Query sales; see Filtering & birthday sats.

Pending sales #

pending lists the selection's sales still in the mempool, newest first, under the same row, group, sub and led rules. Each has the market overview's sale fields (row, u, p, n, s, secondary, seller, buyer, …), placed among the rows exactly as a confirmed sale, plus key (txid:vin), the whole txid, vin, first_seen and fee_rate; seq and h are null. They are never in the columns, count or seq, and never in a median, volume or stat: once mined, the same sale (same txid and vin) arrives in the columns and the pending one is gone. See Pending.