# 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

```text
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](https://raresats.net/docs/errors.md).
- **Rate limits:** 50 requests per 10 seconds per IP on `/api/*`, and 30 POSTs a minute per client. See [Errors and limits](https://raresats.net/docs/errors.md).
- **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:

```bash title="cURL"
curl 'https://raresats.net/api/market/listings?row=uncommon&sort=unit&order=asc&limit=5'
```
```js title="JavaScript"
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');
}
```
```python title="Python"
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](https://raresats.net/docs/listing-object.md). 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](https://raresats.net/docs/concepts.md): rows (collections), unit prices, the fee, the transaction layout, listing statuses.
- **Read the marketplace:** [listings](https://raresats.net/docs/get-listings.md), [one listing](https://raresats.net/docs/get-listing.md), [by outpoint](https://raresats.net/docs/get-listing-by-outpoint.md), [floors](https://raresats.net/docs/get-floors.md), [settings](https://raresats.net/docs/get-config.md), [fee rates](https://raresats.net/docs/get-fees.md), [activity](https://raresats.net/docs/get-activity.md).
- **Trade:** the guides [List a UTXO](https://raresats.net/docs/guide-list.md), [Buy listings](https://raresats.net/docs/guide-buy.md) and [Cancel listings](https://raresats.net/docs/guide-cancel.md), and the reference for each call under Trading API.
- **Market data** across every marketplace: [market overview](https://raresats.net/docs/get-market.md), [sales](https://raresats.net/docs/get-sales.md), [sale parties](https://raresats.net/docs/get-sales-parties.md), [sales stats](https://raresats.net/docs/get-sales-stats.md), [a sat](https://raresats.net/docs/get-sat.md), [an address](https://raresats.net/docs/get-address.md), [an address's activity](https://raresats.net/docs/get-address-activity.md).

## For LLMs and tools

- [/llms.txt](https://raresats.net/llms.txt): an index of these pages, as links to their Markdown.
- [/llms-full.txt](https://raresats.net/llms-full.txt): every page in one Markdown file.
- [/openapi.json](https://raresats.net/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](https://raresats.net/docs/index.md)).