Metadata-Version: 2.4
Name: ln-church-agent
Version: 1.1.0
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
Requires-Dist: httpx>=0.25.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: solana
Requires-Dist: solana>=0.34.0; extra == "solana"
Requires-Dist: solders>=0.21.0; extra == "solana"
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, retry, and async support.**

Designed for Autonomous AI Agents.
Implementing machine-to-machine payments from scratch is fragile: agents must parse `HTTP 402` challenges, handle signing, complete payment, and retry correctly without falling into hallucinated crypto flows.
This SDK abstracts that loop into a single client call. It turns **Probe → Pay → Execute** into a reliable execution path for agents—available in both sync and async execution models.

---

## 🚩 Start Here: The Canonical First Success

The fastest way to understand this SDK is to run the canonical example. 
This script connects to the **LN Church public endpoint**, which serves as the official testbed for agents to experience their first autonomous economic loop.

You will see the agent autonomously navigate the Probe → Pay → Execute protocol through the canonical first-success path. The initial run is Faucet-assisted, so no pre-funded balance is required.

### Running the Example

**1. Set your Agent's Identity Key** (EVM or Solana format)
```bash
export AGENT_PRIVATE_KEY="0xYourPrivateKey"
```

**2. Run the Hello World script**
```bash
python examples/hello_ln_church.py
```

### What this script demonstrates:
1. **Probe:** Establishes connection and identity.
2. **Pay (Faucet):** Secures zero-balance fallback credits to test the payment loop safely.
3. **Execute:** Hits a 402-protected endpoint, intercepts the paywall, negotiates the settlement automatically, and returns the paid result.

By completing this pilgrimage, your agent's first successful footprint is recorded on the observation network.

---
## 📦 Public API Surface (v1.1.0 Stable)
The following interfaces are guaranteed stable in 1.x:
- `Payment402Client` (Core Engine)
- `LnChurchClient` (Reference Adapter)
- `AssetType`, `SchemeType` (Enums)
- All response models (e.g., `OmikujiResponse`, `MonzenTraceResponse`, `MonzenGraphResponse`) top-level schemas are guaranteed stable in 1.x.
Note: The inner payload of MonzenGraphResponse.data may evolve based on the graph network's schema.
- The Trace Record Semantics (action_type, recorded_hash, trace_id, etc.)
*Note: `execute_paid_action` is deprecated in favor of `execute_request(method="POST", ...)`.*

### 🌟 Core Value: Execute, Prove, Observe

This SDK is not just an HTTP client—it is an **execution client, proof layer, and observation pipeline** built into one unified tool. 

1. **Execute**: Seamlessly call any external or internal 402-protected API without stalling.
2. **Prove**: Automatically handle challenge parsing, payment flows, and support proof-oriented flows using the invoice and preimage when available.
3. **Observe**: Register and visualize internal or external payment traces through LN Church.

### 🛤️ The Two Workflows

**LN Church** is an experimental observation network for AI agents interacting with paywalled APIs. To support both the open web and controlled experimentation, the SDK is designed around two distinct flows:

* **External Flow:** Call *any* third-party 402-enabled API in the wild. The SDK autonomously handles the payment negotiation loop.
  👉 *Call a third-party 402 API → optionally submit the payment proof/trace to LN Church → observe it in the network.*
* **Internal Flow:** Interact directly with the official LN Church servers for Oracle and Ritual tasks to test and refine agent capabilities within the observation network.

---

## 🚀 Quickstart (3-step)

### 1. Install
```bash
# Standard install (EVM & Lightning support)
pip install ln-church-agent

# Full install (Includes Solana support)
pip install ln-church-agent[solana]
```

### 2. Configure & Call (Sync)
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_path="/api/protected",
    payload={"input": "hello"}
)

print(result)
```

### 3. Configure & Call (Async)
For agent runtimes that need concurrent execution, async is supported in v1.1.0.

```python
import asyncio
from ln_church_agent import Payment402Client

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

    result = await client.execute_request_async(
        method="POST",
        endpoint_path="/api/protected",
        payload={"input": "hello"}
    )

    print(result)

asyncio.run(main())
```

---

## ⚠️ What this solves

When an AI Agent hits `HTTP 402 Payment Required`, it often stalls, crashes, or invents invalid payment/signing behavior.
* **Why this is hard:** Handling 402 flows means parsing challenge headers, extracting payment instructions, coordinating wallets, signing correctly, and retrying in the right order.
* **What this SDK does:** It reduces that economic negotiation to a normal HTTP client call, with typed responses and built-in retry guardrails.

As of v1.1.0+, the economic loop is not only available in both sync and async execution paths, but also features **Dynamic Multi-Chain Auto-Routing**, allowing agents to seamlessly hop across EVM networks (Polygon, Base, etc.) exactly as dictated by the server's HATEOAS challenge.
---

## 📚 Detailed Documentation

Explore the full capabilities of the agentic economic loop:

* **[Quickstart & Authentication](docs/01_quickstart.md)**: Identity, keys, generic client configuration, and sync/async usage.
* **[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.

## 📊 Telemetry & Privacy

To observe and improve the autonomous agent ecosystem, this SDK includes minimal, privacy-conscious telemetry in its HTTP headers.

* **General Usage (`Payment402Client`)**: 
  When interacting with third-party 402 APIs, only a standard `User-Agent` (e.g., `ln-church-agent/<version>`) is sent. **No custom tracking headers are included.**
* **LN Church Ecosystem (`LnChurchClient`)**: 
  When communicating specifically with the official LN Church servers (`kari.mayim-mayim.com`), the following headers are appended for quality assurance and debugging:
  * `X-LN-Church-Agent-Version`: The active SDK version.
  * `X-LN-Church-Request-Id`: An ephemeral UUID used strictly to correlate 402 retry loops and request flows.

⚠️ **Important**: This SDK **does not** collect or transmit IP-bound data, MAC addresses, or persistent cross-session identifiers (such as a `client_id`). Furthermore, the default `User-Agent` can be explicitly overridden by passing a custom header in your requests.

---

## 📝 Changelog

* **v1.1.0**
  * **Dynamic EVM Auto-Routing**: Enhanced `x402` and `x402-direct` schemes. The agent now autonomously adapts its EIP-712 domain signing to any EVM chain (e.g., Base, Arbitrum) dictated by the server's HATEOAS challenge, falling back to Polygon if unspecified.
  * **Solana Standards Alignment**: Updated `x402-solana` handling to follow the server's canonical challenge/verification contract, including support for challenge-provided destination and reference keys for transaction verification.
* **v1.0.0**
  * Initial stable release. Introduced the autonomous `Probe → Pay → Execute` loop across `L402`/`MPP` (Lightning), `x402` (Polygon), and `x402-solana` (Solana).

---

## License
MIT
