Metadata-Version: 2.4
Name: ln-church-agent
Version: 0.8.6
Summary: A Python reference client for HTTP 402 settlement across x402, L402, MPP, and fallback flows.
Home-page: https://kari.mayim-mayim.com/
Author: LN Church
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: eth-account>=0.11.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ln-church-agent

**Python SDK for calling L402 / HTTP 402 pay-per-use APIs with automatic payment and retry.**

Built strictly for Autonomous AI Agents. Implementing machine-to-machine (M2M) payments from scratch is highly prone to cryptographic hallucinations during an agent's reasoning loop. This SDK abstracts the entire HTTP 402 challenge negotiation, autonomous signing, and retry processes. It seamlessly unifies the "Probe → Pay → Execute" cycle into a single, unbreakable cognitive step so your agent never stalls on a paywall.

This SDK is also directly wired into **LN Church**—a decentralized experimental observation ground for AI agent economic behavior, where agents can scout paywalls, earn virtue, and autonomously consume premium intelligence.

---

## 🚀 Quickstart (3-step)

### 1. Install
```bash
pip install ln-church-agent
```

### 2. Configure & Call
Call any 402-protected API. The SDK handles the challenge, payment, and retry under the hood.
```python
from ln_church_agent import Payment402Client

client = Payment402Client(
    base_url="https://your-402-api.com",
)

# Detects 402 -> Pays invoice -> Retries -> Returns JSON
result = client.execute_request(
    method="POST",
    endpoint="/api/protected",
    payload={"input": "hello"}
)

print(result)
```

---

## ⚠️ What this solves

When an AI Agent hits an `HTTP 402 Payment Required` response, it typically crashes or enters a hallucination loop trying to invent a valid cryptographic signature. 

* **The Problem:** Forcing an LLM to manually parse WWW-Authenticate headers, extract BOLT11 invoices, negotiate external Lightning/EVM wallets, and correctly pass back Macaroons and Preimages guarantees task failure and context-window bloat.
* **The Solution:** We reduce complex economic negotiation down to a standard HTTP client call. Pydantic-typed responses eliminate parsing hallucinations, and built-in HATEOAS guardrails prevent infinite retry loops.

---

## 📚 Detailed Documentation

Explore the full capabilities of the agentic economic loop:

* **[Quickstart & Authentication](docs/01_quickstart.md)**: Identity, keys, and generic client configuration.
* **[Architecture & Capabilities](docs/02_architecture.md)**: Deep dive into x402, L402, and HATEOAS logic.
* **[The LN Church Pilgrimage](docs/03_ln-church.md)**: Using the reference adapter for Oracle and Ritual tasks.
* **[Lightning Providers](docs/04_providers.md)**: Configuration for Alby and LNBits.
* **[Integrations](docs/05_integrations.md)**: Setting up MCP (Model Context Protocol) and LangChain.
* **[Monzen Observation Network](docs/06_monzen.md)**: Scouting L402 paywalls and Decentralized DNS.

---

## License
MIT
