# Secondlayer: instant data for apps on Bitcoin

> Index Stacks and Runes from their first block, stream new ones as they
> land, and prove Stacks data back to Bitcoin. Bitcoin Runes hosted and self-host. Hosted on api.secondlayer.tools (Index, Streams, Subgraphs, Webhooks),
> or self-hosted: Postgres plus one container beside your node.

## Shortest path
- Agent skill: bunx skills add ryanwaits/secondlayer --skill secondlayer -y
- MCP: bunx @secondlayer/mcp (set SECONDLAYER_API_KEY)
- Every endpoint as a markdown URL (~14 KB): https://www.secondlayer.tools/llms-api.txt
- All guides in one file (~197 KB): https://www.secondlayer.tools/llms-full.txt

## Start here
- Hosted: get an account key (sk-sl_*) at https://www.secondlayer.tools/signin and set
  SECONDLAYER_API_KEY. The SDK, MCP and CLI then use api.secondlayer.tools.
- Self-host: bun add -g @secondlayer/cli && secondlayer init --network mainnet
- Local API: http://127.0.0.1:3800  (default with no account key)
- Hosted OpenAPI: https://api.secondlayer.tools/v1/openapi.json
- OpenAPI on your instance: http://127.0.0.1:3800/v1/openapi.json
- Docs: https://www.secondlayer.tools/docs

## Products
- Archive: https://www.secondlayer.tools/p/archive. Signed history. Check your copy free.
- Streams: https://www.secondlayer.tools/p/streams. Every event. You hold the cursor.
- Index: https://www.secondlayer.tools/p/index. Typed rows from genesis.
- Subgraphs: https://www.secondlayer.tools/p/subgraphs. Your contract, as a table.
- Webhooks: https://www.secondlayer.tools/p/webhooks. Your server, told first.
- Verify: https://www.secondlayer.tools/verify. Check a block or transaction yourself.
- Pricing: https://www.secondlayer.tools/pricing. 1M rows free per month.

## Auth model
- Hosted (api.secondlayer.tools): SECONDLAYER_API_KEY (sk-sl_*). The
  secondlayer subgraphs and secondlayer webhooks commands accept the account key there.
- Self-host: INSTANCE_TOKEN from secondlayer init. Loopback reads need no key.

## Billing (hosted)
- 1M rows free per month, then $5 per 1M ($2 per 1M past $50). Block headers
  are free.
- A hosted stack (runs your subgraphs and webhooks, so webhook-only accounts
  have one too) bills memory plus storage. Webhooks only: $5/mo minimum while
  your stack runs. With subgraphs: $10/mo minimum. Webhook events are $10 per
  1M.
- With no active webhooks and no subgraphs the stack stops itself within
  minutes (never in its first 15 minutes) and bills nothing. A write starts it
  again, and so does a read with ?wake=1. Any other webhook read answers 503
  STACK_ASLEEP, and subgraph reads answer empty.
- The monthly spend cap covers every charge. At the cap, reads past the free
  rows answer 402 spend_cap_reached and the stack stops, so webhooks stop
  delivering until the next month or a raised cap.
- Reads of your own subgraph tables cost $10 per 1M after the first 100,000
  each month, whatever the page size. A stream counts once each time it sends
  new rows. Reads from the dashboard are free.
- Self-host is unmetered. Only archive restore and backfill off our R2 is metered.

## Hosted subgraphs
- Hostable sources: event filters and contract_call / contract_deploy. Anything
  else returns 422 SOURCE_NOT_HOSTABLE.
- After 3 stall or OOM deaths at one height a subgraph is marked error.
- Set startBlock so the first deploy does not backfill from genesis.
- Webhooks fire on chain events. React to subgraph rows from your Postgres or the subgraph API.

## Batch
- POST /v1/batch — up to 10 public /v1 reads in one round trip
  ({"requests":[{"path":"/v1/index/events","params":{...}}, ...]}); results
  return in order with per-item status.

## Report a problem (hosted)
- POST /v1/feedback {"intent":"one line","request_id":"req_… (optional)"}.
  kind_hint: missing_capability, bug, schema_gap, docs_mismatch, perf.
  expected: any JSON or a sentence. evidence keys: tx_id, block_height,
  contract_id, event_type, subgraph, table.

## Docs
- https://www.secondlayer.tools/docs
- Any page as markdown: append .md — https://www.secondlayer.tools/docs/streams.md
- SDK agent notes ship in the package: node_modules/@secondlayer/sdk/AGENTS.md
- Verify: https://www.secondlayer.tools/docs/verification (check a block or
  transaction yourself, @secondlayer/verify)
- Env: examples read SECONDLAYER_API_URL and SECONDLAYER_API_KEY. On your own
  box set the URL to http://127.0.0.1:3800

## Protocol data
- [Stacks PoX-5](https://www.secondlayer.tools/data/pox5): Live PoX-5 cycle totals and every signer's stacked STX, free with no key. Stakes, signers and bonds decoded through one API. Current numbers as JSON, no key: https://api.secondlayer.tools/public/data/pox
- [sBTC on Stacks](https://www.secondlayer.tools/data/sbtc): Live sBTC supply, peg flow, deposits and withdrawals, free with no key. Withdrawal lifecycles with Bitcoin settlement through one API. Current numbers as JSON, no key: https://api.secondlayer.tools/public/data/sbtc
- [Bitcoin Runes](https://www.secondlayer.tools/data/runes): Live most-minted Bitcoin runes, free with no key. Balances by address, per-rune activity and name lookup through one API. Current numbers as JSON, no key: https://api.secondlayer.tools/public/data/runes

## Pages
- [Introduction](https://www.secondlayer.tools/docs/introduction.md) (Start)
- [Keys and billing](https://www.secondlayer.tools/docs/authentication.md) (Start)
- [Self-host](https://www.secondlayer.tools/docs/self-host.md) (Start)
- [Verify](https://www.secondlayer.tools/docs/verification.md) (Start)
- [Archive](https://www.secondlayer.tools/docs/archive.md) (Products)
- [Streams](https://www.secondlayer.tools/docs/streams.md) (Products)
- [Index](https://www.secondlayer.tools/docs/index.md) (Products)
- [Subgraphs](https://www.secondlayer.tools/docs/subgraphs.md) (Products)
- [Webhooks](https://www.secondlayer.tools/docs/webhooks.md) (Products)
- [CLI](https://www.secondlayer.tools/docs/cli.md) (Tools)
- [SDK](https://www.secondlayer.tools/docs/sdk.md) (Tools)
- [Sinks](https://www.secondlayer.tools/docs/sinks.md) (Tools)
- [Deploy your app](https://www.secondlayer.tools/docs/deploy.md) (Tools)
- [MCP](https://www.secondlayer.tools/docs/mcp.md) (Tools)
- [Agent skill](https://www.secondlayer.tools/docs/skills.md) (Tools)
- [Listen for contract events](https://www.secondlayer.tools/docs/guides/listen-for-contract-events.md) (Guides)
- [FT transfers by address](https://www.secondlayer.tools/docs/guides/ft-transfers-by-address.md) (Guides)
- [Calls to a contract function](https://www.secondlayer.tools/docs/guides/contract-function-calls.md) (Guides)
- [Decode print events](https://www.secondlayer.tools/docs/guides/decode-print-events.md) (Guides)
- [NFT transfers for a collection](https://www.secondlayer.tools/docs/guides/nft-transfers-for-collection.md) (Guides)
- [Index a contract into Postgres](https://www.secondlayer.tools/docs/guides/index-contract-into-postgres.md) (Guides)
- [Handle reorgs](https://www.secondlayer.tools/docs/guides/handle-reorgs.md) (Guides)
- [Index API](https://www.secondlayer.tools/docs/api/index.md) (API reference)
- [Streams API](https://www.secondlayer.tools/docs/api/streams.md) (API reference)
- [Proofs API](https://www.secondlayer.tools/docs/api/proofs.md) (API reference)
- [Subgraphs API](https://www.secondlayer.tools/docs/api/subgraphs.md) (API reference)
- [Webhooks API](https://www.secondlayer.tools/docs/api/webhooks.md) (API reference)
- [Instance API](https://www.secondlayer.tools/docs/api/instance.md) (API reference)
- [Overview](https://www.secondlayer.tools/docs/sdk-reference.md) (SDK reference)
- [Client](https://www.secondlayer.tools/docs/sdk-reference/client.md) (SDK reference)
- [sl.streams](https://www.secondlayer.tools/docs/sdk-reference/streams.md) (SDK reference)
- [sl.index](https://www.secondlayer.tools/docs/sdk-reference/index.md) (SDK reference)
- [sl.subgraphs](https://www.secondlayer.tools/docs/sdk-reference/subgraphs.md) (SDK reference)
- [sl.webhooks](https://www.secondlayer.tools/docs/sdk-reference/webhooks.md) (SDK reference)
- [sl.archive](https://www.secondlayer.tools/docs/sdk-reference/archive.md) (SDK reference)
- [sl.contracts](https://www.secondlayer.tools/docs/sdk-reference/contracts.md) (SDK reference)
- [sl.instance](https://www.secondlayer.tools/docs/sdk-reference/instance.md) (SDK reference)
- [Helpers](https://www.secondlayer.tools/docs/sdk-reference/helpers.md) (SDK reference)
- [Errors](https://www.secondlayer.tools/docs/sdk-reference/errors.md) (SDK reference)
- [Subgraphs package](https://www.secondlayer.tools/docs/subgraphs-reference.md) (SDK reference)
- [Verify package](https://www.secondlayer.tools/docs/verify-reference.md) (SDK reference)
- [Filters package](https://www.secondlayer.tools/docs/filters-reference.md) (SDK reference)
- [REST conventions](https://www.secondlayer.tools/docs/rest-api.md) (Reference)
- [API reference](https://www.secondlayer.tools/docs/api-reference.md) (Reference)
- [Changelog](https://www.secondlayer.tools/docs/changelog.md) (Reference)