Agent-readable discovery surfaces

If your agent only parses SPAs, you will miss half the market. LVL publishes JSON and text discovery on purpose.

Why JSON-first

Single-page apps are fine for humans. Agents waste tokens and fail on client-only grids. Static HTML listings and JSON catalogs are stable, cacheable, and scriptable.

Primary surfaces

/llms.txt and /llms-full.txt: curated and full maps for LLMs
/catalog.json: full skill inventory with prices and ids
/api/catalog: searchable slim catalog
/api/shop: unified entry with next_action
/agent.json and /.well-known/agent.json: site and A2A identity
/openapi.json and /protocols.json: machine schemas
/schema/products.jsonld and /listings/: schema.org product pages
/learn/guides.json: this Learn guide index

Recommended crawl order

GET /llms.txt
GET /api/shop
GET /catalog.json or /api/catalog?q=
GET free outline for candidates
GET pay challenge only when ready to spend

HTML still matters

Listings under /listings/{id}/ carry Product schema for search engines and careful human readers. Treat them as parallel truth to catalog.json, not as the only agent path.

Anti-patterns

Scraping the marketplace DOM for prices
Ignoring free outlines
Paying without allowlisting payTo
Trusting third-party scam scores over /api/proof and BaseScan

Discovery smoke test you can run now

In under a minute, an agent (or you) can: fetch llms.txt, fetch guides.json, fetch catalog skill_count, fetch shop, fetch one outline, fetch one 402 challenge, and fetch proof. If any step fails, you know whether the outage is education, inventory, commerce, or settlement related.

curl -s -o /dev/null -w "%{http_code}\n" https://lvlltd.com/llms.txt
curl -s -o /dev/null -w "%{http_code}\n" https://lvlltd.com/catalog.json
curl -s -o /dev/null -w "%{http_code}\n" https://lvlltd.com/api/shop
curl -s -o /dev/null -w "%{http_code}\n" https://lvlltd.com/api/proof
curl -si "https://lvlltd.com/api/pay?skill=agent-x402-first-buy" | head -n 1

Automate that as a cron health check for your buyer fleet.

llms.txt as table of contents

llms.txt is intentionally short so models load it first. llms-full.txt expands to the full skill map. Learn guides are linked so education is as discoverable as commerce. If you maintain a fork or mirror, keep llms.txt honest about what is live.

curl -s https://lvlltd.com/llms.txt | head

catalog.json as inventory

This file is large on purpose. It is the full shelf. Cache it with short TTLs. Prefer ETag or short max-age headers already set in production. skill_count should match skills array length; treat mismatches as build bugs.

agent.json versus A2A agent card

Site discovery identity and A2A signed cards are related but not identical schemas. Read discovery_note fields when present. Do not conflate them in your client. If you implement A2A, fetch /.well-known/agent.json and follow that protocol's task model for non-payment work. Payment still settles via x402 HTTP.

OpenAPI driven clients

Generated clients reduce human error. Even partial OpenAPI coverage is better than pure scrape. When OpenAPI lags a new endpoint, prefer measured curl fixtures over hallucinations.

Listings HTML for hybrid agents

Some agents use browser tools. Schema.org Product markup on /listings/{id}/ helps those agents and search engines. Still prefer JSON when both exist.

curl -s https://lvlltd.com/learn/guides.json | jq .count,.guides[0]

Change detection

Poll catalog skill_count and updated_at if present. Alert when count drops sharply (possible delist) or when payTo changes (policy event). Discovery is not static infrastructure; treat it as a product surface that ships.

Field notes from live rails

Everything in this guide is meant to match production behavior on lvlltd.com: free outlines at /skills/{id}/outline.json, challenges at /api/pay, settlement in USDC on Base chain ID 8453, unlock proofs that can be checked on BaseScan, and a public ledger at /api/proof that refuses to invent volume. If a third-party article disagrees with those primary surfaces, trust the primary surfaces.

When you teach teammates, walk them through one canary unlock before any architecture debate. Shared scars on a $0.05 purchase create better systems design conversations than slides alone. Keep notes on what confused people; those notes should become checklist items in your internal runbook and, if you sell skills, clearer outline text for the next buyer.

Finally, remember the integrity line that LVL repeats for a reason: understanding is free; sealed capability is optional and paid. Education pages like this one should make you more demanding, not more impulsive. Read outlines. Allowlist addresses. Prefer small spends first. Verify. Then scale.

Related live checks

After reading, run at least two live checks: open the free outline for a skill you care about, and open /api/proof. Optionally issue a pay challenge with curl and confirm you see HTTP 402 with amount and payTo fields. Those three actions connect this article to production reality in under two minutes.

If you maintain internal wiki mirrors of these guides, include the canonical URLs on lvlltd.com so agents and humans can detect drift. Canonicals and llms.txt exist so education stays discoverable next to commerce, not buried in a slide deck.