# 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 on self-host today. 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)
- All docs in one file: https://secondlayer.tools/llms-full.txt

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

## Products
- Archive: https://secondlayer.tools/p/archive. Signed history. Check your copy free.
- Streams: https://secondlayer.tools/p/streams. Every event. You hold the cursor.
- Index: https://secondlayer.tools/p/index. Typed rows from genesis.
- Subgraphs: https://secondlayer.tools/p/subgraphs. Your contract, as a table.
- Webhooks: https://secondlayer.tools/p/webhooks. Your server, told first.
- Verify: https://secondlayer.tools/verify. Check a block or transaction yourself.
- Pricing: https://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; the next request
  starts it again.
- 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 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.

## Docs
- https://secondlayer.tools/docs
- Any page as markdown: append .md — https://secondlayer.tools/docs/streams.md
- SDK agent notes ship in the package: node_modules/@secondlayer/sdk/AGENTS.md
- Verify: https://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

## Pages
- [Introduction](https://secondlayer.tools/docs/introduction.md) (Start)
- [Keys and billing](https://secondlayer.tools/docs/authentication.md) (Start)
- [Self-host](https://secondlayer.tools/docs/self-host.md) (Start)
- [Verify](https://secondlayer.tools/docs/verification.md) (Start)
- [Archive](https://secondlayer.tools/docs/archive.md) (Products)
- [Streams](https://secondlayer.tools/docs/streams.md) (Products)
- [Index](https://secondlayer.tools/docs/index.md) (Products)
- [Subgraphs](https://secondlayer.tools/docs/subgraphs.md) (Products)
- [Webhooks](https://secondlayer.tools/docs/webhooks.md) (Products)
- [CLI](https://secondlayer.tools/docs/cli.md) (Tools)
- [SDK](https://secondlayer.tools/docs/sdk.md) (Tools)
- [Sinks](https://secondlayer.tools/docs/sinks.md) (Tools)
- [Deploy your app](https://secondlayer.tools/docs/deploy.md) (Tools)
- [MCP and skills](https://secondlayer.tools/docs/mcp.md) (Tools)
- [Index API](https://secondlayer.tools/docs/api/index.md) (API reference)
- [Streams API](https://secondlayer.tools/docs/api/streams.md) (API reference)
- [Proofs API](https://secondlayer.tools/docs/api/proofs.md) (API reference)
- [Subgraphs API](https://secondlayer.tools/docs/api/subgraphs.md) (API reference)
- [Webhooks API](https://secondlayer.tools/docs/api/webhooks.md) (API reference)
- [Instance API](https://secondlayer.tools/docs/api/instance.md) (API reference)
- [Overview](https://secondlayer.tools/docs/sdk-reference.md) (SDK reference)
- [Client](https://secondlayer.tools/docs/sdk-reference/client.md) (SDK reference)
- [sl.streams](https://secondlayer.tools/docs/sdk-reference/streams.md) (SDK reference)
- [sl.index](https://secondlayer.tools/docs/sdk-reference/index.md) (SDK reference)
- [sl.subgraphs](https://secondlayer.tools/docs/sdk-reference/subgraphs.md) (SDK reference)
- [sl.webhooks](https://secondlayer.tools/docs/sdk-reference/webhooks.md) (SDK reference)
- [sl.archive](https://secondlayer.tools/docs/sdk-reference/archive.md) (SDK reference)
- [sl.contracts](https://secondlayer.tools/docs/sdk-reference/contracts.md) (SDK reference)
- [sl.instance](https://secondlayer.tools/docs/sdk-reference/instance.md) (SDK reference)
- [Helpers](https://secondlayer.tools/docs/sdk-reference/helpers.md) (SDK reference)
- [Errors](https://secondlayer.tools/docs/sdk-reference/errors.md) (SDK reference)
- [Subgraphs package](https://secondlayer.tools/docs/subgraphs-reference.md) (SDK reference)
- [Verify package](https://secondlayer.tools/docs/verify-reference.md) (SDK reference)
- [Filters package](https://secondlayer.tools/docs/filters-reference.md) (SDK reference)
- [REST conventions](https://secondlayer.tools/docs/rest-api.md) (Reference)
- [API reference](https://secondlayer.tools/docs/api-reference.md) (Reference)
- [Changelog](https://secondlayer.tools/docs/changelog.md) (Reference)