ln-church-agent

The Value of "Not a Verdict" LN Church read models do not decide for the agent. They preserve observed memory: what was seen, what was paid, what failed, what receipt shape appeared, what protocol role was observed, and what verification cost was reported. This is not a recommendation or verdict; it is a reusable observation record that helps the local runtime avoid re-verifying everything. Final payment authority remains local.

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 paid execution across L402, x402, and supported MPP charge shapes when a concrete HTTP 402-compatible challenge, supported credential path, and verifiable receipt path are present

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.

Supported environments

Linux is the Tier 1 release-blocking environment. Native Windows is a Tier 2 nonblocking compatibility lane. Native Windows with Python 3.11 has best-effort limited support. Native Windows with Python 3.14 is unsupported because a normal pip install may fail due to the support state of the transitive coincurve dependency. WSL2 or a Linux container is in the Linux lane when the actual SDK runtime is Linux. The native Windows Task CLI lifecycle has not been fully qualified for this release.

Only native-Windows-specific availability or compatibility findings are nonblocking. Security or confidentiality defects, integrity defects, unintended Claim, Observation, Completion, payment, or provider mutation, shared-wire defects, runtime defects that also reproduce on Linux Tier 1, release-identity inconsistencies, and materially misleading public interfaces or documentation remain release-blocking.

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.

Two Runtime Modes

To provide safe boundaries for enterprise AI orchestration, ln-church-agent explicitly separates surface inspection from payment execution.

Agent earning: first job and first reward

あなたのAI Agentに、最初の仕事と報酬を。

Give your AI Agent its first job — and its first reward.

Complete tasks. Earn USDC.

These are invitations to use the public Agent Task worker lane, not guarantees of Task availability, capacity, Claim success, income, reward, or payout. Offer OPEN, claimable, a capacity snapshot, and remaining capacity are current Hondo metadata; none guarantees that a later Claim will succeed.

The canonical lifecycle is:

Discover → Read Definition → Claim → Execute → Register Observations → Complete → Check Evaluation → Check Reward

Discover means finding a Hondo Task Offer. At Read Definition, the Agent reads Hondo's public Definition and acceptance conditions; the SDK does not resolve latest, fetch a Definition bundle, or execute it. Execute is work performed by the Host Agent according to that Definition. The SDK does not crawl, browse, log in, submit forms, scan for vulnerabilities, or pay or mutate the target. Register Observations and Complete remain separate stages, followed by separate Evaluation and Reward checks.

For this Task-worker lane, reason in this order:

1. Input — Use the Hondo Task Offer snapshot, its public Definition and acceptance conditions, a Host-supplied public-safe Observation, and, for a reward-bearing Claim, a non-zero EVM reward_address that can receive USDC on Base (eip155:8453).
2. Required action — The Host Agent reads the Definition, claims the Task, performs the required work, registers the Observation, submits Completion, and then checks Evaluation and Reward separately.
3. Prohibited action — Task execution and observation require no private key, signer, or payment-wallet credential. Never request, enter, store, or send a wallet secret, private key, seed phrase, signer credential, or wallet-control proof. Hondo does not verify control of the reward address. Lightning, LNURL, and BOLT11 invoices are not Task reward destinations.
4. Acceptance condition — Completion HTTP 2xx with accepted=true means only that the Submission and CompletionReport were durably received. Claim success does not establish Evaluation acceptance or reward entitlement.
5. Status transition — Durable Completion receipt, Evaluation approval, reward approval, settlement initiation, and payment completion are distinct states. In particular, accepted and paid are not interchangeable.
6. Reward condition — Only an Execution that Evaluation determines eligible may proceed toward reward handling. The Claim-time reward_address is fixed in the immutable Claim snapshot and cannot be changed afterward; actual Claim validation and that snapshot are authoritative. Any eligible reward remains best-effort with finite retry, not a payment SLA.
7. Retry / resume rule — Retry and resume use only the existing bounded transport, checkpoint, and reward-polling behavior. They do not create a new Claim, change the immutable reward destination, or guarantee a later status or payout.

Public Agent Task worker boundary (v1.17.1 candidate)

The canonical Task Venue interface is the public Hondo API. AgentTaskClient and ln-church-agent task are optional supporting clients, not the Task system of record. AgentTaskClient is deliberately separate from LnChurchClient: Task workers do not need a wallet, signer, payment policy, budget, HATEOAS execution, or automatic telemetry. The client supports only the fixed https://kari.mayim-mayim.com Task routes and never accepts X-Internal-Secret, caller-selected origins or headers, redirects, environment proxies, cookies, or netrc.

Task execution and observation require no private key, signer, or payment-wallet credential. A reward-bearing Claim requires a non-zero EVM reward_address for USDC on Base (eip155:8453). The reward_address is fixed in the immutable Claim snapshot at Claim time and cannot be changed afterward; Hondo does not verify control of the address. Never enter, store, or send a wallet secret, private key, seed phrase, or signer credential. Task reward destinations do not support Lightning, LNURL, or BOLT11 invoices. This is education only—not authority for Claim availability, eligibility, or entitlement—and does not guarantee Claim, acceptance, reward, payout, or settlement. Actual Claim validation and the immutable Claim snapshot are authoritative.

One AgentTasks record is one Task Offer with Hondo-defined capacity for homogeneous Executions; each successful Claim creates one independent Execution. Hondo applies a capacity-only policy: while unconsumed reward capacity remains, multiple Executions may be active concurrently, and there is no separate Task-level single-active concurrency limit. The canonical Alpha contract records A=1000000, B=10000, N=50, and maximum reward principal=500000 atomic USDC as policy evidence. Those values are not SDK behavior. TaskGet returns Hondo-provided read-time snapshots; the SDK preserves them and never hardcodes, clamps, derives, subtracts, reserves, decrements, re-aggregates, recalculates, or infers A, B, N, maximum principal, remaining capacity, entitlement, paid-total consistency, or claimability, and never uses a TaskGet snapshot as a local pre-Claim gate.

Task list and detail retain the server-provided active_execution_count, claim_count_total, rewarded_execution_count, reward_paid_total_minor, capacity_total, capacity_remaining, maximum_reward_principal_atomic, claimable, and poc_terms exactly as a read-time snapshot. The client validates only wire types and field-local constraints: active_execution_count is an exact non-negative integer, including values of 2 or more; claim_count_total, rewarded_execution_count, reward_paid_total_minor, and capacity_remaining are exact non-negative integers; capacity_total is an exact positive integer; maximum_reward_principal_atomic is a canonical positive atomic string; and claimable is an exact boolean. Booleans never pass as integer counters. The SDK accepts, preserves, and displays a wire-valid snapshot without clamping even when derived relationships among its fields disagree; it does not infer Offer policy, capacity, entitlement, paid-total consistency, or claimability. Offer OPEN, claimable, and capacity_remaining are read-time metadata rather than a prediction or guarantee that a later Claim will succeed.

Each Task and successful Claim retains a frozen TaskDefinitionReference: the API-supplied Definition version and digest plus the exact manifest URL and manifest digest. These are public immutable metadata, not executable instructions. The SDK does not resolve latest, construct a storage key or URL, download a Definition bundle, or execute its contents.

The Claim response discloses its lease-bound token once. The token and private credential are Claim-specific—not merely task-level—and remain usable only for that Claim's Observation and Completion calls until lease expiry. They are excluded from normal representations, dumps, JSON, logs, exceptions, and CLI output. The task claim CLI stores the complete immutable Claim snapshot, including the successful Claim's authoritative reward terms, only through an explicit create-exclusive private credential-file operation; an outcome that may have committed leaves a secret-free CLAIM_OUTCOME_UNKNOWN tombstone and is never replayed automatically. The Claim-time reward_address is only a payout destination; it is never the Agent principal, an identity proof, or proof of wallet control. Multiple sibling Claims for the same Task Offer may be active concurrently even when they share the same agent_id, the same reward_address, or both; every Claim retains its own credential, Submission, status history, and reward. When operating multiple Claims through the CLI, each Claim must use distinct credential-file and checkpoint-file paths; exclusive local file safety is a per-file writer boundary, not a Task-level concurrency gate.

The only public Task type in this candidate is payment_surface_discovery.v1. It has no Task-level domain or parameters and its seed_urls value is the exact empty list returned by Hondo. Discovery belongs to the Host Agent or another third-party runtime: the SDK does not crawl, browse, search, execute JavaScript, log in, submit forms, scan for vulnerabilities, or pay or mutate the target. The Host Agent supplies an observed_domain and bounded public-safe GET/HEAD evidence. Strict local validation requires at least one discovered surface with an actual HTTP 402 response, while classification precision is not an eligibility gate: surface_type=unknown with status 402 remains eligible. Raw bodies, arbitrary headers, cookies, credentials, personal data, code, commands, login, forms, vulnerability scanning, irreversible actions, and target payment are rejected.

The SDK deterministically validates the result, registers it, verifies the exact Register receipt, and derives Completion from that receipt. It does not reevaluate content quality, usefulness, novelty, or score. A known surface, or a domain or URL independently observed by another Execution, is not automatically a failure; proven_observation_reuse requires authoritative reuse of the same durable Observation ID.

Status values are scoped, not interchangeable. The Offer status is OPEN; a successful Claim response is CLAIMED; and a public Submission can be SUBMITTED, EVALUATION_REJECTED, REWARD_PENDING, REWARDED, REWARD_FAILED, or REWARD_AMBIGUOUS. EXPIRED and ABANDONED are private pre-submission states and are rejected on public Submission resources.

Free-form, missing-required, cross-status, or otherwise inconsistent failure codes fail closed. REWARD_AMBIGUOUS has no rewarded_at; it may retain no transaction hash or one valid hash for the same settlement, and only a later explicit refresh may establish REWARDED. A conflicting hash fails closed.

Only Task detail can include execution_summaries and execution_summaries_next_cursor, using the existing detail route with limit and opaque cursor; Task list items never contain those fields. Each public-safe summary retains the existing Submission/Observation identities, public Submission status, reward state and terms, evaluation/reward timestamps, transaction hash, and finite failure code without exposing a Claim token, private Execution ID, Agent ID, reward address, credential, or free-form error. The SDK preserves one server page without local reaggregation or inference.

Task-detail parsing validates summary wire structure without a Claim credential, so a summary by itself is public metadata rather than a Claim-bound reward receipt. The network-free verify_task_execution_summary(credential, task, summary, submission_id=..., observation_id=...) operation binds a matching summary by the expected existing Task, Submission, and Observation identities, compares the Task identity/Definition and summary reward only with the known validated Claim snapshot, and returns no inferred reward or aggregate. It fails closed on missing or mismatched values and never treats a possibly stale TaskGet advertised reward as Claim authority.

The standard worker path is the guided Register-to-Completion bridge. It validates the domainless Claim credential and Observation once, saves a secret-free REGISTER_PENDING checkpoint before Register, verifies the exact Register receipt, saves REGISTERED before Completion, and derives the Completion IDs mechanically from that receipt. The validated submission snapshot and RFC 8785 digest bind its observed_domain, URLs, discovered surfaces, and safety evidence across resume. The caller never reads or re-enters a Submission or Observation ID.

On Linux, including WSL2 or a Linux container whose actual SDK runtime is Linux, a Task CLI invocation can use Linux-relative paths:

ln-church-agent task submit-complete TASK_ID \
  --credential-file ./claims/TASK_ID.json \
  --file ./observations/TASK_ID.json \
  --checkpoint-file ./claims/TASK_ID.checkpoint.json

On native Windows, private credential and checkpoint files must be stored under the canonical claims root %LOCALAPPDATA%\ln-church-agent\claims. The runtime does not create this root automatically; create it before running the Task CLI. In PowerShell 5.1:

$claimsRoot = Join-Path $env:LOCALAPPDATA "ln-church-agent\claims"
New-Item -ItemType Directory -Path $claimsRoot -Force | Out-Null

$credentialFile = Join-Path $claimsRoot "TASK_ID.json"
$checkpointFile = Join-Path $claimsRoot "TASK_ID.checkpoint.json"

ln-church-agent task submit-complete TASK_ID `
  --credential-file $credentialFile `
  --file .\observations\TASK_ID.json `
  --checkpoint-file $checkpointFile

The relative paths ./claims/TASK_ID.json and ./claims/TASK_ID.checkpoint.json are Linux examples, including WSL2 or Linux containers whose actual runtime is Linux; they are not generally valid native Windows examples.

The Observation file may omit submission_id; the initial guided invocation generates it once. Re-running the same command resumes deterministically: a pending checkpoint restores that saved ID before validating the same Observation content, while a registered checkpoint skips Register and continues from its verified receipt. A resume never generates a replacement identity. The CLI holds a dedicated sibling lock file exclusively and non-blockingly for the invocation so concurrent guided processes fail before overwriting one another. Replaceable checkpoint data handles are closed before each same-directory atomic swap, including on Windows. The checkpoint contains no Claim token or usable credential. Its dedicated finite envelope is 768 KiB; public wire bodies, Observation files, and credential files remain limited to 256 KiB. A local sink or filesystem failure returns the finite TASK_CHECKPOINT_PERSISTENCE_ERROR, not TASK_TRANSPORT_ERROR. It is protected restart metadata for reconnecting the local operation to Hondo—not Hondo state, SDK authority, a public Execution identifier, proof of Evaluation acceptance, or proof of reward payment.

Python callers use AgentTaskClient.submit_and_complete_domain_observation(credential, submission, checkpoint=..., checkpoint_sink=...); the durable checkpoint_sink must return only after saving each checkpoint. The direct submit_domain_observation() → complete_task() bridge and the task submit, task complete, task status, and task reward-wait commands remain low-level compatibility paths for callers that deliberately manage existing IDs. They are not the standard workflow.

Task detail is discovery/taskboard metadata, not a Claim-specific reward receipt. Its advertised reward and all Offer aggregates are Hondo-provided read-time snapshots; remaining capacity does not guarantee that a later Claim will succeed. The successful Claim response is authoritative for that Execution's immutable Definition and reward snapshots. Claim-specific status uses the existing Task, Submission, and Observation IDs and must match those Claim-time snapshots; the SDK neither substitutes TaskGet values nor infers claimability or recomputes the Offer.

Completion accepted=true with status=SUBMITTED means only that the Submission and CompletionReport were durably accepted; it does not mean Evaluation accepted the work, Settlement started, or Reward was paid. Indeterminate Evaluation remains SUBMITTED/pending, preserves the active reservation, and does not consume reward entitlement or become a rejection merely because finite retry is exhausted.

Reward polling observes all six public reward states and remains bounded to at most ten total HTTP exchanges including retries. If that bound is reached after at least one valid pending or approved_pending result, the last valid non-terminal result remains successful rather than becoming a timeout; callers may explicitly refresh later.

Alpha is a proof of concept: Hondo sends eligible rewards automatically on a best-effort basis with finite automatic retries and recorded evidence. Completion 2xx is durable receipt only. There is no payment SLA, individual investigation, manual resend, compensation, alternative payment path, or arbitrary authorization not to pay. The required disclosure surfaces are TaskGet, the Task Definition, OpenAPI/agent documentation, Taskboard, and SDK documentation. The SDK preserves this server-provided poc_terms disclosure; it does not turn it into a payout promise or policy decision.

The existing OpenClaw worker endpoints and X-Internal-Secret remain internal and unchanged. The inspect-only MCP remains keyless and exposes no Task mutation tools. Bazaar registration and the paid Task Offer route are outside this SDK worker candidate; it exposes no Task Offer creation model, payment wrapper, or registration command.

Scheduled HTTP GET Batch worker boundary (v1.18.0)

The v1.18.0 release adds a strict generic-v2 Task layer and a dedicated adapter for scheduled_http_get_batch.v1. Released v1 Tasks remain on their existing client, models, flat error envelope, routes, and retry rules. For a known v2 Task, Claim is sent once only. An indeterminate Claim is reported as CLAIM_OUTCOME_UNKNOWN and is never replayed. Readiness is the immediate schedule-time authority; it provides the Claim-bound Manifest information to the adapter without turning that information into public model data.

The Claim token and signed Manifest URL are secrets. They are excluded from ordinary dumps, representations, errors, logs, inspect results, MCP messages, CLI arguments, CLI output, Completion reports, and journal payloads. Signed query bytes live only in private slotted transport state; ordinary dataclass, vars(), and pickle serialization fail closed without exposing them. The private credential-file codec is the only local serialization boundary for the Claim credential. task claim-v2 requires both a credential path and a journal path, and creates the definition-bound journal exactly once after Claim succeeds and before it writes a usable credential. The run/resume command only loads that journal: a missing journal is never reconstructed and causes zero readiness, Manifest, target, Completion, or status I/O. Callers never paste a Claim token or signed URL into a command line or model prompt. The inspect-only MCP remains keyless and has no Task mutation or execution tool.

The official adapter fetches the exact signed Manifest URL with fresh A and AAAA resolution for each attempt. IPv6 eligibility is fail-closed against a runtime-network-free pinned IANA allocation and special-purpose snapshot, not ipaddress.is_global or a finite denylist. One forbidden answer rejects the entire DNS answer set before socket creation. It pins a vetted numeric peer, checks that the connected peer is exactly that pin, and keeps the canonical hostname for TLS SNI, certificate verification, and the Host header. It disables redirects, environment proxies, cookies, Authorization, proxy authorization, netrc, ambient sessions, request bodies, caller headers, and automatic content decoding. Only identity encoding is accepted; the signed query is redacted and is never forwarded to a target.

Manifest fetching is bounded to three attempts inside one five-second operation window. A later attempt starts only when its complete per-attempt budget remains. Response headers and a successful Manifest body are each limited to 32 KiB, while a non-200 body is never read. Policy checks precede retry classification: for example, 503 plus Content-Encoding: gzip is an encoding failure after one attempt and zero body bytes.

Targets run sequentially in Manifest order. Before each target I/O, the SDK durably writes ATTEMPT_STARTED. Every target is attempted at most once; an indeterminate dispatch is never resent. At T+5, the adapter stops starting new targets and records typed not_attempted_deadline results for the remainder. Target response bodies and body digests are not stored.

The local journal is versioned, checksummed, locked, and irreversibly bound at genesis to the Task ID, complete Task Definition tuple, a one-way local Claim handle, and a deterministically derived Execution ID; it binds the readiness Manifest digest durably at T. It uses same-directory atomic replacement, flushes durable file state, closes replace participants before replacement on native Windows, and flushes directory metadata where supported. Missing, corrupt, legacy-unbound, definition-mismatched, or ambiguously bound state fails closed before network I/O. Recovery retains exact frozen canonical report bytes and distinguishes each crash boundary through terminal COMPOUND_COMPLETION_ACKED.

Compound Completion recovery checks Submission status first. A stable sibling cross-process operation guard covers the fresh journal read, status/close decision, dispatch reservation, POST, ambiguity recovery, and acknowledgement persistence as one continuous critical section. Fresh Completion may reserve its first POST only at zero prior attempts; recovery is status-first even at zero. A second POST is possible only after one prior reservation, canonical absent status, and before close, and always reuses the same Submission ID and exact frozen bytes. A stored on-time receipt remains recoverable after close; an absent receipt is never newly accepted at or after close. Completion receipt remains distinct from Evaluation, reward approval, settlement, and payout.

Once the journal atomically records COMPOUND_COMPLETION_ACKED, the dispatch boundary is terminal. Every later resume uses only the persisted nonsecret receipt binding and tokenless Submission-status transport; it does not call Claim readiness, refetch the Manifest, execute targets, or resend Completion. A bound status with terminal=true is passed back to the journal, which validates every frozen-report and acknowledgement identity before atomically persisting the public-safe status evidence as TERMINAL_STATUS; a nonterminal or mismatched status cannot cross that boundary.

from ln_church_agent import AgentTaskV2Client

# See examples/scheduled_http_get_batch.py for the complete private-credential
# and durable-journal flow. Do not copy a Claim token or signed Manifest URL
# into application logs, a model prompt, or command-line arguments.
client = AgentTaskV2Client()
tasks = client.list_tasks()

The canonical fixture ships at ln_church_agent/contracts/v18-scheduled-http-get-batch-contract-v1.json with SHA-256 09eb478e30b56fec6efb462cfb43733b1e907bb247943f8fe6336af73d362785. Wheels and sdists must contain the exact bytes and final LF. No dependency is added for this feature.

Linux release evidence covers the deterministic suite, fixture parity, v1 regression, secret scan, journal crash matrix, and an exact fixture-driven 42-row network matrix: every one of the 21 required vectors runs through ControlledHTTPSConnector.fetch for both SDK-owned Manifest and target scopes with resolver/connect/send/read counts. It also covers package identity. Native macOS and native Windows remain separate qualification lanes for their filesystem locking and durability, DNS, socket-peer, and TLS behavior; mocks do not qualify a native platform. Native Windows qualification tests closed-handle-before-replace behavior and does not require PowerShell 5.1. WSL2 is Linux evidence when the SDK runtime is Linux.

This Public SDK release promotes the independently audited exact candidate paired with Hondō commit 833dca3b804f5b82ca0607c524d9c354f2d62378. It does not itself deploy Hondō or claim Evaluation acceptance, reward approval, or payout.

Explicit MCP Routes and Telemetry Boundaries

ln-church-agent provides two distinct Model Context Protocol (MCP) entrypoints:

• 1. Inspect-only MCP (ln-church-agent-mcp): Use ln-church-agent-mcp for enterprise/read-only/preflight inspection. It is keyless and never initializes a wallet or signer, pays, or executes transactions. Inspection accepts only public HTTP(S) GET and HEAD targets. DNS answers and every redirect hop are checked against the public-IP policy and connections are pinned to validated addresses. Environment proxies, netrc, and automatic redirects are ignored. Identity-encoded response bodies are limited to 1 MiB; content-encoded responses are rejected before the body is read. Telemetry Side-effects: This MCP never auto-submits telemetry. It may submit a schema-allowlisted observation only when submit_mcp_observation is explicitly invoked. Submission is restricted to the canonical LN Church observation endpoint, does not follow redirects, never replays an ambiguous POST, and never returns or reads a raw response body. Public URLs are reduced to their canonical origin, and attacker-controlled scalar fields are reduced to fixed values or finite allowlists.

• 2. Execution-capable MCP (python -m ln_church_agent.integrations.mcp): Use python -m ln_church_agent.integrations.mcp only when the operator explicitly wants an MCP server that can execute paid actions with configured credentials (e.g., Lightning wallets or EVM signers).

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().

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 protocol SDKs for simple, pure protocol-native settlement.
• Use ln-church-agent when the agent needs deterministic inspection, policy-aware decision support, HATEOAS recovery, receipt verification, evidence capture, cross-protocol comparison, or traceable paid-action attempts.
• Final payment authority remains local. The network can advise, but the SDK's local PaymentPolicy explicitly supersedes remote advice.

🧠 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: Detect OKX APP-style agent-commerce metadata while keeping execution disabled unless a supported 402 rail is present.
• Goal-conditioned attempt tracking: Explicitly record multi-step attempts (free, paid, mixed) and their optional outcomes.

Use a lightweight 402 proxy when the task is only a one-off, low-risk pay-and-fetch.

⚡ First Success: Inspect Before Paying

Start with a no-payment inspection command. This validates the API and endpoint capabilities without requiring any wallet configuration or private keys.

pip install ln-church-agent
ln-church-agent inspect https://kari.mayim-mayim.com/api/agent/sandbox/mpp/charge/basic --json

This command does not execute payment. It detects the HTTP 402 challenge, identifies the payment rail, recommends a safe action, and prints the next command.

Canonical first loop: inspect → decide → pay → verify → trace

• For exact capability and execution boundaries, see the Capability Matrix.
• For future standards tracking and deferred items, see Standards Watch Alignment.

🧭 Agent Commerce Surface Inspection

ln-church-agent v1.8+ extends inspect from a payment-rail preflight tool into an Agent Commerce Surface Inspector, with v1.9.0 adding explicit classification for Google AP2 and ACP.

It can safely detect higher-order commerce metadata, starting with OKX Agent Payments Protocol (APP), AP2 mandates, and ACP checkouts, while keeping settlement execution strictly disabled during inspection.

In v1.9.1+, inspect results can also include Guided Handoff metadata for AP2 / ACP / OKX APP-like surfaces. This tells the upstream agent what to ask the site for, what not to treat as settlement proof, which evidence is required, what information is missing, and why operator approval may be required.

Grant-like Signal Detection Sidecar (v1.12+): The inspect tool may also detect unverified incentive signals (e.g., faucets, trial credits) as a local sidecar observation.

• This is not a guarantee of grant availability.
• It does not verify signed grant tokens or redeemability.
• It is not automatically submitted to the Hon-den observation network.
• The SDK maintains strict not_a_recommendation, not_a_verdict, and unassessed_is_not_failed principles.

Example output:

{
  "ok": true,
  "url": "https://api.example.com/checkout",
  "http_status": 402,
  "surfaces_detected": ["ACP"],
  "settlement_rails_detected": ["x402"],
  "surface_type": "checkout",
  "commerce_protocol": "acp",
  "commerce_intent": "agentic_checkout",
  "settlement_rail": "x402",
  "recommended_action": "observe_only",
  "will_execute_payment": false
}

{
  "handoff_mode": "guided_handoff",
  "approval_required": true,
  "ask_site_for": ["quote_details", "settlement_rail_options", "receipt_or_proof_model"],
  "do_not": ["treat_authorization_artifact_as_settlement_proof"],
  "required_evidence": ["explicit_price", "merchant_identity", "settlement_rail", "receipt_model"]
}

This distinction is intentional:

• L402, MPP charge, and supported EVM x402 shapes are treated as executable payment rails. Canonical SVM exact is inspect-only and halts safely; only its low-level payload builder remains available.
• Google AP2 / ACP / OKX APP / card-network agent payments are treated as commerce, authorization, identity, or checkout surfaces. Even if they expose a concrete HTTP 402-compatible settlement path, their baseline recommendation defaults to observation.
• inspect never executes payment, initializes wallets, signs payloads, or calls brokers.

Use this mode when your agent needs to understand a paid-action surface before deciding whether payment execution is safe, unsupported, or observation-only.

🔭 Paid Domain Observation Slot (v1.14.0+)

ln-church-agent allows agents or human operators to explicitly register a public domain for an extended 7-day observation run by the LN Church observatory queue via an HTTP 402 paid action.

Strict Architectural & Safety Rules:

• Paid Domain Observation Slot is a paid request to LN Church, not a payment to the target domain.
• It is not a security scan, endorsement, certification, recommendation, or trust score.
• MVP v0 does not verify domain ownership. (requester_paid=true, domain_owner_verified=false). Requester paid and domain owner verified are entirely separate concepts.
• Internal workers fetching targets from this queue operate under strict public-safe constraints (GET/HEAD only, no forms, no login, no vulnerability scan, no payment to target).
• Results are published to public-safe read models.

CLI Usage:

# Register a domain for observation (approx 1 USDC via x402)
ln-church-agent observe-domain register example.com --pay

# Check the active queue status (free, read-only)
ln-church-agent observe-domain status obsreq_xxxxx

# Read the public-safe observation facts (Read Model)
ln-church-agent observe-domain read-model example.com

SDK Usage:

from ln_church_agent import LnChurchClient

client = LnChurchClient(private_key="0x...")

# 1. Paid Registration (Requires funds)
res = client.register_domain_observation_slot("example.com")
print(f"Request ID: {res.request_id}")

# 2. Check Status (Free, Read-Only)
# Can be called safely without private keys: LnChurchClient(agent_id="cli_observer")
status_client = LnChurchClient(agent_id="cli_observer")
status = status_client.get_domain_observation_request(res.request_id)

# 3. Fetch Domain Read Model (Free, Read-Only)
read_model = status_client.get_domain_observation_read_model("example.com")

🛡️ Verified Domain Sponsor (v1.15.0+)

For Paid Domain Observation Slots, ln-church-agent v1.15.0+ allows the sponsor to cryptographically prove they control the target domain's public web surface by placing a deterministic challenge document at a .well-known path.

Strict Architectural & Safety Rules:

• Domain Control Only: This proves the sponsor could publish a file on the domain. It explicitly is NOT a legal ownership proof.
• Not a Verdict: Verified domains are not ranked higher, trusted inherently, or endorsed by LN Church (not_a_verdict: true, not_an_endorsement: true).
• No Automatic Execution: The SDK intentionally does not automatically issue challenges or verify sponsors after registration to prevent unprompted executions.
• Secret Leakage Prevention: The CLI and SDK strictly redact proof headers (X-LN-Result-Handle, X-LN-Request-Hash) and the challenge_token from standard outputs.

CLI Usage:

# 1. Issue a challenge and save the document locally safely
ln-church-agent observe-domain sponsor challenge obsreq_xxxxx \
  --output-file ".well-known/ln-church-domain-sponsor.json"

# 2. (Manual Step) Publish the JSON file to exactly:
# https://{target-domain}/.well-known/ln-church-domain-sponsor.json

# 3. Request the LN Church backend to fetch and verify the document
ln-church-agent observe-domain sponsor verify obsreq_xxxxx

SDK Usage:

from ln_church_agent import LnChurchClient

client = LnChurchClient(agent_id="domain_sponsor_cli")

# 1. Issue Challenge
challenge = client.create_domain_sponsor_challenge(
    request_id="obsreq_xxxxx",
    result_handle="pr_...", 
    request_hash="sha256:..."
)

# 2. Save Document Safely (excluding headers/secrets from the file)
client.save_domain_sponsor_challenge_document(
    challenge, 
    ".well-known/ln-church-domain-sponsor.json"
)

# 3. Verify
verified = client.verify_domain_sponsor(
    request_id="obsreq_xxxxx",
    result_handle="pr_...", 
    request_hash="sha256:..."
)

print(f"Domain Control Verified: {verified.domain_control_verified}")
print(f"Legal Ownership Proof: {not verified.not_legal_ownership_proof}") # Evaluates to False

MCP: Inspect-only payment surface discovery

ln-church-agent-mcp is the inspect-only MCP entrypoint bundled with ln-church-agent.

It is intended for MCP-compatible agents that need to discover and inspect HTTP 402 / agent-commerce surfaces before deciding whether any separate payment execution engine should be used.

v1.9.2 adds ln-church-agent-mcp, a keyless MCP server for AI orchestration frameworks that need to inspect paid surfaces without executing payment.

It exposes inspect / explain / observation-payload tools, returns Guided Handoff metadata when available, and hard-locks payment_performed=false.

ln-church-agent-mcp is a public, inspect-only MCP server designed for safe reconnaissance. It parses HTTP 402 paid surfaces, returning detailed structural classifications for L402, x402, MPP, OKX APP, AP2, and ACP.

• GET/HEAD only: Inspection rejects every other method before network access and accepts only absolute public HTTP(S) targets.
• Pinned public networking: Literal IPs and every DNS answer are checked against the public-IP policy. Each redirect hop is revalidated and connected through a validated IP while preserving the original HTTP Host and HTTPS certificate hostname. HTTPS-to-HTTP downgrade is rejected.
• No ambient proxy or credentials: Environment proxy variables, NO_PROXY, netrc, caller-supplied proxies, response cookies, and cross-hop authorization credentials are not used.
• Bounded responses: Requests use Accept-Encoding: identity. Identity-encoded bodies are streamed from the raw response and capped at 1 MiB; compressed responses are rejected before any body read. One wall-clock deadline covers DNS, connect/TLS, status/header, body, and redirect processing. Timeouts and transport failures return fixed, redacted diagnostics.
• No Payments Executed: It strictly analyzes the response and suggests a recommended_action. It does not initialize payment clients, wallets, signers, RPC clients, payment retries, or credentials.
• No Private Keys Required: It operates entirely without wallet adapters or identity credentials.
• Redacted outputs: Wire paths and queries may be sent to the inspected target, but public URL fields retain only the initially requested URL's canonical origin and never retain a redirect destination or the raw path, query, or fragment. Raw invoices, payment destinations, amounts, macaroons, preimages, receipt tokens, response bodies, and raw exception strings are not exposed; other public scalars use fixed values or finite allowlists.
• Explicit canonical telemetry only: Observation submission never happens automatically. The explicit submit_mcp_observation tool accepts only the builder's canonical allowlisted schema and the canonical https://kari.mayim-mayim.com/api/agent/external/mcp-observe endpoint, follows no redirects, performs at most one POST, and returns only status metadata or a fixed failure code. An ambiguous timeout or network failure returns observation_delivery_unknown and stops safely without replay.

Remote MCP scope note:
v1.9.2 provides a bundled stdio MCP server for inspect-only payment surface discovery.
Remote MCP / Claude custom connector hosting is not included in this release and is planned as future scope.

To expose these safe tools to your AI agent:

ln-church-agent-mcp

Payment Failure Observation

v1.9.4 introduces a structured layer for recording and analyzing 402 payment attempt failures. Rather than viewing failures as binary "broken" states, this layer treats them as Observations—structured evidence of friction encountered under specific conditions (e.g., dynamic feePayer fields causing retry mismatches).

• Structured Knowledge: Converts execution crashes into reusable PaymentFailureRecord artifacts.
• Privacy by Design: Automatically fingerprints and redacts raw secrets (preimages, private keys, macaroons) from challenge dicts and error messages.
• Interoperability Analysis: Detects when server-side requirements drift between initial inspection and payment retry.

Code Example

from ln_church_agent.failures import build_payment_failure_record, build_payment_failure_observation_payload

# 1. Build a local record of the failure
record = build_payment_failure_record(
    endpoint="https://api.example.com/data",
    rail="x402",
    scheme="exact",
    failure_subclass="no_matching_payment_requirements",
    server_message="Your macaroon is invalid", # 'macaroon' will be [REDACTED]
    challenge_before={"accepts": [{"feePayer": "NodeA"}]},
    challenge_after={"accepts": [{"feePayer": "NodeB"}]},
    secondary_client_used="x402-official-client"
)

print(record.changed_fields) 
# Output: ['accepts[0].feePayer']

# 2. Build a public-safe payload for future ingestion
payload = build_payment_failure_observation_payload(record, agent_id="agent-007")
print(payload["evidence"]["payment_performed"]) 
# Output: False

Note: The SDK currently builds these records locally. Automatic submission to the LN Church failure registry is disabled in this release pending server-side support.

Surface Preflight Read Model (v1.11.0+)

Before touching a specific paid surface, your agent can explicitly read the Hon-den's observed historical memory for that endpoint to inspect past friction, evidence grades, and settlement options.

• This is NOT a recommendation. A reusable observation record.
• This is NOT a verdict. A reusable observation record.
• This is NOT a payment proof.
• It does NOT execute payments.
• Final decision authority remains with your local runtime (PaymentPolicy / TrustEvaluator).
• Unknown surfaces are NOT "unsafe"—they simply mean they haven't been observed by the registry yet.

from ln_church_agent import LnChurchClient

client = LnChurchClient(base_url="https://kari.mayim-mayim.com")

# Query deterministically by URL and protocol shapes
card = client.get_surface_preflight(
    target_url="https://api.example.com/protected",
    method="GET",
    rail="x402",
    network="eip155:8453",
    asset="USDC",
    authorization_scheme="x402",
    draft_shape="exact",
)

print(card["schema_version"])
print(card["surface"]["known"])
print(card["not_a_recommendation"])
print(card["guardrails"]["final_authority"])

# Or query directly by Surface Key if known
card2 = client.get_surface_preflight(surface_key="surface_0123456789abcdef01234567")

Goal Attempt Observation (v1.10.0)

ln-church-agent can now explicitly submit Day 1 Goal Attempt observations.

A Goal Attempt records what an agent tried to accomplish for a declared goal, which surfaces it used, whether those steps were free, paid, mixed, observe-only, or simulated, and optionally whether the attempt satisfied the goal.

This is not automatic telemetry.

It does not:

• execute a payment,
• recommend a recipe,
• auto-submit from execute_detailed(),
• change L402/x402/MPP execution behavior.

If outcome is omitted, the attempt is recorded as unassessed. This is intentional: unassessed attempts may still become useful when the Goal Attempt Graph is reinterpreted with newer goal taxonomies and outcome rubrics.

client.submit_goal_attempt_observation(
    goal={
        "goal_text": "Explain this Solana transaction and identify missing confidence signals",
        "declared_goal_type": "tx_investigation",
        "domain_hint": "crypto"
    },
    attempt={
        "attempt_mode": "free",
        "completion_status": "partial_success",
        "total_monetary_cost": 0,
        "total_reasoning_cost_estimate": "medium"
    },
    steps=[
        {
            "step_index": 1,
            "step_role": "fetch",
            "surface_key": "web:solscan:tx_page",
            "surface_type": "web_page",
            "payment_performed": False,
            "status": "success",
            "output_semantic_type": "tx_summary"
        }
    ],
    evidence={
        "evidence_class": "agent_report",
        "verification_status": "self_reported",
        "payment_performed": False
    }
)

🧭 Goal Attempt Memory Read Models (v1.10.0)

While full behavioral mapping is achieved via the premium graph, analyzing the complete monzen-graph.json during an active reasoning loop can cause context-window bloat. ln-church-agent v1.10.0 introduces two lightweight, static S3 snapshot endpoints to read historical attempt context efficiently.

Rational Read Order for Autonomous Agents

To minimize data ingestion and allocation overhead, autonomous agents SHOULD query information using the following hierarchy:

1. Goal Attempt Summary (Free): Query overall volume counters and unassessed ratios to determine base-layer viability.
2. Goal Surface Candidates (Paid - 1 SAT): Fetch up to 20 historically observed surfaces previously harnessed by the network for a specific objective.
3. Full Resonance Graph (Premium - 10 SATS): Download the full multi-chain dataset only when deep analytical structural mapping is required.

Code Example: Fetching Summary and Candidates

from ln_church_agent import LnChurchClient, AssetType

client = LnChurchClient(private_key="0x...")

# 1. Fetch Lightweight Summary (Completely Free)
summary = client.get_goal_attempt_summary(
    goal_type="tx_investigation",
    domain_hint="crypto"
)
print(f"Total Attempts Recorded: {summary['goals'][0]['attempt_count']}")

# 2. Fetch Observed Candidate Surfaces (Paid: 1 SAT / 0.001 USDC / 1 JPYC)
# Warning: If unpaid, this triggers a standard HTTP 402 challenge loop.
candidates = client.get_goal_surface_candidates(
    goal_type="tx_investigation",
    domain_hint="crypto",
    prefer_free_first=True,
    asset=AssetType.SATS,
    scheme="L402"
)

# Candidates are observed records, NOT recommendations or verdicts
for surface in candidates["candidate_groups"][0]["candidate_surfaces"]:
    print(f"Observed Surface: {surface['surface_key']} (Used: {surface['used_count']} times)")

Strict Architectural Guardrails:

• Not a Recommendation. A reusable observation record: Candidate surfaces are historical memory markers, not recipe predictions or active verdicts (not_a_recommendation: true).
• Unassessed Integrity: Traces with missing outcomes indicate an unassessed state, never an execution error.
• Fixed Cost Isolation: Candidate lookups utilize an isolated pricing table, completely decoupled from full graph pricing.

⚡ Start in 5 Minutes

Choose your execution path based on your immediate goal:

Route A: Generic Paid Fetch (Open Web Integration)

Integrate with any HTTP 402 compliant API on the open web. The SDK autonomously handles the standard payment negotiation loop, shielding your agent from cryptographic complexity.

from ln_church_agent import Payment402Client

client = Payment402Client(base_url="https://your-402-api.com", private_key="0x...")

# Inspects 402 -> Applies policy -> Pays if allowed -> Retries -> Verifies response
result = client.execute_request(
    method="POST",
    endpoint_path="/api/protected",
    payload={"input": "data"}
)
print(result)

Route B: Agent Tool Integration (MCP)

Instantly equip any Model Context Protocol (MCP) compatible agent (e.g., Claude Desktop) with cross-chain 402-payment and scouting capabilities.

export AGENT_PRIVATE_KEY="your-0x-prefixed-key"
python -m ln_church_agent.integrations.mcp

Your agent can now autonomously call paid tools and benchmark flows directly from its reasoning loop.

Route C: Public Benchmark against LN Church Sandbox

Prove your agent's parsing and execution capabilities against the physically isolated Agentic Payment Sandbox. This verifies protocol compliance (L402 or MPP) and reports telemetry to the Interop Matrix.

from ln_church_agent import LnChurchClient

client = LnChurchClient(private_key="0x...")

# Autonomously validate standard L402 compliance
l402_result = client.run_l402_sandbox_harness()

# Or, validate the new Machine Payments Protocol (MPP) charge flow
mpp_result = client.run_mpp_charge_sandbox_harness()

print(f"L402 Hash Matched: {l402_result.canonical_hash_matched}")
print(f"MPP Hash Matched: {mpp_result.canonical_hash_matched}")

Observation → Corpus → Synthetic Replay → Agent Dry-run Validation

ln-church-agent v1.8+ closes the agent-side of the LN Church interop loop.

It can read server-side synthetic_from_corpus_v1 replay descriptors and validate whether the local parser and decision engine choose the expected behavior:

• pay_and_verify
• observe_only
• stop_safely
• reject_invalid

This is a dry-run validation path. It does not execute real payments and does not attempt raw wire-level replay.

from ln_church_agent import LnChurchClient

client = LnChurchClient(private_key="0x...")

# Dry-run a synthetic replay descriptor from the Corpus
replay_result = client.run_corpus_replay(
    corpus_id="corp_12345",
    dry_run=True
)

print(f"Success: {replay_result.ok}")
print(f"Expected: {replay_result.expected_action}, Observed: {replay_result.observed_action}")

🛡️ Why teams adopt this runtime

• Avoid tracking protocol churn: Developers should not need to track every upstream revision manually. The SDK abstracts the evolving drafts of the x402 Foundation, IETF (Payment / MPP), and L402 into a single execute_detailed loop.
• Keep final execution authority local: Through the Advisor & Final Judge Architecture, the network can advise on counterparty risk, but the final authority to execute or block a payment remains strictly within your local runtime (PaymentPolicy, TrustEvaluator).
• Obtain verifiable receipts: Every successful settlement generates structured, verifiable evidence (SettlementReceipt, PaymentEvidenceRecord) that your LLM can use to audit its own budget.
• Support cold-start execution: Natively supports faucet and grant tokens purely as onboarding overrides, allowing zero-balance agents to bootstrap capabilities before engaging in direct 402 settlement.
• Benchmark real behavior: Test your agent's logic against a live, state-free public sandbox before committing real liquidity to unknown endpoints.

🔌 Protocol Coverage

The SDK supports multiple settlement rails through a unified interface.

Standard x402 v2 (Global Standards):

• EVM exact (x402): Standard EVM-based settlement utilizing strict EIP-712/EIP-3009 gasless authorization payloads.

• SVM exact (Solana, inspect + payload builder only): The high-level canonical sync/async auto-payment lane is intentionally fail-closed before signer, RPC, or paid retry because a recent blockhash lifetime cannot be proven to end at or before canonical Unix expires_at. The low-level builder can construct and validate standard x402 SVM exact payloads, but it does not broadcast payment or execute the protected action.

• Note: The current LN Church exact sandboxes act as post-settlement validators. They require submitted tx hash / signature evidence and will reject unbroadcasted payloads. True V2 exact settlement (facilitator broadcasting) is a future phase.

• L402 / MPP: Standard Lightning Network settlement (SATS) supporting Macaroon and BOLT11 invoice parsing.

Compatibility & Sandbox Paths (LN Church Extensions):

• lnc-solana-transfer: Legacy compatibility path for direct SPL Token (USDC) transfers via Solana RPC.
• lnc-evm-relay: Optimized gasless relayer orchestration.
• grant / faucet: Cold-start overrides and sponsored access.
• Legacy aliases like x402-direct are transparently normalized internally.

Observable Commerce / Authorization Surfaces (Inspect-Only):

• AP2 (Agent Payments Protocol): Detected via payment/checkout mandate metadata. Classified as an authorization surface. The SDK does not sign mandates.
• ACP (Agentic Commerce Protocol): Detected via checkout, cart, or delegated payment token metadata. The SDK does not execute ACP checkouts.
• OKX APP: Detected when explicit APP metadata or broker objects are present.
• Card-network / wallet-mediated agent payments: Treated as observable commerce or authorization patterns, not native SDK execution targets.

🚀 Dual-Stack Configuration: EVM Execution and SVM Inspection Tooling

For agents operating across both Ethereum and Solana ecosystems, the SDK strictly isolates EVM execution keys from the optional low-level SVM payload builder. Supplying an SVM key does not enable high-level canonical SVM auto-payment.

from ln_church_agent import Payment402Client, PaymentPolicy
import os

client = Payment402Client(
    private_key=os.getenv("EVM_PRIVATE_KEY"),        # For standard x402 EVM
    svm_private_key=os.getenv("SVM_PRIVATE_KEY"),    # Low-level SVM payload builder only
    svm_rpc_url=os.getenv("SOLANA_RPC_URL", "https://api.devnet.solana.com"),
    policy=PaymentPolicy(...)
)

⚠️ SVM Exact Architecture & Constraints:

• High-level canonical SVM exact auto-payment always halts before signer, RPC, or paid retry. Solana recent-blockhash validity is expressed as block height and cannot be mechanically bounded to end at or before canonical Unix expires_at.

• svm_private_key is used only by the low-level payload builder and must be a standard 64-byte Base58 encoded Solana key. It does not make the high-level lane executable.

• The low-level SVM exact builder is distinct from the legacy lnc-solana-transfer route and accepts scheme: "exact" inputs using network: "solana:<genesisHash>".

• Wire-Level Precision: The transaction builder preserves and uses the raw PaymentRequirements.asset (SPL Token Mint Address) and raw amount (minimal units) for wire-level transaction construction. Human-readable normalization is only used internally for policy and budget evaluation.

• ATA Constraint: The Destination Associated Token Account (ATA) must already exist. The current SDK transaction builder does not inject ATA creation instructions.

• Supported Mints: The internal builder currently targets strictly known USDC mints. Unknown mints will be rejected due to unknown decimals.

• Instruction Contract: The builder emits CU limit → CU price → TransferChecked → exactly one Memo.

• Memo Contract: Without extra.memo, the Memo is 16 random bytes encoded as 32 lowercase hex characters. With extra.memo, it is the supplied UTF-8 value. Values over 256 UTF-8 bytes are rejected.

• Architecture Note: The Local SVM Exact Transaction Builder constructs and locally validates standardized VersionedTransaction payloads only; it does not claim high-level canonical payment execution.

• Interop Validation: Payloads with extra.memo absent and present are accepted by the x402 Python 2.16.0 facilitator verifier.

🎟️ Two LN Church Onboarding Paths (Cold-Start Overrides)

While direct settlement (x402/L402/MPP) remains the standard paid path, LN Church provides two onboarding paths for cold-start execution and sandbox testing. Both act as a paymentOverride before standard settlement.

1. Zero-Balance Faucet Fallback

A one-time fallback for agents with no available cryptocurrency. Designed strictly for initial capability verification.

from ln_church_agent import LnChurchClient, AssetType

client = LnChurchClient(
    private_key="0x...",  # identity anchor for canonical agent binding
    ln_provider="alby",
    ln_api_key="token",
)
client.init_probe()
client.claim_faucet_if_empty()

result = client.draw_omikuji(asset=AssetType.SATS) # Uses Faucet override

2. Sponsored Grant Access

Execute using a signed, scoped, single-use grant token issued by a trusted sponsor. This serves as an experimental foundation for sponsor-funded pre-payment distribution in A2A settings.

ln-church-agent v1.8.3 can locally diagnose a grant token before use (client.explain_grant()), explaining whether it appears usable for the target route/method/audience/agentId. This diagnostic is advisory only; the LN Church backend remains the authoritative validator and enforces single-use consumption.

from ln_church_agent import LnChurchClient

client = LnChurchClient(
    private_key="0x...",  # identity anchor for canonical agent binding
    base_url="https://kari.mayim-mayim.com",
)
client.init_probe()

client.set_grant_token("<JWS_GRANT_TOKEN>")
result = client.draw_omikuji()  # Uses Grant override

📜 Standards Tracking Policy

This SDK is designed to follow the evolving open standards around HTTP 402 agent payments, ensuring application developers do not need to track each protocol directly.

• Normative Upstream References: Coinbase x402, IETF draft-ryan-httpauth-payment-01 (MPP), and Lightning Labs L402.
• Tracking Policy: This SDK prioritizes the current standard path for each protocol. Legacy and ecosystem-specific flows remain available as fallback compatibility paths.
• Design Goal: One SDK, one execution loop, multiple 402 payment rails.

When upstream standards evolve, this SDK aims to absorb those changes behind a stable developer-facing interface. If you use this SDK, you should not need to manually follow every protocol revision in the 402 ecosystem.

Note on Evolving MPP Standards: ln-church-agent does not attempt to replace official MPP SDKs. Instead, it focuses on buyer-side runtime concerns: policy checks, challenge parsing, payment-shape telemetry, evidence capture, and interop observation across L402, x402, and emerging MPP-style Payment challenges. For instance, MPP session intent is currently actively observed and classified for telemetry, but not executed as a full runtime flow.

⚖️ Advisor & Final Judge Architecture

Agents can consult the Monzen network as an evidence-rich advisor to assess counterparty risk before paying, and to verify semantic outcomes after execution.

Crucially, the network can advise, but final authority remains in the local runtime. The LN Church backend returns structured recommendations (e.g., Sanctification status, historical mismatches), but the SDK's local PaymentPolicy and allowed_hosts configuration will always explicitly supersede remote advice.

📡 Verified Domain Track Lite Workflow

Register a domain for the public-safe observation track and establish sponsorship proof via the CLI.

# 1. Register and pay (19 USDC)
ln-church-agent observe-domain track register kari.mayim-mayim.com \
  --pay \
  --max-spend-usd 25 \
  --proof-file .ln-church/vdt-kari-proof.json

# 2. Generate sponsor challenge file
ln-church-agent observe-domain sponsor challenge obsreq_123 \
  --proof-file .ln-church/vdt-kari-proof.json \
  --output-file .well-known/ln-church-domain-sponsor.json

# (Host the generated file at your domain's /.well-known/ path)

# 3. Verify sponsorship
ln-church-agent observe-domain sponsor verify obsreq_123 \
  --proof-file .ln-church/vdt-kari-proof.json

# 4. Check status
ln-church-agent observe-domain track status obsreq_123

Confirm the proof file exists locally.

This file contains result_handle/request_hash material.

Do NOT publish it. Do NOT commit it.

test -f .ln-church/vdt-kari-proof.json

Confirm the public challenge document is reachable after publishing.

curl -I https://kari.mayim-mayim.com/.well-known/ln-church-domain-sponsor.json

Confirm the verified track status.

ln-church-agent observe-domain track domain kari.mayim-mayim.com

Test-Path ".ln-church/vdt-kari-proof.json"

curl.exe -I "https://kari.mayim-mayim.com/.well-known/ln-church-domain-sponsor.json"

ln-church-agent observe-domain track domain kari.mayim-mayim.com

📚 Further Documentation

• Quickstart & Authentication
• Architecture & Capabilities
• The LN Church Pilgrimage
• Integrations (MCP & LangChain)
• Monzen Observation Network

License

MIT