L402 edge cache for AI agents paying over Lightning

Charles Strogish released version 1.1.0 of the bitcoin-stratigraphy-mcp repository, a remote-first integration bundle for the Bitcoin Stratigraphy MCP engine that connects to a hosted endpoint at bitcoin-stratigraphy-dashboard.replit.app/mcp and advertises 15 canonical capabilities. The release ships dependency-free Node and Python clients with a free sandbox that executes only the stratigraphy.list and proof.list tools, while paid capabilities require tool-scoped credentials and an X-L402-Batch-Size header for batch requests. LlamaIndex source is preserved but installation and execution are unavailable because its NLTK dependency is affected by advisory GHSA-8mgp-746c-j5xp.

Release: 1.1.0 · MCP registry name: crstrogish/bitcoin-stratigraphy A standalone, remote-first integration repository for the Bitcoin Stratigraphy MCP engine: registry metadata, OpenAPI contracts, dependency-free clients, and native framework agent examples. No Replit workspace, wallet, API key, or model provider account is needed for the free sandbox. This bundle connects to the hosted engine ; it does not contain or claim to run the complete settlement server offline. Client sources can be run locally against the live service or an independently operated compatible MCP endpoint. There are no workspace aliases, vendored credentials, private signing keys, operator state, or dependency on a parent repository. LangChain execution is supported. LlamaIndex source is preserved, but dependency installation and execution are temporarily unavailable : its NLTK dependency is affected by GHSA-8mgp-746c-j5xp https://github.com/nltk/nltk/security/advisories/GHSA-8mgp-746c-j5xp . The LlamaIndex requirements file intentionally installs nothing. Do not bypass security checks or treat the badge as a claim of supported execution. Restore installation only after auditing a safe, complete dependency tree. | Surface | URL | |---|---| | Streamable HTTP MCP | https://bitcoin-stratigraphy-dashboard.replit.app/mcp | | Developer portal | https://bitcoin-stratigraphy-dashboard.replit.app/docs | | Live OpenAPI | https://bitcoin-stratigraphy-dashboard.replit.app/openapi.json | Use the MCP URL in any Streamable HTTP client. Import mcp.json https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp/blob/main/mcp.json where your client supports URL-based MCP configuration; some hosts require an explicit transport type in their own configuration format. smithery.yaml https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp/blob/main/smithery.yaml is canonical remote registration metadata , not a local-server launch recipe. The server advertises 15 canonical capabilities. initialize and tools/list are free protocol discovery operations. Exactly two tool executions are free: | Tool | Arguments | Purpose | |---|---|---| | stratigraphy.list | {} | Discover indexed dates/heights, bounds, and available metrics | | proof.list | {} | List supported proof operations and schema metadata | Catalog discovery is not payment authorization. Other canonical tools require paid access; query live schemas and payment terms before authorizing purchases. From this repository's root, with no package installation : node examples/free-sandbox.mjs This negotiates MCP, sends the initialized notification, then calls only stratigraphy.list and proof.list . It does not sign, pay, attach credentials, or make LLM requests. It fails rather than paying if a free call returns HTTP 402. To use your own compatible endpoint: node examples/free-sandbox.mjs --url http://127.0.0.1:5000/mcp This is a client connection, not a command to start the production engine. The bundled client works with the standard library; no framework installation is required: python -m examples.free sandbox Equivalent copy-paste Python: python from sdk.python.client import BitcoinStratigraphyClient client = BitcoinStratigraphyClient print client.call tool "stratigraphy.list", {} print client.call tool "proof.list", {} Run code from the repository root so the sdk namespace is importable. TLS verification remains enabled. If your organization uses a private CA, configure its trusted certificate store; do not disable verification. Paid capabilities use tool-scoped credentials. To request a batch, include: X-L402-Batch-Size: 100 For example, this request asks for a notarization batch challenge ; it does not pay an invoice: curl --include --request POST \ 'https://bitcoin-stratigraphy-dashboard.replit.app/mcp' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json, text/event-stream' \ --header 'X-L402-Batch-Size: 100' \ --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"proof.notarize","arguments":{"hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}' 1. Inspect HTTP 402, the L402 WWW-Authenticate challenge, invoice amount, expiry, and exact tool scope. 2. Pay only through a trusted Lightning wallet/client with explicit spending limits. Verify the settlement proof matches the challenged payment hash. 3. Retry the same tool call with the batch header and: Authorization: L402 <macaroon :<preimage X-L402-Batch-Size: 100 The registered notarization quote is 250 sats/call × 100 = 25,000 sats . The live invoice is authoritative; registry target-price examples are not a price guarantee. A proof.notarize pass does not unlock other paid tools. Budgets, expiration, revocation, and inherited caveats still apply on every use. Attenuation delegates or narrows scope; it does not reset the parent budget. Native framework adapters are not wallets . Provide a prepaid credential via L402 AUTHORIZATION , or a trusted loopback Streamable HTTP wallet proxy via L402 PROXY URL with explicit spending limits. Do not commit either credentials or model-provider secrets. The older one-shot SDK payment callbacks are not automatic Macro-Macaroon batching implementations. Use a separate consumer Python environment, not an older MCP 1.x environment: python -m pip install -r cookbooks/requirements-langchain.txt python cookbooks/langchain agent.py Default mode discovers tools only. To opt into an LLM and paid notarization, configure your provider key and a prepaid proof.notarize batch credential through your secret manager, then run: python cookbooks/langchain agent.py --run Copy-paste free-tool-only ReAct loop MCP calls are free; model usage is billed by your model provider : python import asyncio from fastmcp.client import Client from fastmcp.client.transports import StreamableHttpTransport from langchain.mcp import MCPAdapter from langchain.agents import create agent from langchain openai import ChatOpenAI async def main : transport = StreamableHttpTransport url="https://bitcoin-stratigraphy-dashboard.replit.app/mcp" client = Client transport, mode="legacy", timeout=30 async with MCPAdapter client as adapter: tools = await adapter.list tools free = t.model copy update={"name": t.name.replace ".", " " } for t in tools if t.name in {"stratigraphy.list", "proof.list"} if len free = 2: raise RuntimeError "Expected both free sandbox capabilities" agent = create agent model=ChatOpenAI model="gpt-4.1-mini", temperature=0 , tools=free, system prompt="Use only these discovery tools. Report actual results.", result = await agent.ainvoke {"messages": {"role": "user", "content": "List indexed stratigraphy bounds and supported proof operations."} } print result "messages" -1 .content asyncio.run main create agent implements the current ReAct model → tool → observation loop. Underscore aliases satisfy model-provider naming rules; the wrappers retain the original dotted remote tool names. Source-only until the dependency security hold is lifted. The following copy-paste example documents the supported API shape for a future audited environment; it is not an instruction to install vulnerable dependencies now. The full paid-notarization example is cookbooks/llamaindex agent.py https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp/blob/main/cookbooks/llamaindex agent.py . python import asyncio from llama index.tools.mcp import BasicMCPClient, McpToolSpec from llama index.core.agent.workflow import ReActAgent from llama index.llms.openai import OpenAI async def main : client = BasicMCPClient "https://bitcoin-stratigraphy-dashboard.replit.app/mcp", timeout=30 try: tools = await McpToolSpec client=client .to tool list async free = t for t in tools if t.metadata.name in {"stratigraphy.list", "proof.list"} if len free = 2: raise RuntimeError "Expected both free sandbox capabilities" for tool in free: tool.metadata.name = tool.metadata.name.replace ".", " " agent = ReActAgent tools=free, llm=OpenAI model="gpt-4.1-mini", temperature=0 , system prompt="Use only the discovery tools. Report actual results.", timeout=90, response = await agent.run user msg="List indexed stratigraphy bounds and supported proof operations." print str response finally: await client.http client.aclose asyncio.run main Model credentials and charges are separate from MCP payments. sdk/typescript https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp/blob/main/sdk/typescript contains both the REST client and MCP client sources, independent compiler configurations, local tests, and its own package manifest. SDK version 0.1.0 is independent of registry release 1.1.0. cd sdk/typescript npm install npm test npm run build The root package manifest retains the canonical MCP registry identity and release version but replaces monorepo scripts/dependencies with portable distribution commands. It is not the private workspace orchestration manifest. README.md Distribution and operational guide package.json Portable MCP metadata and sandbox/test commands smithery.yaml Canonical remote registration manifest mcp.json Remote MCP client configuration openapi.yaml Canonical self-contained REST/OpenAPI contract openapi.json JSON rendering of the same canonical contract LICENSE MIT license cookbooks/ Native framework sources, requirements, and offline tests sdk/typescript/ TypeScript REST/MCP clients and standalone package sdk/python/ Python REST/MCP clients and offline tests examples/ Wallet-free Node/Python sandbox entrypoints test/ Node sandbox transport and safety tests scripts/verify-export.mjs Portable structure, import, and reference checks npm run verify npm test python -m unittest discover -s cookbooks -p 'test .py' python -m unittest discover -s sdk/python -p 'test .py' verify checks relative source imports and Markdown file references, script and SDK package paths, JSON syntax, and absence of workspace dependency aliases. Compile Python and build the SDK as additional syntax checks. Tests are offline unless you explicitly run a sandbox or agent entrypoint. - Indexed stratigraphy heights are a documented daily-data index, not the live Bitcoin tip or native per-block provenance. - OTS calendar acceptance is not Bitcoin confirmation. Preserve the detached receipt and verify its matching digest and Bitcoin attestation separately. - Grounding signatures, ZK proofs, and OTS receipts establish different facts; do not describe one as another. - SDKs stop on payment errors. Do not retry paid calls blindly or log payment proofs. Store credentials in a secret manager and review spending and tool scope before enabling an agent. - The OpenAPI contract covers REST; live MCP tools/list describes executable MCP schemas. OpenAPI schema version and SDK version need not match the registry release. - Audit optional framework dependencies before installing or updating them. No local wallet, signing, or settlement credentials are shipped. MIT. See LICENSE https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp/blob/main/LICENSE . Frameworks and optional dependencies retain their own licenses and terms.