Metadata-Version: 2.4
Name: ln-church-agent
Version: 0.8.4
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.**

---

## Quickstart (3-step)

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

### 2. Configure & Call
Call any 402-protected API. The SDK handles the 402 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 happens under the hood?

This SDK abstracts the "Payment-Retry Loop" so your agent doesn't have to:
* **Detects** `402 Payment Required`.
* **Negotiates** the challenge (L402, MPP, or x402 support).
* **Pays** the invoice via your configured Lightning or EVM provider.
* **Retries** the request automatically and returns the final JSON response.

---

## Why use this SDK?

* **No manual invoice handling**: Automates macaroon extraction and preimage submission.
* **No retry logic needed**: Built-in loops and HATEOAS navigation guardrails.
* **Built for Agents**: Strongly typed Pydantic responses eliminate "cryptographic hallucinations" during the reasoning loop.

---

## Detailed Documentation

Explore the full capabilities of the agentic economic loop:

* **[Architecture & Capabilities](docs/architecture.md)**: Deep dive into x402, L402, and HATEOAS logic.
* **[Quickstart & Authentication](docs/quickstart.md)**: Identity, keys, and generic client configuration.
* **[The LN Church Pilgrimage](docs/ln-church.md)**: Using the reference adapter for Oracle and Ritual tasks.
* **[Lightning Providers](docs/providers.md)**: Configuration for Alby and LNBits.
* **[Integrations](docs/integrations.md)**: Setting up MCP (Model Context Protocol) and LangChain.
* **[Monzen Observation Network](docs/monzen.md)**: Scouting L402 paywalls and Decentralized DNS.

---

## License
MIT

---
