agent-bitcoin 26.2.0__py3-none-any.whl

agent_bitcoin/__init__.py

@@ -0,0 +1,65 @@
+"""
+Agent-Bitcoin SDK
+=================
+
+A Python library for Lightning Network payments between autonomous AI agents.
+"""
+
+__version__ = "26.2.0"
+
+# Core
+from .client import AgentBitcoinClient, create_client
+from .constants import (
+    DEFAULT_L402_PRICE_SATS,
+    DEFAULT_MAX_PAYMENT_SATS,
+    DEFAULT_MIN_PAYMENT_SATS,
+)
+from .l402 import L402Client, L402Challenge, parse_www_authenticate
+from .models import LightningConfig, Invoice, InvoiceQuote, PayerDecisionInputs
+
+# Exceptions
+from .exceptions import (
+    AgentBitcoinError,
+    InvoiceCreationError,
+    PaymentError,
+    MacaroonError,
+    InsufficientBalanceError,
+    NoRouteError,
+)
+
+# Intelligent Agents (kept for future use)
+from .agents.payment_decision import (
+    PaymentDecisionAgent,
+    create_payment_decision_agent,
+    create_grok_payment_decision_agent,
+    PaymentDecision,
+)
+
+# Main public API
+__all__ = [
+    # Core
+    "AgentBitcoinClient",
+    "LightningConfig",
+    "Invoice",
+    "InvoiceQuote",
+    "PayerDecisionInputs",
+    "create_client",
+    "DEFAULT_MIN_PAYMENT_SATS",
+    "DEFAULT_MAX_PAYMENT_SATS",
+    "DEFAULT_L402_PRICE_SATS",
+    "L402Client",
+    "L402Challenge",
+    "parse_www_authenticate",
+    # Exceptions
+    "AgentBitcoinError",
+    "InvoiceCreationError",
+    "PaymentError",
+    "MacaroonError",
+    "InsufficientBalanceError",
+    "NoRouteError",
+    # Intelligent Agents
+    "PaymentDecisionAgent",
+    "create_payment_decision_agent",
+    "create_grok_payment_decision_agent",
+    "PaymentDecision",
+]

agent_bitcoin/agents/__init__.py

@@ -0,0 +1,15 @@
+# agent_bitcoin/agents/__init__.py
+
+from .payment_decision import (
+    PaymentDecisionAgent,
+    BitcoinLNDAgent,
+    create_grok_payment_decision_agent,
+    create_grok_bitcoin_lnd_agent,
+)
+
+__all__ = [
+    "PaymentDecisionAgent",
+    "BitcoinLNDAgent",
+    "create_grok_payment_decision_agent",
+    "create_grok_bitcoin_lnd_agent",
+]

agent_bitcoin/agents/payment_decision.py

@@ -0,0 +1,244 @@
+"""Payment decision agents with coded policy limits (not prompt-only)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from enum import Enum
+from typing import Any, Optional
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from langchain_xai import ChatXAI
+
+from agent_bitcoin.constants import (
+    min_payment_sats,
+    payment_decision_max_sats,
+)
+from agent_bitcoin.prompts import (
+    BITCOIN_LND_SYSTEM_PROMPT,
+    PAYMENT_DECISION_DEFAULT_INSTRUCTIONS,
+    PAYMENT_DECISION_SYSTEM_PROMPT,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PaymentDecision(Enum):
+    PAY = "PAY"
+    REJECT = "REJECT"
+    CONFIRM_REQUIRED = "CONFIRM_REQUIRED"
+
+
+class PaymentDecisionAgent:
+    """
+    Conservative gatekeeper for Lightning invoice payments.
+
+    Policy is enforced in code first; the LLM only runs if hard limits pass.
+    This agent never executes payments — callers must act on the returned decision.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "grok-4-1-fast-reasoning",
+        min_sats: Optional[int] = None,
+        max_sats: Optional[int] = None,
+        confirm_above_sats: Optional[int] = None,
+    ):
+        self.llm = ChatXAI(
+            model=model,
+            api_key=api_key,
+            temperature=0.1,
+        )
+        self.system_prompt = PAYMENT_DECISION_SYSTEM_PROMPT
+        self.default_instructions = PAYMENT_DECISION_DEFAULT_INSTRUCTIONS
+
+        # Coded limits (shared defaults; constructor / env overrides)
+        self.min_sats = min_sats if min_sats is not None else min_payment_sats()
+        self.max_sats = (
+            max_sats if max_sats is not None else payment_decision_max_sats()
+        )
+        # Amounts above this require human confirmation (no automatic PAY)
+        if confirm_above_sats is not None:
+            self.confirm_above_sats = confirm_above_sats
+        else:
+            raw = os.getenv("PAYMENT_DECISION_CONFIRM_ABOVE_SATS", "").strip()
+            self.confirm_above_sats = int(raw) if raw else None
+
+    def _parse_amount(self, invoice_data: dict) -> Optional[int]:
+        raw = invoice_data.get("amount_sats")
+        if raw is None:
+            return None
+        try:
+            return int(raw)
+        except (TypeError, ValueError):
+            return None
+
+    def _policy_gate(self, amount: Optional[int]) -> Optional[dict[str, Any]]:
+        """Return a reject/confirm result if policy blocks LLM, else None."""
+        if amount is None:
+            return {
+                "decision": PaymentDecision.REJECT.value,
+                "reasoning": "Policy: missing or invalid amount_sats; refusing to evaluate.",
+                "blocked_by_policy": True,
+                "policy_code": "INVALID_AMOUNT",
+                "amount_sats": None,
+            }
+        if amount < self.min_sats:
+            return {
+                "decision": PaymentDecision.REJECT.value,
+                "reasoning": (
+                    f"Policy: amount {amount} sats is below minimum {self.min_sats} sats."
+                ),
+                "blocked_by_policy": True,
+                "policy_code": "BELOW_MINIMUM",
+                "amount_sats": amount,
+            }
+        if amount > self.max_sats:
+            return {
+                "decision": PaymentDecision.REJECT.value,
+                "reasoning": (
+                    f"Policy: amount {amount} sats exceeds hard maximum "
+                    f"{self.max_sats} sats (PAYMENT_DECISION_MAX_SATS)."
+                ),
+                "blocked_by_policy": True,
+                "policy_code": "ABOVE_MAXIMUM",
+                "amount_sats": amount,
+            }
+        if self.confirm_above_sats is not None and amount > self.confirm_above_sats:
+            return {
+                "decision": PaymentDecision.CONFIRM_REQUIRED.value,
+                "reasoning": (
+                    f"Policy: amount {amount} sats is above confirmation threshold "
+                    f"{self.confirm_above_sats} sats. Human approval required before PAY."
+                ),
+                "blocked_by_policy": True,
+                "policy_code": "CONFIRM_REQUIRED",
+                "amount_sats": amount,
+            }
+        return None
+
+    def decide_payment(self, invoice_data: dict, context: str = "") -> dict:
+        amount = self._parse_amount(invoice_data)
+        gate = self._policy_gate(amount)
+        if gate is not None:
+            result = {
+                **gate,
+                "raw_response": None,
+                "policy": {
+                    "min_sats": self.min_sats,
+                    "max_sats": self.max_sats,
+                    "confirm_above_sats": self.confirm_above_sats,
+                },
+            }
+            logger.info(
+                "payment_decision policy_block code=%s decision=%s amount=%s",
+                result.get("policy_code"),
+                result["decision"],
+                amount,
+            )
+            return result
+
+        # Never put full BOLT11 / secrets in the prompt
+        pay_req = str(invoice_data.get("payment_request") or "")
+        pay_req_preview = (pay_req[:48] + "…") if len(pay_req) > 48 else pay_req
+        memo = str(invoice_data.get("memo") or "No memo")[:200]
+        ctx = (context or "No additional context")[:500]
+
+        prompt = f"""Invoice details:
+Amount: {amount} sats
+Memo: {memo}
+Payment Request (truncated): {pay_req_preview or "N/A"}
+
+Context: {ctx}
+
+Hard policy already applied (do not override):
+- Minimum: {self.min_sats} sats
+- Maximum: {self.max_sats} sats
+{f"- Confirm above: {self.confirm_above_sats} sats" if self.confirm_above_sats else ""}
+
+{self.default_instructions}
+
+Should we pay this invoice? Respond with clear reasoning and final decision (PAY / REJECT).
+Do not invent payment execution; only decide."""
+
+        messages = [
+            SystemMessage(content=self.system_prompt),
+            HumanMessage(content=prompt),
+        ]
+
+        response = self.llm.invoke(messages)
+        text = response.content if hasattr(response, "content") else str(response)
+        text_upper = text.upper()
+
+        # Prefer explicit REJECT if both words appear
+        if "REJECT" in text_upper and "PAY" in text_upper:
+            # last occurrence wins lightly: if REJECT after last PAY → reject
+            decision = (
+                PaymentDecision.REJECT.value
+                if text_upper.rfind("REJECT") > text_upper.rfind("PAY")
+                else PaymentDecision.PAY.value
+            )
+        elif "REJECT" in text_upper:
+            decision = PaymentDecision.REJECT.value
+        elif "PAY" in text_upper:
+            decision = PaymentDecision.PAY.value
+        else:
+            decision = PaymentDecision.REJECT.value  # fail closed
+
+        result = {
+            "decision": decision,
+            "reasoning": text,
+            "raw_response": text,
+            "blocked_by_policy": False,
+            "policy_code": None,
+            "amount_sats": amount,
+            "policy": {
+                "min_sats": self.min_sats,
+                "max_sats": self.max_sats,
+                "confirm_above_sats": self.confirm_above_sats,
+            },
+        }
+        logger.info(
+            "payment_decision llm decision=%s amount=%s",
+            decision,
+            amount,
+        )
+        return result
+
+
+class BitcoinLNDAgent:
+    """Agent for the counterparty node (agent-bitcoin-lnd). Prompt helper only."""
+
+    def __init__(
+        self, api_key: Optional[str] = None, model: str = "grok-4-1-fast-reasoning"
+    ):
+        self.llm = ChatXAI(
+            model=model,
+            api_key=api_key,
+            temperature=0.3,
+        )
+        self.system_prompt = BITCOIN_LND_SYSTEM_PROMPT
+
+    def create_invoice_prompt(self, amount_sats: int, memo: str) -> str:
+        return (
+            f"Create a Lightning invoice for {amount_sats} sats "
+            f"with memo: '{memo}'. Be professional and clear."
+        )
+
+
+def create_grok_payment_decision_agent(
+    api_key: Optional[str] = None,
+    **policy_kwargs,
+):
+    """Create Grok-powered payment decision agent (optional policy kwargs)."""
+    return PaymentDecisionAgent(api_key=api_key, **policy_kwargs)
+
+
+def create_grok_bitcoin_lnd_agent(api_key: Optional[str] = None):
+    """Create Grok-powered agent for the counterparty LND node."""
+    return BitcoinLNDAgent(api_key=api_key)
+
+
+# Alias for backward compatibility with __init__.py
+create_payment_decision_agent = create_grok_payment_decision_agent

agent_bitcoin/client.py

@@ -0,0 +1,258 @@
+from dotenv import load_dotenv
+
+from .constants import (
+    autopay_allowed,
+    fee_send_allowed,
+    max_daily_payment_sats,
+    max_payment_sats,
+    min_payment_sats,
+    current_network,
+)
+from .lightning import LNDClient
+from .models import (
+    Invoice,
+    InvoiceQuote,
+    PayerDecisionInputs,
+    PaymentResult,
+    OnChainSendResult,
+    LightningBalance,
+    ChannelBalance,
+)
+from .spend_ledger import assert_can_spend, record_spend
+
+load_dotenv()
+
+
+def _invoice_amount_sats(decoded: dict) -> int:
+    """Extract sat amount from lncli/gRPC decodepayreq dict."""
+    for key in ("num_satoshis", "num_sats", "amt_sat"):
+        if decoded.get(key) is not None:
+            try:
+                return int(decoded[key])
+            except (TypeError, ValueError):
+                pass
+    for key in ("num_msat", "amt_msat"):
+        if decoded.get(key) is not None:
+            try:
+                return int(decoded[key]) // 1000
+            except (TypeError, ValueError):
+                pass
+    return 0
+
+
+class AgentBitcoinClient:
+    def __init__(self):
+        self.lnd = LNDClient()
+
+        self.min_payment_sats = min_payment_sats()
+        self.max_payment_sats = max_payment_sats()
+        self.max_daily_payment_sats = max_daily_payment_sats()
+
+    def create_invoice(
+        self, memo: str, amount_sats: int, expiry_seconds: int = 3600
+    ) -> Invoice:
+        if amount_sats < self.min_payment_sats:
+            raise ValueError(f"Minimum payment is {self.min_payment_sats} sats")
+        if amount_sats > self.max_payment_sats:
+            raise ValueError(f"Maximum payment is {self.max_payment_sats} sats")
+        return self.lnd.create_invoice(memo, int(amount_sats), expiry_seconds)
+
+    def create_invoice_quote(
+        self,
+        memo: str,
+        amount_sats: int,
+        expiry_seconds: int = 3600,
+    ) -> InvoiceQuote:
+        """
+        Payee: create one BOLT11 for the requested amount.
+
+        amount_sats is the service amount (min/max apply). BOLT11 and
+        total_cost_sats equal that amount. There is no platform fee.
+        """
+        if amount_sats < self.min_payment_sats:
+            raise ValueError(f"Minimum payment is {self.min_payment_sats} sats")
+        if amount_sats > self.max_payment_sats:
+            raise ValueError(f"Maximum payment is {self.max_payment_sats} sats")
+        total = int(amount_sats)
+        inv = self.lnd.create_invoice(memo, total, expiry_seconds)
+        return InvoiceQuote(
+            payment_request=inv.payment_request,
+            amount_sats=total,
+            total_cost_sats=total,
+            memo=memo or "",
+            r_hash=inv.r_hash,
+            payment_hash=inv.payment_hash,
+            network=current_network(),
+        )
+
+    def validate_invoice_quote(self, quote: InvoiceQuote | dict) -> InvoiceQuote:
+        """
+        Payer: check quote internal consistency and BOLT11 amount match.
+        Raises ValueError if invalid.
+        """
+        if isinstance(quote, dict):
+            quote = InvoiceQuote.model_validate(quote)
+        if quote.amount_sats < 0:
+            raise ValueError("amount_sats must be >= 0")
+        if quote.total_cost_sats != quote.amount_sats:
+            raise ValueError(
+                f"total_cost_sats={quote.total_cost_sats} != "
+                f"amount_sats={quote.amount_sats}"
+            )
+        if not quote.payment_request:
+            raise ValueError("payment_request is required")
+
+        decoded = self.lnd.decode_pay_req(quote.payment_request.strip())
+        bolt_amt = _invoice_amount_sats(decoded)
+        if bolt_amt != quote.total_cost_sats:
+            raise ValueError(
+                f"BOLT11 amount {bolt_amt} does not match quote total_cost_sats "
+                f"{quote.total_cost_sats} (requested {quote.amount_sats})"
+            )
+        return quote
+
+    def build_payer_decision_inputs(
+        self,
+        quote: InvoiceQuote | dict,
+        routing_fee_limit_sats: int = 200,
+    ) -> PayerDecisionInputs:
+        """
+        Payer: produce decision inputs for PaymentDecisionAgent / budget checks.
+        Does not pay. Sets quote_valid False on validation failure (no raise).
+        """
+        if isinstance(quote, dict):
+            try:
+                q = InvoiceQuote.model_validate(quote)
+            except Exception as e:
+                return PayerDecisionInputs(
+                    payment_request=str(quote.get("payment_request") or ""),
+                    amount_sats=int(quote.get("amount_sats") or 0),
+                    total_cost_sats=int(quote.get("total_cost_sats") or 0),
+                    routing_fee_limit_sats=int(routing_fee_limit_sats),
+                    quote_valid=False,
+                    validation_error=str(e),
+                )
+        else:
+            q = quote
+
+        try:
+            q = self.validate_invoice_quote(q)
+            decoded = self.lnd.decode_pay_req(q.payment_request.strip())
+            dest = str(decoded.get("destination") or "")
+            return PayerDecisionInputs(
+                payment_request=q.payment_request,
+                amount_sats=q.amount_sats,
+                total_cost_sats=q.total_cost_sats,
+                routing_fee_limit_sats=int(routing_fee_limit_sats),
+                quote_valid=True,
+                validation_error=None,
+                memo=q.memo or str(decoded.get("description") or ""),
+                destination=dest,
+            )
+        except Exception as e:
+            return PayerDecisionInputs(
+                payment_request=q.payment_request,
+                amount_sats=q.amount_sats,
+                total_cost_sats=q.total_cost_sats,
+                routing_fee_limit_sats=int(routing_fee_limit_sats),
+                quote_valid=False,
+                validation_error=str(e),
+                memo=q.memo,
+            )
+
+    def pay_invoice(
+        self, payment_request: str, fee_limit_sats: int = 200
+    ) -> PaymentResult:
+        if not payment_request:
+            raise ValueError("Payment request is required")
+        if not autopay_allowed():
+            raise RuntimeError(
+                "Lightning pay blocked: set AGENT_BITCOIN_ALLOW_AUTOPAY=1 "
+                "(required on mainnet; optional kill-switch on lab nets with =0). "
+                "See docs/mainnet-pilot.md Phase 2."
+            )
+
+        amount_sats = 0
+        try:
+            decoded = self.lnd.decode_pay_req(payment_request.strip())
+            amount_sats = _invoice_amount_sats(decoded)
+        except Exception:
+            decoded = {}
+
+        if amount_sats > 0:
+            if amount_sats < self.min_payment_sats:
+                raise ValueError(
+                    f"Invoice amount {amount_sats} below minimum {self.min_payment_sats}"
+                )
+            if amount_sats > self.max_payment_sats:
+                raise ValueError(
+                    f"Invoice amount {amount_sats} above maximum {self.max_payment_sats}"
+                )
+            assert_can_spend(amount_sats, self.max_daily_payment_sats)
+
+        result = self.lnd.pay_invoice(
+            payment_request.strip(), fee_limit_sats=fee_limit_sats
+        )
+        if result.success:
+            recorded = amount_sats or int(result.amount or 0)
+            if recorded > 0:
+                record_spend(recorded, payment_hash=result.payment_hash)
+        return result
+
+    def pay_invoice_quote(
+        self,
+        quote: InvoiceQuote | dict,
+        routing_fee_limit_sats: int = 200,
+    ) -> PaymentResult:
+        """
+        Payer: validate quote, budget total_cost_sats, pay BOLT11 amount on LN.
+
+        total_cost_sats equals the requested amount (no platform fee).
+        Daily/deposit ledger uses total_cost_sats.
+        """
+        q = self.validate_invoice_quote(quote)
+        if not autopay_allowed():
+            raise RuntimeError(
+                "Lightning pay blocked: set AGENT_BITCOIN_ALLOW_AUTOPAY=1 "
+                "(required on mainnet; optional kill-switch on lab nets with =0). "
+                "See docs/mainnet-pilot.md Phase 2."
+            )
+        if q.amount_sats < self.min_payment_sats:
+            raise ValueError(
+                f"Invoice amount {q.amount_sats} below minimum {self.min_payment_sats}"
+            )
+        if q.amount_sats > self.max_payment_sats:
+            raise ValueError(
+                f"Invoice amount {q.amount_sats} above maximum {self.max_payment_sats}"
+            )
+        assert_can_spend(q.total_cost_sats, self.max_daily_payment_sats)
+
+        result = self.lnd.pay_invoice(
+            q.payment_request.strip(), fee_limit_sats=routing_fee_limit_sats
+        )
+        if result.success:
+            record_spend(q.total_cost_sats, payment_hash=result.payment_hash)
+        return result
+
+    def send_onchain(self, address: str, amount_sats: int) -> OnChainSendResult:
+        if not fee_send_allowed():
+            raise RuntimeError(
+                "On-chain fee/send blocked on mainnet unless "
+                "AGENT_BITCOIN_ALLOW_MAINNET_FEE=1 (pilot default off)."
+            )
+        if not address:
+            raise ValueError("Destination address is required")
+        if amount_sats <= 0:
+            raise ValueError("Amount must be positive")
+        return self.lnd.send_coins(address, amount_sats)
+
+    def get_balance(self) -> LightningBalance:
+        return self.lnd.get_balance()
+
+    def get_channel_balance(self) -> ChannelBalance:
+        return self.lnd.get_channel_balance()
+
+
+def create_client() -> AgentBitcoinClient:
+    """Factory function"""
+    return AgentBitcoinClient()

agent_bitcoin/constants.py

@@ -0,0 +1,116 @@
+"""
+Shared payment policy defaults for SDK, backend API, and agents.
+
+Env vars may still override at runtime; these are the single source of truth
+for default numeric limits so invoice and agent ceilings cannot drift.
+
+Mainnet pilot defaults (docs/mainnet-pilot.md Phase 0):
+  single pay 50_000, daily 100_000, autopay off, fee sends off.
+"""
+
+from __future__ import annotations
+
+import os
+
+# --- Canonical defaults (sats) ---
+DEFAULT_MIN_PAYMENT_SATS = 1_000
+DEFAULT_MAX_PAYMENT_SATS = 1_000_000
+# When LND_NETWORK=mainnet and MAX_PAYMENT_SATS unset (pilot ceiling)
+DEFAULT_MAINNET_MAX_PAYMENT_SATS = 50_000
+DEFAULT_MAX_DAILY_PAYMENT_SATS = 100_000
+DEFAULT_MAX_FEE_SEND_SATS = 100_000
+# Aperture L402 price per paid request (matches MIN_PAYMENT_SATS)
+DEFAULT_L402_PRICE_SATS = 1_000
+
+
+def env_int(name: str, default: int) -> int:
+    """Read a positive-capable int from the environment, or return default."""
+    raw = os.getenv(name)
+    if raw is None or str(raw).strip() == "":
+        return default
+    return int(raw)
+
+
+def current_network() -> str:
+    return os.getenv("LND_NETWORK", "regtest").strip().lower() or "regtest"
+
+
+def is_mainnet() -> bool:
+    return current_network() == "mainnet"
+
+
+def min_payment_sats() -> int:
+    return env_int("MIN_PAYMENT_SATS", DEFAULT_MIN_PAYMENT_SATS)
+
+
+def max_payment_sats() -> int:
+    """
+    Maximum invoice / payment amount (sats).
+
+    MAX_INVOICE_SATS and PAYMENT_DECISION_MAX_SATS both default to this value.
+    On mainnet, default ceiling is pilot 50_000 unless MAX_PAYMENT_SATS is set.
+    """
+    if os.getenv("MAX_PAYMENT_SATS", "").strip():
+        return env_int("MAX_PAYMENT_SATS", DEFAULT_MAX_PAYMENT_SATS)
+    if is_mainnet():
+        return DEFAULT_MAINNET_MAX_PAYMENT_SATS
+    return DEFAULT_MAX_PAYMENT_SATS
+
+
+def max_daily_payment_sats() -> int:
+    """
+    Max sum of successful Lightning pays per UTC day (sats).
+
+    0 = disabled (no daily cap). On mainnet defaults to pilot 100_000;
+    on lab nets defaults to 0 (unlimited) unless MAX_DAILY_PAYMENT_SATS is set.
+    """
+    if os.getenv("MAX_DAILY_PAYMENT_SATS", "").strip():
+        return env_int("MAX_DAILY_PAYMENT_SATS", 0)
+    if is_mainnet():
+        return DEFAULT_MAX_DAILY_PAYMENT_SATS
+    return 0
+
+
+def max_invoice_sats() -> int:
+    """Backend invoice ceiling; defaults to shared max payment."""
+    if os.getenv("MAX_INVOICE_SATS", "").strip():
+        return env_int("MAX_INVOICE_SATS", DEFAULT_MAX_PAYMENT_SATS)
+    return max_payment_sats()
+
+
+def payment_decision_max_sats() -> int:
+    """Agent hard max; defaults to shared max payment."""
+    if os.getenv("PAYMENT_DECISION_MAX_SATS", "").strip():
+        return env_int("PAYMENT_DECISION_MAX_SATS", DEFAULT_MAX_PAYMENT_SATS)
+    return max_payment_sats()
+
+
+def max_fee_send_sats() -> int:
+    return env_int("MAX_FEE_SEND_SATS", DEFAULT_MAX_FEE_SEND_SATS)
+
+
+def autopay_allowed() -> bool:
+    """
+    Whether non-interactive Lightning pay is allowed.
+
+    Mainnet: require AGENT_BITCOIN_ALLOW_AUTOPAY=1 (human pilot default off).
+    Lab nets: allowed unless AGENT_BITCOIN_ALLOW_AUTOPAY=0.
+    """
+    flag = (os.getenv("AGENT_BITCOIN_ALLOW_AUTOPAY") or "").strip()
+    if is_mainnet():
+        return flag == "1"
+    if flag == "0":
+        return False
+    return True
+
+
+def fee_send_allowed() -> bool:
+    """
+    Generic on-chain send (`send_onchain`).
+
+    Mainnet: disabled unless AGENT_BITCOIN_ALLOW_MAINNET_FEE=1.
+    Lab nets: allowed.
+    """
+    if is_mainnet():
+        return (os.getenv("AGENT_BITCOIN_ALLOW_MAINNET_FEE") or "").strip() == "1"
+    return True