raresats.net API

raresats.net is a non-custodial marketplace and data site for rare sats on Bitcoin mainnet. Its public JSON API is the one the site itself uses: read listings, floors, sales, sats and addresses, and list, buy or cancel with your own wallet.

The server never holds keys or funds. Every trade is three calls: prepare (the server builds a PSBT), sign (your wallet or library signs it), submit (the server checks, completes and broadcasts it).

Base URL #

https://raresats.net

• No authentication, no API key, no account.
• JSON only. Responses are application/json (except the event stream and one redirect). POST bodies must be JSON with content-type: application/json, at most 256 KiB.
• Mainnet only. Addresses are mainnet addresses; GET /api/market/config reports the network.
• Amounts are integers in sats. Unit prices are numbers to the hundredth of a sat. PSBTs are base64. Times are unix seconds.
• Errors are {"error": "...", "code": "..."} on the marketplace routes (/api/market/*) and {"error": "..."} on the data routes. See Errors and limits.
• Rate limits: 50 requests per 10 seconds per IP on /api/*, and 30 POSTs a minute per client. See Errors and limits.
• Browsers: a POST from another site (a foreign Origin header) is refused. Call the API from your server or script; those send no Origin.

A first request #

The five cheapest uncommon sats for sale, by price per sat:

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

const response = await fetch('https://raresats.net/api/market/listings?row=uncommon&sort=unit&order=asc&limit=5');
const { listings, total } = await response.json();
for (const listing of listings) {
  console.log(listing.id, listing.outpoint, listing.price, 'sats,', listing.unit_price, 'sats per sat');
}

import requests

page = requests.get("https://raresats.net/api/market/listings",
                    params={"row": "uncommon", "sort": "unit", "order": "asc", "limit": 5}).json()
for listing in page["listings"]:
    print(listing["id"], listing["outpoint"], listing["price"], listing["unit_price"])

Each item is a Listing. Its price is what the seller receives; a buyer pays that plus the 2.5% platform fee and the network fee.

What is where #

• Concepts: rows (collections), unit prices, the fee, the transaction layout, listing statuses.
• Read the marketplace: listings, one listing, by outpoint, floors, settings, fee rates, activity.
• Trade: the guides List a UTXO, Buy listings and Cancel listings, and the reference for each call under Trading API.
• Market data across every marketplace: market overview, sales, sale parties, sales stats, a sat, an address, an address's activity.

For LLMs and tools #

• /llms.txt: an index of these pages, as links to their Markdown.
• /llms-full.txt: every page in one Markdown file.
• /openapi.json: the OpenAPI 3.1 document, the source of every parameter, schema, example and error code on these pages.
• Every page is also Markdown: add .md to its URL (this one is /docs/index.md).