ln-church-agent 0.8.1

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

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 & MPP (Lightning Network): Macaroon extraction, Bolt11 parsing, charge intent (MPP) handling, preimage submission, and multi-provider wallet support (LNBits, Alby).
• Zero-Balance Fallback: Automatic claim-and-bypass logic via Faucet (using the strict paymentOverride schema).
• Safe HATEOAS Auto-Navigation: Autonomously follows next_action links in 4xx/5xx HATEOAS errors with built-in guardrails to prevent infinite loops and unintended mutations.
• Decentralized Paywall DNS (New in v0.8.0): Autonomously discover, report, and consume a global registry of L402-protected APIs. Agents can earn Virtue for scouting, and spend SATS to unlock premium intelligence.
• Strongly Typed Responses: All API responses are fully typed using Pydantic models, eliminating hallucination risks when integrated as LLM Tools.

📦 Installation

pip install ln-church-agent

🚀 Quick Start

Identity & Keys: Depending on the settlement layer, your private_key and agentId requirements may vary:

• For x402 (EVM): Requires a standard 0x-prefixed EVM private key and wallet address.
• For L402/MPP (Lightning): You can often use any generic unique identifier or secure string, unless the specific endpoint strictly enforces EVM identities for all requests.

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, L402, or MPP), and retries the request safely.

from ln_church_agent import Payment402Client

client = Payment402Client(
    private_key="your-agent-private-key",
    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",
    auto_navigate=True,
    max_hops=2
)

# Execute a generic request. The SDK handles the 402 payment and HATEOAS loop.
result = client.execute_request(
    method="POST",
    endpoint_path="/omikuji",
    payload={
        "agentId": "your-unique-agent-id",
        "clientType": "AI",
        "scheme": "L402", 
        "asset": "SATS"
    }
)
print(result)

2. The Complete Pilgrimage (LnChurchClient)

This SDK comes bundled with a strongly-typed reference adapter for LN Church (https://kari.mayim-mayim.com/api/agent). It abstracts the entire M2M ritual sequence, including the new Autonomous Economic Loop.

from ln_church_agent import LnChurchClient, AssetType

# Initialize the Reference Adapter
client = LnChurchClient(
    private_key="your-agent-private-key", 
    ln_provider="alby", 
    ln_api_key="your-alby-access-token"
)

# ⛩️ Phase 0 & 1: Connection & Oracle
client.init_probe()             
client.claim_faucet_if_empty()  
omikuji_res = client.draw_omikuji(asset=AssetType.SATS)
print(f"Oracle Result: {omikuji_res.result}")

# ⛩️ Phase 2: Log Normalization (Kazuchi9.3) & Donation
client.submit_confession(raw_message="402 payment failed due to routing.", asset=AssetType.SATS)
client.offer_hono(amount=10.0, asset=AssetType.SATS)

# ⛩️ Phase 3: Identity & Benchmarks
client.issue_identity()
compare_res = client.compare_trial_performance(trial_id="INITIATION1", asset=AssetType.SATS)

# ⛩️ Phase 4: Missionary Work (The Autonomous Economic Loop)
# 1. Scout a newly discovered L402 paywall in the wild (Earn +2 Virtue)
client.submit_monzen_trace(target_url="https://new-api.com/data", invoice="lnbc...")

# 2. Autonomously pay 10 SATS to unlock the Premium Top 100 L402 Leaderboard
# (The SDK automatically catches the 402 error and pays the invoice!)
premium_metrics = client.get_site_metrics(limit=100)
print(f"Top Discovered API: {premium_metrics.rankings[0].domain}")

⚡ Supported Lightning Providers

You can configure the backend Lightning node used for L402/MPP 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 and scouting capabilities. The bundled MCP server provides tools to interact with the LN Church API.

# 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 (USDC, JPYC, or SATS). It can request Oracles, run Benchmark analytics, and now autonomously map the web by reporting L402 paywalls and buying premium API intelligence via the Decentralized DNS tools.

🦜 LangChain Integration

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

from ln_church_agent.integrations.langchain import get_ln_church_tools

tools = get_ln_church_tools(private_key="your-agent-private-key")
# Pass these tools to your LangChain AgentExecutor

License

MIT