Sales stats
Every row's market #
GET/api/sales/stats
Per row: the last unit price, the 30-day median unit price, volume and sales, and all-time sales. With years, month or luck, every row's market over only the sales of its sats of those years, that month or those lucks (matched as /api/sales matches them; the sales' outlier verdicts are their row's), and filter echoed: the Statistics' sales columns under a year, month or luck filter, and a collection's head under its Activity filter. Confirmed sales only: pending (mempool) sales never count.
Query parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
years | string | no | Only the sales of each row's sats mined in these years (comma-separated YYYY, 2009 to this year; year too). |
month | string | no | Only the sales of each row's sats mined in this month (UTC, YYYY-MM, by each block's own time), matched on the dashboard: any rare-sat index. |
blocks | string | no | Only the sales of each row's sats mined in these blocks: heights from-to, inclusive (1000-5000), or one block (9), up to the tip (400 past it or for a malformed or reversed range), matched on the dashboard: any rare-sat index. |
luck | string | no | Only the sales of each row's sats mined in blocks of these lucks: N (N or more) or N-M. |
Example request #
curl 'https://raresats.net/api/sales/stats?years=2009&month=2017-12&blocks=1000-5000&luck=10'const response = await fetch('https://raresats.net/api/sales/stats?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/stats", params={"years": "2009", "month": "2017-12", "blocks": "1000-5000", "luck": "10"}).json()Response 200 #
| Field | Type | Description |
|---|---|---|
available | boolean | Whether the sales index is available. |
generation | integer | Sales generation. |
seq | integer | The newest sale's sequence number. |
count | integer | Sales held. |
as_of | object | null | {height, time}. |
first_time | integer | null | The first sale, unix seconds. |
stats | map of object | Per row. |
stats.<key>.last_unit_price | number | null | The last sale's unit price (outliers excluded). |
stats.<key>.last_time | integer | null | Its time. |
stats.<key>.median_30d | number | null | 30-day median unit price. |
stats.<key>.volume_30d | integer | 30-day volume in sats. |
stats.<key>.volume_all | integer | All-time volume in sats (inscribed sales aside). |
stats.<key>.sales_30d | integer | 30-day sales. |
stats.<key>.sales | integer | Sales in all. |
Errors #
{error} (a message, no code):
| Status | When |
|---|---|
| 400 | A malformed years, month or luck. |
| 429 | Too many new filtered answers (each a pass over every sale) from your network (an IPv4 address or IPv6 /64), or from everyone at once: retry: true; try again after Retry-After seconds. Answers already built are served all the same. |
| 501 | years or luck asked of a server without the sat filters. |
| 503 | The mint days or the block luck are still being read (retry: true), or the luck is not available. |
With ?years=2009, ?month=2017-12, ?blocks=1000-5000 or ?luck=10 (or several), every row's market is over only the sales of its own sats mined in those years, in that month, in those blocks (heights, inclusive), or in blocks of those lucks: a sale counts under its row when a sat of that row it sold passes, as the collection's Activity filters it (/api/sales/query?row=…&years=…). The sales keep their row's outlier verdicts.
A sale's transaction #
GET/api/sales/{seq}/tx
A 302 redirect to the sale's transaction page, /tx/{txid} (the compact sales carry only part of the txid). With accept: application/json, {txid, href} instead.
Path parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
seq | integer | yes | The sale's sequence number. (min 0) |
Example request #
curl 'https://raresats.net/api/sales/1/tx'const response = await fetch('https://raresats.net/api/sales/1/tx');
const data = await response.json();import requests
data = requests.get("https://raresats.net/api/sales/1/tx").json()Response 200 #
| Field | Type | Description |
|---|---|---|
txid | string | |
href | string | /tx/{txid}. |
{
"txid": "d78f3f29369db39032219ae561732dda47b54b6f6d4d93d72a22c257c3946ac2",
"href": "/tx/d78f3f29369db39032219ae561732dda47b54b6f6d4d93d72a22c257c3946ac2"
}Response 302 #
Redirect; location is /tx/{txid}.
Errors #
{error} (a message, no code):
| Status | When |
|---|---|
| 404 | No such sale. |
To turn sats into dollars at the time of a sale, use the daily BTC/USD history of Prices.
Stats are of confirmed sales only: a sale still in the mempool (pending in Sales) never counts.