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 https://api.secondlayer.tools · spec version 1.0.0

index

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

GET/v1/indexbearer

Index discovery

Responses: 200400

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: 200400

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: 200400

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/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: 200400

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: 200400

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: 200400

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

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: 200400

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: 200400

streams

Raw firehose, bearer

GET/v1/streamsbearer

Streams discovery

Responses: 200400

GET/v1/streams/eventsbearer

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/reorgsbearer

Chain reorg history

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

Responses: 200400

GET/v1/streams/canonical/{height}bearer

Canonical block by height

Parameter	Type	Notes
`height`required	integer	Path segment

Responses: 200400

GET/v1/streams/tipbearer

Current chain tip

Responses: 200400

subgraphs

Deployed subgraph reads — public anon, private bearer

GET/v1/subgraphsbearer

List readable subgraphs (public + your own with a bearer key)

Responses: 200400

GET/v1/subgraphs/{name}bearer

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

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400

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

Generated OpenAPI spec for one subgraph

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400

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

Generated agent schema for one subgraph

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400

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

Generated markdown docs for one subgraph

Parameter	Type	Notes
`name`required	string	Path segment

Responses: 200400

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

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

Parameter	Type	Notes
`name`required	string	Path segment
`table`required	string	Path segment
`limit`	integer	Page size; capped at 1000.
`cursor`	string
`_order`	string
`_fields`	string

Responses: 200400401404429

GET/v1/subgraphs/{name}/{table}/countbearer

Count rows matching filters

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

Responses: 200400

GET/v1/subgraphs/{name}/{table}/aggregatebearer

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

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

Responses: 200400

GET/v1/subgraphs/{name}/{table}/streambearer

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

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

Responses: 200400

other

GET/v1bearer

Surface discovery

Responses: 200400

GET/v1/x402/supportedbearer

x402 pay-per-call capability advertisement

Scheme, network (CAIP-2), priced surfaces, accepted assets, free-quota/session metadata, and the per-call USD floor for the pay-per-call rail. Public, no auth.

POST/v1/subgraphs/deploy-paidbearer

x402-paid subgraph deploy (actual path: POST /v1/subgraphs)

Accountless deploy: pay the subgraph-deploy quote via x402 and the subgraph is owned by the paying wallet principal — live indexing from deploy (forward-only), expires in 7 days unless renewed (POST /v1/subgraphs/{name}/renew, subgraph-renew quote) or the account is claimed. Managed plane only.

POST/v1/batchbearer

Batch public reads

Up to 10 public /v1 reads in one round trip. Body: { requests: [{ path, params? }] }. Each item keeps its own auth/quota/pay-per-call semantics; forwarded credentials apply to every item; results return in order with per-item status.

POST/v1/x402/depositbearer

Load a prepaid x402 tab

Pay once on-chain (?usd=<amount>, $0.25–$100, confirmed tier) and receive a PAYMENT-BALANCE token; subsequent Index/Streams calls carrying it debit the tab instantly. Responses report X-BALANCE-REMAINING-USD.

GET/v1/x402/balancebearer

Read a prepaid tab

Current balance for the PAYMENT-BALANCE token presented.

GET/v1/openapi.jsonbearer

This document

Responses: 200400