For agent developers / Model Context Protocol

Connect your agent to 19 MCP tools in four lines.

Bitcoin Stratigraphy exposes an MCP server over streamable HTTP. The Python client handles NIP-98 Schnorr authentication and L402 Lightning macaroons, so your agent calls tools and the transport settles access.

View repository Read llms.txt Developer docs

Endpoint and source

MCP endpoint: https://bitcoinstratigraphy.com/mcp
Repository: github.com/CharlesStrogish/bitcoin-stratigraphy-mcp
Machine-readable spec: /llms.txt
License: AGPLv3 core. Commercial exemption available for proprietary deployments.

Install

shell

pip install bitcoin-stratigraphy-mcp-client

Self-host the MCP server

shell

npm install @bitcoin-stratigraphy/mcp-server@2.1.3
npx bitcoin-stratigraphy-mcp-server --help

Self-hosting requires Node.js 22+, PostgreSQL and Python enterprise dependencies. Configure the wallet and runtime as described in the server deployment guide. Installation alone does not start or fund a server.

Discover the enabled catalog at runtime with tools/list. Clearing is a host-enabled extension and may not be present on every deployment.

Framework integration

LangChain

from bitcoin_stratigraphy_mcp_client import L402Nip98Transport
from langchain.agents import create_agent

async with L402Nip98Transport(private_key=key, wallet_handler=wallet) as tools:
    agent = create_agent(model, tools=tools)
    # Execute inside the context block to keep the MCP session alive

CrewAI

from crewai import Agent
from bitcoin_stratigraphy_mcp_client.crewai import CrewAISwarmTools

with CrewAISwarmTools(private_key=key, wallet_handler=wallet) as tools:
    agent = Agent(role="Treasury auditor", tools=tools)

Tool namespaces

stratigraphy.*5
proof.*7
mesh.*2
payment.*2
workflow.*1
clearing.*2

clearing.settle_contract verifies Groth16 preimage receipts. It is preimage evidence, not proof of arbitrary task execution. Automated payouts and refunds are disabled.

Prepaid API Access (B2B)

Grants: 100 calls to POST /api/scanner
Validity: Credits expire 30 days after issuance.
Not included: Does not fund unrelated MCP tools; those settle per call over L402.

The Lightning checkout loads in your browser.

19 MCP tools and API pricing

API base URL: https://bitcoinstratigraphy.com. REST API: https://bitcoinstratigraphy.com/api. MCP: https://bitcoinstratigraphy.com/mcp.

Standard paid core calls: 250 sats/call via Bitcoin Lightning L402. Use tools/list for the host-enabled catalog and current schemas.

$500 Enterprise API Block: $500 USD by credit card via Stripe-hosted Checkout, or 100,000 sats via Lightning. 100 prepaid heuristic scanner calls, 30 days from issuance. POST /api/scanner only; these credits do not authorize unrelated MCP tools.

Credits are issued only after verified payment and configured treasury funding. Card checkout requires the payer's approval; never submit card details through MCP.

stratigraphy.get: Retrieve one indexed Bitcoin telemetry snapshot. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
stratigraphy.get_digest: Retrieve a compact telemetry digest. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
stratigraphy.get_diff: Compare indexed telemetry snapshots. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
stratigraphy.get_range: Retrieve a bounded range of indexed snapshots. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
stratigraphy.list: Discover available indexed heights and dates. Free discovery; no invoice.
proof.attenuate: Restrict an existing authorization capability. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
proof.verify: Verify supported cryptographic proof inputs. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
proof.get_by_hash: Look up retained proof payloads, receipts or lifecycle status. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
proof.list: Discover indexed proof lifecycle records. Free discovery; no invoice.
proof.submit: Submit evidence to the supported proof lifecycle. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
proof.ground: Obtain signed Bitcoin-tip context for a payload. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
payment.get_info: Inspect MCP payment terms or verify authenticated settlement. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
mesh.get_status: Inspect configured mesh peer status. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
mesh.broadcast: Broadcast a signed stored telemetry snapshot to pinned peers. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
proof.notarize: Request a detached OpenTimestamps receipt for a SHA256 digest. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
workflow.audit_trajectory: Record an authenticated, Bitcoin-anchored batch of agent decisions; not a reasoning or correctness proof. Standard: 250 sats/call via Lightning L402; consult current quotes for grants, discounts and batches.
payment.get_escrow: Look up escrow state with the required caller authorization. Authenticated escrow lookup; not a flat 250-sat MCP call.
clearing.create_contract: Create a worker contract and its Lightning funding invoice; host-enabled and funded at the requested contract amount, not a flat MCP call fee. Host-enabled; separate Lightning contract funding at the requested amount.
clearing.settle_contract: Record authenticated funded-contract proof settlement when the host enables it; automated payouts and refunds remain disabled. Host-enabled; requires authenticated worker and verified contract funding.

HTTP 402 WWW-Authenticate: L402 macaroon="<macaroon>", invoice="<BOLT11>". Pay the exact invoice once, then retry the original request. Pending merchant confirmation is not authorization to pay again. Never expose payment credentials or spend without an authorized budget.

Public price quotes $500 Enterprise API Block — payment options Agent payment instructions