Metadata-Version: 2.4
Name: ln-church-agent
Version: 0.6.1
Summary: A Python reference client for HTTP 402 settlement across x402, L402, 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
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: mcp>=1.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ln-church-agent

**A Python reference client abstraction for HTTP 402 (Payment Required) settlement, built for Autonomous AI Agents.**

Implementing machine-to-machine (M2M) payments from scratch is painful and highly prone to cryptographic hallucinations during an AI agent's reasoning loop. **ln-church-agent** abstracts the entire "Settlement Negotiation" process triggered by HTTP 402 errors, allowing agents to seamlessly pay for APIs, oracles, and services without manual intervention.

**Fully compatible with Lightning Labs' L402 protocol standards and the emerging Machine Payments Protocol (MPP), uniquely extended with EVM cross-chain support (x402).**

## 🧩 What it abstracts

This SDK natively handles the "Payment-Retry Loop" so your agent doesn't have to:
* **x402 (EVM Gasless):** Autonomous EIP-712/EIP-3009 signing and relayer orchestration.
* **L402 (Lightning Network):** Macaroon extraction, Bolt11 parsing, preimage submission, and **multi-provider wallet support (LNBits, Alby)**.
* **Zero-Balance Fallback:** Automatic claim-and-bypass logic via Faucet.
* **Verifiable Receipts:** Capture and pass-through of verifiable execution receipts for downstream verification.

## 📦 Installation

```bash
pip install ln-church-agent
```

## 🚀 Quick Start

> **Note:** The core client currently works out-of-the-box with 402 challenge shapes compatible with the LN Church protocol. It is designed to evolve toward broader, protocol-agnostic 402 client reuse in future releases.

### 1. Generic Core Example (`Payment402Client`)
Use the pure core client to execute raw payloads against 402-protected endpoints. The core automatically intercepts the 402 challenge, negotiates the payment (x402 or L402), and retries the request.

```python
from ln_church_agent import Payment402Client

client = Payment402Client(
    private_key="0xYourAgentPrivateKey...",
    base_url="https://your-custom-402-api.com/api/agent",
    ln_provider="lnbits",
    ln_api_url="https://your-lnbits-url",
    ln_api_key="your-lnbits-api-key"
)

# Execute a generic POST request. The SDK handles the 402 payment loop.
result = client.execute_paid_action(
    endpoint_path="/omikuji",
    payload={
        "agentId": "0xYourAgentAddress",
        "clientType": "AI",
        "scheme": "x402",
        "asset": "USDC"
    }
)
print(result)
```

### 2. Reference Adapter Example (`LnChurchClient`)
This SDK comes bundled with a reference adapter for **LN Church** (`https://kari.mayim-mayim.com/api/agent`). It extends the core client with domain-specific methods (Probe, Faucet, Omikuji).

```python
from ln_church_agent import LnChurchClient, AssetType

# Initialize the Reference Adapter (Inherits from Payment402Client)
client = LnChurchClient(
    private_key="0xYourEVMKey...", 
    ln_provider="alby", 
    ln_api_key="your-alby-access-token"
)

client.init_probe()             # Verify connectivity
client.claim_faucet_if_empty()  # Get free test credits if balance is zero
result_l402 = client.draw_omikuji(asset=AssetType.SATS) # Execute autonomous L402 payment

print(f"Receipt: {result_l402.receipt.txHash}")
```

### ⚡ Supported Lightning Providers
You can configure the backend Lightning node used for L402 settlements by setting the `ln_provider` argument:
* **LNBits (Default):** Set `ln_provider="lnbits"`. Requires both `ln_api_url` and `ln_api_key`.
* **Alby:** Set `ln_provider="alby"`. Pass your Alby Bearer Access Token into the `ln_api_key` parameter.

## 🔌 MCP (Model Context Protocol) Integration

You can instantly equip any MCP-compatible agent (like Claude Desktop) with cross-chain 402-payment capabilities. The bundled MCP server provides a tool called `execute_paid_entropy_oracle`.

Run the MCP server:
```bash
# Requires AGENT_PRIVATE_KEY in your environment variables
python -m ln_church_agent.integrations.mcp
```

**What the AI Agent sees:**
The agent can autonomously choose the settlement layer by passing the `asset_type` argument (`"USDC"`, `"JPYC"`, or `"SATS"`). The SDK will autonomously negotiate the 402 challenge and return the cryptographic receipt to the agent's context.

## 🦜 LangChain Integration

Easily integrate the client into your LangChain agent's toolset:

```python
from ln_church_agent.integrations.langchain import LNChurchOracleTool

tools = [LNChurchOracleTool(private_key="0x...")]
# Pass this tool to your LangChain AgentExecutor
```

## License
MIT
```

---
