# Bitcoin Stratigraphy - Complete MCP Tool Reference

> Static reference for the fourteen canonical tools returned by `tools/list` at https://bitcoin-stratigraphy-dashboard.replit.app/mcp. JSON Schemas below include every input property, type, required field, enum, range, pattern, and additional-properties rule. Human-readable examples and property descriptions are condensed; `tools/list` is authoritative for the live metadata and any later schema changes.

## Developer portal, Python SDK and integration cookbooks

- [Interactive Developer Portal & Live Tool Explorer](https://bitcoin-stratigraphy-dashboard.replit.app/docs): inspect live schemas and manually test the 14 canonical MCP tools across 4 namespaces.
- [Integration suite](https://bitcoin-stratigraphy-dashboard.replit.app/cookbooks): setup guide and CrewAI, LangChain and AutoGen examples.
- [Python SDK/client source](https://bitcoin-stratigraphy-dashboard.replit.app/cookbooks/l402_client.py): HTTPX-based remote JSON-RPC client with bounded, explicit L402 Lightning payment callbacks. It never pays automatically.
- [MCP discovery manifest](https://bitcoin-stratigraphy-dashboard.replit.app/.well-known/mcp.json): direct documentation and SDK links.

For free batch pricing, POST `{"tools":["stratigraphy.get_latest","proof.verify_zk_proof"]}` as JSON to `https://bitcoin-stratigraphy-dashboard.replit.app/api/v1/cost`. The response includes `perToolSats`, itemized `items`, `total_sats` and `l402` invoice-generation details. These two descriptive pricing selectors resolve to canonical `stratigraphy.get` and `proof.verify` only for quoting; they are not new callable MCP tools. No invoice is created or paid by a quote, and the aggregate total is not a multi-tool credential. Each paid tools/call obtains its own path-bound, single-use L402 challenge. Existing GET tier/asset discovery remains available.

## Public dataset export for fine-tuning

`GET /api/export/huggingface` requires no L402 authorization. It returns newline-delimited JSON (`application/x-ndjson`) by default, one Hugging Face instruction-tuning row per line. Use `?format=json` for a JSON array and `?limit=N` for the most recent N rows (1–500, default 500), returned oldest-to-newest. Each row has `height`, UTC `timestamp`, `target_multiplier`, `record_hash`, `zk_proof_status`, `instruction`, a formatted `prompt`, `response`, and the validated source fields needed to reproduce the fingerprint. `GET /.well-known/llm-schema.json` publishes the parameter definitions, JSON Schema, domain constraints, and hash/verification protocol for crawlers.

Indexed heights and dates are deterministic daily labels, not observed per-record Bitcoin blocks. `target_multiplier` is a title-derived target-distance proxy, not measured energy. `record_hash` is SHA-256 over the listed source fields; the historical dataset has no per-record ZK proofs, so `zk_proof_status` is `unavailable`. This public export does not change the L402 requirements of interactive MCP tools.

## Protocol and payment

Use Streamable HTTP: POST JSON-RPC 2.0 to `https://bitcoin-stratigraphy-dashboard.replit.app/mcp` with `Content-Type: application/json`, `Accept: application/json, text/event-stream`, and `MCP-Protocol-Version: 2025-11-25`. List tools using `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`; call one using `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mesh.get_status","arguments":{}}}`. `mesh.get_status`, `payment.get_info`, `stratigraphy.list`, and `tools/list` are free. Paid calls return an HTTP 402 L402 invoice challenge before they can return their tool result. Prices and supported assets are endpoint- and policy-dependent: confirm MCP terms with `payment.get_info`, REST prices/assets with GET `https://bitcoin-stratigraphy-dashboard.replit.app/api/v1/cost`, and use the actual challenge. Never send a wallet secret in an MCP request.

The L402 router supports `btc-lightning`, `l-btc`, and `taproot-assets` where
enabled. MCP uses Lightning L402; Base USDC x402 is conditional and applies
only to MCP when explicitly reported available. Do not infer Base USDC support
for REST. The paid REST route `GET /api/v1/stratigraphy/stream` is a separate
Server-Sent Events (SSE) transport with a 30-second refresh interval, not an
MCP transport. It uses L402 assets reported by `/api/v1/cost`; Base USDC is not
promised for this stream.

The seven capability areas are macaroon attenuation (including TTL/request
limits), multi-asset payment routing, Groth16/Poseidon BN254 telemetry and
drift verification plus separate OTS receipt verification, off-chain Schnorr
Bitcoin-tip context/CID receipts, pinned reciprocal Nostr NIP-01/78 peer
broadcast and quorum, indexed stratigraphy diffs/digests for efficient context,
and the separate paid SSE stream. Nostr quorum is not source truth. Indexed
historical daily heights are not live-tip readings or native per-record
Bitcoin block provenance.

Input schemas (JSON Schema objects; descriptive fields and sample values are shortened, but validation constraints match the published tool definitions):

## 1. stratigraphy.get — 250 sats

Retrieve indexed telemetry by recent-day count, one date, indexed block height, or a bounded/open date or block range. Selector modes cannot be combined; range upper bounds must not precede lower bounds.

```json
{"type":"object","additionalProperties":false,"properties":{"days":{"type":"integer","minimum":1,"maximum":365},"date":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","minLength":1},"blockHeight":{"type":"integer","minimum":0},"metrics":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["target_multiplier","difficulty_epoch_progress","thermodynamic_signal"]}},"startDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","minLength":1},"endDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","minLength":1},"startBlock":{"type":"integer","minimum":0},"endBlock":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10}},"required":[]}
```

## 2. stratigraphy.get_digest — 250 sats

Return a compressed summary for an indexed block height, ISO date, or inclusive date range such as `2026-09-01..2026-09-09` (at most 100 days). The default `latest` selects the latest *indexed dataset entry*, not the live Bitcoin tip. `minimal` returns `[height,date,target_multiplier,record_hash]`; `kv` returns `{h,ts,tm,hash}`; `compact` returns `HEIGHT:...|DATE:...|TM:...|HASH:...`. A range returns an array of these results. The hash is SHA-256 of the validated source record fields, not a Bitcoin block hash. MCP `structuredContent.proofAvailable` is `false` because the indexed dataset has no per-record ZK proof; the text content retains the exact requested compact shape.

```json
{"type":"object","additionalProperties":false,"properties":{"target":{"type":"string","pattern":"^(?:latest|(?:0|[1-9]\\d*)|\\d{4}-\\d{2}-\\d{2}(?:\\.\\.\\d{4}-\\d{2}-\\d{2})?)$","default":"latest"},"format":{"type":"string","enum":["compact","minimal","kv"],"default":"compact"}},"required":[]}
```

## 3. stratigraphy.get_diff — 250 sats

Compare two indexed daily strata by height or ISO date. `fromTarget` is required; `toTarget` defaults to the latest indexed dataset entry, not the live Bitcoin tip. Returns `from` and `to` with `height`, `date`, and `target_multiplier`, and `delta` with signed `heightDelta`, `multiplierDelta`, `percentageChange` (a percentage string rounded to two decimals), and `timeSpanDays`. Height is a deterministic daily dataset index and the stored multiplier is not a direct measurement of energy or difficulty. Reversed targets yield negative height/day differences. A zero starting multiplier cannot produce a percentage change; unavailable targets are rejected before an L402 challenge.

```json
{"type":"object","additionalProperties":false,"properties":{"fromTarget":{"type":"string","pattern":"^(?:(?:0|[1-9]\\d*)|\\d{4}-\\d{2}-\\d{2})$"},"toTarget":{"type":"string","pattern":"^(?:latest|(?:0|[1-9]\\d*)|\\d{4}-\\d{2}-\\d{2})$","default":"latest"}},"required":["fromTarget"]}
```

## 4. stratigraphy.get_range — 250 sats

Retrieve ascending daily-index entries between inclusive `startTarget` and `endTarget` bounds, identified by exact indexed height or ISO UTC date. Mixed height/date bounds are allowed; `endTarget` defaults to the latest indexed entry, not the live tip. Reversed or unavailable targets are rejected before an invoice. `limit` defaults to 50 and caps at 100; results are truncated to the first matching records. Each item uses the same compact, minimal, or kv source-record digest format as `stratigraphy.get_digest` (fingerprint, not block hash or proof). One L402 challenge pays for the batch, not for each record.

```json
{"type":"object","additionalProperties":false,"properties":{"startTarget":{"type":"string","pattern":"^(?:(?:0|[1-9]\\d*)|\\d{4}-\\d{2}-\\d{2})$"},"endTarget":{"type":"string","pattern":"^(?:latest|(?:0|[1-9]\\d*)|\\d{4}-\\d{2}-\\d{2})$","default":"latest"},"limit":{"type":"number","minimum":1,"maximum":100,"default":50},"format":{"type":"string","enum":["compact","minimal","kv"],"default":"compact"}},"required":["startTarget"]}
```

## 5. stratigraphy.list — free

List available indexed stratigraphy catalog entries.

```json
{"type":"object","additionalProperties":false,"properties":{},"required":[]}
```

## 6. proof.attenuate — no new invoice

Derive a narrower child from an authentic, unexpired subscription macaroon. The supplied caveats accept `time_before = YYYY-MM-DD` (inclusive UTC calendar date), `time_before = ISO-UTC-timestamp`, `max_target = indexed-height`, `allowed_tools = tool.name,tool.name`, `allowed_path = /path`, and `max_requests = positive-integer`. An optional `ttlSeconds` appends an expiration caveat. The response lists canonical `key=value` caveats and a new encoded macaroon. Parent signature, expiry, and revocation are checked; a forged, expired, or revoked parent cannot produce a child. This call creates no invoice but **does not pay for the child**: using it still requires the parent's valid payment preimage and all inherited restrictions. Existing tool-scoped single-use L402 macaroons cannot be widened to other tools by delegation. Target bounds are enforced on indexed MCP telemetry selectors; a target-bound token is denied on unrelated tools and REST routes rather than silently ignoring the bound. Similarly, tool-restricted tokens are denied on REST routes.

```json
{"type":"object","additionalProperties":false,"properties":{"macaroon":{"type":"string","minLength":1,"maxLength":8192},"caveats":{"type":"array","maxItems":16,"items":{"type":"string","minLength":1,"maxLength":256}},"ttlSeconds":{"type":"number","minimum":1,"maximum":2592000}},"required":["macaroon","caveats"]}
```

## 7. proof.verify — 250 sats

Perform offline/stateless proof verification. The telemetry path verifies an encoded Groth16/Poseidon BN254 proof against committed public inputs and the supplied telemetry snapshot; the separate drift circuit is not described by the telemetry schema below. A distinct OTS mode verifies a complete OpenTimestamps receipt and Bitcoin attestation; neither proof-verification mode creates an off-chain Bitcoin-tip context/CID receipt (use `proof.ground`) or submits a Bitcoin transaction. Verification is distinct from attestation submission. The output requires `valid` (boolean), `verifiedAt` (ISO 8601 timestamp), and `computationTimeMs` (non-negative number).

```json
{"type":"object","additionalProperties":false,"properties":{"proof":{"type":"string","minLength":1},"publicInputs":{"type":"object","additionalProperties":false,"properties":{"blockHeight":{"type":"integer","minimum":0},"snapshotDigest":{"type":"string","minLength":1},"thermodynamicHash":{"type":"string","minLength":1},"timestamp":{"type":"integer","minimum":0},"valuationSat":{"type":"integer","minimum":0}},"required":["blockHeight","snapshotDigest","thermodynamicHash","timestamp","valuationSat"]},"verificationKeyId":{"type":"string","minLength":1},"data":{"type":["object","array"]}},"required":["proof","publicInputs","verificationKeyId","data"]}
```

## 8. proof.get_by_hash — 250 sats

Fetch a recorded ZK proof or receipt by hash fingerprint/CID. Do NOT use to generate new proofs or anchors. Provide either `hash` or `jobId`: `hash` accepts a proof/receipt SHA-256 fingerprint (`0x` optional), exact IPFS CID, decimal snapshot digest, UUID job ID, or an agent grounding receipt's `contextHash`; `jobId` accepts the UUID returned by `proof.submit`. Results use `kind` values `zk-proof`, `dataset-receipt`, `context-receipt`, or `zk-proof-status`. Every result has `kind`, `hash`, `status`, and `timestamp`; optional fields are `jobId`, `attestationCount`, `meshQuorum`, and `proofPayload`. A status-only result omits `proofPayload` unless a payload is actually retained—status history is never fabricated into a proof. A missing or evicted record returns HTTP 404 before an invoice. The index is bounded process memory, not a permanent archive.

```json
{"type":"object","additionalProperties":false,"properties":{"hash":{"type":"string","pattern":"^(?:(?:0x)?[0-9a-fA-F]{64}|Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{20,}|\\d{1,77}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"jobId":{"type":"string","format":"uuid"}},"required":[],"oneOf":[{"required":["hash"]},{"required":["jobId"]}]}
```

## 9. proof.list — 10 sats

List the bounded process-memory attestation index with optional pagination and status filtering; it is not a durable archive.

```json
{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"offset":{"type":"integer","minimum":0,"maximum":1000,"default":0},"status":{"type":"string","enum":["verified","cached","pending","invalid"]}},"required":[]}
```

## 10. proof.submit — 250 sats

Submit new ZK proof instances to process memory. Do NOT use to verify existing proofs (use `proof.verify`). Submit Groth16 coordinates in camelCase (`piA`, `piB`, `piC`) and five public signals, in order: block height, thermodynamic hash, timestamp, valuation in sats, and snapshot digest. The result requires `proofHash`, UUID `jobId`, `status`, `submittedAt`, and `attestationStatus`; `jobId` is indexed for lookup with `proof.get_by_hash`.

```json
{"type":"object","additionalProperties":false,"properties":{"proof":{"type":"object","additionalProperties":false,"properties":{"piA":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","pattern":"^\\d+$"}},"piB":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"string","pattern":"^\\d+$"}}},"piC":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string","pattern":"^\\d+$"}}},"required":["piA","piB","piC"]},"publicSignals":{"type":"array","minItems":5,"maxItems":5,"items":{"type":"string","pattern":"^\\d+$"}},"snapshotDigest":{"type":"string","pattern":"^(?:\\d+|Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{20,})$"}},"required":["proof","publicSignals"]}
```

## 11. proof.ground — 250 sats

Issue an off-chain Schnorr-signed receipt binding agent context or a dataset CID to an observed Bitcoin tip. This is not a Bitcoin transaction or on-chain anchor. Do NOT use for stateless proof verification (use `proof.verify`) or querying existing hashes (use `proof.get_by_hash`). The input accepts either agent context (`contextHash`, `agentId`, optional `metadata`) or a dataset identifier (`cid`, optional `nostrEventId` and `context`). The output nests the result under `receipt`. For CID input, `receipt` is the original dataset wrapper with `receiptHash`, `blockTip`, `blockHash`, `ipfsCid`, `attestation: {proofPayload, verified: true}`, and `timestamp`; parse the original signed dataset payload with `JSON.parse(receipt.attestation.proofPayload)`. Context grounding receipts are also indexed under their `contextHash` for `proof.get_by_hash`. These receipts are not Groth16 proofs or proof of work. Context metadata must fit the server's 16 KiB serialized limit.

```json
{"type":"object","oneOf":[{"type":"object","additionalProperties":false,"properties":{"contextHash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$","minLength":64,"maxLength":64},"agentId":{"type":"string","minLength":1,"maxLength":256},"metadata":{"type":"object","additionalProperties":true}},"required":["contextHash","agentId"]},{"type":"object","additionalProperties":false,"properties":{"cid":{"type":"string","pattern":"^(?:Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{20,}|(?:0x)?[0-9a-fA-F]{64})$","maxLength":256},"nostrEventId":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"context":{"type":"object","additionalProperties":true}},"required":["cid"]}]}
```

## 12. payment.get_info — free

Return the standard 250-sat amount, actual per-tool prices (0 for free tools and 10 for `proof.list`; `stratigraphy.list` is free and `proof.get_by_hash` is 250 sats), 3,600-second Lightning L402 invoice expiry, HTTP 402 challenge fields, and path-bound single-use Macaroon requirements. Pass an advertised `toolName` to narrow the pricing map; omit it for every canonical tool. This call does not create an invoice.

```json
{"type":"object","additionalProperties":false,"properties":{"toolName":{"type":"string","minLength":1}},"required":[]}
```

## 13. mesh.get_status — free

Inspect mesh topology, configured and active peers, and quorum readiness without making a paid call.

```json
{"type":"object","additionalProperties":false,"properties":{},"required":[]}
```

## 14. mesh.broadcast — 250 sats

Broadcast a freshly signed existing telemetry record to configured mesh peers. The payload is a date selector, not arbitrary caller-provided telemetry; this can change peer state.

```json
{"type":"object","additionalProperties":false,"properties":{"signalType":{"type":"string","enum":["telemetry_snapshot"]},"payload":{"type":"object","additionalProperties":false,"properties":{"date":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["date"]}},"required":["signalType","payload"]}
```

## TypeScript SDK

The repository's TypeScript SDK supplies an L402-aware REST client and an NWC wallet adapter. Pass an NWC client obtained by your application; never hardcode a pairing URI, private key or invoice preimage in source. REST subscription credentials have REST-specific path/request/expiry scope; they are distinct from MCP paid-call authorizations and cannot be carried across scopes.

```ts
import { BitcoinStratigraphyClient, NwcWalletAdapter } from "@bitcoin-stratigraphy/sdk";

const client = new BitcoinStratigraphyClient({
  baseUrl: "https://bitcoin-stratigraphy-dashboard.replit.app",
  wallet: new NwcWalletAdapter(yourNwcClient),
});

const latest = await client.getLatest();
console.log(latest);
```

The SDK's REST client discovers pre-flight prices, pays the selected REST subscription invoice with the supplied wallet, and may reuse that REST-scoped macaroon and preimage within its enforced scope until expiry. This behavior does not make MCP paid-call credentials reusable. The package also exports an MCP entry point (`@bitcoin-stratigraphy/sdk/mcp`); consult the package's README for install and export details. The SDK's REST `getLatest()` example is not a substitute for a paid MCP `tools/call` request. For plain MCP discovery, use the free `tools/list` request above.