# raresats.net API

> Public JSON API of raresats.net, a non-custodial rare-sat marketplace and data site on Bitcoin mainnet. Read listings, floors, sales, sats and addresses; list, buy, bid and cancel with your own wallet (prepare, sign a PSBT, submit). No authentication. Base URL https://raresats.net.

- Base URL `https://raresats.net`; no auth, no API key; JSON in and out.
- POST bodies: `content-type: application/json`, at most 256 KiB. A POST with a foreign `Origin` header is refused; server-side clients send none.
- Amounts are integer sats; unit prices are numbers (hundredths of a sat); PSBTs are base64; mainnet only.
- Errors: `{error, code}` on `/api/market/*`, `{error}` elsewhere.
- Rate limits: 50 requests per 10 s per IP on `/api/*`; 30 POSTs a minute per client.
- Buyers pay a 2.5% platform fee (at least 546 sats) on top of the listing price; sellers pay nothing. Every purchase carries an `OP_RETURN raresats.net` marker.
- Offers (bids): anyone may bid on a tracked UTXO, listed or not; the bidder pays the 2.5% fee (at least 546 sats) on top of the offer price, signs first, and the holder accepts by signing their UTXO. Offers expire after 1, 3, 7 (default) or 30 days, or never.
- Affiliates: any address's `?ref=<address>` or `/r/<address>` links, or the `affiliate` field of a purchase, split the platform fee 50/50 with the referrer in the purchase transaction; self-referrals are not paid.
- Chat and display names: reading is public; posting needs a session opened by a BIP-322 signature (an HttpOnly cookie), and every display-name change its own signature.

## Getting started

- [Overview](https://raresats.net/docs/index.md): What the API is, the base URL, conventions, a first request and where everything is.
- [Concepts](https://raresats.net/docs/concepts.md): Rows (collections), listings, unit prices, the platform fee, the transaction layout and listing statuses.
- [Errors and limits](https://raresats.net/docs/errors.md): The error object, every error code with its HTTP status, rate limits, body limits and the origin rule.
- [The Listing object](https://raresats.net/docs/listing-object.md): Every field of a listing, as all listing endpoints return it.

## Guides

- [List a UTXO](https://raresats.net/docs/guide-list.md): Prepare a listing PSBT, sign it SIGHASH_SINGLE|ANYONECANPAY with your own key, submit it; with a complete Node example.
- [Buy listings](https://raresats.net/docs/guide-buy.md): Prepare a purchase, sign your inputs (and the setup PSBT), submit; padding, fees, expiry and retries explained.
- [Cancel listings](https://raresats.net/docs/guide-cancel.md): Sign the BIP-322 cancel message, the 10-minute window, replays, and what a public signature means.
- [Make, accept and cancel offers](https://raresats.net/docs/guide-offers.md): Bid on any tracked UTXO, accept the offers on yours, cancel by BIP-322: the transaction layout, expiry or none, and a complete Node example.
- [Extract rare sats](https://raresats.net/docs/guide-extract.md): Carve the rare sats of your UTXOs into outputs of their own with your own wallet: prepare, sign every input, submit; the layout, padding, skipped items and the checks.
- [Send rare sats and bitcoin](https://raresats.net/docs/guide-send.md): Send whole UTXOs or only their rare sats, N sats of a type, chopped block 9 ranges, consolidate plain bitcoin or pay many recipients; destinations, the flat tools fee, listings.
- [Speed up or cancel a transfer](https://raresats.net/docs/guide-speed-up.md): Replace a pending wallet transfer at a higher fee (RBF) or send every source UTXO back; the fee rules, voiding a dropped transfer, the refusals.
- [Filtering & birthday sats](https://raresats.net/docs/guide-filters.md): Filter sales and listings by row, rarer sub-category, mint year, mint day or month-day (birthday sats) and sat luck; facets and paging.
- [Affiliates](https://raresats.net/docs/guide-affiliates.md): Referral links for any address (no registration), the 50/50 fee split in the purchase transaction, the 546-sat minimum, the 24-hour last-click cookie, self-referral.
- [Chat & profiles](https://raresats.net/docs/guide-chat.md): The chat page and its topics, signing in with a BIP-322 signature, posting, replying in threads, links to messages, paging and following messages live, display names (their rules), and moderation (AI and admins).

## Listings API

- [List active listings](https://raresats.net/docs/get-listings.md): GET /api/market/listings: active listings filtered by row and seller, sorted by unit price, price or age, paged.
- [Get a listing](https://raresats.net/docs/get-listing.md): GET /api/market/listings/{id}: one listing by id, any status.
- [Get listings by outpoint](https://raresats.net/docs/get-listing-by-outpoint.md): GET /api/market/listings/by-outpoint/{outpoint} and the batch form ?outpoints=: the live listing of UTXOs.
- [Get floors](https://raresats.net/docs/get-floors.md): GET /api/market/floors: each collection's lowest unit price and how much is listed.
- [Get settings](https://raresats.net/docs/get-config.md): GET /api/market/config: fee, fee address, marker, limits, readiness.
- [Get fee rates](https://raresats.net/docs/get-fees.md): GET /api/market/fees: slow, normal, fast and minimum network fee rates in sat/vB.
- [Get activity](https://raresats.net/docs/get-activity.md): GET /api/market/activity: listed, cancelled and sold events, newest first.
- [Query listings](https://raresats.net/docs/get-listings-query.md): GET /api/listings/query and /api/listings/events: listings and activity filtered by row, sub-category and mint date.
- [Get an affiliate](https://raresats.net/docs/get-affiliate.md): GET /api/market/affiliates/{address}: an affiliate's earnings and referred purchases.

## Trading API

- [Prepare a listing](https://raresats.net/docs/prepare-listing.md): POST /api/market/listings/prepare: the listing PSBT to sign.
- [Submit a listing](https://raresats.net/docs/submit-listing.md): POST /api/market/listings: the signed listing PSBT; creates the listings.
- [Cancel listings](https://raresats.net/docs/cancel-listings.md): POST /api/market/listings/cancel: off sale by a BIP-322 signed message.
- [Prepare a purchase](https://raresats.net/docs/prepare-purchase.md): POST /api/market/purchase/prepare: the PSBTs to sign, fee breakdown and expiry.
- [Submit a purchase](https://raresats.net/docs/submit-purchase.md): POST /api/market/purchase/submit: the signed PSBTs; broadcast.
- [Register an affiliate](https://raresats.net/docs/register-affiliate.md): POST /api/market/affiliates/register: optional, kept for compatibility (any address is an affiliate without it).

## Offers API

- [The Offer object](https://raresats.net/docs/offer-object.md): Every field of an offer, its statuses, and a listing's best_offer.
- [List offers](https://raresats.net/docs/get-offers.md): GET /api/market/offers: offers by UTXO, seller, bidder, row and status, sorted by price, unit price, age or expiry, paged.
- [Get an offer](https://raresats.net/docs/get-offer.md): GET /api/market/offers/{id}: one offer by id, any status.
- [Get the best offers](https://raresats.net/docs/get-best-offers.md): GET /api/market/offers/best: the best active offer of many UTXOs.
- [Prepare an offer](https://raresats.net/docs/prepare-offer.md): POST /api/market/offers/prepare: the offer PSBT to sign, its fee breakdown and expiry.
- [Submit an offer](https://raresats.net/docs/submit-offer.md): POST /api/market/offers: the signed offer PSBT; the offer goes active.
- [Cancel offers](https://raresats.net/docs/cancel-offers.md): POST /api/market/offers/cancel: withdraw offers by a BIP-322 signed message.
- [Prepare to accept an offer](https://raresats.net/docs/prepare-accept-offer.md): POST /api/market/offers/{id}/accept/prepare: the PSBT the UTXO's holder signs.
- [Accept an offer](https://raresats.net/docs/accept-offer.md): POST /api/market/offers/{id}/accept: the signed PSBT; broadcast.

## Wallet tools API

- [Prepare a transfer](https://raresats.net/docs/prepare-transfer.md): POST /api/market/transfer/prepare: plan an extraction, send, send N, chop, consolidation, multisend, speed-up or cancel; the PSBT to sign and what it does.
- [Submit a transfer](https://raresats.net/docs/submit-transfer.md): POST /api/market/transfer/submit: the signed PSBT; verified, rechecked and broadcast, idempotent.
- [List wallet transfers](https://raresats.net/docs/get-wallet-transfers.md): GET /api/market/transfers: an address's transfers built with the wallet tools, pending or all.
- [Get a wallet transfer](https://raresats.net/docs/get-wallet-transfer.md): GET /api/market/transfers/{txid}: one wallet transfer, its status and whether it can be sped up or cancelled.

## Market data

- [Market overview](https://raresats.net/docs/get-market.md): GET /api/market: the homepage's market over a window, across every marketplace.
- [Sales](https://raresats.net/docs/get-sales.md): GET /api/sales: every sale as compact columns, with the column key.
- [Query sales](https://raresats.net/docs/get-sales-query.md): GET /api/sales/query: sales filtered by row, sub-category, mint years, day or month-day, newest first, with facets.
- [Sale parties](https://raresats.net/docs/get-sales-parties.md): GET /api/sales/parties: seller and buyer addresses of sales.
- [Sales stats](https://raresats.net/docs/get-sales-stats.md): GET /api/sales/stats and /api/sales/{seq}/tx: each row's market, and a sale's transaction.
- [Sat](https://raresats.net/docs/get-sat.md): GET /api/sat/{n}: one sat, its location, sales and listing.
- [UTXO](https://raresats.net/docs/get-utxo.md): GET /api/utxo/{outpoint}: one output, every rare sat in it with its offset, where they went once spent, its sales and listing.
- [Transaction](https://raresats.net/docs/get-tx.md): GET /api/tx/{txid}: one transaction, every input and output, the tracked rare sats each input carried and the output each landed in, its sales and notable verdicts.
- [Address](https://raresats.net/docs/get-address.md): GET /api/address/{address}: an address's rare-sat UTXOs.
- [Address activity](https://raresats.net/docs/get-address-activity.md): GET /api/address/{address}/activity: an address's sales, listings, extractions and transfers, filtered and paged.
- [Birthday sats](https://raresats.net/docs/get-birthday.md): GET /api/birthday/counts and /api/days: what was mined on a day, and the mint-day table.
- [Prices](https://raresats.net/docs/get-prices.md): GET /api/prices: the current BTC/USD price and one a day since 2010.

## Chat & profiles API

- [Chat sessions](https://raresats.net/docs/chat-sessions.md): GET /api/session/nonce, POST, GET and DELETE /api/session: sign in to chat with BIP-322, the session cookie, sign out.
- [Chat messages](https://raresats.net/docs/chat-messages.md): Topics (GET /api/chat/topics; admins create and archive them), GET and POST /api/chat/messages by topic, threads (reply_to, GET /api/chat/messages/{id}/replies), and the admins' delete and ban routes.
- [Display names](https://raresats.net/docs/chat-profiles.md): POST /api/profile, GET /api/profile/{address} and /api/profiles: set a display name with BIP-322, read names one at a time or 200 at once.

## Site feeds

- [Supply, rows and status](https://raresats.net/docs/site-feeds.md): The dashboard's own feeds: supply, rows, notable events, what is pending in the mempool, status and health.
- [Live events](https://raresats.net/docs/live-events.md): The SSE stream: every event type and its payload, ids and Last-Event-ID resume, bursts, and what never goes down it.

## Optional

- [Everything in one file](https://raresats.net/llms-full.txt): every page above, concatenated
- [OpenAPI 3.1 document](https://raresats.net/openapi.json): every route, parameter, schema, example and error code