API reference

Every public endpoint, generated from the API's own OpenAPI description.

The SDK is the shorter path

Cursor walking, checkpointing, and reorg rewind are already solved in @secondlayer/sdk; reach for HTTP when you're not writing TypeScript. Envelope, cursor, and filter grammar live in REST API.

Base URL / · spec version 1.0.0

index

Decoded chain events (transfers, mints/burns, prints, stacking)

GET/v1/indexno key

Index discovery

Responses: 200400401

GET/v1/index/eventsno key

Decoded events by event_type

Parameter	Type	Notes
`event_type`required	ft_transfer · nft_transfer · stx_transfer · stx_mint · stx_burn · stx_lock · ft_mint · ft_burn · nft_mint · nft_burn · print
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`contract_id`	string	Contract principal, or a comma-separated set of up to 20 (e.g. `SP1.sbtc-token,SP1.sbtc-registry`). Mutually exclusive with `trait`.
`asset_identifier`	string
`sender`	string
`recipient`	string

Responses: 200400401429503

GET/v1/index/ft-transfersno key

Fungible token transfers

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`contract_id`	string
`sender`	string
`recipient`	string

Responses: 200400401429503

GET/v1/index/nft-transfersno key

NFT transfers

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`contract_id`	string
`asset_identifier`	string
`sender`	string
`recipient`	string

Responses: 200400401429503

GET/v1/index/contract-callsno key

Decoded contract-call transactions

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`contract_id`	string	Contract principal, or a comma-separated set of up to 20 (e.g. `SP1.sbtc-token,SP1.sbtc-registry`). Mutually exclusive with `trait`.
`function_name`	string
`sender`	string

Responses: 200400401429503

GET/v1/index/canonicalno key

Canonical block-hash map

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer

Responses: 200400401429503

GET/v1/index/blocksno key

Canonical blocks

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer

Responses: 200400401429503

GET/v1/index/blocks/{height_or_hash}no key

Block by height or hash

Parameter	Type	Notes
`height_or_hash`required	string	Path segment

Responses: 200400401

GET/v1/index/transactionsno key

Full transaction documents

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`type`	string
`sender`	string
`contract_id`	string

Responses: 200400401429503

GET/v1/index/transactions/{tx_id}no key

Transaction by tx_id

Parameter	Type	Notes
`tx_id`required	string	Path segment

Responses: 200400401

GET/v1/index/transactions/{tx_id}/proofno key

Trustless tx-inclusion proof (raw tx, Nakamoto header, merkle path)

Parameter	Type	Notes
`tx_id`required	string	Path segment

Responses: 200400401

GET/v1/index/stackingno key

PoX-4 stacking actions

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`function_name`	string
`stacker`	string
`caller`	string

Responses: 200400401429503

GET/v1/index/pox/cyclesno key

PoX-4 reward-cycle aggregates

Per-cycle rollup over pox4_calls: total stacked ustx, unique stackers/delegators, action count, block range, function breakdown. Cursor-paginated by reward_cycle descending; may carry an optional `notes` field (decoder disabled, or PoX-4 era closed at the epoch 4.0 fork).

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	integer	Reward cycle to page backward from (exclusive).

Responses: 200400401429

GET/v1/index/pox/cycles/{reward_cycle}no key

PoX-4 reward-cycle aggregate by cycle number

Parameter	Type	Notes
`reward_cycle`required	integer	Path segment

Responses: 200400404

GET/v1/index/pox5/eventsno key

PoX-5 boot-contract events (decoded)

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.

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`confirmed`	boolean
`topic`	string
`staker`	string
`signer`	string
`signer_manager`	string
`bond_index`	integer
`reward_cycle`	integer
`fields`	string

Responses: 200400401429503

GET/v1/index/sbtc/eventsno key

sBTC peg events (decoded)

Decoded sBTC peg protocol-state events Hiro declined to filter (SBA #1709): completed-deposit, withdrawal-create/accept/reject, key-rotation, update-protocol-contract.

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`confirmed`	boolean
`topic`	string
`sender`	string
`request_id`	integer
`bitcoin_txid`	string

Responses: 200400401429503

GET/v1/index/sbtc/depositsno key

sBTC peg-ins (completed deposits)

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`confirmed`	boolean
`sender`	string
`bitcoin_txid`	string

Responses: 200400401429503

GET/v1/index/sbtc/withdrawalsno key

sBTC peg-outs (lifecycle, one per request_id)

Peg-outs rolled up per request_id with derived status (REQUESTED→ACCEPTED|REJECTED) and the committed BTC sweep_txid. Never immutably cached (status mutates as later events land).

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`confirmed`	boolean
`status`	string
`sender`	string
`request_id`	integer
`settlement_confirmed`	boolean

Responses: 200400401429503

GET/v1/index/sbtc/withdrawals/{request_id}no key

sBTC peg-out lifecycle by request_id

Parameter	Type	Notes
`request_id`required	integer	Path segment

Responses: 200400401

GET/v1/index/sbtc/deposits/{bitcoin_txid}no key

sBTC peg-in by Bitcoin txid

Parameter	Type	Notes
`bitcoin_txid`required	string	Path segment

Responses: 200400401

GET/v1/index/sbtc/summaryno key

sBTC peg summary scoreboard

One scalar aggregate over the whole bridge: lifecycle counts, net peg flow, locked sats, and circulating sBTC supply (mints − burns). All-time canonical totals; no params.

Responses: 200400401

GET/v1/index/mempoolno key

Pending (unconfirmed) transactions

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`sender`	string
`type`	string
`function_name`	string

Responses: 200400401429503

GET/v1/index/mempool/{tx_id}no key

Pending transaction by tx_id

Parameter	Type	Notes
`tx_id`required	string	Path segment

Responses: 200400401

GET/v1/index/contracts/{contract_id}/print-schemano key

Empirical per-topic print payload schemas for a contract

Parameter	Type	Notes
`contract_id`required	string	Path segment

Responses: 200400401

streams

Raw event firehose, chain tip, and reorg history

GET/v1/streamsno key

Streams discovery

Responses: 200400401

GET/v1/streams/eventsno key

Raw event firehose

Parameter	Type	Notes
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`from_cursor`	string
`from_height`	integer
`to_height`	integer
`types`	string
`contract_id`	string

Responses: 200400401429503

GET/v1/streams/events/streamno key

SSE tail of the raw event firehose (same filters as /events)

Parameter	Type	Notes
`cursor`	string
`from_cursor`	string
`from_height`	integer
`types`	string
`contract_id`	string

Responses: 200400401

GET/v1/streams/reorgsno key

Chain reorg history

Parameter	Type	Notes
`since`	string
`limit`	integer	Page size; capped at 1000.

Responses: 200400401

GET/v1/streams/canonical/{height}no key

Canonical block by height

Parameter	Type	Notes
`height`required	integer	Path segment

Responses: 200400401

GET/v1/streams/tipno key

Current chain tip

Responses: 200400401

subgraphs

Reads over deployed subgraphs — rows, counts, aggregates, generated schema and docs

GET/v1/subgraphsno key

List the subgraphs this instance serves

Responses: 200400401

GET/v1/subgraphs/{name}no key

Subgraph metadata: tables, columns, sync tip, doc links

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400401

GET/v1/subgraphs/{name}/openapi.jsonno key

Generated OpenAPI spec for one subgraph

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400401

GET/v1/subgraphs/{name}/schema.jsonno key

Generated agent schema for one subgraph

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400401

GET/v1/subgraphs/{name}/docs.mdno key

Generated markdown docs for one subgraph

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400401

GET/v1/subgraphs/{name}/{table}no key

Rows, cursor-paginated by _id, or by _sort/_order ({ rows, next_cursor, tip }). Column filters via col.op=value, _limit, _fields.

Parameter	Type	Notes
`name`required	string	Path segment
`table`required	string	Path segment
`_limit`	integer	Page size, 1–1000. Non-integers, 0, negatives, and values above 1000 are rejected (400), not clamped.
`cursor`	string	Opaque; pass back the previous page's next_cursor verbatim. Its shape depends on whether _sort was used to fetch that page — do not hand-construct one, and don't replay a cursor from one _sort/_order under a different _sort/_order (400).
`_sort`	string	Single column to sort by (no comma list — composite keyset pagination pairs it with the _id tiebreaker, which only works for one column). jsonb columns are rejected (no meaningful ordering). Omit to keep the default _id-only ordering.
`_order`	string	"asc" or "desc" — direction of the _id scan, or of the _sort column when _sort is present (any other value is rejected).
`_fields`	string

Responses: 200400401404429

GET/v1/subgraphs/{name}/{table}/countno key

Count rows matching filters

Parameter	Type	Notes
`name`required	string	Path segment
`table`required	string	Path segment

Responses: 200400401

GET/v1/subgraphs/{name}/{table}/aggregateno key

Scalar aggregates (_count/_countDistinct/_sum/_min/_max) over filtered rows

Parameter	Type	Notes
`name`required	string	Path segment
`table`required	string	Path segment

Responses: 200400401

GET/v1/subgraphs/{name}/{table}/streamno key

SSE tail of new rows (?since=<block> to replay)

Parameter	Type	Notes
`name`required	string	Path segment
`table`required	string	Path segment

Responses: 200400401

deployments

Deploy, reindex, backfill, stop, and delete subgraphs on this instance (write plane, `/api`)

GET/api/subgraphsbearer

List deployed subgraphs with status, sync lag, and row counts

Responses: 200401

POST/api/subgraphsbearer

Deploy or redeploy a subgraph

Takes bundled handler code (see `/api/subgraphs/bundle`) plus the schema and sources extracted from it. Redeploying the same name updates in place; the response `action` says what happened (`created`, `unchanged`, `handler_updated`, `updated`, `reindexed`). `dryRun` validates without writing.

Body field	Type	Notes
`name`required	string	Lowercase alphanumeric and hyphens.
`sources`required	object	At least one event source, keyed by name. Extracted from the handler module.
`schema`required	object	Table definitions.
`handlerCode`required	string	Bundled handler module, 1 MB max.
`startBlock`	integer	First block to index. Rejected (400 `START_BLOCK_PAST_TIP`) when it is past the chain tip.
`version`	string
`description`	string
`sourceCode`	string	Unbundled source, kept for `sl subgraph source`.
`dryRun`	boolean

Responses: 200400401415

POST/api/subgraphs/bundlebearer

Bundle subgraph source into deployable handler code

Compiles a subgraph module and returns `{ name, sources, schema, handlerCode }` ready to POST to `/api/subgraphs`. Deploys nothing.

Body field	Type	Notes
`code`required	string	Subgraph module source.

Responses: 200400401413415

GET/api/subgraphs/{name}bearer

Deployed subgraph detail: definition, status, operations

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200401404

DELETE/api/subgraphs/{name}bearer

Delete a subgraph and drop its schema

Cancels any running operation, waits for the processor to release it, then drops the Postgres schema and the registry row. Irreversible.

Parameter	Type	Notes
`name`required	string	Path segment
`force`	boolean	Proceed even when an active operation has not cleared.

Responses: 200400401404415

POST/api/subgraphs/{name}/reindexbearer

Queue a full reindex (drops and rebuilds the schema)

Always rebuilds the whole subgraph from its start block — a `fromBlock`/`toBlock` body is rejected with 400 `REINDEX_RANGE_NOT_SUPPORTED` rather than silently destroying everything outside the range; use `backfill` for a range. Returns an `operationId` to poll on `/api/subgraphs/{name}/operations`.

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400401404409415

POST/api/subgraphs/{name}/backfillbearer

Queue a non-destructive backfill over a block range

Re-runs handlers over `[fromBlock, toBlock]` without dropping data. Refused with 422 when the handlers apply deltas (`ctx.increment`/`patchOrInsert`/`update`), which would double-count on blocks already processed.

Parameter	Type	Notes
`name`required	string	Path segment

Body field	Type	Notes
`fromBlock`required	integer
`toBlock`required	integer

Responses: 200400401404409415422

POST/api/subgraphs/{name}/stopbearer

Request cancellation of the running reindex or backfill

Body-less. Marks the active operation `cancel_requested`; the processor releases it at its next checkpoint.

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400401404415

GET/api/subgraphs/{name}/operationsbearer

Reindex/backfill history with queue position and progress

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200401404

GET/api/subgraphs/{name}/operations/{operation_id}bearer

One operation by id (poll a queued reindex or backfill)

Parameter	Type	Notes
`name`required	string	Path segment
`operation_id`required	string	Path segment

Responses: 200401404

GET/api/subgraphs/{name}/gapsbearer

Block ranges this subgraph has not processed

Parameter	Type	Notes
`name`required	string	Path segment
`_limit`	integer	Page size, 1–1000.
`_offset`	integer
`resolved`	string	"true" for resolved gaps, "all" for both; unresolved only by default.

Responses: 200401404

subscriptions

Webhook subscriptions: create, update, pause, replay, and inspect deliveries (write plane, `/api`)

GET/api/subscriptionsbearer

List webhook subscriptions

Parameter	Type	Notes
`_limit`	integer	Page size, 1–200 (default 50).
`_offset`	integer

Responses: 200401

POST/api/subscriptionsbearer

Create a webhook subscription

Two mutually exclusive modes: a subgraph subscription (`subgraphName` + `tableName`, optional column `filter`) or a chain subscription (`triggers`). Responds 201 with the signing secret — the only time it is returned in full.

Body field	Type	Notes
`name`required	string
`url`required	string	HTTPS delivery target.
`subgraphName`	string
`tableName`	string
`filter`	object	Column filter on the subgraph table.
`triggers`	array	Chain-event triggers; mutually exclusive with `subgraphName`/`tableName`.
`format`	string
`runtime`	stringnull
`authConfig`	object
`maxRetries`	integer
`timeoutMs`	integer
`concurrency`	integer

Responses: 200201400401409415

GET/api/subscriptions/{id}bearer

Subscription detail

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200401404

PATCH/api/subscriptions/{id}bearer

Update a subscription

Parameter	Type	Notes
`id`required	string	Path segment

Body field	Type	Notes
`name`	string
`url`	string
`filter`	object
`format`	string
`runtime`	stringnull
`authConfig`	object
`maxRetries`	integer
`timeoutMs`	integer
`concurrency`	integer

Responses: 200400401404415

DELETE/api/subscriptions/{id}bearer

Delete a subscription

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200400401404415

POST/api/subscriptions/{id}/pausebearer

Pause delivery (body-less)

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200400401404415

POST/api/subscriptions/{id}/resumebearer

Resume delivery (body-less)

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200400401404415

POST/api/subscriptions/{id}/rotate-secretbearer

Rotate the signing secret (body-less)

Returns the new secret once. Deliveries signed with the old secret stop verifying immediately.

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200400401404415

POST/api/subscriptions/{id}/testbearer

Send a one-off test delivery (body-less)

Builds a sample event in the subscription's format, posts it to the configured URL through the SSRF guard, and records it under deliveries.

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200400401404415

GET/api/subscriptions/{id}/deliveriesbearer

Last 100 delivery attempts, newest first

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200401404

GET/api/subscriptions/{id}/deadbearer

Dead-letter queue: events that exhausted their retries

Parameter	Type	Notes
`id`required	string	Path segment

Responses: 200401404

POST/api/subscriptions/{id}/dead/{outbox_id}/requeuebearer

Requeue one dead event at live priority (body-less)

Parameter	Type	Notes
`id`required	string	Path segment
`outbox_id`required	string	Path segment

Responses: 200400401404415

POST/api/subscriptions/{id}/replaybearer

Replay a block range through a subscription

Queues historical events for redelivery; replays drain through a 10% share of the outbox so live traffic keeps priority. 202 on accept.

Parameter	Type	Notes
`id`required	string	Path segment

Body field	Type	Notes
`fromBlock`required	integer
`toBlock`required	integer
`force`	string	Suffix that makes the replay ids unique, so an already-replayed range can be sent again.

Responses: 200202400401404415

node

Proxy to the Stacks node this instance follows

GET/api/node/contracts/{contract_id}/abibearer

Clarity contract ABI, proxied from the local Stacks node

Responses: 200401404502

instance

What this instance is, holds, and has enabled

GET/v1/instanceno key

Local instance catalog

Instance status, local subgraphs, subscriptions, and default features. No signup or pricing.

Responses: 200400401

GET/v1/instance/featuresno key

Default feature manifest

Responses: 200400401

other

GET/v1no key

Surface discovery

Responses: 200400401

POST/v1/batchno key

Batch public reads

Up to 10 `/v1` reads in one round trip. Body: `{ requests: [{ path, params? }] }`. Each item keeps its own auth semantics; a forwarded credential applies to every item; results return in order with per-item status. Read-only, so the `/api` JSON content-type guard does not apply.

Responses: 200400401

GET/v1/openapi.jsonno key

This document

Responses: 200400401

Sunbelt Computer Software

PL/B Language Development and Support

API reference

index

streams

subgraphs

deployments

subscriptions

node

instance

other