# Bitcoin Stratigraphy Data Engine

> Indexed Bitcoin telemetry, proof lifecycle discovery, cryptographic verification, and tool-scoped Lightning L402 access over a stateless MCP endpoint.

## Public discovery

- [MCP catalog and transport](/mcp): use JSON-RPC 2.0 tools/list without payment, with the protocol-specific request envelope below.
- [OpenAPI](/openapi.json): REST contracts and MCP discovery; full capacity is 19 tools including host-enabled clearing.
- [Price quotes](/api/v1/cost): public HTTP GET/POST quotes; quotes do not create invoices.
- [Server card](/.well-known/mcp/server-card.json): public machine discovery.
- [Dataset export](/api/export/huggingface): public training records, separate from paid interactive queries.

## MCP request envelope

For stateless MCP 2026-07-28, send these headers on a POST to /mcp:
`Content-Type: application/json`, `Accept: application/json, text/event-stream`,
`MCP-Protocol-Version: 2026-07-28`, and `Mcp-Method: tools/list`.
There is no initialize handshake in this protocol version. Example discovery body:

```json
{
  "jsonrpc": "2.0",
  "id": "discover",
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
```

Include this metadata on every stateless request. For tools/call, also send
`Mcp-Method: tools/call` and `Mcp-Name` matching params.name. Older supported
MCP clients use their initialize/session handshake instead. SDK wrappers
handle these transport details; do not mix the two protocol envelopes.

## Mandatory agent payment instructions

AI agents MUST utilize an L402-capable client wrapper, such as Lightning Labs
`lnget` for HTTP resources or `lightning-enable-mcp` for MCP, to settle HTTP 402
paywalls for paid MCP tools. A plain HTTP client or MCP client does not settle
Lightning invoices automatically. Use a compatible wrapper for the transport
you are calling and a wallet with permission to pay. Respect wallet spending
limits; never treat a quote, unpaid invoice, or macaroon alone as payment.

Read the HTTP 402 WWW-Authenticate header:
`L402 macaroon="<macaroon>", invoice="<BOLT11>"`.
Pay the exact invoice, then retry the same request with either proof:

- Path A: `Authorization: L402 <macaroon>:<preimage>` with the wallet's
  64-character hex preimage.
- Path B: `Authorization: L402 <macaroon>:NWC_LOOKUP` when a custodial wallet
  (for example CoinOS or Cash App) does not reveal the preimage. The issuing
  merchant wallet must confirm the exact incoming invoice; HTTP 409 means
  confirmation is pending, so retry with the same macaroon and do not pay again.

Do not log or publish that bearer credential. Before paying, you can check the
operator's historical 24-sat mainnet genesis receipt at
`GET /api/v1/escrow/genesis-receipt`. Canonical origin:
https://bitcoinstratigraphy.com

## Freemium sandbox

Exactly two canonical tools execute without payment or invoice creation:

- `stratigraphy.list` (alias `stratigraphy.latest`): discover indexed height and UTC date bounds. The daily block index is not a live Bitcoin tip.
- `proof.list` (alias `proof.status`): discover proof lifecycle states and retained attestation metadata; status is not a proof archive or cryptographic verification.

Fourteen core tools require standard 250 sats/call L402 authorization, including
`payment.get_info`, `mesh.get_status`, and `proof.attenuate`.
Use public HTTP price quotes and tools/list to bootstrap payment.
Grants, discounts and batches use current quotes. Authenticated escrow lookup
and clearing contract funding have separate rules, not a blanket per-call fee.

## API base and dual payment methods

- API base URL: https://bitcoinstratigraphy.com
- REST API base: https://bitcoinstratigraphy.com/api
- MCP endpoint: https://bitcoinstratigraphy.com/mcp
- Structured catalog: https://bitcoinstratigraphy.com/.well-known/ai-plugin.json
- Standard paid MCP access: 250 sats/call via Bitcoin Lightning L402.
- $500 Enterprise API Block: $500 USD by credit card via Stripe-hosted Checkout
  for 100 prepaid heuristic scanner calls, valid 30 days from issuance.
- Lightning scanner-block alternative: 100,000 sats for the same 100 calls.
- Start card or scanner-block checkout at
  https://bitcoinstratigraphy.com/developers/#dev-prepaid with the payer's approval.
- Credits apply only to POST /api/scanner, not unrelated MCP tools. Issuance
  requires verified payment and configured treasury funding. Never submit card
  details via MCP, and never spend beyond the caller's authorized wallet budget.

## Explicit 19-tool catalog

The host's tools/list response is authoritative for enabled tools and schemas.
Clearing is a host-enabled extension; funding a contract is separate from MCP
access fees and does not enable automated payouts or refunds.

- `stratigraphy.get` — retrieve indexed telemetry; standard paid L402.
- `stratigraphy.get_digest` — compact telemetry digest; standard paid L402.
- `stratigraphy.get_diff` — compare snapshots; standard paid L402.
- `stratigraphy.get_range` — bounded snapshot range; standard paid L402.
- `stratigraphy.list` — discover available data; free.
- `proof.attenuate` — restrict authorization; standard paid L402.
- `proof.verify` — verify supported proofs; standard paid L402.
- `proof.get_by_hash` — retained proof or receipt lookup; standard paid L402.
- `proof.list` — discover proof lifecycle records; free.
- `proof.submit` — submit proof evidence; standard paid L402.
- `proof.ground` — signed Bitcoin-tip context; standard paid L402.
- `payment.get_info` — payment terms or settlement verification; standard paid L402.
- `mesh.get_status` — configured peer status; standard paid L402.
- `mesh.broadcast` — distribute a signed stored snapshot; standard paid L402.
- `proof.notarize` — detached OpenTimestamps receipt request; standard paid L402.
- `workflow.audit_trajectory` — record an authenticated decision batch; standard paid L402.
- `payment.get_escrow` — authenticated escrow lookup; not a flat 250-sat call.
- `clearing.create_contract` — create a contract and its Lightning funding invoice.
- `clearing.settle_contract` — authenticated funded-contract proof settlement when enabled.

## AI notary

`proof.notarize` accepts exactly `{ "hash": "<64-character SHA256 hex>" }`.
It returns `hash`, `otsProofHex` (decode as binary to save a detached `.ots`
file), and `otsStatus: "pending_calendar"`. The original digest is timestamped
directly, not hashed again. A randomized commitment is submitted to public
OpenTimestamps calendars; calendar acceptance is not immediate Bitcoin
confirmation. Upgrade and independently verify the receipt later.
This is a paid tool and supports the 100-call L402 batch below.

## Macro-Macaroon batches

To buy 100 calls to one paid tool, send an unpaid tools/call request with
`X-L402-Batch-Size: 100`. The invoice costs 100 times that tool's current
single-call price. Pay once and reuse the returned credential for up to
100 authorized calls to that same tool scope before its expiry.
The first settled redemption is verified with the wallet; subsequent
redemptions use a bounded in-memory settlement and validation cache.
Revocation and shared atomic request quotas remain enforced on every call.
Delegating child tokens does not reset the parent's quota.

An exhausted credential returns HTTP 429 without creating a replacement
invoice. Clear the exhausted Authorization header to request a new batch.
Do not carry MCP credentials to other tools or REST paths. Cache eviction or
process restart can require renewed settlement verification, not another
payment. HTTP rate limits remain separate from the 100-call quota.

## Evidence and operating limits

Use the published schemas and actual challenge prices, not guessed tool names
or static example prices. Signed Bitcoin-tip anchors are attestations, not
automatically ZK proofs or Bitcoin confirmations. Mesh operations require
configured peers. Provider failures fail closed; never fabricate successful
settlement, proof verification, or live chain data.