.md

Index API

Decoded rows over plain HTTP, every endpoint a GET under /v1/index. Envelope, cursors and filters work the same on all of them: see REST conventions.

Decoded events by event_type

GET/v1/index/events
Open .md

One event_type per request, oldest first unless order=desc. Which filters and fields apply depends on the type; anything a type does not accept is refused.

Filters

event_typeenumrequired#

The event type to read. Required, unless you pass types instead.

11 possible values
ft_transfernft_transferstx_transferstx_mintstx_burnstx_lockft_mintft_burnnft_mintnft_burnprint
typesstring#

Alias for event_type, the Streams spelling. Takes one value; a comma-separated set is refused. Mutually exclusive with event_type.

orderenum#

asc (default) reads oldest first. desc reads newest first: with no height range, page one is the newest rows of the last day. A desc page's next_cursor starts with desc: and pages older; a cursor resumes only under the order that issued it, and the other order is refused with 400.

2 possible values
ascdesc
contract_idstring#

Contract principal, or a comma-separated set of up to 20 (e.g. SP1.sbtc-token,SP1.sbtc-registry). Mutually exclusive with trait.

traitenum#

Only contracts that declare or implement this SIP standard, resolved as of the page's to_height. Mutually exclusive with contract_id.

3 possible values
sip-009sip-010sip-013
asset_identifierstring#

Asset identifier (<contract>::<asset>). ft and nft transfer, mint and burn types only.

senderstring#

Sending principal. Types with a sender only; on stx_lock it is the locked address.

recipientstring#

Receiving principal. Types with a recipient only.

tx_contextboolean#

true adds the submitting transaction's tx_sender, tx_type, tx_status, tx_contract_id and tx_function_name to each row.

waitinteger#

Seconds (max 25) to hold the response open when there's nothing new past your cursor/from_height, instead of answering immediately. Returns early the moment new data commits, or at the timeout — either way you get a normal response, just later. Omit for the old poll-and-retry behavior.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

fieldsstring#

Comma-separated columns to return: the universal ones, the type's own columns, and the tx_* columns when tx_context=true. cursor, block_height and event_type always come back; an unknown name is refused. Leaving out block_time skips a join.

Returns

A cursor envelope. events holds Index event objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Fungible token transfers

GET/v1/index/ft-transfers
Open .md

Same rows as /v1/index/events?event_type=ft_transfer, oldest first unless order=desc, with a typed row. Filters combine with AND.

Filters

orderenum#

asc (default) reads oldest first. desc reads newest first: with no height range, page one is the newest rows of the last day. A desc page's next_cursor starts with desc: and pages older; a cursor resumes only under the order that issued it, and the other order is refused with 400.

2 possible values
ascdesc
contract_idstring#

Token contract. One principal; no comma-separated set here.

asset_identifierstring#

Asset identifier (<contract>::<asset>).

senderstring#

Sending principal.

recipientstring#

Receiving principal.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

fieldsstring#

Comma-separated columns to return, from block_time, tx_id, tx_index, event_index, contract_id, asset_identifier, sender, recipient, amount and event_type. cursor and block_height always come back; an unknown name is refused.

Returns

A cursor envelope. events holds FT transfer objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

NFT transfers

GET/v1/index/nft-transfers
Open .md

Same rows as /v1/index/events?event_type=nft_transfer, oldest first unless order=desc, with a typed row. Filters combine with AND.

Filters

orderenum#

asc (default) reads oldest first. desc reads newest first: with no height range, page one is the newest rows of the last day. A desc page's next_cursor starts with desc: and pages older; a cursor resumes only under the order that issued it, and the other order is refused with 400.

2 possible values
ascdesc
contract_idstring#

NFT contract. One principal; no comma-separated set here.

asset_identifierstring#

Asset identifier (<contract>::<asset>).

senderstring#

Sending principal.

recipientstring#

Receiving principal.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

fieldsstring#

Comma-separated columns to return, from block_time, tx_id, tx_index, event_index, contract_id, asset_identifier, sender, recipient, value and event_type. cursor and block_height always come back; an unknown name is refused.

Returns

A cursor envelope. events holds NFT transfer objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Decoded contract-call transactions

GET/v1/index/contract-calls
Open .md

Top-level contract_call transactions in canonical blocks, oldest first, with arguments and result decoded. Failed calls are included; check status. The cursor is <block_height>:<tx_index>. reorgs covers every height on the page.

Filters

contract_idstring#

Contract principal, or a comma-separated set of up to 20 (e.g. SP1.sbtc-token,SP1.sbtc-registry). Mutually exclusive with trait.

traitenum#

Only contracts that declare or implement this SIP standard, resolved as of the page's to_height. Mutually exclusive with contract_id.

3 possible values
sip-009sip-010sip-013
function_namestring#

Called function. Exact match.

senderstring#

Transaction sender principal. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<tx_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

Returns

A cursor envelope. contract_calls holds Contract call objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Canonical block-hash map

GET/v1/index/canonical
Open .md

One row per height on the canonical chain, oldest first. Orphaned blocks never appear, so you can check your own chain against it. Lean by design; /v1/index/blocks is the full block. Not metered.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

Returns

A cursor envelope. canonical holds Canonical block objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Canonical blocks

GET/v1/index/blocks
Open .md

Canonical blocks, oldest first. The cursor is <block_height>:0. The window follows the ingest tip, so it can run ahead of the decoded tip.block_height.

Filters

waitinteger#

Seconds (max 25) to hold the response open when there's nothing new past your cursor/from_height, instead of answering immediately. Returns early the moment new data commits, or at the timeout — either way you get a normal response, just later. Omit for the old poll-and-retry behavior.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

Returns

A cursor envelope. blocks holds Block objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Block by height or hash

GET/v1/index/blocks/{height_or_hash}
Open .md

A height returns the canonical block there. A hash returns that block whether or not it is canonical, so check canonical to spot an orphan. Not metered.

Path parameters

height_or_hashstringrequired#

A block height (digits only) or a 0x-prefixed block hash.

Returns

  • 200The block and the tip it was read against
  • 401This bind requires the instance token, and it was missing or wrong
  • 404No block at that height or with that hash (Block not found)
  • 429Rate limited; retry after Retry-After seconds

Full transaction documents

GET/v1/index/transactions
Open .md

Transactions in canonical blocks, oldest first, with fee, nonce, post-conditions and payload detail decoded from the raw bytes. Filters combine with AND. The cursor is <block_height>:<tx_index>. reorgs covers every height on the page.

Filters

typestring#

Transaction type as stored, e.g. contract_call, token_transfer, smart_contract, coinbase, tenure_change. Exact match.

senderstring#

Sender principal. Exact match.

contract_idstring#

Called or deployed contract. One principal. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<tx_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

fieldsstring#

Comma-separated columns to return, from block_time, burn_block_height, tx_index, tx_type, sender, status, fee, nonce, sponsored, anchor_mode, post_condition_mode, post_conditions, contract_call, smart_contract, token_transfer. cursor, block_height and tx_id always come back; an unknown name is refused.

Returns

A cursor envelope. transactions holds Transaction objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Transaction by tx_id

GET/v1/index/transactions/{tx_id}
Open .md

One transaction document, only if it sits in a canonical block. A transaction still pending is at /v1/index/mempool/{tx_id}. Not metered.

Path parameters

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

Returns

  • 200The transaction and the tip it was read against
  • 401This bind requires the instance token, and it was missing or wrong
  • 404No canonical transaction with that id (Transaction not found)
  • 429Rate limited; retry after Retry-After seconds

Transaction inclusion proof

GET/v1/index/transactions/{tx_id}/proof
Open .md

What you need to check, without trusting this API, that a transaction is in a signed Nakamoto block: the raw tx, the raw block header, and the tx merkle path. consensus adds the cycle's signer set when the node can resolve it. The SDK's verifyTransactionProof runs every check. The instance must reach its Stacks node. Immutable once served.

Path parameters

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

Returns

The Transaction proof object.

  • 200The inclusion proof
  • 401This bind requires the instance token, and it was missing or wrong
  • 404The transaction or its block is not indexed or not on the node (PROOF_UNAVAILABLE)
  • 429Rate limited; retry after Retry-After seconds
  • 503The Stacks node is unreachable (PROOF_NODE_UNAVAILABLE), or the stored transactions do not reproduce the block's merkle root (PROOF_TX_SET_INCOMPLETE)

Pending transactions

GET/v1/index/mempool
Open .md

Pending transactions this instance's node has seen since the observer connected, in arrival order. A single-node, go-forward view: the backlog from before the observer connected is never replayed. Confirmed transactions leave the list. No height window. Never cached.

Filters

senderstring#

Sender principal. Exact match.

typestring#

Transaction type as stored, e.g. contract_call, token_transfer. Exact match.

contract_idstring#

Called contract. Exact match.

function_namestring#

Called function. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

Opaque next_cursor from a previous page. Pass it back unchanged. Mutually exclusive with from_cursor.

from_cursorstring#

Same as cursor.

Returns

A cursor envelope. mempool holds Mempool transaction objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Pending transaction by tx_id

GET/v1/index/mempool/{tx_id}
Open .md

One pending transaction. It 404s once the transaction confirms (read it from /v1/index/transactions/{tx_id}) or drops. Never cached.

Path parameters

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

Returns

  • 200The pending transaction and the current tip
  • 401This bind requires the instance token, and it was missing or wrong
  • 404Not pending on this instance: confirmed, dropped, or never seen (Pending transaction not found)
  • 429Rate limited; retry after Retry-After seconds

Print payload schemas for a contract

GET/v1/index/contracts/{contract_id}/print-schema
Open .md

Infers the shape of a contract's print payloads from its canonical print events, grouped by the tuple's topic field. Reads the newest 1500 and oldest 500 events, so fields the contract stopped emitting still show. Takes no query parameters. Held in memory for 5 minutes per contract. Not metered.

Path parameters

contract_idstringrequired#

Contract principal, <address>.<name>. Anything that does not look like one is refused.

Returns

The Print schema object.

  • 200Inferred print schemas
  • 400contract_id is not a contract principal, or a query parameter was sent (VALIDATION_ERROR)
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

State writes

GET/v1/index/state-writes
Open .md

The exact MARF writes each canonical block committed, in the node's write order: every changed leaf of the block's state trie, named. Oldest first; the cursor is <block_height>:<ordinal>. block_height reads one block. Present only from the height this instance's node subscribed to the state_writes observer key, with no earlier history. The window follows the ingest tip. reorgs overlaps by height.

Filters

block_heightinteger#

Read one block: the same as from_height and to_height both set to it, which it excludes. A cursor with it must sit at that height.

contract_idstring#

One contract, <address>.<contract-name>: only keys under vm::<contract_id>:: (its data maps, data vars and token balances). Exact, no wildcards.

tx_contextboolean#

true adds the writing transaction's tx_id, tx_sender, tx_type, tx_status, tx_contract_id and tx_function_name to each row; null for block-level writes.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<ordinal> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

Returns

A cursor envelope. state_writes holds State write objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

PoX-4 stacking actions

GET/v1/index/stacking
Open .md

Decoded PoX-4 contract calls (stack-stx, delegate-stx, stack-aggregation-commit-indexed, …), one row per call, oldest first. Pages on <block_height>:<tx_index>. With no cursor or from_height, the read covers the last day. PoX-4 stopped at the epoch 4.0 fork, so read history with from_height and use /v1/index/pox5/events for what came after.

Filters

function_namestring#

PoX-4 function name, e.g. stack-stx or delegate-stack-stx. Exact match.

stackerstring#

Stacker principal named in the call. Exact match. Solo stack-stx calls leave it null, so filter those by caller.

callerstring#

Transaction sender. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<tx_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

Returns

A cursor envelope. stacking holds PoX-4 stacking action objects.

  • 200Cursor-paginated envelope
  • 304The page is past finality and matches your If-None-Match ETag.
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds
Open .md

One row per pox-5 reward cycle, descending, exact to the node: total stacked, reward-eligible STX, bond sats, sBTC custodied, rewards allocated/claimed, and cumulative rewards-per-token. Without a cursor, your list starts at the next reward cycle (the current one plus one) and goes back in time. Pass a higher cursor to reach cycles further in the future, which PoX-5 bonds can lock many cycles ahead. pox_version marks the era; at the next PoX fork this endpoint follows the chain and reports the new PoX instead. PoX-4 history is final and not served here; rebuild it from /v1/index/stacking on a self-hosted instance. Frozen cycles cache for an hour; the still-open current cycle caches briefly.

Range and paging

limitinteger · 1 to 100#

Cycles per page, 1 to 100. Defaults to 20; anything else is refused.

cursorinteger#

next_cursor from the previous page, or any reward cycle (exclusive) to page from. Returns cycles below it. Omit it and the list starts at the next reward cycle.

Returns

A cursor envelope. cycles holds PoX-5 reward cycle objects.

  • 200Reward cycles, descending from the next reward cycle
  • 400limit or cursor is out of range, or an unknown parameter was sent
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

A PoX-5 reward cycle by cycle number

GET/v1/index/pox/cycles/{reward_cycle}
Open .md

One pox-5 reward cycle, the same shape as a row of /v1/index/pox/cycles plus its per-signer breakdown. 404 when the cycle doesn't exist yet. A cycle number below 141 (pox-5's first) 404s with a note that PoX-4 cycles are final and not served here.

Path parameters

reward_cycleintegerrequired#

Reward cycle number.

Returns

  • 200The cycle, with its signers
  • 400reward_cycle is not a non-negative integer
  • 401This bind requires the instance token, and it was missing or wrong
  • 404The cycle doesn't exist yet, or (below 141) is PoX-4 history: final and not served here; rebuild it from /v1/index/stacking on a self-hosted instance
  • 429Rate limited; retry after Retry-After seconds

Decoded PoX-5 boot-contract events

GET/v1/index/pox5/events
Open .md

Decoded print log of the pox-5 boot contract (SIP-045 Bitcoin Staking) — all 19 topics (stake, stake-update, register-signer, unstake, claim-rewards, etc.), one row per print. Starts at the epoch 4.0 hard fork, where /v1/index/stacking's pox-4 feed ends.

Filters

topicenum#

One print topic. Omit for all of them.

19 possible values
set-bond-adminset-pause-adminpause-rewardssetup-bondadd-to-allowlistregister-for-bondupdate-bond-registrationregister-signerstakestake-updateannounce-l1-early-exitunstake-sbtcunstakecalculate-rewardsbond-distributionclaim-rewardsclaim-staker-rewards-for-signergrant-signer-keyrevoke-signer-grant
stakerstring#

Staker principal. Exact match.

signerstring#

The signer: a signer-manager contract. Set on every topic that involves a signer, so signer= returns a pool's full activity.

signer_managerstring#

The same principal, as printed on claim and grant topics (claim-rewards, claim-staker-rewards-for-signer, grant-signer-key, revoke-signer-grant). Kept for compatibility; signer covers it.

bond_indexinteger#

Bond index. Exact match.

reward_cycleinteger#

Reward cycle. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

confirmedboolean#

true stops the page at the finality boundary, so every row is past the reorg margin.

fieldsstring#

Comma-separated columns to return. cursor, block_height and topic always come back; an unknown name is refused.

Returns

A cursor envelope. events holds PoX-5 event objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Rune catalog

GET/v1/index/runes
Open .md

Every etched rune, with the identity bundle (id, name, spaced_name, symbol, divisibility) every Runes response carries plus its computed supply, mint/burn counters and mint terms. search prefix-matches the name (spacers and case ignored); sort is etch order (number, default) or busiest-first (mints).

Filters

searchstring#

Name prefix, spacers and case ignored (e.g. dog matches DOG•GO•TO•THE•MOON).

sortenum#

number (etch order, oldest first — default) or mints (busiest first).

2 possible values
numbermints

Range and paging

cursorstring#

Opaque token from a previous page's next_cursor. Resumes after it — pass back unchanged.

limitinteger · 1 to 1000#

Page size; capped at 1000.

Returns

A cursor envelope. runes holds Rune entry objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

A single rune's entry

GET/v1/index/runes/{rune}
Open .md

One rune's full entry by id or name, with computed supply (premine + mints × terms.amount). 404 when no rune matches.

Path parameters

runestringrequired#

A rune id (<block>:<tx>, e.g. 840000:3) or name — spacers and case are ignored, so DOG•GO•TO•THE•MOON, dog.go.to.the.moon and doggotothemoon are the same rune.

Returns

  • 200The rune
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 404No rune matches this id/name, or Runes isn't configured on this instance (code: NOT_FOUND, the latter case also carries details.notes)
  • 429Rate limited; retry after Retry-After seconds

Rune etches, mints, transfers and burns

GET/v1/index/runes/activity
Open .md

Every rune-moving event — etch, mint, transfer, burn — filterable by rune/address/kind/txid and cursor-paginated. Returns events[], next_cursor, tip, reorgs[]. Cursor: <block_height>:<event_index>, same shape as every other decoded-event feed.

Filters

runestring#

A rune id (<block>:<tx>, e.g. 840000:3) or name — spacers and case are ignored, so DOG•GO•TO•THE•MOON, dog.go.to.the.moon and doggotothemoon are the same rune.

addressstring#

Mainnet Bitcoin address. Exact match.

kindstring#

One or more of rune_etch, rune_mint, rune_transfer, rune_burn, comma-separated.

txidstring#

Bitcoin txid, hex with no 0x prefix (Rune txids come back as stored, unlike Stacks ones). Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

Returns

A cursor envelope. events holds Rune event objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Rune balances by address or outpoint

GET/v1/index/runes/balances
Open .md

Current per-outpoint rune balances. Exactly one of address or outpoint is required; rune narrows either to one rune. Returns balances[], next_cursor, tip.

Filters

addressstring#

Mainnet Bitcoin address. Mutually exclusive with outpoint; exactly one is required.

outpointstring#

<txid>:<vout>. Mutually exclusive with address; exactly one is required.

runestring#

A rune id (<block>:<tx>, e.g. 840000:3) or name — spacers and case are ignored, so DOG•GO•TO•THE•MOON, dog.go.to.the.moon and doggotothemoon are the same rune. Narrows the result to one rune.

Range and paging

cursorstring#

Opaque token from a previous page's next_cursor. Resumes after it — pass back unchanged.

limitinteger · 1 to 1000#

Page size; capped at 1000.

Returns

A cursor envelope. balances holds Rune balance objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Decoded sBTC peg events

GET/v1/index/sbtc/events
Open .md

Every decoded sbtc-registry print, all topics, one row per event, oldest first: deposits, withdrawal create/accept/reject, signer key rotations and protocol-contract updates. With no cursor or from_height, the read covers the last day.

Filters

topicenum#

One print topic. Omit for all of them; an unknown topic is refused.

6 possible values
completed-depositwithdrawal-createwithdrawal-acceptwithdrawal-rejectkey-rotationupdate-protocol-contract
senderstring#

Stacks principal on the event (the withdrawal requester on withdrawal-create). Exact match.

request_idinteger#

Withdrawal request id. Exact match.

bitcoin_txidstring#

Bitcoin txid on the event, 0x-prefixed hex. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

confirmedboolean#

true stops the page at the finality boundary, so every row is past the reorg margin.

Returns

A cursor envelope. events holds sBTC event objects.

  • 200Cursor-paginated envelope
  • 304The page is past finality and matches your If-None-Match ETag.
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Completed sBTC deposits

GET/v1/index/sbtc/deposits
Open .md

Completed deposits, one row per completed-deposit event, oldest first. The event fires once the signers have swept the BTC in, so every row is final on the peg side. With no cursor or from_height, the read covers the last day.

Filters

senderstring#

Stacks principal on the event. Exact match. Mainnet deposits currently carry none.

bitcoin_txidstring#

Deposit's Bitcoin txid, 0x-prefixed hex. Exact match.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

confirmedboolean#

true stops the page at the finality boundary, so every row is past the reorg margin.

fieldsstring#

Comma-separated columns to return, from: block_time, tx_id, tx_index, event_index, amount, sender, bitcoin_txid, output_index, recipient_btc_version, recipient_btc_hashbytes. cursor and block_height always come back; an unknown name is refused.

Returns

A cursor envelope. deposits holds sBTC deposit objects.

  • 200Cursor-paginated envelope
  • 304The page is past finality and matches your If-None-Match ETag.
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

sBTC peg-in by Bitcoin txid

GET/v1/index/sbtc/deposits/{bitcoin_txid}
Open .md

One completed deposit, looked up by the Bitcoin txid of the deposit. Past finality it is cached for good and answers If-None-Match with 304.

Path parameters

bitcoin_txidstringrequired#

Deposit's Bitcoin txid, 0x-prefixed hex, as it appears in bitcoin_txid.

Returns

  • 200The deposit
  • 304The resource is past finality and matches your If-None-Match ETag.
  • 401This bind requires the instance token, and it was missing or wrong
  • 404No completed deposit has this Bitcoin txid
  • 429Rate limited; retry after Retry-After seconds

sBTC withdrawals, one per request

GET/v1/index/sbtc/withdrawals
Open .md

Withdrawals, one row per request_id, ordered by when they were requested. Each row carries its current status from the latest accept or reject, the BTC sweep the signers committed to, and that sweep's Bitcoin settlement. The height window and cursor apply to the request event. Status can change after a row is final, so pages are never long-cached.

Filters

statusenum#

Current lifecycle status.

3 possible values
REQUESTEDACCEPTEDREJECTED
senderstring#

Requester's Stacks principal. Exact match.

request_idinteger#

Withdrawal request id. Exact match.

settlement_confirmedboolean#

true returns withdrawals whose sweep has confirmed on Bitcoin. false returns the rest, including ones with no sweep yet.

confirmed_afterstring · date-time#

ISO 8601 timestamp. Returns only withdrawals whose sweep confirmed on Bitcoin strictly after it. Combine with from_height=0 to scan all history.

Range and paging

limitinteger · 1 to 1000#

Page size; capped at 1000.

cursorstring#

<block_height>:<event_index> from a previous page's next_cursor. Resumes after it.

from_cursorstring#

Same as cursor. Mutually exclusive with it and with from_height.

from_heightinteger#

First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip.

to_heightinteger#

Last block height to read, inclusive.

confirmedboolean#

true stops the page at the finality boundary, so every row is past the reorg margin.

fieldsstring#

Comma-separated columns to return, from: status, amount, sender, recipient_btc_version, recipient_btc_hashbytes, sweep_txid, settlement_confirmed, btc_confirmations, btc_block_height, confirmed_at, requested_at, resolved_at. cursor and request_id always come back; an unknown name is refused.

Returns

A cursor envelope. withdrawals holds sBTC withdrawal objects.

  • 200Cursor-paginated envelope
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

sBTC peg-out lifecycle by request_id

GET/v1/index/sbtc/withdrawals/{request_id}
Open .md

One withdrawal's full lifecycle: the request, the accept or reject, and the Bitcoin settlement of its sweep. Once it is accepted or rejected and past finality, it is cached for good and answers If-None-Match with 304.

Path parameters

request_idintegerrequired#

Withdrawal request id.

Returns

  • 200The withdrawal's lifecycle
  • 304The resource is past finality and matches your If-None-Match ETag.
  • 400request_id is not a non-negative integer
  • 401This bind requires the instance token, and it was missing or wrong
  • 404No withdrawal request has this id
  • 429Rate limited; retry after Retry-After seconds

sBTC peg summary scoreboard

GET/v1/index/sbtc/summary
Open .md

All-time totals for the whole bridge: deposit and withdrawal counts, net peg flow, and circulating sBTC supply read from sbtc-token on this instance's node. Takes no parameters.

Returns

  • 200The bridge totals
  • 401This bind requires the instance token, and it was missing or wrong
  • 429Rate limited; retry after Retry-After seconds

Bitcoin output spend status

GET/v1/bitcoin/outspend/{txid}/{vout}
Open .md

Whether one Bitcoin output is spent, and by which transaction, read live from this instance's Bitcoin node. A spend in the mempool shows on the next read, with mempool: true. A confirmed spend names its block. The spender of a confirmed spend is found by reading blocks back from the tip, up to 144 of them. A spend deeper than that answers spent: true with a null spending_txid and a note. Answers can change with the mempool and with reorgs, so they are cached for 2 seconds at most. Hosted: one row per answer, 20 requests per second per key. Self-host needs Bitcoin Core 24 or later with txindex=1 at BITCOIN_RPC_URL.

Path parameters

txidstringrequired#

The txid of the transaction that created the output, display order: 64 hex characters, 0x optional.

voutintegerrequired#

The output's index in that transaction, from 0.

Returns

The Bitcoin output spend object.

  • 200The output's spend status
  • 400The txid is not 64 hex characters, or vout is not a non-negative integer (VALIDATION_ERROR)
  • 401This bind requires the instance token, and it was missing or wrong
  • 404No transaction with that txid, no output at that index, or an OP_RETURN output, which can never be spent
  • 429Rate limited; retry after Retry-After seconds
  • 502The Bitcoin node could not be read, or lacks a method this needs (BITCOIN_SOURCE_ERROR)
  • 503BITCOIN_UNAVAILABLE: this instance has no Bitcoin node (BITCOIN_RPC_URL unset). BITCOIN_BUSY: block reads are at capacity; retry after Retry-After seconds

Index discovery

GET/v1/index
Open .md

Lists every Index route with its accepted filters, plus the per-event_type column and filter vocabulary for /v1/index/events. Open: it runs before auth, so it never needs a token.

Returns

The Index discovery object.

  • 200Index routes and filters
Open .md

Every Index route with the filters it accepts.

Returned by Index discovery

Attributes

routesarray of objectrequired#

One entry per route: path, method, description, and filters where it takes any. The /v1/index/events entry adds event_types and event_type_filters (columns and accepted filters per type).

authstringrequired#

How to authenticate, in prose.

cursorobjectrequired#

Cursor format and how to resume with it.

Open .md

One decoded event, flat. The universal columns are always there; the rest depend on event_type, and a type's own columns are always set for its rows.

Returned by Decoded events by event_type

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the row landed in.

block_timestring · date-time · nullable#

That block's timestamp, ISO 8601 UTC.

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

tx_indexintegerrequired#

The transaction's position in its block.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

event_typeenumrequired#

The event type. Decides which columns are set.

11 possible values
ft_transfernft_transferstx_transferstx_mintstx_burnstx_lockft_mintft_burnnft_mintnft_burnprint
contract_idstring · nullablerequired#

Contract that emitted the event. null for STX transfers, mints, burns and locks.

asset_identifierstring · nullable#

<contract>::<asset>, on ft and nft types.

senderstring · nullable#

Sending principal. The locked address on stx_lock.

recipientstring · nullable#

Receiving principal.

amountstring · nullable#

Amount as a decimal string (bigint-safe). microSTX on STX types.

valuestring · nullable#

NFT id as hex-encoded Clarity, on nft types.

memostring · nullable#

Transfer memo, on stx_transfer.

payloadobject#

Decoded print payload on print; { unlock_height } on stx_lock.

tx_senderstring · nullable#

Submitting transaction's sender. Only with tx_context=true.

tx_typestring · nullable#

Submitting transaction's type. Only with tx_context=true.

tx_statusstring · nullable#

Submitting transaction's status. Only with tx_context=true.

tx_contract_idstring · nullable#

Contract the submitting transaction called or deployed. Only with tx_context=true.

tx_function_namestring · nullable#

Function the submitting transaction called. Only with tx_context=true.

Open .md

One fungible token transfer.

Returned by Fungible token transfers

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the row landed in.

block_timestring · date-time · nullable#

That block's timestamp, ISO 8601 UTC.

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

tx_indexintegerrequired#

The transaction's position in its block.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

event_typeenumrequired#

Always ft_transfer.

1 possible values
ft_transfer
contract_idstringrequired#

Token contract.

asset_identifierstringrequired#

<contract>::<asset>.

senderstringrequired#

Sending principal.

recipientstringrequired#

Receiving principal.

amountstringrequired#

Amount in the token's base units, as a decimal string (bigint-safe).

Open .md

One NFT transfer.

Returned by NFT transfers

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the row landed in.

block_timestring · date-time · nullable#

That block's timestamp, ISO 8601 UTC.

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

tx_indexintegerrequired#

The transaction's position in its block.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

event_typeenumrequired#

Always nft_transfer.

1 possible values
nft_transfer
contract_idstringrequired#

NFT contract.

asset_identifierstringrequired#

<contract>::<asset>.

senderstringrequired#

Sending principal.

recipientstringrequired#

Receiving principal.

valuestringrequired#

The token id as hex-encoded Clarity.

Open .md

One top-level contract-call transaction, arguments and result decoded to JSON. Clarity integers come back as decimal strings.

Returned by Decoded contract-call transactions

Attributes

cursorstringrequired#

<block_height>:<tx_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the row landed in.

block_timestring · date-time · nullable#

That block's timestamp, ISO 8601 UTC.

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

tx_indexintegerrequired#

The transaction's position in its block.

contract_idstringrequired#

Called contract.

function_namestringrequired#

Called function.

senderstringrequired#

Transaction sender principal.

statusstringrequired#

Execution status, e.g. success or abort_by_response.

argsarray of objectrequired#

Decoded arguments, in call order.

resultobjectrequired#

Decoded result. null when there is none.

result_hexstring · nullablerequired#

The result as hex-encoded Clarity.

Open .md

One height of the canonical chain: the hash, its parent, and the Bitcoin anchor. Every row is canonical.

Returned by Canonical block-hash map

Attributes

cursorstringrequired#

<block_height>:0. Pass as cursor.

block_heightintegerrequired#

Stacks block height.

block_hashstringrequired#

The block's hash.

parent_hashstringrequired#

The parent block's hash, to check linkage.

burn_block_heightintegerrequired#

The Bitcoin block it anchors to.

burn_block_hashstring · nullablerequired#

That Bitcoin block's hash.

Open .md

One MARF write a block committed, as the node's state_writes observer key delivered it.

Returned by State writes

Attributes

cursorstringrequired#

<block_height>:<ordinal>. Pass as cursor.

block_heightintegerrequired#

Stacks block height.

ordinalintegerrequired#

Position in the block's write order, from 0. A separate clock from event_index.

tx_indexinteger · nullablerequired#

The writing transaction's index in the block; null for block-level writes.

keystringrequired#

The full MARF key, e.g. vm::<contract>::0::map::<hex> or vm-account::<address>::19.

value_hexstringrequired#

The value written, hex as the node sent it.

tx_idstring · nullable#

Writing transaction's id. Only with tx_context=true; null for block-level writes.

tx_senderstring · nullable#

Writing transaction's sender. Only with tx_context=true.

tx_typestring · nullable#

Writing transaction's type. Only with tx_context=true.

tx_statusstring · nullable#

Writing transaction's status. Only with tx_context=true.

tx_contract_idstring · nullable#

Contract the writing transaction called or deployed. Only with tx_context=true.

tx_function_namestring · nullable#

Function the writing transaction called. Only with tx_context=true.

Open .md

A Stacks block: chain linkage and Bitcoin anchor. Only what ingest stores; no miner, tx count or cost data.

Returned by Canonical blocks

Attributes

cursorstringrequired#

<block_height>:0. Pass as cursor.

block_heightintegerrequired#

Stacks block height.

block_hashstringrequired#

The block's hash.

parent_hashstringrequired#

The parent block's hash.

burn_block_heightintegerrequired#

The Bitcoin block it anchors to.

burn_block_hashstring · nullablerequired#

That Bitcoin block's hash.

index_block_hashstring · nullablerequired#

Nakamoto block id. Pass it as ?tip= to a node read-only call to pin the read to this block. null on rows ingested before it was stored.

block_timestring · date-time · nullablerequired#

That block's timestamp, ISO 8601 UTC.

canonicalbooleanrequired#

Whether the block is on the canonical chain. Always true in the list; a hash lookup can return an orphan.

Open .md

A confirmed transaction: stored columns plus what decodes from the raw bytes. Payload objects appear only for the matching tx_type. Decoded fields are null when the raw bytes do not decode (burnchain ops).

Returned by Full transaction documents

Attributes

cursorstringrequired#

<block_height>:<tx_index>. Pass as cursor.

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

block_heightintegerrequired#

Stacks block the row landed in.

block_timestring · date-time · nullable#

That block's timestamp, ISO 8601 UTC.

burn_block_heightinteger · nullable#

The Bitcoin block its Stacks block anchors to.

tx_indexintegerrequired#

The transaction's position in its block.

statusstringrequired#

Execution status, e.g. success or abort_by_response.

tx_typestringrequired#

token_transfer, contract_call, smart_contract, coinbase, tenure_change or poison_microblock, decoded from the raw bytes. Falls back to the stored type when they do not decode.

senderstringrequired#

Sender principal.

feestring · nullablerequired#

Fee in microSTX as a decimal string. null when the raw bytes do not decode.

noncestring · nullablerequired#

Sender nonce as a decimal string.

sponsoredboolean · nullablerequired#

Whether a sponsor paid the fee.

anchor_modeenum · nullablerequired#

Anchor mode from the raw bytes.

3 possible values
on_chain_onlyoff_chain_onlyany
post_condition_modeenum · nullablerequired#

Post-condition mode from the raw bytes.

2 possible values
allowdeny
post_conditionsarray of PostConditionrequired#

Decoded post-conditions. Empty when there are none.

token_transferobject#

token_transfer only.

coinbaseobject#

coinbase only.

tenure_changeobject#

tenure_change only.

contract_callobject#

contract_call only.

smart_contractobject#

smart_contract only.

Open .md

Everything needed to verify inclusion offline. Hex values have no 0x prefix.

Returned by Transaction inclusion proof

Attributes

txidstringrequired#

Transaction id. Recompute it from raw_tx.

index_block_hashstringrequired#

Nakamoto block id. Recompute it from raw_header.

block_heightintegerrequired#

Stacks block height.

tx_indexintegerrequired#

The transaction's position in the block; the merkle leaf index.

raw_txstringrequired#

The serialized transaction.

raw_headerstringrequired#

The serialized Nakamoto block header, signer signatures included.

tx_merkle_patharray of objectrequired#

Sibling hashes from the leaf up to the header's tx merkle root.

consensusobject#

The reward cycle and its signer set, to check the header's signatures pass 70% of signer weight. Absent when the node cannot resolve the set.

Open .md

A pending transaction: the transaction document before it has a block, so no height, index, status or result, plus when this instance first saw it.

Returned by Pending transactions

Attributes

cursorstringrequired#

Opaque. Pass it back as cursor unchanged.

tx_idstringrequired#

Transaction id, 0x-prefixed hex.

received_atstring · date-time · nullablerequired#

When this instance's node first saw it, ISO 8601 UTC.

tx_typestringrequired#

token_transfer, contract_call, smart_contract, coinbase, tenure_change or poison_microblock, decoded from the raw bytes. Falls back to the stored type when they do not decode.

senderstringrequired#

Sender principal.

feestring · nullablerequired#

Fee in microSTX as a decimal string. null when the raw bytes do not decode.

noncestring · nullablerequired#

Sender nonce as a decimal string.

sponsoredboolean · nullablerequired#

Whether a sponsor paid the fee.

anchor_modeenum · nullablerequired#

Anchor mode from the raw bytes.

3 possible values
on_chain_onlyoff_chain_onlyany
post_condition_modeenum · nullablerequired#

Post-condition mode from the raw bytes.

2 possible values
allowdeny
post_conditionsarray of PostConditionrequired#

Decoded post-conditions. Empty when there are none.

token_transferobject#

token_transfer only.

coinbaseobject#

coinbase only.

tenure_changeobject#

tenure_change only.

contract_callobject#

contract_call only. No result yet.

smart_contractobject#

smart_contract only.

Open .md

A contract's print payloads, grouped by topic and typed field by field from the events sampled.

Returned by Print payload schemas for a contract

Attributes

Open .md

One decoded PoX-4 contract call. Which columns are set depends on function_name; a failed call sets only the base fields.

Returned by PoX-4 stacking actions

Attributes

cursorstringrequired#

<block_height>:<tx_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the call landed in.

block_timestring · date-time · nullable#

That block's timestamp.

burn_block_heightintegerrequired#

Bitcoin block that Stacks block anchors to.

tx_idstringrequired#

The calling transaction.

tx_indexintegerrequired#

Its position in the block. With block_height, the cursor.

function_namestringrequired#

PoX-4 function called, e.g. stack-stx.

callerstringrequired#

Transaction sender.

stackerstring · nullable#

Stacker the call acts on, on delegate-side calls. Null on solo stack-stx, where caller is the stacker.

delegate_tostring · nullable#

Pool operator, on delegate-stx.

amount_ustxstring · nullable#

microSTX as a decimal string (bigint-safe): the amount locked, delegated or increased by.

lock_periodinteger · nullable#

Cycles locked, or extended by.

pox_addrobjectrequired#

Bitcoin reward address. Every field is null when the call names none.

start_cycleinteger · nullable#

First reward cycle the lock covers.

end_cycleinteger · nullable#

Last reward cycle the lock covers.

reward_cycleinteger · nullable#

Reward cycle named by aggregation and signer-key calls. What /v1/index/pox/cycles groups on.

signer_keystring · nullable#

Signer public key, 0x-prefixed hex.

result_okbooleanrequired#

Whether the call returned ok.

Open .md

Materialized per-cycle rollup of pox-5.clar's own state (plan 078), exact to the node.

Returned by Reward cycles of the current PoX (PoX-5)

Attributes

reward_cycleintegerrequired#

The reward cycle.

start_burn_heightintegerrequired#

Bitcoin block at which this cycle starts.

prepare_start_burn_heightintegerrequired#

Bitcoin block at which this cycle's totals froze: the start of the prior cycle's prepare phase.

end_burn_heightintegerrequired#

Bitcoin block at which this cycle ends.

total_stacked_ustxstringrequired#

STX + bond ustx delegated to signers this cycle, as a decimal string.

reward_eligible_ustxstringrequired#

STX actually counted toward rewards. Signers below the 50,000 STX threshold don't count, even though they're in total_stacked_ustx.

stakersintegerrequired#

Distinct stakers (STX and bond) with a position this cycle.

signers_in_setintegerrequired#

Signers that met the 50,000 STX delegation threshold this cycle.

bond_satsobjectrequired#

Bond index (as a string key) -> sats staked for this cycle.

bond_total_satsstringrequired#

Sum of bond_sats for this cycle.

sbtc_custodied_satsstringrequired#

sBTC currently custodied by pox-5 (non-L1 bonds only). A running total, not scoped to this cycle: the contract's get-total-sbtc-staked takes no cycle argument.

rewards_allocated_stxstringrequired#

STX rewards allocated to this cycle's distributions so far.

rewards_allocated_bondstringrequired#

Bond (sBTC) rewards allocated to this cycle's distributions so far.

reserve_depositstringrequired#

STX deposited to the protocol reserve from this cycle's distributions.

rewards_per_token_stxstring · nullablerequired#

Cumulative STX rewards per micro-STX for this cycle. null before the first distribution.

rewards_per_token_bondobjectrequired#

Bond index (as a string key) -> cumulative rewards-per-sat for this cycle.

distributionsintegerrequired#

Distributions run for this cycle so far (0, 1, or 2).

rewards_claimedstringrequired#

Rewards claimed for this cycle so far, across every signer.

computed_through_heightintegerrequired#

Stacks block height this rollup was last computed through.

is_currentbooleanrequired#

True for the cycle containing the tip's burn height.

is_frozenbooleanrequired#

True once totals can no longer change: the tip has reached prepare_start_burn_height. Closed and current cycles are always frozen; only a not-yet-started future cycle is open.

Open .md

One print event from the pox-5 boot contract, decoded. Promoted columns cover the common filters; data always holds the complete tuple, so no topic loses fields.

Returned by Decoded PoX-5 boot-contract events

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the print landed in.

block_timestring · date-time · nullable#

That block's timestamp.

tx_idstringrequired#

Transaction that emitted the print.

tx_indexintegerrequired#

Its position in the block.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

topicenumrequired#

The print topic. Decides which columns are set.

19 possible values
set-bond-adminset-pause-adminpause-rewardssetup-bondadd-to-allowlistregister-for-bondupdate-bond-registrationregister-signerstakestake-updateannounce-l1-early-exitunstake-sbtcunstakecalculate-rewardsbond-distributionclaim-rewardsclaim-staker-rewards-for-signergrant-signer-keyrevoke-signer-grant
stakerstring · nullable#

Staker principal.

signerstring · nullable#

Signer-manager contract, on stake-side topics.

signer_managerstring · nullable#

Signer-manager contract, on claim and grant topics.

bond_indexinteger · nullable#

The bond this event belongs to, on bond topics.

amount_ustxstring · nullable#

microSTX as a decimal string (bigint-safe).

amount_satsstring · nullable#

Satoshis as a decimal string (bigint-safe).

reward_cycleinteger · nullable#

Reward cycle the event refers to, on reward and claim topics.

first_reward_cycleinteger · nullable#

First cycle a stake earns in.

unlock_cycleinteger · nullable#

Cycle the stake unlocks at.

unlock_burn_heightinteger · nullable#

Bitcoin block height the stake unlocks at.

is_l1_lockboolean · nullable#

Bond registrations: whether the lockup is on Bitcoin L1.

signer_keystring · nullable#

Signer public key, on key-grant topics.

dataobjectrequired#

The full decoded print tuple. Nested shapes (btc-lockup, bond-rewards, bond-periods) come through intact.

Open .md

One etched rune's full entry — identity, premine/mint/burn counters, computed supply, and mint terms.

Returned by Rune catalog

Attributes

idstringrequired#

<block>:<tx> of the etch, e.g. 840000:3.

numberstringrequired#

Etch sequence number (u128 decimal string) — 0 is genesis.

namestringrequired#

The rune's name with spacers stripped, uppercase.

spaced_namestringrequired#

The name as etched, spacers (•) included.

symbolstring · nullablerequired#

The etched display symbol, if any.

divisibilityintegerrequired#

Decimal places a whole unit divides into.

preminestringrequired#

Premined amount, u128 decimal string.

supplystringrequired#

Computed: premine + mints × terms.amount (0 with no terms). u128 decimal string.

burnedstringrequired#

Total burned, u128 decimal string.

mintsstringrequired#

Total mint transactions, u128 decimal string.

turbobooleanrequired#

Whether the etch opted into future protocol upgrades.

etching_txidstringrequired#

The etch transaction's Bitcoin txid.

etched_heightintegerrequired#

Bitcoin block the etch landed in.

etched_tx_indexintegerrequired#

The etch transaction's position in that block.

termsobject · nullablerequired#

Mint terms, or null for a premine-only rune that was never mintable.

Open .md

One etch/mint/transfer/burn event from rune_events, with the rune's identity embedded so an activity feed never needs a second lookup to show a name.

Returned by Rune etches, mints, transfers and burns

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Bitcoin block the event landed in.

tx_indexintegerrequired#

The transaction's position in that block.

txidstringrequired#

The Bitcoin transaction's txid.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

kindenumrequired#

What happened.

4 possible values
rune_etchrune_mintrune_transferrune_burn
amountstringrequired#

u128 decimal string.

voutinteger · nullablerequired#

The output the amount landed on, when this event has one.

addressstring · nullablerequired#

The output's mainnet address. Only ever set on a rune_transfer event.

runeRuneRefSummaryrequired#
Open .md

A rune's balance on one unspent output, with the rune's identity embedded.

Returned by Rune balances by address or outpoint

Attributes

runeRuneRefSummaryrequired#
addressstring · nullablerequired#

The output's mainnet address, or null for a non-standard script.

txidstringrequired#

The outpoint's Bitcoin txid.

voutintegerrequired#

The outpoint's output index.

amountstringrequired#

u128 decimal string.

Open .md

One decoded sbtc-registry print. Every topic shares this shape; topic decides which columns are set.

Returned by Decoded sBTC peg events

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the print landed in.

block_timestring · date-time · nullable#

That block's timestamp.

tx_idstringrequired#

Transaction that emitted the print.

tx_indexintegerrequired#

Its position in the block.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

topicenumrequired#

The print topic.

6 possible values
completed-depositwithdrawal-createwithdrawal-acceptwithdrawal-rejectkey-rotationupdate-protocol-contract
request_idinteger · nullable#

Withdrawal request id, on withdrawal topics.

amountstring · nullable#

Sats as a decimal string, on deposits and withdrawal requests.

senderstring · nullable#

Stacks principal, e.g. the withdrawal requester.

recipient_btc_versioninteger · nullable#

Bitcoin address type of the recipient: 0 p2pkh, 1 p2sh, 2 p2sh-p2wpkh, 3 p2sh-p2wsh, 4 p2wpkh, 5 p2wsh, 6 p2tr.

recipient_btc_hashbytesstring · nullable#

Recipient's hash bytes, 0x-prefixed hex.

bitcoin_txidstring · nullable#

Bitcoin txid, 0x-prefixed hex: the deposit transaction, or the sweep on an accept.

output_indexinteger · nullable#

Output within that Bitcoin transaction.

sweep_txidstring · nullable#

Signers' sweep transaction on Bitcoin.

burn_hashstring · nullable#

Bitcoin block hash the signers anchored the event to.

burn_heightinteger · nullable#

That Bitcoin block's height.

signer_bitmapstring · nullable#

Bitmap of the signers' votes, as a decimal string.

max_feestring · nullable#

Most the requester will pay in BTC fees, in sats.

feestring · nullable#

BTC fee charged on an accepted withdrawal, in sats.

governance_contract_typeinteger · nullable#

Which protocol contract changed, on update-protocol-contract.

governance_new_contractstring · nullable#

The new contract, on update-protocol-contract.

signer_aggregate_pubkeystring · nullable#

The registry's aggregate-key field, on key-rotation (33 bytes, hex). In v1 it is the signers' aggregate public key. Once DKG is disabled (no height set yet) it is the marker 0xFF || bitcoin block hash, not a key, so do not derive addresses from it.

signer_thresholdinteger · nullable#

New signature threshold, on key-rotation.

signer_addressstring · nullable#

New signer principal, on key-rotation.

signer_keys_countinteger · nullable#

Number of signer keys in the new set, on key-rotation.

Open .md

A completed peg-in: one completed-deposit event. Keyed by the Bitcoin txid; deposits carry no request id.

Returned by Completed sBTC deposits

Attributes

cursorstringrequired#

<block_height>:<event_index>. Pass as cursor.

block_heightintegerrequired#

Stacks block the deposit completed in.

block_timestring · date-time · nullable#

That block's timestamp.

tx_idstringrequired#

Stacks transaction that completed the deposit.

tx_indexintegerrequired#

Its position in the block.

event_indexintegerrequired#

The event's position in the block. With block_height, the cursor.

amountstring · nullable#

Sats minted, as a decimal string.

senderstring · nullable#

Stacks principal on the event. Null on mainnet deposits today.

bitcoin_txidstring · nullable#

The deposit's Bitcoin txid, 0x-prefixed hex.

output_indexinteger · nullable#

The deposit output within that Bitcoin transaction.

recipient_btc_versioninteger · nullable#

Bitcoin address type of the recipient: 0 p2pkh, 1 p2sh, 2 p2sh-p2wpkh, 3 p2sh-p2wsh, 4 p2wpkh, 5 p2wsh, 6 p2tr.

recipient_btc_hashbytesstring · nullable#

Recipient's hash bytes, 0x-prefixed hex.

Open .md

A peg-out rolled up to one row per request_id: the request, its current status, and the Bitcoin settlement of its sweep.

Returned by sBTC withdrawals, one per request

Attributes

cursorstringrequired#

The request event's <block_height>:<event_index>. Pass as cursor.

request_idintegerrequired#

Withdrawal request id.

statusenum#

REQUESTED until the signers act, then ACCEPTED or REJECTED from the latest resolution event.

3 possible values
REQUESTEDACCEPTEDREJECTED
amountstring · nullable#

Sats requested, as a decimal string.

senderstring · nullable#

Requester's Stacks principal.

recipient_btc_versioninteger · nullable#

Bitcoin address type of the recipient: 0 p2pkh, 1 p2sh, 2 p2sh-p2wpkh, 3 p2sh-p2wsh, 4 p2wpkh, 5 p2wsh, 6 p2tr.

recipient_btc_hashbytesstring · nullable#

Recipient's hash bytes, 0x-prefixed hex.

sweep_txidstring · nullable#

Bitcoin sweep the signers committed to on accept. Null until then.

settlement_confirmedboolean · nullable#

True once the sweep has confirmed on Bitcoin, false while it is pending, null when there is no sweep or it has not been seen yet.

btc_confirmationsinteger · nullable#

Bitcoin confirmations on the sweep at the last check.

btc_block_heightinteger · nullable#

Bitcoin block the sweep landed in.

confirmed_atstring · date-time · nullable#

When the sweep reached the confirmation threshold.

requested_atstring · date-time · nullable#

Block time of the request.

resolved_atstring · date-time · nullable#

Block time of the accept or reject. Null while requested.

Open .md

One output's spend status. An unspent output carries only txid, vout and spent.

Returned by Bitcoin output spend status

Attributes

txidstringrequired#

The output's transaction, display order, no 0x.

voutintegerrequired#

The output's index.

spentbooleanrequired#

True once any transaction spends it, in the mempool or in a block.

spending_txidstring · nullable#

The spending transaction. Null for a confirmed spend deeper than the blocks a lookup reads; note says so.

spending_vininteger · nullable#

The index of the spending input in that transaction.

confirmedboolean#

True when the spend is in a block of the active chain.

mempoolboolean#

True when the spend is only in the mempool so far.

block_heightinteger · nullable#

Height of the block with the spend. Null in the mempool.

block_hashstring · nullable#

Hash of the block with the spend. Null in the mempool.

notestring#

Present when the answer is incomplete: why the spender is not named.

Edit on GitHub