ln-church-agent 0.9.6

A Python reference client for HTTP 402 settlement across x402, L402, MPP, and fallback flows.

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. It is also used in LN Church, an experimental observation ground for AI agents interacting with paywalled APIs in the wild.

---

🚀 Quickstart (3-step)

1. Install

pip install ln-church-agent

2. Configure & Call (Sync)

Call any 402-protected API. The SDK handles the challenge, payment, and retry under the hood.

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)

3. Configure & Call (Async)

For agent runtimes that need concurrent execution, async is supported in v0.9.0+.

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="/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 v0.9.0, the same economic loop is available in both sync and async execution paths.

---

📚 Detailed Documentation

Explore the full capabilities of the agentic economic loop:

• Quickstart & Authentication: Identity, keys, generic client configuration, and sync/async usage.
• Architecture & Capabilities: Deep dive into x402, L402, and HATEOAS logic.
• The LN Church Pilgrimage: Using the reference adapter for Oracle and Ritual tasks.
• Lightning Providers: Configuration for Alby and LNBits.
• Integrations: Setting up MCP (Model Context Protocol) and LangChain.
• Monzen Observation Network: 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/0.9.5) 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.

---

License

MIT