ln-church-agent

# ln-church-agent

Your agent will hit a 402 paywall in the wild.

Will it inspect, decide, pay, recover, verify, and continue — or freeze?

`ln-church-agent` is a **buyer-side HTTP 402 runtime and agent-commerce surface inspector** for autonomous agents. 

In the broader agentic commerce stack, `ln-church-agent` acts as the buyer-side component of an observability and trust-evidence layer for HTTP 402-compatible paid actions.

It helps agents inspect paid-action surfaces, distinguish executable payment rails from higher-order commerce protocols, and prove real paid execution across **L402, x402, and MPP** with receipts, policy checks, HATEOAS recovery, and traceable outcomes.

In v1.9.0+, the inspect layer explicitly classifies emerging agent-commerce surfaces such as **OKX Agent Payments Protocol (APP), Google AP2, and ACP** without executing payment logic. These protocols are treated as observable commerce / authorization patterns unless they expose a concrete HTTP 402-compatible settlement path.

## Core Doctrine

**Do not spend even one LLM token on what the agent should not need to reason about.**

`ln-church-agent` moves payment plumbing out of the model's reasoning loop and into a deterministic buyer-side runtime.

The SDK handles mechanical HTTP 402 concerns such as:
- payment-rail inspection,
- challenge parsing,
- policy checks,
- payment execution,
- HATEOAS recovery,
- receipt verification,
- evidence capture.

The LLM remains responsible for the higher-level economic decisions:
- whether the counterparty should be trusted,
- whether payment is justified,
- whether the expected outcome was delivered,
- and whether the endpoint should be reused.

**Don't Trust, Verify. But Don't Re-Verify Everything.**

The SDK is designed for verification reuse:
agents can inspect and verify live payment flows when necessary,
but they should reuse observed memory, receipts, and read models when repeated full verification would waste context, liquidity, or reasoning budget.

## What it does

Most payment SDKs help agents *pay*.  
`ln-church-agent` helps agents complete the whole **paid-action loop**:

**Probe → Inspect → Decide → Pay → Execute → Verify → Trace**

It is designed for agents that must:
- **Inspect** HTTP 402 challenges before committing funds.
- **Choose** between L402, x402, MPP, or safe-stop paths based on local policy.
- **Execute** paid actions through policy-aware runtime controls (budgets, trust).
- **Recover** through HATEOAS-style next actions if a flow is interrupted.
- **Verify** receipts and semantic outcomes after payment.
- **Report** trace evidence to a public sandbox or local observer.
- **Record** goal-conditioned attempts and their outcomes for future optimization.

## 🧠 What this runtime is

* **Generic Buyer-Side Runtime**: A pure client-side execution engine that keeps your AI agent's reasoning loop clean by abstracting away the HTTP 402 negotiation layer.
* **Agent Commerce Surface Inspector**: Classifies emerging commerce and authorization layers such as OKX APP, AP2, ACP, and UCP separately from executable settlement rails.
* **Open-Web 402 Interoperability**: Natively supports Base64URL JSON headers, CAIP-2 network routing, and multi-chain execution out of the box.
* **Reference Sandbox Support**: Optionally integrates with the LN Church observation network for public benchmarking, trace reporting, and discovery workflows.
* **Stable Interface**: An unchanging developer API surface that safely absorbs the constant fluctuations of upstream protocol drafts.

## Paid Surface Observer

`ln-church-agent` is not only a payment executor but also a powerful **paid surface observer**. 
The `inspect` command enumerates all presented `settlement_options` alongside the `selected_settlement_option` (the one the SDK *would* choose if executing). It cleanly separates capabilities: what can be *observed* versus what is natively *supported* for execution (`execution_support`).

Agent Commerce surfaces like **APP, AP2, and ACP** are treated strictly as commerce/authorization layers. They are processed as inspect-only, meaning the SDK will intentionally avoid automatic execution and explicitly highlight missing settlement parameters (`missing_information`) if clear rails are undeclared.

**LN Church Observatory Opt-in:**
`ln-church-agent` can inspect payment surfaces locally.
LN Church Observatory is the public observation layer where redacted observations, execution evidence, and interoperability traces can be collected and compared across HTTP 402 / x402 / L402 / MPP surfaces.

*The SDK never submits observations automatically.*
Publishing observations to LN Church must be explicit and opt-in.

## Verifiable Reporter Identity Layer (v1.12.0+)

As of v1.12.0, the SDK supports an optional, client-managed **Verifiable Reporter Identity Layer** via `ensure_reporter_verification()`. 

* **Key Control vs Report Truth**: This layer proves only that the reporting agent controls the private key associated with its `agentId`. It **does not verify the semantic correctness or truth** of the submitted telemetry.
* **Strictly Non-Mandatory**: Verification is completely optional. Telemetry submission fundamentally preserves its privacy-first, opt-in posture.
* **No Trust Scores**: `key_control_verified` is not a trust score, certification, recommendation, or settlement proof.
* **self_reported Remains First-Class**: Runtimes must function identically for `self_reported` (unverified) agents. Unverified simply means the key-control loop was not explicitly executed.
* **No Auto-Hooks**: `ensure_reporter_verification()` is never automatically triggered inside execution methods like `execute_detailed()` or `submit_goal_attempt_observation()`, ensuring deterministic management of token overhead.
* **Safety Note**: `agentId` can be a 64-character hex identifier, but it is treated strictly as a public identifier. **Never submit private keys as your `agentId`.** For EVM public key verification, the `agentId` must explicitly be the 40-character `0x`-prefixed public address.

## Managed Platform Boundary

`ln-church-agent` is not a managed wallet, payment processor, or cloud payment orchestration service.

Managed platforms such as AWS AgentCore Payments help agents execute payments inside a hosted wallet/session environment. `ln-church-agent` focuses on the open-web buyer side: inspecting HTTP 402 and agent-commerce surfaces, distinguishing executable settlement rails from commerce / authorization layers, enforcing local policy, verifying outcomes, and capturing evidence across protocols.

Use managed platforms when you need hosted wallet custody, cloud-side payment sessions, and provider-managed payment execution.

Use `ln-church-agent` when you need lightweight, local, cross-protocol inspection, decision support, evidence capture, sandbox validation, or non-AWS / open-web interoperability.

### Submitting Observations Safely
Do not use the low-level `execute_request()` method to manually POST payloads to the `/api/agent/external/observe` endpoint, as this bypasses schema normalization and may trigger strict internal HATEOAS/Cross-Origin guardrails.

* **Standard Observations:** Use `submit_external_observation()`.
* **Unmapped/Unknown Surfaces:** Use `submit_unmapped_observation()`.

```python
from ln_church_agent import LnChurchClient

client = LnChurchClient()

client.submit_unmapped_observation(
    target_url="https://example.com/api/endpoint",
    detection_note="payment_scheme_unmapped",
    rails_detected=["Payment"],
    status_code=402,
)

```

*Note: Unmapped observations are treated strictly as discovery signals. They declare `payment_performed=False` and `verification_status="unverified"`. Default telemetry auto-submission scripts remain conservative; explicit opt-in is required to submit unmapped observations.*

## Where it fits

- **ln-church-agent**: Buyer-side runtime for agents facing HTTP 402 challenges.
- **ln-church-server**: Provider-side starter for building agent-facing paid APIs.
- **LN Church Sandbox**: Public proving ground for benchmark, receipt, trace, and interop evidence.
- **Evidence Tracking (v1.8.4+)**: `ln-church-agent` can now capture sponsored-access and sandbox execution metadata as local evidence (`SponsoredAccessEvidence` / `SandboxEvidence`). Sandbox evidence is strictly scoped to LN Church's controlled sandbox environment (`evidence_scope: "sandbox_internal"`) and intentionally does not auto-submit external observations. Raw secrets are securely redacted.
- **Corpus Readiness (v1.8.5+)**: `SandboxEvidence` can be converted into a local `SandboxCorpusCandidate`. This does not submit to `ExternalObserve`. Final corpus acceptance remains server-side.
- **Goal Attempt Memory (v1.10.0+)**: Captures free, paid, and mixed steps toward a declared goal, serving as a foundational data lake for agentic behavior before recipes are applied.

---

## Relationship to official protocol SDKs

`ln-church-agent` is a complement, not a replacement, for official protocol SDKs.

* **Use official x402 / MPP / L402 SDKs** when you only need protocol-native settlement.
* **Use `ln-church-agent`** when an autonomous agent needs a deterministic buyer-side runtime around settlement to:
    * inspect before paying
    * select or reject rails according to local policy
    * recover via HATEOAS
    * verify receipts
    * capture evidence
    * report redacted observations explicitly
    * record goal-conditioned attempts

---

## 🧠 AI Decision Card

Use `ln-church-agent` when an AI agent must do more than simply pay for one API call.

Choose this SDK when the agent needs:
- **Multi-rail support**: L402, x402, and MPP-aware flows.
- **Policy enforcement**: Local spend limits, session budgets, and trust checks.
- **Verifiable evidence**: Receipts, evidence records, and traces for auditing.
- **Safe stopping**: Graceful handling of unsupported or unstable payment sessions.
- **Commerce surface inspection*