Skip to main content

bitcoinstratigraphy-agent-yield

One-call Python onboarding for Bitcoin Stratigraphy MCP tools: HTTPX discovery, automatic bounded L402 retries, durable spending reservations, and the same stderr terminal receipts as @bitcoinstratigraphy/agent-yield.

Install from PyPI:

pip install bitcoinstratigraphy-agent-yield

For local development, install from this checkout:

pip install ./packages/python-agent-yield

Two-line quick starts

Start with your existing agent_config. Its fiduciary policy is the explicit wallet authorization shown below. No wallet is created, connected or funded by installing or importing this package.

LangChain

from bitcoinstratigraphy_agent_yield import with_fiduciary_yield

agent = with_fiduciary_yield({**agent_config, "framework": "langchain"})

Pass agent["tools"] to langchain.agents.create_agent(model=..., tools=...). Existing tools are preserved; discovered tools are native StructuredTools with sync .invoke() and async .ainvoke().

CrewAI

from bitcoinstratigraphy_agent_yield import with_fiduciary_yield

agent = with_fiduciary_yield({**agent_config, "framework": "crewai"})

Pass agent["tools"] to crewai.Agent(role=..., goal=..., backstory=..., tools=...). They are native CrewAI BaseTools. You can also wrap an existing public-tools CrewAI agent with with_fiduciary_yield(existing_agent, fiduciary=policy); this returns a copy, never mutating the original agent.

AutoGen

from bitcoinstratigraphy_agent_yield import with_fiduciary_yield

agent = with_fiduciary_yield({**agent_config, "framework": "autogen"})

Pass agent["tools"] to autogen_agentchat.agents.AssistantAgent(..., tools=...). These are native autogen_core.tools.BaseTools, not OpenAI descriptors requiring a separate dispatcher. Cancellation is checked before starting execution.

Framework imports are lazy. Install your chosen framework separately; the base wheel has only three direct runtime dependencies, all exactly pinned: HTTPX, bech32 and coincurve. No LangChain, CrewAI, AutoGen, NWC or MCP framework is forced on other consumers. Native adapters target the current public LangChain Core 1.x, CrewAI 1.x and AutoGen Core 0.7 APIs.

Explicit wallet and spending policy

policy = {
    "wallet": authorized_wallet,
    "max_payment_sats": 500,
    "max_total_sats": 5000,
    "fee_reserve_sats": 10,
    "state_directory": ".agent-yield-state",
}
agent_config = {"tools": existing_tools, "fiduciary": policy}

authorized_wallet.pay_invoice(bolt11) is a synchronous wallet adapter returning {"preimage": "<64 hex characters>", "fees_paid": 0}. fees_paid is optional integer millisatoshis. Use your wallet provider's authorized SDK inside the adapter; secrets never belong in prompts, source, HTTP headers, terminal receipts, or tool arguments. This scaffold does not implement NWC wallet transport.

Without a wallet and explicit positive budgets, discovery and free tools work; paid execution fails closed. Optional make_invoice(amount_msats) returns {"invoice": "<receiving BOLT11>"} to enable automatic yield withdrawals. Wallet adapters must enforce their own operation timeouts and fee ceiling: Python cannot cancel an external payment already submitted to a wallet.

agent["fiduciary"] exposes .list_tools(), .call_tool(name, arguments), await .acall_tool(name, arguments), .recover_claim(payment_hash), and .close(). Framework tools are added to a configuration before constructing a graph/AssistantAgent; this does not retrofit private internals of running agents. Async execution offloads synchronous HTTP/wallet work to a worker thread. Cancelling the awaiting task does not reverse an in-progress wallet operation. Close the config's client at application shutdown. For public-tools object wrapping, supply an application-owned http_client and close it yourself.

Connection and payment guarantees

  • Discovers the live paginated catalog at https://bitcoinstratigraphy.com/mcp. Handles MCP 2026-07-28, JSON and SSE, bounded response sizes, timeout and one bounded Hashcash admission retry. Discovery never pays a wallet.
  • Validates mainnet BOLT11 checksum, recoverable signature, explicit payee, amount, expiry and payment hash against the HTTP JSON quote before spending.
  • Reserves invoice principal plus fee allowance in private SQLite storage before contacting the wallet. Per-invoice and cumulative limits are integer satoshis. Reservations survive threads, processes and restarts. Reported excessive/invalid fees block future new payments.
  • Verifies every preimage against its invoice hash, then retries the identical MCP body/ID exactly once with Authorization: L402 macaroon:preimage. Credentials are bound to the exact invoice/request, not globally reused across unrelated tools. A repeated 402 never triggers a second payment.
  • Never follows redirects or replaces caller-supplied payment credentials. Supply identity_headers(url, method, body_bytes) for fresh NIP-98 headers; it runs again for admission and paid retries. Valid Genesis Grant calls incur no payment, paid-history credit, yield allocation or earned receipt.
  • Unknown payments and invalid returned proofs stay reserved. Do not delete the state directory or change directories to retry a payment. Operators must establish the payment outcome before recovery. Use private persistent storage, exclude it from Git, and use one directory per wallet and policy.

The SQLite ledger contains sensitive payment proofs, though never wallet keys. The folder is created with mode 0700 and the database with 0600. Protect and back up this directory. Existing directories must already be private. This is client-side accounting, not a replacement for server-side settlement ledgers or a wallet-enforced spending limit.

Terminal receipts

On a successful paid execution with a receiving wallet:

[Bitcoin Stratigraphy] ⚡ Thermodynamic Yield Allocated: 21 Sats (settlement pending).
[Bitcoin Stratigraphy] ⚡ Thermodynamic Yield Earned: 21 Sats routed to agent wallet.

Allocated is yellow; earned is green. An earned receipt appears only after the claim API confirms SETTLED and payment_sent: true, never on allocation, free grants, pending claims, failed tools or failed payouts. Millisatoshi precision is preserved. Logging goes exclusively to sys.stderr to preserve MCP JSON-RPC stdout. QUIET_STRATIGRAPHY=true disables receipts at event time; logging failures never change successful tool results.

Claims are best effort, not guaranteed income. on_error({"code": ...}) reports recovery needs without exposing wallet/server error text. on_yield_claim({"status": ..., "amount_msats": ...}) observes claim status. .recover_claim(payment_hash) replays only a persisted withdrawal request and never buys a new tool invoice. Recovery after a crash during receiving-invoice creation needs operator intervention; it does not create a second invoice. Claims run synchronously after paid execution, bounded by the HTTP timeout.

Development / packaging (no publication)

From the repository root, using its Python environment:

uv run --no-sync python -m pytest packages/python-agent-yield
cd packages/python-agent-yield
uv run --no-sync python -m hatchling build -d ../../generated-artifacts/python-agent-yield

Or install .[test] inside this package, then run python -m pytest. The dedicated tests use signed synthetic invoices, httpx.MockTransport, temporary state, and fake wallets. They do not contact mainnet or move funds. Native LangChain/AutoGen integration tests run when those frameworks are installed; the CrewAI adapter has a public-API contract fixture without pulling CrewAI's full dependency tree into this standalone package. Wheel/sdist build output belongs in generated-artifacts/, never source control. Building never uploads to PyPI; publication is an explicit release step.

Metadata

Release files for bitcoinstratigraphy-agent-yield 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bitcoinstratigraphy-agent-yield 0.1.0
File Size Uploaded Provenance Actions
bitcoinstratigraphy_agent_yield-0.1.0.tar.gz 22.2 kB Without provenance Details for bitcoinstratigraphy_agent_yield-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bitcoinstratigraphy-agent-yield 0.1.0
File Interpreter ABI Platform Actions
bitcoinstratigraphy_agent_yield-0.1.0-py3-none-any.whl Python 3 none any Details for bitcoinstratigraphy_agent_yield-0.1.0-py3-none-any.whl

Total release size: 41.4 kB

Release files / bitcoinstratigraphy_agent_yield-0.1.0.tar.gz

Download URL bitcoinstratigraphy_agent_yield-0.1.0.tar.gz
Size 22.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e4b7aae4240ba995a0cff18fe1ed6f7ca498449f39030c935cf4d15148dcdf08
BLAKE2b-256 checksum
How to use checksums
e19c8f2a01b7140ecf79c7a15e942da721432612a468875428dc595ae56a52c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / bitcoinstratigraphy_agent_yield-0.1.0-py3-none-any.whl

Download URL bitcoinstratigraphy_agent_yield-0.1.0-py3-none-any.whl
Size 19.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e97501c393dc7cb9bf44ddf3a62cb36a92f3d66afe4d284cc40a30d2edfdc119
BLAKE2b-256 checksum
How to use checksums
9129f7299ad7074d627ff5a42214e1710250d3ce68880ba54d12907a2363f46e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for bitcoinstratigraphy-agent-yield 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page