usdsat API
The US dollar measured in satoshis, as JSON. Live price, daily history back to July 2010, changes over time, conversion and the QE / QT markers from the chart. Free, no key, CORS enabled.
Quick start
Get the current value of one US dollar in sats:
curl {BASE}/price
const r = await fetch('{BASE}/price');
const { sats_per_usd } = await r.json();
console.log(`$1 = ${sats_per_usd.toFixed(0)} sats`);
import requests
p = requests.get("{BASE}/price", timeout=10).json()
print(f"$1 = {p['sats_per_usd']:.0f} sats")
Units & data
| Field | Meaning |
|---|---|
sats_per_usd | How many satoshis one US dollar buys: 100,000,000 ÷ BTC price in USD. Falls as bitcoin rises. |
usd_per_sat | Dollar value of one satoshi. |
btc_usd | Bitcoin price in US dollars. |
source | coinbase, kraken or bitstamp for live prices (polled every few seconds, falling back in that order);
daily_close if no exchange answered in the last two minutes. |
change_pct | Change in the dollar's value in sats, in percent. Negative = the dollar buys fewer sats than then. |
annualized_pct | The same change expressed per year (compound). |
History is one close per UTC day, 2010-07-17 to yesterday, updated shortly after 00:15 UTC. Dates are YYYY-MM-DD (UTC);
times are ISO 8601 with offset.
REST endpoints
GET/price
Current sats per dollar, with the latest daily close for reference.
{
"sats_per_usd": 1538.46,
"usd_per_sat": 0.00065,
"btc_usd": 65000.0,
"volume_24h_btc": 8123.4512,
"source": "coinbase",
"time": "2026-11-15T22:40:03+00:00",
"daily_close": { "date": "2026-11-14", "sats_per_usd": 1541.85 }
}
GET/history
Closing values for a date range: daily, or the last close of each week (Monday-based) or month.
| Parameter | Default | Description |
|---|---|---|
start | 2010-07-17 | First date, YYYY-MM-DD |
end | latest | Last date, YYYY-MM-DD |
interval | day | day, week or month |
format | json | json or csv |
{
"interval": "month", "start": "2024-01-01", "end": "2026-11-14", "count": 35,
"updated": "2026-11-15T00:15:04+00:00",
"data": [
{ "period_start": "2024-01-01", "date": "2024-01-31", "sats_per_usd": 2333.12, "btc_usd": 42861.0 },
…
]
}
Spreadsheet-friendly: {BASE}/history?interval=month&format=csv
GET/change
How much the dollar's value in sats has changed since a date (or N years ago), using the live value for "now".
| Parameter | Description |
|---|---|
since | Date, YYYY-MM-DD. Uses the close on or before that date. |
years | Alternative: years back from today (decimals allowed, e.g. 0.5). |
{
"now": { "sats_per_usd": 1538.46, "time": "2026-11-15T22:40:03+00:00", "source": "coinbase" },
"then": { "date": "2020-03-15", "sats_per_usd": 18705.92 },
"change_pct": -91.775, "annualized_pct": -31.29, "years": 6.669
}
GET/stats
Everything the headline tiles show: current value, change over 1, 4 and 10 years and since the first record, and the extremes.
GET/convert
Dollars to sats, or sats to dollars, at the live rate.
| Parameter | Description |
|---|---|
usd | Amount in dollars → returns sats |
sats | Amount in sats → returns usd |
GET/markers
The QE (Fed quantitative easing) and QT (bitcoin halving) markers shown on the chart, with the dollar's value in sats on each date.
WebSocket
WS/ws
Connect to , subscribe to channels, and receive updates as they happen. The connection is pinged every 30 s;
send {"op":"ping"} yourself if you want an application-level heartbeat.
| Channel | Pushes |
|---|---|
price | A price message (same fields as GET /price) whenever the live price changes, typically every few seconds. |
presence | A presence message with watching: how many people have usdsat.com open, when it changes. |
Messages you send
{"op": "subscribe", "channels": ["price", "presence"]}
{"op": "unsubscribe", "channels": ["presence"]}
{"op": "ping"}
Messages you receive
{"type": "welcome", "version": "1.0", "channels": ["price", "presence"]}
{"type": "subscribed", "channels": ["presence", "price"]}
{"type": "price", "sats_per_usd": 1538.46, "btc_usd": 65000.0, "source": "coinbase", "time": "…", …}
{"type": "presence", "watching": 42}
{"type": "pong", "time": "…"}
{"type": "error", "code": "bad_channel", "message": "channels are price, presence"}
Right after you subscribe to price you receive the current value, so you never start empty.
const ws = new WebSocket('{WSBASE}');
ws.onopen = () => ws.send(JSON.stringify({ op: 'subscribe', channels: ['price'] }));
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === 'price') console.log(`$1 = ${m.sats_per_usd.toFixed(1)} sats`);
};
ws.onclose = () => setTimeout(() => location.reload(), 5000); // reconnect however suits you
# pip install websockets
import asyncio, json, websockets
async def main():
async with websockets.connect("{WSBASE}") as ws:
await ws.send(json.dumps({"op": "subscribe", "channels": ["price"]}))
async for raw in ws:
m = json.loads(raw)
if m["type"] == "price":
print(f"$1 = {m['sats_per_usd']:.1f} sats")
asyncio.run(main())
Live console
Embed on your site
No code needed: paste an <iframe> and your page shows the dollar in sats, refreshed every minute, linking back to usdsat.com.
It uses the same data as this API, so the same fair-use limits apply. Pick a style to get the snippet.
Parameters: style card | badge, theme auto | light | dark, range 1y | 5y | all (card only).
The card stretches to the iframe's size; 300–420 × 150–190 px works well. The badge is meant for about 250 × 40 px.
Errors
Errors use normal HTTP status codes and a JSON body:
{"error": {"code": "bad_request", "message": "since must be a date like 2024-04-20"}}
| Status | Code | When |
|---|---|---|
| 400 | bad_request | A parameter is missing or malformed |
| 404 | not_found / before_data | Unknown endpoint, or a date before July 2010 |
| 429 | rate_limited | Over the limit; wait for Retry-After seconds |
| 503 | no_data / busy | History temporarily unavailable, or too many WebSocket clients |
Limits & caching
- 120 requests per minute per IP address (bursts up to 120, refilling at 2 per second). WebSocket connections don't count.
- Responses carry
Cache-Control: a few seconds for live values, 5 minutes for history and markers. Cache on your side too. - For anything that updates continuously, use the WebSocket instead of polling.
- CORS is open (
Access-Control-Allow-Origin: *), so you can call it straight from a web page.
OpenAPI
A machine-readable description lives at /api/v1/openapi.json (OpenAPI 3.1), ready for code generators, Postman or Insomnia.
Help & FAQ
- Why does
sourcesaydaily_close? - None of the exchanges answered for two minutes, so you're getting the latest daily close instead of a live price. It recovers automatically.
- Which exchange is the live price from?
- Coinbase BTC-USD, falling back to Kraken and then Bitstamp. The
sourcefield tells you which one answered. - Is the history a BTC price index?
- It's one daily closing price per UTC day from a long-running public BTC/USD history, topped up each night from Coinbase (or Kraken / Bitstamp). Early years (2010–2013) come from thin markets, so treat them as indicative.
- Can I use this in my app or website?
- Yes. Please cache sensibly, stay within the limits, and link back to usdsat.com where it's shown. The data is provided as-is, without warranty; it is not financial advice.
- Will the API change?
- Breaking changes would come under a new version path (
/api/v2). New fields may be added to v1 responses at any time, so ignore fields you don't know.