LOPWDocumentation

Docs / For AI agents

Agents start here

Everything on this site is available in a form you can consume directly. This page tells you where, then gives you the facts you most often need, in the order you need them.

Machine-readable files

FileWhat it isFormat
/llms.txtIndex of every documentation page with one-line descriptions and links to the Markdown twinsMarkdown (llms.txt convention)
/llms-full.txtThe entire documentation concatenated, generated from the same source as the HTMLMarkdown
/docs/<path>.mdA Markdown twin of every HTML page at the same path, for example /docs/protocol/predicates.md; each HTML page links to it with <link rel="alternate" type="text/markdown">Markdown
/.well-known/lopw.jsonProtocol descriptor: names, flow, wire placement, signing, predicates, states, error codes, floors, SDK exports, chain bindings and every documentation linkJSON
offer.json, receipt.json, terms.jsonJSON Schemas (draft 2020-12) derived from the contract types of the Stellar reference binding, with the XDR mapping in each descriptionJSON Schema
offer-evm.json, receipt-evm.json, terms-evm.jsonThe same types for the EVM binding: Solidity struct fields, the exact EIP-712 type strings and the 0x-hex ABI wire form of SignedOffer and SignedReceiptJSON Schema
/docs/vectors/v1.jsonShared test vectors: exact XDR bytes, hashes and signatures every implementation must reproduceJSON
/docs/api/openapi.jsonOpenAPI 3.1 description of the read-only HTTP APIJSON
/docs/search-index.jsonTitle, section, headings and text of every page, used by the site searchJSON

Facts you need first

To decide whether to pay a service

  1. Read its bond: the service’s own GET /v1/warranty if it exposes one, GET /v1/{network}/services/{id} on the public API, or get_service and get_terms on the registry.
  2. Require state == "Active", stake at or above your threshold, the predicates you care about in terms.predicates, and an offer max_claim at or above your floor.
  3. Verify the offer signature against get_key(service_id, offer.key_version), check valid_until, and check that offer.terms_hash equals the service’s current terms_hash and that price and asset match the x402 requirement.
  4. The buyer SDK does all of this in agent.fetch(url) with a BuyerPolicy: Getting started for agents (Markdown).

To verify a receipt you received

  1. Decode PAYMENT-RESPONSE.extensions.lopw.receipt (base64 ScVal XDR of SignedReceipt).
  2. Compute receipt_hash with the registry the Claims contract serves and verify the Ed25519 signature with get_key(service_id, receipt.key_version).public_key; the key must not have retired_at at or before served_at.
  3. Check offer_hash equals the hash of the offer you paid, buyer is your address, payment_reference is the settlement transaction, request_hash and response_hash match what you sent and received, response_bytes is the body length and status is the HTTP status.
  4. Evaluate each predicate in the terms exactly as in Predicates (Markdown); for P6 read price(oracle_asset, oracle_timestamp) from the oracle named in the terms.
  5. Any failure in step 2 or 3 means the response is untrusted and cannot be claimed. A breach in step 4 can be claimed until served_at + claim_window.

To file a claim

Claims contract
claim(predicate_id: u32, offer: SignedOffer, receipt: SignedReceipt, extra: ClaimExtra) -> Result<ClaimOutcome, ClaimError>
// extra = SecondReceipt(second_signed_receipt) for predicate 1, None otherwise
// Ok(Paid(amount)) | Ok(Rejected(1 NotProven | 2 NotVerifiable)) | Err(1 UnknownService .. 11 SlashRateLimited)

With the SDK: agent.claim(warranty). Without it: binding.submitClaim(signer, predicateId, offer, receipt, secondReceipt?) in @lopw/protocol, which waits one ledger if needed, submits, and decodes the outcome. Error codes and their causes: Claims (Markdown).

To read protocol state without a key

NeedWhere
Network totalsGET /v1/{network}/stats
Services, filtered by stateGET /v1/{network}/services?state=Active&cursor=&limit=
One service with claim totalsGET /v1/{network}/services/{id}
Claims, newest firstGET /v1/{network}/claims?outcome=paid|rejected or per service /services/{id}/claims
Live eventsGET /v1/{network}/stream (Server-Sent Events; resume with Last-Event-ID)
Recorded scenario runsGET /v1/{network}/scenarios?runs=5
The chain itselfget_service, get_terms, get_key, get_claim, get_validator through a read-only simulation

Conventions: JSON, snake_case, amounts as decimal strings, times as Unix seconds, 32-byte values as lowercase hex, cursor pagination, ETags, problem+json errors, open CORS. Full reference: HTTP API (Markdown).

Page map

Start here

  • What is LOPW (.md): LOPW in plain words: a seller puts money behind a promise, every paid answer comes with a signed receipt, and a broken promise pays the buyer automatically. Start here.
  • How a warranty works (.md): An animated, step-by-step walk through a LOPW warranty: offer, payment, receipt, local check, claim, validator, and payout or rejection.
  • Who it is for (.md): What LOPW gives agents, API sellers and platforms, what each has to do, and where each should start reading.
  • Glossary (.md): Every LOPW term in one place, from stake and terms to predicates, epochs and key versions, with links to where each is specified.
  • FAQ (.md): Short answers to the first questions people ask about LOPW: what it costs, what it covers, what it cannot do, and how it relates to x402.

Guides

  • Getting started (.md): Pick your track: make an agent pay only bonded x402 services, add a stake-backed warranty to your x402 API, or read bonds and claims from any app over HTTP.
  • Getting started for agents (.md): Make an agent pay only bonded x402 services with @lopw/buyer-sdk: install, set a policy, fetch with warranty checks before and after payment, and claim when a promise is broken.
  • Getting started for sellers (.md): Add a stake-backed warranty to an x402 API: generate a signing key, choose terms, register and stake in the Bond Registry, and add @lopw/seller-middleware to your resource server.
  • Getting started for app builders (.md): Read bonded services, claims, events and live streams from the public LOPW HTTP API: JSON, cursor pagination, ETags, problem+json errors and Server-Sent Events, with open CORS.
  • How-to guides (.md): Task-focused recipes for sellers, agents and apps: add a warranty, pay only bonded services, file a claim, choose predicates, rotate keys, unbond, read a bond, run the scenarios.
  • Add a warranty to an x402 API (.md): Checklist to turn an existing x402 endpoint into a bonded one: signing key, terms, registration, stake, the lopw extension and the freshness header.
  • Make an agent pay only bonded services (.md): Configure the buyer policy so an agent refuses unbonded, under-staked or under-covered sellers before any money moves, and handle refusals.
  • File a claim (.md): From a breached receipt to a payout: what the SDK checks, when to claim, what the Claims contract returns, and every error you can meet.
  • Choose predicates and limits (.md): How a seller picks which predicates to promise and sets limits it can keep: parameters per predicate, claim window, max_claim and min_stake, and the registry's validity rules.
  • Rotate a signing key (.md): Replace a service's Ed25519 signing key without stranding any receipt: what rotate_key does, what happens to old receipts, and what a leaked key can no longer do.
  • Withdraw stake safely (.md): Partial and full withdrawals through request_unbond, the unbonding delay, cancel_unbond, withdraw, and what remains slashable, with the exact contract rules.
  • Read a bond from any app (.md): Three ways to read a service's bond without a wallet: the service's own GET /v1/warranty, the public API, and a direct chain read with the protocol package.
  • Run the scenarios yourself (.md): Reproduce every demonstrated scenario with the demo agent against the reference services: honest quote, each predicate's breach, tampered signature, replay, honest claim rejected and policy refusal.

Protocol reference

  • Protocol overview (.md): The LOPW protocol for engineers: the six roles, the eight-step flow, the three kinds of contract, what is portable across chains and what is not, and what is out of scope.
  • Offer, receipt and terms (.md): Field-by-field reference for the LOPW Terms, Offer, Receipt and oracle types, exactly as the contract types define them, with validity rules and JSON Schemas.
  • Hashing and signing (.md): Exactly which bytes are hashed and signed in LOPW: ScVal XDR encoding, the domain-separated message, request and terms hashes, service IDs, key rotation, replay protection and the shared test vectors.
  • Predicates P1 to P6 (.md): The six LOPW breach conditions with their exact proven conditions and edge rules (data_as_of 0, oracle tick rounding, the exact deviation test), the validator interface, and an interactive explorer.
  • Claims (.md): The LOPW Claims contract: the seven checks in order (animated), outcomes, every error code, the payout rule, records, events and functions.
  • Bond Registry (.md): The LOPW Bond Registry: every function, event and error, the five service states with an animated state machine, protocol floors, launch limits, fees, time locks, the slash rate limit and the unbonding maths with a calculator.
  • x402 extension (.md): The LOPW x402 v2 extension on the wire: where the signed offer and receipt travel, the exact JSON shapes, the buyer echo, the handler headers, and why verify and settle are untouched.
  • HTTP API (.md): The read-only LOPW HTTP API: every public endpoint, parameters, response shapes, pagination, caching, errors and the Server-Sent Events stream, with the OpenAPI 3.1 document.
  • Chain bindings (.md): What a LOPW chain binding supplies, and the Stellar binding in detail: Soroban contracts, USDC stake, x402 exact payments, SEP-40 oracles, ScVal XDR and Ed25519.

Networks

  • Networks (.md): LOPW is one protocol with the same semantics on every chain. What a chain binding is, what differs per chain (signatures, hashing, token, oracle, x402 scheme), a comparison table, and the networks: Stellar as the reference binding, the EVM networks, and the planned Solana binding.
  • Stellar (.md): The reference LOPW binding: Soroban contracts, Ed25519 signatures, SHA-256 over domain-separated ScVal XDR, the USDC Stellar Asset Contract with 7 decimals, Reflector SEP-40 oracles, x402 exact with SEP-41, network names testnet and mainnet, and the live contract addresses on Stellar testnet.
  • EVM binding (.md): The LOPW binding shared by Base, Ethereum, Arbitrum, Optimism, Polygon and Avalanche: Solidity contracts, EIP-712 typed data with the exact type strings, keccak-256 termsHash, secp256k1 signatures, Chainlink getRoundData(roundId) with the round id as the citation, EIP-3009 for x402, ABI-hex wire encoding, and confirmations before indexing.
  • Base (.md): LOPW on Base through the EVM binding: chain ids and CAIP-2 ids for Base Sepolia and Base, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
  • Ethereum (.md): LOPW on Ethereum through the EVM binding: chain ids and CAIP-2 ids for Ethereum Sepolia and Ethereum, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
  • Arbitrum (.md): LOPW on Arbitrum through the EVM binding: chain ids and CAIP-2 ids for Arbitrum Sepolia and Arbitrum One, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
  • Optimism (.md): LOPW on Optimism through the EVM binding: chain ids and CAIP-2 ids for OP Sepolia and OP Mainnet, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
  • Polygon (.md): LOPW on Polygon through the EVM binding: chain ids and CAIP-2 ids for Polygon Amoy and Polygon PoS, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
  • Avalanche (.md): LOPW on Avalanche through the EVM binding: chain ids and CAIP-2 ids for Avalanche Fuji and Avalanche C-Chain, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
  • Solana (.md): The planned LOPW binding for Solana, as a design: Anchor programs, Ed25519 over domain-separated SHA-256 of Borsh bytes, USDC SPL with 6 decimals, Pyth price updates verified in-program, x402 exact with an SPL transfer, and the network names solana-devnet and solana. Nothing is deployed.

Deep dive

  • Security model (.md): LOPW's security model: what is protected, trust assumptions, the threats and their mitigations, residual risks, and the known limits accepted in version 1.
  • Economics (.md): What a seller risks and pays, what a buyer gains and pays, how the payout, caps, epochs and fees interact, with exact fee maths and worked examples.
  • The decisions log, explained (.md): Why each LOPW rule exists: the twenty-two recorded decisions that refine the specification, in plain language, with what they changed and why.
  • Proofs and scenarios (.md): What LOPW has demonstrated on a live network: every predicate's payout after a real x402 payment, the stake lifecycle, governance safety and the automated test suites, with links to the demo and proofs pages.

For AI agents

  • Agents start here (.md): Machine-readable entry point to LOPW: Markdown twins of every page, llms.txt, llms-full.txt, the protocol descriptor, JSON Schemas for Offer, Receipt and Terms, shared test vectors and the OpenAPI document, plus the facts an agent needs to decide and act.