# Agents start here

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

*LOPW documentation · For AI agents.* Canonical page: https://lopw.com/docs/agents/ · This Markdown twin: https://lopw.com/docs/agents/index.md · Index of all pages: https://lopw.com/llms.txt · Everything in one file: https://lopw.com/llms-full.txt

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

| File | What it is | Format |
| --- | --- | --- |
| [/llms.txt](https://lopw.com/llms.txt) | Index of every documentation page with one-line descriptions and links to the Markdown twins | Markdown (llms.txt convention) |
| [/llms-full.txt](https://lopw.com/llms-full.txt) | The entire documentation concatenated, generated from the same source as the HTML | Markdown |
| `/docs/.md` | A Markdown twin of every HTML page at the same path, for example [/docs/protocol/predicates.md](https://lopw.com/docs/protocol/predicates.md); each HTML page links to it with `` | Markdown |
| [/.well-known/lopw.json](https://lopw.com/.well-known/lopw.json) | Protocol descriptor: names, flow, wire placement, signing, predicates, states, error codes, floors, SDK exports, chain bindings and every documentation link | JSON |
| [offer.json](https://lopw.com/docs/schemas/offer.json), [receipt.json](https://lopw.com/docs/schemas/receipt.json), [terms.json](https://lopw.com/docs/schemas/terms.json) | JSON Schemas (draft 2020-12) derived from the contract types of the Stellar reference binding, with the XDR mapping in each description | JSON Schema |
| [offer-evm.json](https://lopw.com/docs/schemas/offer-evm.json), [receipt-evm.json](https://lopw.com/docs/schemas/receipt-evm.json), [terms-evm.json](https://lopw.com/docs/schemas/terms-evm.json) | The 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 SignedReceipt | JSON Schema |
| [/docs/vectors/v1.json](https://lopw.com/docs/vectors/v1.json) | Shared test vectors: exact XDR bytes, hashes and signatures every implementation must reproduce | JSON |
| [/docs/api/openapi.json](https://lopw.com/docs/api/openapi.json) | OpenAPI 3.1 description of the read-only HTTP API | JSON |
| [/docs/search-index.json](https://lopw.com/docs/search-index.json) | Title, section, headings and text of every page, used by the site search | JSON |

## Facts you need first

- **Protocol version** 1. Offers and receipts with any other `version` fail a claim with `UnsupportedVersion`.
- **Wire:** x402 v2 extension `lopw`. Offer: `PaymentRequired.extensions.lopw.info.offer` (`SignedOffer`), echoed in `PaymentPayload.extensions.lopw`. Receipt: `PAYMENT-RESPONSE.extensions.lopw.receipt` (`SignedReceipt`). The encoding of those two values is the only per-chain difference in the envelope: base64 ScVal XDR on Stellar, 0x-hex ABI encoding on EVM networks.
- **Signing:** on Stellar (reference binding) `message = SHA-256(tag || network_id || XDR(registry) || XDR(body))`, tags `LOPW/OFFER/v1` and `LOPW/RECEIPT/v1`, `network_id = SHA-256(passphrase)`, Ed25519 over the 32-byte message by a dedicated service key that cannot move stake. On EVM networks the same fields are EIP-712 typed data under the domain `LOPW` / `1` / `chainId` / registry, signed with secp256k1.
- **Networks:** one protocol, the same semantics on every chain. `testnet` and `mainnet` are Stellar (`stellar:testnet`, `stellar:pubnet`); `base-sepolia`, `base`, `sepolia`, `ethereum`, `arbitrum-sepolia`, `arbitrum`, `optimism-sepolia`, `optimism`, `polygon-amoy`, `polygon`, `avalanche-fuji`, `avalanche` are `eip155:`; Solana is a planned binding. Per-network ids, addresses and deployment status: [Networks](https://lopw.com/docs/networks/) and `networks[]` in [lopw.json](https://lopw.com/.well-known/lopw.json).
- **Predicates:** 1 Equivocation, 2 Terms mismatch, 3 Stale data (`served_at − data_as_of > max_data_age`; 0 means not applicable), 4 Bad status, 5 Size limit, 6 Oracle deviation (`|reported − oracle| × 10000 > bps × oracle` against the observation the oracle returns for the cited timestamp).
- **Payout:** `min(max_claim, stake remaining)`, capped by `max_payout` if set, to `receipt.buyer`; one paid claim per `(service_id, payment_reference)`; at most 50% of epoch-start stake per epoch.
- **Service states:** Pending, Active, Suspended, Unbonding, Closed. Pay only Active services.
- **Floors:** `min_stake` at least 100 USDC (1,000,000,000 units of 7 decimals); claim window at most 24 h, at most 1 h with P6; unbonding delay = largest claim window ever + 1 h; admin time lock 26 h.
- **Not slashable:** invalid signature, missing receipt, receipt citing an offer you never saw, answer quality, latency only you observed.

## 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)](https://lopw.com/docs/guides/agents.md).

## 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)](https://lopw.com/docs/protocol/predicates.md); 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*

```text
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)](https://lopw.com/docs/protocol/claims.md#error-codes).

## To read protocol state without a key

| Need | Where |
| --- | --- |
| Network totals | `GET /v1/{network}/stats` |
| Services, filtered by state | `GET /v1/{network}/services?state=Active&cursor=&limit=` |
| One service with claim totals | `GET /v1/{network}/services/{id}` |
| Claims, newest first | `GET /v1/{network}/claims?outcome=paid\|rejected` or per service `/services/{id}/claims` |
| Live events | `GET /v1/{network}/stream` (Server-Sent Events; resume with `Last-Event-ID`) |
| Recorded scenario runs | `GET /v1/{network}/scenarios?runs=5` |
| The chain itself | `get_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)](https://lopw.com/docs/protocol/api.md).

## Page map

**Start here**

- [What is LOPW](https://lopw.com/docs/index.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](https://lopw.com/docs/start/how-it-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](https://lopw.com/docs/start/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](https://lopw.com/docs/start/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](https://lopw.com/docs/start/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](https://lopw.com/docs/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](https://lopw.com/docs/guides/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](https://lopw.com/docs/guides/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](https://lopw.com/docs/guides/apps.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](https://lopw.com/docs/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](https://lopw.com/docs/guides/add-warranty.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](https://lopw.com/docs/guides/bonded-only.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](https://lopw.com/docs/guides/file-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](https://lopw.com/docs/guides/predicates-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](https://lopw.com/docs/guides/rotate-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](https://lopw.com/docs/guides/unbonding.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](https://lopw.com/docs/guides/read-bond.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](https://lopw.com/docs/guides/run-scenarios.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](https://lopw.com/docs/protocol/index.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](https://lopw.com/docs/protocol/offer-and-receipt.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](https://lopw.com/docs/protocol/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](https://lopw.com/docs/protocol/predicates.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](https://lopw.com/docs/protocol/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](https://lopw.com/docs/protocol/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](https://lopw.com/docs/protocol/x402.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](https://lopw.com/docs/protocol/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](https://lopw.com/docs/protocol/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](https://lopw.com/docs/networks/index.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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/evm.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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/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](https://lopw.com/docs/networks/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](https://lopw.com/docs/deep-dive/security.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](https://lopw.com/docs/deep-dive/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](https://lopw.com/docs/deep-dive/decisions.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](https://lopw.com/docs/deep-dive/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](https://lopw.com/docs/agents/index.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.