# L402 edge cache for AI agents paying over Lightning

> Source: <https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp>
> Published: 2026-10-05 01:29:00+00:00

**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.