Metadata-Version: 2.4
Name: ln-church-agent
Version: 0.5.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, uniquely extended with EVM cross-chain support (x402) and Zero-Balance Faucets.**

## 🧩 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.
* **Deterministic Receipts:** Capture and normalization of payment proofs (JWS).



## 📦 Installation

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

## 🚀 Quick Start (Generic Client)

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

The client is designed to communicate with any API endpoint that implements the x402/L402 protocol standards. **It seamlessly abstracts both EVM Gasless (x402) and Lightning Network (L402) settlements.**


### ⚡ 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` (Admin or Invoice key).
* **Alby:** Set `ln_provider="alby"`. Pass your Alby Bearer Access Token into the `ln_api_key` parameter. The URL is handled automatically.

```python
from ln_church_agent import Payment402Client, AssetType

# 1. Initialize the generic 402 client with full capabilities
# You can easily switch Lightning providers (e.g., "lnbits" or "alby").
client = Payment402Client(
    private_key="0xYourAgentPrivateKey...",      # Required for x402 & Identity
    base_url="https://your-custom-402-api.com/api/agent",
    
    # --- Lightning Network Setup ---
    # Example A: Using LNBits (Default)
    ln_api_url="https://your-lnbits-url",
    ln_api_key="your-lnbits-api-key",
    
    # Example B: Using Alby
    ln_provider="alby", 
    ln_api_key="your-alby-access-token"  # Acts as the universal token/key slot
)

# 2. Execute with Polygon Gasless (x402)
# The SDK handles EIP-712 hashing, signing, and relayer orchestration.
result_x402 = client.draw_omikuji(asset=AssetType.USDC)

# OR Execute with Lightning Network (L402)
# The SDK parses the Macaroon, pays the Bolt11 invoice via your chosen provider.
result_l402 = client.draw_omikuji(asset=AssetType.SATS)

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

## 🔌 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.


## ⛩️ Reference Service: LN Church Oracle

This SDK comes bundled with **LN Church** (`https://kari.mayim-mayim.com/api/agent`) as its primary reference API. 
LN Church is a high-uptime entropy oracle and capability benchmark for AI agents. By default, if `base_url` is omitted, the SDK connects to the LN Church Oracle to help you test your agent's payment capabilities instantly.

```python
from ln_church_agent import LnChurchClient, AssetType

# Connects to the LN Church Reference API using the bundled adapter
client = LnChurchClient(
    private_key="0xYourEVMKey...", 
    ln_api_url="https://your-lnbits", 
    ln_api_key="your-lnbits-key"
)

client.init_probe()             # Verify connectivity
client.claim_faucet_if_empty()  # Get free test credits if balance is zero
result = client.draw_omikuji()  # Execute paid oracle
```

## 🦜 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
```

---
