sBTC

Overview

The sBTC dataset captures every protocol-state event on the sBTC contracts plus the SIP-010 token movements on sbtc-token. It is the canonical reference for sBTC supply, deposit and withdrawal lifecycle, and signer-set rotations.

Topics are kept verbatim (kebab-case) to match the on-chain print payloads. Field names are decoded into snake_case columns for ergonomic SQL. Cross-chain joins use bitcoin_txid.

Source

Decoded from canonical Stacks Streams events on two contracts:

  • SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-registry — protocol-state print events
  • SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token — SIP-010 transfer / mint / burn events

Tables

sbtc_events — one row per registry event. Wide schema; columns not relevant to a given topic are null. Topic discriminator: completed-deposit, withdrawal-create, withdrawal-accept, withdrawal-reject, key-rotation, update-protocol-contract.

sbtc_token_events — one row per SIP-010 event on sbtc-token: transfer / mint / burn.

sbtc_supply_snapshots — daily rollup with end-of-day total supply (deferred to a follow-up rollup job).

API

GET /v1/datasets/sbtc/events — protocol events. Filters: topic, request_id, bitcoin_txid, sender, from_block, to_block. Pagination via cursor.

GET /v1/datasets/sbtc/token-events — SIP-010 events. Filters: event_type (transfer/mint/burn), sender, recipient.

Try sbtc/events
GET/v1/datasets/sbtc/events?topic=completed-deposit&limit=5
curl
curl "https://api.secondlayer.tools/v1/datasets/sbtc/events?topic=completed-deposit&limit=5"
fetch (TypeScript)
const res = await fetch(
  "https://api.secondlayer.tools/v1/datasets/sbtc/events?topic=completed-deposit&limit=5",
);
const data = await res.json();
Response
// Hit Send to see live JSON.
Try sbtc/token-events
GET/v1/datasets/sbtc/token-events?limit=5
curl
curl "https://api.secondlayer.tools/v1/datasets/sbtc/token-events?limit=5"
fetch (TypeScript)
const res = await fetch(
  "https://api.secondlayer.tools/v1/datasets/sbtc/token-events?limit=5",
);
const data = await res.json();
Response
// Hit Send to see live JSON.

Sample response shape:

{
  "events": [
    {
      "cursor": "7869999:42",
      "block_height": 7869999,
      "block_time": "2026-05-05T12:34:56.000Z",
      "tx_id": "0xabc...",
      "tx_index": 12,
      "event_index": 42,
      "topic": "completed-deposit",
      "amount": "100000000",
      "bitcoin_txid": "0xa1b2...",
      "output_index": 0,
      "sweep_txid": "0xc3d4...",
      "burn_hash": "0xe5f6...",
      "burn_height": 902481
    }
  ],
  "next_cursor": "7870001:7",
  "tip": { "block_height": 7879089 }
}

Parquet

sBTC ships as two parquet families under one prefix. events/ covers protocol-state events (deposits, withdrawals, signer rotations, governance); token-events/ covers SIP-010 movements on sbtc-token. Both are partitioned by 10,000-block range, with per-family manifests.

Object prefix:

stacks-datasets/mainnet/v0/sbtc/events/data/block_height/<range>/data.parquet
stacks-datasets/mainnet/v0/sbtc/events/manifest/latest.json
stacks-datasets/mainnet/v0/sbtc/events/schema.json
stacks-datasets/mainnet/v0/sbtc/token-events/data/block_height/<range>/data.parquet
stacks-datasets/mainnet/v0/sbtc/token-events/manifest/latest.json
stacks-datasets/mainnet/v0/sbtc/token-events/schema.json

DuckDB:

SELECT topic, count(*) AS n
FROM read_parquet(
  'https://pub-08fa583203de40b2b154e6a56624adc2.r2.dev/stacks-datasets/mainnet/v0/sbtc/events/data/block_height/*/data.parquet'
)
GROUP BY topic
ORDER BY n DESC;

Freshness

/public/status.datasets[] includes sbtc-events and sbtc-token-events entries with latest_finalized_cursor, generated_at, and lag_blocks against the chain tip. Expect ~10K + 144 blocks of lag in steady state.

Schema doc: docs/datasets/sbtc/schema.md.