agent-bitcoin 26.2.0__tar.gz

agent_bitcoin-26.2.0/CHANGELOG.md

@@ -0,0 +1,418 @@
+## v26.2.0 — 2026-08-16
+
+First **pypi.org** release. Package metadata aligned with GitHub release **v.26.2.0** (L402 gateway + prior 26.x work). Install: `pip install agent-bitcoin==26.2.0`.
+
+---
+
+## Publish — agent-bitcoin on PyPI (2026-08-16)
+
+### Changed
+
+- Release workflow publishes to **pypi.org** with GitHub Trusted Publishing (`environment: pypi`)
+- Install docs use `pip install agent-bitcoin` (TestPyPI is no longer the install target)
+
+---
+
+## Add — Aperture L402 HTTP gateway (mainnet) (2026-08-15)
+
+### Added
+
+- `docker-compose.l402.mainnet.yml` + `l402/aperture.mainnet.yaml`
+- `./startup-l402-aws.sh mainnet` / `./shutdown-l402-aws.sh mainnet`
+
+Price remains **1,000 sats**. Payer needs mainnet + autopay latches. Autoloop stays off. Live Mac→AWS paid GET **PASS** (2026-08-15).
+
+---
+
+## Add — Aperture L402 HTTP gateway (signet) (2026-08-15)
+
+### Added
+
+- `docker-compose.l402.signet.yml` + `l402/aperture.signet.yaml` (AWS signet LND, `:8081`)
+- `./startup-l402-aws.sh signet` / `./shutdown-l402-aws.sh signet`
+
+Same 1,000 sat price and Mac `L402Client` as regtest. Stop the other L402 stack first (shared `:8081`). Live Mac→AWS paid GET **PASS** (2026-08-15).
+
+---
+
+## Add — Aperture L402 HTTP gateway (regtest) (2026-08-15)
+
+### Added
+
+- Dummy origin + Aperture sidecar (`agent-l402-aperture` on `:8081`, **not** Loop `aperture`)
+- `L402Client` pays a 1,000 sat challenge and retries with `Authorization: L402 …`
+- `PaymentResult.preimage` from `lncli` / gRPC
+- `examples/l402_pay.py`, `startup-l402-aws.sh`, [docs/l402-aperture.md](docs/l402-aperture.md)
+- Security group default port **8081** (Mac IP `/32`)
+
+Live regtest Mac→AWS paid GET **PASS** (2026-08-15). Signet and mainnet overlays are later PRs.
+
+---
+
+## Remove — platform / transaction fee (2026-08-15)
+
+### Removed
+
+- Bundled platform fee (`DEFAULT_FEE_AMOUNT_SATS`, `fee_amount_sats()`, `FEE_AMOUNT_SATS` / `FEE_SATS`)
+- Quote / HTTP fields `platform_fee_sats`, `transaction_fee_sats`, `collection`
+- `AgentBitcoinClient.fee_amount_sats` and `create_invoice_quote(..., platform_fee_sats=)`
+- Ignored `collect_platform_fee` argument on `pay_invoice_quote`
+
+### Changed
+
+- BOLT11 is the requested amount **X** (`create_invoice`, `create_invoice_quote`, NWC `make_invoice`)
+- `total_cost_sats` equals `amount_sats`
+- Minimum payment remains **1,000 sats**; Lightning routing-fee limits and generic `send_onchain` are unchanged
+
+Stale host `FEE_AMOUNT_SATS` / `FEE_SATS` env vars are ignored.
+
+---
+
+## Security — pin Actions SHAs and least-privilege tokens (2026-08-14)
+
+### Fixed
+
+- CodeQL `actions/unpinned-tag` and `actions/missing-workflow-permissions` on CI / Docker / Release
+- Third-party actions pinned to commit SHAs; `contents: read` (Docker also `actions: write` for GHA cache)
+
+---
+
+## Security — CodeQL code scanning (2026-08-14)
+
+### Added
+
+- `.github/workflows/codeql.yml` — CodeQL on Python and GitHub Actions (PRs, `main`, weekly)
+- Alerts appear under GitHub **Security → Code scanning**
+
+---
+
+## Docs — sync current fee, min, and NWC status (2026-08-14)
+
+### Documented
+
+- Product policy: min **1,000** requested; **21** sat fee **inside** BOLT11; no `/send-fee`
+- NWC public-relay read path PASS; `make_invoice` bills X+21
+- HTTP `/invoices` quote shape; `ALLOW_MAINNET_FEE` is only generic `send_onchain`
+
+---
+
+## Remove — unused on-chain platform-fee APIs (2026-08-13)
+
+### Removed
+
+- `AgentBitcoinClient.collect_transaction_fee()`
+- Backend `POST /send-fee`
+- `/pay` response fields `fee_sent` / `fee_address`
+
+Platform fee remains bundled in the Lightning invoice (`FEE_AMOUNT_SATS`).
+
+---
+
+## Change — platform fee bundled into the Lightning invoice (2026-08-13)
+
+### Changed
+
+- Payee BOLT11 is **requested amount + 21 sats** (`create_invoice`, `create_invoice_quote`, NWC `make_invoice`)
+- Quote `collection` is **`lightning_bundled`**; payer pays one invoice
+- No separate on-chain platform-fee send on the quote pay path
+
+---
+
+## Change — minimum Lightning payment is 1,000 sats (2026-08-13)
+
+### Changed
+
+- `DEFAULT_MIN_PAYMENT_SATS` **2,000 → 1,000** (`MIN_PAYMENT_SATS`)
+- NWC min follows the same default (`NWC_MIN_PAYMENT_SATS` unset → `min_payment_sats()`)
+- Mainnet NWC **max** remains **2,000 sats**
+
+---
+
+## v.26.0.0 — 2026-08-13
+
+Align package / `__version__` / git tag after NWC, 21-sat fee, and CI hygiene.
+
+### Highlights
+
+- Public-relay NWC (NIP-44 v2) Mac ↔ AWS; listener no longer hangs or drops the second call
+- Platform fee default **21 sats** (min payment still 2,000)
+- Dependabot Actions + aiohttp / setuptools / cryptography 50
+- Docker CI: pin `trivy-action` v0.36.0 by commit SHA
+
+---
+
+## Fix — pin Trivy action so Docker CI can resolve (2026-08-13)
+
+### Fixed
+
+- `aquasecurity/trivy-action@0.28.0` no longer exists (tags moved to `v*` after the March 2026 supply-chain incident)
+- Pin `trivy-action` to commit SHA of **v0.36.0**; scan stays non-blocking (`exit-code: 0`)
+
+---
+
+## Change — platform / transaction fee default is 21 sats (2026-08-13)
+
+### Changed
+
+- `DEFAULT_FEE_AMOUNT_SATS` **1,000 → 21** (`FEE_AMOUNT_SATS` / backend `FEE_SATS`)
+- Minimum Lightning payment remains **2,000 sats** (`MIN_PAYMENT_SATS`)
+- Invoice quote `total_cost_sats` is now Lightning amount + 21 (e.g. 2,000 + 21 = 2,021)
+
+---
+
+## Fix — NWC listener handles a second Mac call (2026-08-12)
+
+### Fixed
+
+- Re-send the kind-23194 REQ every poll (`run_sync` opens a new websocket and dropped the SUB after `get_info`)
+- Publish 23195 on the live manager instead of a second `RelayManager` on the same Tornado IOLoop
+
+---
+
+## Fix — NWC public-relay listener does not hang on connect (2026-08-12)
+
+### Fixed
+
+- Probe each relay in a side thread (~2s, hard skip ~3.5s) so a dead `wss://` cannot block `add_relay` / `run_sync`
+- Long-lived SUB and client `wait_for_response` use `close_on_eose=False` (empty EOSE no longer drops the socket before 23195)
+- Do not pass the 15–30s NWC wait as `RelayManager(timeout=…)` (that made the first poll look hung)
+- AWS logs per-relay `connecting` / `ok` / `skip`, then **`subscribed, polling`** — start Mac only after that line
+
+---
+
+## Feat — NIP-44 v2 + public-relay NWC (2026-08-12)
+
+### Added
+
+- `agent_bitcoin/nostr/nip44.py` — NIP-44 v2 (ECDH / HKDF / ChaCha20 / HMAC) + spec vector tests
+- NWC client/service default encryption **`nip44_v2`** (NIP-04 only if `AGENT_BITCOIN_NWC_ALLOW_NIP04=1`)
+- NIP-46 / NIP-17 payloads use the same NIP-44 facade
+- Public-relay operator scripts: `nwc_relay_service.py` (AWS, reconnect), `nwc_relay_client.py` (Mac)
+- Defaults: `wss://relay.damus.io`, `wss://nos.lol`
+- Mainnet pay still multi-latch + 2k; Autopay off
+
+---
+
+## Feat — M3 production swarm primitives (2026-08-12)
+
+### Added
+
+- [docs/m3-production-swarm.md](docs/m3-production-swarm.md): M3 scope vs NWC N1–N6
+- `agent_bitcoin/nostr/`: NIP-46 bunker, NIP-17 gift-wrap (NIP-04 lab crypto), swarm registry, optional `WebsocketNWCRelay`
+- Examples: `nip46_bunker_demo.py`, `swarm_registry_demo.py`, `nwc_relay_loopback.py`, `nwc_dual_pay_runbook.py`
+- Tests: `tests/test_nostr_m3.py`
+- Mainnet NWC `--pay` and always-on autopay remain **off** (2k Dual pay is operator-only)
+
+---
+
+## Ops — NWC mainnet invoice smoke PASS; session closed (2026-08-12)
+
+### Documented
+
+- AWS live N6 invoice path **PASS** (`nwc_mainnet_smoke.py --yes-mainnet --amount 2000`)
+- Payment hash `7afc7a2b0c0098a61aaa64ed4b7d433424faa3996ccca70db4bafdb7f47c28e6`
+- Operator closed at invoice-only (no `--pay`); latches unset
+- Further mainnet NWC pays require a **new written go**
+
+---
+
+## Feat — NWC mainnet tight-budget go (N6) (2026-08-12)
+
+### Added
+
+- `AGENT_BITCOIN_NWC_ALLOW_MAINNET` + `assert_nwc_network_allowed()` (requires enable + LND mainnet latch)
+- Mainnet NWC default max **2,000 sats** (`DEFAULT_NWC_MAINNET_MAX_SATS` / `NWC_MAX_PAYMENT_SATS`)
+- `examples/nwc_mainnet_smoke.py` (`--yes-mainnet`, optional `--pay`)
+- Tests: `tests/test_nwc_mainnet_policy.py`
+
+### Policy
+
+- Operator go for human-attended mainnet NWC smoke only; unset latches after session
+- Autoloop remains off
+
+---
+
+## Feat — NWC decision → pay product path (N5) (2026-08-12)
+
+### Added
+
+- `agent_bitcoin/nwc/flow.py`: `decision_is_pay`, `nwc_pay_if_approved`, `rule_based_decision`
+- `examples/nwc_decision_pay.py`: offline/mock (and optional LLM) gate then NWC settle
+- SDK.md section for automatic wallets; tests in `tests/test_nwc_flow.py`
+- PaymentDecisionAgent remains recommend-only; execution only via NWC after PAY
+
+---
+
+## Feat — NWC LND service (N4) (2026-08-12)
+
+### Added
+
+- `NWCService`: authorize clients, enforce budgets/enable latch, dispatch to LND
+- `create_nwc_service()`, `issue_connection()` → `nostr+walletconnect://` URI
+- Offline tests with FakeLND (`tests/test_nwc_service.py`)
+- `examples/nwc_regtest_smoke.py` (`--mock` or live docker LND)
+- Mainnet still off unless `AGENT_BITCOIN_NWC_ENABLE=1` + separate go
+
+---
+
+## Feat — NWC client + mock bus (N3) (2026-08-12)
+
+### Added
+
+- `NWCClient`: encrypted NIP-47 requests (`get_info`, `get_balance`, `make_invoice`, `pay_invoice`)
+- `InMemoryNWCBus` + `attach_mock_wallet` for offline/lab tests (no WebSocket relays)
+- NIP-04 payload crypto via pynostr; tests in `tests/test_nwc_client.py`
+- No LND-backed service yet (N4)
+
+---
+
+## Feat — NWC scaffold URI + policy (N2) (2026-08-12)
+
+### Added
+
+- `agent_bitcoin/nwc/`: `parse_nwc_uri`, `build_nwc_uri`, v1 method allowlist, amount budgets, `AGENT_BITCOIN_NWC_ENABLE` kill switch
+- Offline tests: `tests/test_nwc_uri.py`, `tests/test_nwc_policy.py`
+- No client/service wire protocol yet (N3–N4)
+
+---
+
+## Docs — NWC automatic wallets design (2026-08-12)
+
+### Added
+
+- [docs/nwc-automatic-wallets.md](docs/nwc-automatic-wallets.md): NIP-47 automatic wallets ADR — architecture, allowlist, budgets, phases N0–N6
+- Policy go: **design + regtest implementation**; mainnet NWC remains frozen
+- Cross-links: index, mainnet-pilot, nostr-agent-identity
+
+---
+
+## Ops — Nostr mainnet M2 Dual 2k SUCCESS (2026-08-12)
+
+### Done
+
+- Private dual channel Mac↔AWS: 25k capacity, push 12k to Mac (`b76115f9…1002:0`)
+- Phase B signed bus: request → AWS invoice → Mac pay **2000 sats SUCCEEDED** (fee 0)
+- Payment hash `f87a39a3597a59859436d6d947e3788cc6e1dc5cea9dc092f0d715a70fa8ca71`
+- Phase B defaults `LND_TRANSPORT=docker` to avoid stale signet gRPC `:30009` failures
+
+### Hard stop
+
+- No further Nostr mainnet pays without a new N budget; Autoloop/NWC/autopay remain off
+
+---
+
+## Ops/docs — Nostr mainnet M2 Dual go (2026-08-12)
+
+### Policy
+
+- **M2 go:** Dual path (Mac alice → AWS bob), **2,000 sats** max, human-attended, autopay off
+- Capital HOLD still covers deposits / new channels / Loop / Autoloop
+- Live pay pending Stage 3 (Mac wallet unlock + outbound path) and Stage 5 dry-run
+
+### Documented
+
+- Expanded dual-host runbook Stages 3–6 in [docs/nostr-agent-identity.md](docs/nostr-agent-identity.md)
+
+---
+
+## Ops/docs — Nostr mainnet Stage 2 Phase C (2026-08-12)
+
+### Done
+
+- Phase C local policy signer **PASS** for alice + bob against `.nostr-poc-mainnet` keys (client never loaded nsec; policy deny verified)
+- CLI: `nostr_phase_c_signer.py` accepts `--agent` / `--dir` before **or** after the subcommand
+- M2 pay still deferred; Dual path reserved
+
+---
+
+## Ops/docs — Nostr mainnet M1 identity (2026-08-12)
+
+### Done
+
+- **Stage 0 go:** M1 only; Dual path reserved for later M2; capital HOLD unchanged
+- **M1:** dedicated alice/bob keys under gitignored `.nostr-poc-mainnet/`; Phase A offline crypto **PASS**
+- `.gitignore` covers `.nostr-poc-mainnet/`; no nsec/passphrase in git
+- ADR + pilot post-pilot table record M1 complete; M2/M3 still deferred
+
+---
+
+## Docs — Nostr mainnet process (not yet executed) (2026-08-11)
+
+### Documented
+
+- Confirmed Nostr Phase A/B live on **regtest + signet only**; mainnet identity/pay and NWC remain **frozen** without a new go
+- Step-by-step mainnet process (M1 identity → M2 2k smoke → M3 roadmap) in [docs/nostr-agent-identity.md](docs/nostr-agent-identity.md)
+- Cross-links in [docs/mainnet-pilot.md](docs/mainnet-pilot.md) and [docs/index.md](docs/index.md)
+- Phase B example prints `LND_NETWORK` and mainnet warning; live mainnet still gated by `AGENT_BITCOIN_ALLOW_MAINNET=1` in `LNDClient`
+
+---
+
+## Docs — topology A′ Loop Out complete + capital HOLD (2026-08-11)
+
+### Documented
+
+- First mainnet **Loop Out SUCCESS** (250k; ~841 sats total cost) and dual **public** channels (ACINQ + LNBiG, 500k each)
+- **Capital intent: HOLD as-is** — no further opens, deposits, or swaps without a new go; Autoloop remains **off**
+- Updated [docs/public-routing-loop.md](docs/public-routing-loop.md): execution log, P0–P3 checkmarks, steady-state HOLD ops
+- Updated [docs/mainnet-pilot.md](docs/mainnet-pilot.md): post-pilot decision table + cross-links
+- [docs/index.md](docs/index.md) index line for A′ status
+
+### Ops note (not automated)
+
+- L402 `timeout_seconds` fix remains in [docker/loop-timeout-fix/](docker/loop-timeout-fix/) (merged PR #56)
+
+---
+
+## Docs — public routing + Loop design (2026-08-10)
+
+### Added
+
+- [docs/public-routing-loop.md](docs/public-routing-loop.md): post-pilot **topology A′** — single AWS LND opens **public** channels to external peers; **loopd** manages liquidity; Mac not permanent partner; no second AWS agent required
+- P0–P4 operator checklist (policy, harden, open, Loop, product integration)
+
+### Changed
+
+- [docs/mainnet-pilot.md](docs/mainnet-pilot.md): cooperative close in pilot log; post-pilot table points at public-routing design
+- Cross-links in index, liquidity-automation, loop-multi-network, loop-autoloop
+
+---
+
+## Docs — mainnet Phase 8 ops pilot (2026-08-10)
+
+### Documented
+
+- **Phase 8 ops complete:** dual-node mainnet private channel (43k sats), fund ≤50k, **N=5** human-attended Lightning pays via `lncli`
+- Updated [docs/mainnet-pilot.md](docs/mainnet-pilot.md): pilot log, BIP-110 freeze historical, **pilot-complete checklist**, post-pilot non-goals
+- Aligned [docs/mainnet-infra.md](docs/mainnet-infra.md), [docs/loop-multi-network.md](docs/loop-multi-network.md), [docs/liquidity-topology-b.md](docs/liquidity-topology-b.md), [docs/index.md](docs/index.md), README
+
+### Still out of scope (unchanged policy)
+
+- Mainnet Autoloop / raising loss budget / autonomous autopay without a new go decision
+- SDK mainnet pay path remains optional post-pilot validation
+
+---
+
+## [23.1.0] - 2026-07-14
+
+### Major Changes
+- **Split architecture support**: AWS backend (`agent-payment-decision-lnd` + `bitcoind`) + Mac counterparty node
+- **Persistent chain mode**: New `startup-aws.sh` (no aggressive reset) and `startup-aws-reset.sh` for full reset when needed
+- **Improved startup scripts**: `startup-mac.sh` and `shutdown-mac.sh` for local testing
+- **Better Docker Compose separation**: `docker-compose.regtest.aws.yml` and `docker-compose.regtest.mac.yml`
+
+### Added
+- Channel opening and Lightning payments between Mac and AWS nodes
+- Automatic wallet detection (create vs unlock)
+- Pre-warming and mining logic for faster startup
+- TestPyPI publishing workflow
+
+### Fixed
+- Port binding and firewall issues on AWS (18443/9735)
+- LND sync and "block height out of range" errors
+- Wallet unlock reliability across restarts
+- Docker service name and volume management
+
+### Dependencies
+- Updated to support latest Lightning Labs LND (v0.17.5-beta / v0.18.5-beta)
+
+[Compare with previous version](https://github.com/gpu7/agent-bitcoin/compare/23.0.0...23.1.0)

agent_bitcoin-26.2.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 [Richard Casey]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_bitcoin-26.2.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude *.pyc
+global-exclude __pycache__/

agent_bitcoin-26.2.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: agent-bitcoin
+Version: 26.2.0
+Summary: Lightning Bitcoin payments for autonomous AI Agents.
+Author-email: Richard Casey <richardcaseyhpc@protonmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gpu7/agent-bitcoin
+Project-URL: Repository, https://github.com/gpu7/agent-bitcoin
+Project-URL: Documentation, https://github.com/gpu7/agent-bitcoin/blob/main/README.md
+Project-URL: Issues, https://github.com/gpu7/agent-bitcoin/issues
+Project-URL: Changelog, https://github.com/gpu7/agent-bitcoin/blob/main/CHANGELOG.md
+Keywords: bitcoin,lightning,lightning-network,ai-agents,sdk,crypto-payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: grpcio-tools>=1.60.0
+Requires-Dist: lnd-grpc-client>=0.5.0
+Requires-Dist: langchain-ollama>=1.1.0
+Requires-Dist: langchain-xai>=1.2.2
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
+Requires-Dist: langchain-ollama>=0.1.0; extra == "langchain"
+Requires-Dist: langchain-xai>=0.1.0; extra == "langchain"
+Provides-Extra: nostr
+Requires-Dist: pynostr[websocket-client]>=0.6.0; extra == "nostr"
+Requires-Dist: cryptography>=50.0.0; extra == "nostr"
+Dynamic: license-file
+
+<br>
+
+<p align="center">
+  <img src="./images/dark-factory-image.jpg" alt="Dark Factory Agent Bitcoin" width="700"/>
+</p>
+
+<br>
+
+[![PyPI](https://img.shields.io/pypi/v/agent-bitcoin)](https://pypi.org/project/agent-bitcoin/)
+[![Python](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Release](https://img.shields.io/github/v/release/gpu7/agent-bitcoin)](https://github.com/gpu7/agent-bitcoin/releases/latest)
+[![GitHub Repo](https://img.shields.io/badge/GitHub-gpu7/agent--bitcoin-black)](https://github.com/gpu7/agent-bitcoin)
+
+<br>
+
+## Lightning Bitcoin payments for autonomous AI Agents
+
+A lightweight Python SDK that enables AI agents to send and receive Lightning/Bitcoin payments.
+
+| Doc | Who it's for |
+|-----|----------------|
+| **[SDK.md](SDK.md)** | App & agent developers (install, API, fees, quotes, LLM agents, HTTP API) |
+| **[docs/backend.md](docs/backend.md)** | Operators: AWS/Mac **regtest** dual-node lab |
+| **[docs/signet.md](docs/signet.md)** | Operators: dual-node **signet** (current pre-mainnet lab) |
+| **[docs/mainnet-pilot.md](docs/mainnet-pilot.md)** | Mainnet pilot **Phases 0–8** (ops complete; ≤50k dual-node) |
+| **[docs/public-routing-loop.md](docs/public-routing-loop.md)** | Topology A′: public channels + first Loop Out done; capital HOLD; Autoloop off |
+
+---
+
+## Features
+
+- Simple, agent-friendly API (`create_client`)
+- Create and pay Lightning invoices (**payee** creates, **payer** pays)
+- **Explicit invoice quotes** for independent agents (`create_invoice_quote` / `pay_invoice_quote`) — one BOLT11 for the requested amount
+- LND transports: **docker** `lncli` (lab default) or **gRPC** + macaroon ([docs/lnd-client.md](docs/lnd-client.md))
+- Networks: **regtest** (default), **signet**, testnet; **mainnet** only with explicit latch
+- Pydantic models and structured errors
+- Optional LLM **payment decision** agent (PAY / REJECT / CONFIRM — never executes pays)
+- Balance checks (Lightning and on-chain)
+- Operator tooling: dual-node health, SCB backup, daily ops ([docs/index.md](docs/index.md))
+- Optional **Aperture L402** HTTP gateway (regtest PoC; Mac pays AWS `:8081`) — [docs/l402-aperture.md](docs/l402-aperture.md)
+
+---
+
+## Roles: payee and payer
+
+| Role | Does |
+|------|------|
+| **Payee** | Creates the invoice (and quote); receives **X sats** over Lightning |
+| **Payer** | Validates quote / budget; pays the BOLT11 amount (plus optional Lightning routing fee limit) |
+
+Either physical node (AWS agent LND or Mac counterparty LND) can act as payee or payer depending on who creates the invoice.
+
+---
+
+## Payment amounts
+
+There is **no platform / transaction fee**. A requested payment of **X** sats creates and pays a BOLT11 for **exactly X**. Lightning **routing** fees (the `fee_limit_sats` / `routing_fee_limit_sats` cap) are separate and still apply when paying.
+
+| Rule | Default |
+|------|--------|
+| Platform / transaction fee | **None** |
+| Minimum Lightning invoice amount | **1,000 sats** (`MIN_PAYMENT_SATS`) |
+
+For independent agents, prefer **`create_invoice_quote`** so the payer sees `amount_sats` / `total_cost_sats` without shared env. Details: **[SDK.md](SDK.md#transaction-fees-and-limits)**.
+
+There is no `collect_transaction_fee` / `POST /send-fee`. Mainnet **pays** stay latch-gated — see [docs/mainnet-pilot.md](docs/mainnet-pilot.md).
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install agent-bitcoin
+```
+
+### From source
+
+```bash
+git clone https://github.com/gpu7/agent-bitcoin.git
+cd agent-bitcoin
+uv sync
+```
+
+More detail (optional LangChain / Grok / Ollama deps): **[SDK.md](SDK.md#installation)**.
+
+---
+
+## Quick start
+
+```python
+from agent_bitcoin import create_client
+
+client = create_client()
+
+# Payee: invoice + explicit quote for independent payers
+quote = client.create_invoice_quote(memo="Test payment", amount_sats=2000)
+# quote.payment_request, amount_sats, total_cost_sats (equals amount)
+
+# Payer: validate / decision inputs, then pay Lightning amount
+inputs = client.build_payer_decision_inputs(quote, routing_fee_limit_sats=200)
+if inputs.quote_valid:
+    result = client.pay_invoice_quote(quote, routing_fee_limit_sats=200)
+    if result.success:
+        print(f"Paid {result.amount} sats (LN); total_cost was {quote.total_cost_sats}")
+```
+
+Bare `create_invoice` / `pay_invoice` remain available for simple lab flows.
+
+Configure LND via env (`LND_NETWORK`, `LND_TRANSPORT=docker|grpc`, container or gRPC cert/macaroon).
+Full API → **[SDK.md](SDK.md)**.
+Regtest operators → **[docs/backend.md](docs/backend.md)**.
+Signet operators → **[docs/signet.md](docs/signet.md)**.
+
+---
+
+## Security
+
+Agent-Bitcoin is developed with security in mind:
+
+- **Secrets stay out of the repository** — API keys, wallet material, and host credentials are configured via environment and local ops practice, not committed source
+- **Least privilege** for network and node access (admin/API/RPC not left open to the whole internet in operator deployments)
+- **Conservative defaults** for payment amounts and fees (see [SDK.md](SDK.md))
+- **Authenticated payment APIs** — backend balance/invoice/pay routes require an API key when deployed
+- **Bounded autonomous payment decisions** — hard amount limits in code before any LLM approval
+- **Mainnet kill switches** — e.g. `AGENT_BITCOIN_ALLOW_MAINNET`, `AGENT_BITCOIN_ALLOW_AUTOPAY`, daily spend caps
+- **Operator health checks** — dual-node signet health, backups ([docs/daily-ops-signet.md](docs/daily-ops-signet.md), [docs/security-hardening.md](docs/security-hardening.md))
+- **Regtest / signet first** for lab work; mainnet is never the implicit default (pilot ops complete under ≤50k dual-node — [docs/mainnet-pilot.md](docs/mainnet-pilot.md))
+
+Report vulnerabilities privately — see **[SECURITY.md](SECURITY.md)**. Do not open public issues for security reports.
+
+---
+
+## Documentation
+
+| Link | Description |
+|------|-------------|
+| [SDK.md](SDK.md) | Python SDK, quotes, fees, LLM agents, Backend HTTP API |
+| [docs/index.md](docs/index.md) | Full docs index (signet, mainnet readiness, backup, health, liquidity) |
+| [docs/backend.md](docs/backend.md) | Regtest dual-node workflow |
+| [docs/signet.md](docs/signet.md) | Signet dual-node lab |
+| [docs/mainnet-pilot.md](docs/mainnet-pilot.md) | Mainnet pilot Phases 0–8 (ops complete; ≤50k dual-node) |
+| [docs/public-routing-loop.md](docs/public-routing-loop.md) | Public routing + Loop on AWS (topology A′; HOLD) |
+| [examples/](examples/) | Runnable sample scripts (incl. signet product path) |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
+| [SECURITY.md](SECURITY.md) | Security policy and vulnerability reporting |
+
+---
+
+## Repository
+
+- GitHub: https://github.com/gpu7/agent-bitcoin
+- PyPI: https://pypi.org/project/agent-bitcoin/
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE).
+
+---
+
+## Support
+
+Richard Casey
+richardcaseyhpc@protonmail.com
++1 970-980-5975