Bitcoin live data API and webhooks

Quick start

Every read is a plain GET that answers JSON, with cross-origin access open to any site. There is nothing to sign up for to read.

The whole current picture is one request. The reply below is cut down to two readings; the real one carries all six.

curl https://maketo.com/api/live/state

{
  "now": 1761820020,
  "keys": {
    "price": {
      "updated": 1761820020,
      "data": { "ts": 1761820020, "px": 110234.5, "change_5m_bps": -3.1, "change_1h_bps": 12.4, "change_24h_bps": -85.0 }
    },
    "blockclock": {
      "updated": 1761820020,
      "data": { "ts": 1761820020, "tip": { "height": 973833 }, "secs_since": 339, "p_next_within": { "60s": 0.1, "300s": 0.41, "600s": 0.63 } }
    }
  }
}

Endpoints

The state reply

The reply has the time on our clock, now, and one entry for each reading. An entry holds the time the reading was made, updated, and the reading itself, data. A reading that has not been made yet is left out rather than sent empty.

GET /api/live/state/<key> answers one reading, with the same updated and data. Check updated before you trust a number: if it is old, the feed behind it has paused.

The tape

The tape lists every Bitcoin payment of 1 coin or more that has joined the queue for a block, with how old its coins are and what block should take it. A row changes when the payment gets a block or is dropped, and each change gets a higher upd.

To follow it, ask once without since, then keep asking with the highest upd you have. The pages here ask every 4 seconds.

let since = 0;
async function poll() {
  const url = since ? `https://maketo.com/api/live/tape?since=${since}&limit=500` : `https://maketo.com/api/live/tape?limit=300`;
  const res = await fetch(url);
  if (!res.ok) return;                       // wait and try again
  const body = await res.json();
  for (const row of body.events) handle(row); // a row can come again, with a higher upd
  since = Math.max(since, body.upd);
}
setInterval(poll, 4000);

{
  "now": 1761820020,
  "upd": 9000,
  "events": [
    {
      "id": 4999,
      "txid": "6b4cb2424a23d5962217beaddbc496cb8e81973e0becd7b03898d190f9ebdacc",
      "first_seen": 1761819971,
      "in_btc": 105.8768,
      "moved_btc": 66.9722,
      "n_in": 37,
      "n_out": 3,
      "age_wavg_days": 412.3,
      "mvrv_spent": 1.87,
      "kinds": ["big100"],
      "status": "waiting",
      "proj_block": 1,
      "price_seen": 110234.5,
      "upd": 8999
    }
  ]
}

Health

GET /api/live/health says whether the feed is healthy and how old each reading is, in seconds. It is the cheapest way to tell a paused feed from a quiet market.

{
  "ok": true,
  "now": 1761820020,
  "ages": { "price": 3, "vol": 12, "window": 2, "blockclock": 4, "tapemeta": 4, "receipts": 211 }
}

Webhooks

A webhook sends you the feed instead of waiting to be asked. Register an address and the topics you want. The reply holds an id and a secret. The secret is shown once and cannot be looked up again, so keep it.

Registering is checked: Maketo first sends one signed delivery with the topic ping to your address and saves the webhook only if you answer it with the challenge it carried, as plain text or as JSON.

A delivery is a POST of JSON to your address. Its body names the topic and the time it was sent, then carries what the read endpoints return: for tape, an events list of rows; for the other topics, a data object holding the same reading the state reply holds.

curl -X POST https://maketo.com/api/live/webhooks \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/hooks/maketo","topics":["tape","blockclock"],"min_btc":100}'

{ "topic": "ping", "sent": 1761820020, "challenge": "9f2c0d3a77b14e6a8c51d0e2b4a6f813" }

{ "challenge": "9f2c0d3a77b14e6a8c51d0e2b4a6f813" }

{ "id": "wh_2f9c1e", "secret": "shown once, keep it" }

{
  "topic": "tape",
  "sent": 1761820020,
  "events": [
    { "id": 4999, "txid": "6b4cb2424a23d5962217beaddbc496cb8e81973e0becd7b03898d190f9ebdacc", "in_btc": 105.8768, "status": "waiting", "upd": 8999 }
  ]
}

{
  "topic": "blockclock",
  "sent": 1761820020,
  "data": { "ts": 1761820020, "tip": { "height": 973833 }, "secs_since": 339 }
}

curl -X DELETE https://maketo.com/api/live/webhooks/wh_2f9c1e \
  -H "x-secret: <the secret you were given>"

Checking a delivery is from Maketo

Every delivery carries two headers that matter here: x-maketo-timestamp, the time we sent it in epoch seconds, and x-maketo-signature, which reads sha256= followed by a hex code. It also carries x-maketo-topic, x-maketo-delivery (an id, the same again if the delivery is retried) and x-maketo-attempt.

The code is an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your secret. Work it out yourself from the raw bytes you received and compare. Refuse a delivery whose timestamp is more than a few minutes off, and compare in constant time.

import hashlib, hmac, time

def is_from_maketo(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:          # too old or too new
        return False
    signed = timestamp.encode() + b"." + body            # the timestamp, a dot, the raw body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromMaketo(secret, timestamp, rawBody, signature) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

Limits and good manners

• Reads are cached for a few seconds in front of the feed (Cache-Control: public, max-age=2, s-maxage=3), so asking more than once every 2 seconds returns the same answer.
• The pages themselves ask for the state every 5 seconds and the tape every 4 seconds. Staying at that pace or slower is fine.
• Each visitor may make 120 reads a minute that reach the feed (the cached ones do not count). The pages themselves use about 27. Going over answers 429 with a retry-after header that says how many seconds to wait. Wait that long, then go back to your normal pace.
• Registering webhooks is limited to 10 an hour for each visitor, and checking or removing one to 60 an hour. These answer 429 the same way.
• A webhook body and every reply are small. Nothing here needs a key, and nothing here can change anything but your own webhooks.
• Times are UTC epoch seconds. Bitcoin amounts have 4 decimals, prices 2, and a missing figure is null, never NaN.

Using the data

The numbers are measured values with the size of the sample behind them. They are not advice. For how to reuse them and the credit we ask for, see the licence page.

Licence and citation ↗