# Agent Economy Rails — LVL LTD (2026+)

**Operator:** LVL LTD CO / OMGawdMadeit / Dr.Drop-it  
**Canonical surface:** https://lvlltd.com  
**Proof authority:** https://lvlltd.com/api/proof (only source of unlock counts / volume)  
**Readiness:** https://lvlltd.com/api/ready  

This document is the machine- and human-readable contract for the foundational rails that make autonomous agent commerce reliable, economic, and honest.

---

## Why these rails (economic thesis)

Autonomous agents cannot trust marketing dashboards. They need:

1. **Atomic settlement** they can complete without a human (x402 + Base USDC).
2. **Free evaluation** before any payment (outline + sample).
3. **Idempotent unlock** so a single `txHash` is a permanent credential.
4. **Public proof** that anyone can re-verify on-chain — zero inventable metrics.
5. **Open discovery** (llms.txt, OpenAPI, MCP, A2A) so foreign agents find and buy without scraping HTML.

Inflated unlock counts, fake reputation scores, and “API key to buy” models break agent economies. LVL rails refuse those.

**Sacred invariants**

| Invariant | Enforcement |
|-----------|-------------|
| Free outline before pay | `/skills/{id}/outline.json` + `sample.md` always public |
| One tx → permanent access | Idempotent `POST /api/pay` redeem by `txHash` |
| Proof ledger is truth | `/api/proof` only; never invent volume |
| Wallet-native buy | No API key required for first-party unlocks |
| Ready is truthful | `/api/ready` fails when challenge_shape / live 402 / sealed pack break |

---

## Prioritized roadmap

### P0 — Payment + Discovery + Proof (NOW)

| Rail | Deliverable | Acceptance |
|------|-------------|------------|
| Payment | Hardened x402 GET→402→USDC→POST unlock; EIP-55 safe challenge_shape; canary `$0.05`; recover path | Agent pure HTTP purchase works; human MetaMask works; `/api/ready` → `ready:true` |
| Discovery | Catalog schema fields; `/catalog.json` + `/api/catalog`; OpenAPI; llms.txt; shop entry | Agent: shop → catalog → outline → pay with zero human steps |
| Proof | `/api/proof` confirmed-only; BaseScan links; honest zero-state | Anyone verifies every unlock on-chain |

**P0 tests**

```bash
npm run test:challenge-shape:local   # EIP-55 unit gates
npm run test:challenge-shape         # live ready + multi-skill 402 + proof honesty
npm run test:agent-purchase          # 402 reliability (+ optional AGENT_PURCHASE_TX redeem)
npm run smoke                        # production smoke
```

### P1 — Identity, Delivery, Observability *(implemented)*

| Rail | Deliverable | Acceptance | Status |
|------|-------------|------------|--------|
| Identity | Wallet proof = credential; short-lived capability tokens after pay (`lvl-capability-token-v1`) | No API key to unlock first-party skill; tokens scoped + TTL | **Code ready** |
| Sealed delivery | Versioned packs; `sealed_pack_hash` from manifest; integrity on unlock; idempotent re-download | Same `txHash` always same files; hash verifiable | **Code ready** |
| Observability | status.json, ready, status-history, `trace_id` on unlocks + ledger | Public metrics match proof ledger | **Code ready** |

**P1 surfaces**

| Path | Role |
|------|------|
| `POST /api/pay` unlock response | Issues `capability` (short TTL) + `license` (long) + `trace_id` + `sealed_pack.integrity` |
| `GET/POST /api/capability` | Discovery, verify token, re-issue from verified license only |
| `X-CAPABILITY` on `POST /api/pay` | Redownload during capability TTL without chain re-scan |
| `GET /api/packs?skill=` | Public `sealed_pack_hash` / version (no paywall contents) |
| `/api/proof` recent_unlocks | Surfaces `trace_id` when ledger has one (never invents) |

**P1 tests**

```bash
npm run test:p1-rails:local
npm run test:p1-rails
npm run promote:sealed-hashes
```

### P2 — Execution, Interop, Escrow, Multi-asset

| Rail | Deliverable | Acceptance |
|------|-------------|------------|
| Sandbox | Documented container patterns; optional SBOM/sign (additive) | Skills run isolated with documented resources |
| Interop | Full MCP tools; A2A cards; fleet.json; swarm bridges | External agent discovers via MCP/A2A and calls tools |
| Escrow | Open-market multi-party escrow (not skill payTo) | Third-party listing settles without polluting treasury |
| Multi-asset / gas | USDbC accepted; gas abstraction / sponsored canary path | Canary unlock possible with lower gas friction |
| Multi-chain | Extension points beyond Base | Clear CAIP-2 network fields in challenges |

---

## Concrete schemas

### Skill record (`lvl-skill-v1`)

```json
{
  "id": "agent-x402-first-buy",
  "name": "Agent x402 First Buy",
  "price_usd": 0.05,
  "price_label": "$0.05 / unlock",
  "category": "payments",
  "quality_score": 54,
  "last_verified": "2026-07-27T14:17:42.308Z",
  "depth_label": "Deep",
  "implementation_quality": "deep",
  "free_outline_url": "https://lvlltd.com/skills/agent-x402-first-buy/outline.json",
  "sample_url": "https://lvlltd.com/skills/agent-x402-first-buy/sample.md",
  "sealed_pack_hash": null,
  "tags": ["x402", "canary"],
  "execution_notes": "Canary path for first agent purchase",
  "x402": {
    "challenge": "https://lvlltd.com/api/pay?skill=agent-x402-first-buy",
    "max_amount_atomic": "50000",
    "network": "base",
    "network_caip2": "eip155:8453",
    "asset": "USDC",
    "asset_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "quality": { "score_0_100": 54, "reasons": ["detail_rich"] },
  "trust": { "schema_version": "lvl-trust-scorecard-v1", "unproven": true }
}
```

**Honesty rules**

- `quality_score` — measured from pack content (`quality.score_0_100`); never random/marketing.
- `last_verified` — real verification timestamp from trust/execution/detail; **null is valid**.
- Never invent unlock counts, GMV, or reputation on skill cards.

### HTTP 402 challenge (x402 v2 + LVL legacy fields)

Agents MUST parse:

| Field | Meaning |
|-------|---------|
| `maxAmountRequired` / `amount` | Atomic USDC (6 decimals) |
| `payTo` | Treasury (EIP-55 or any case; normalize to lower for compare) |
| `network` + `network_caip2` | `base` + `eip155:8453` |
| `asset` + `assetContract` | USDC on Base |
| `skill` / `skill_id` | Catalog id |
| `accepts[0]` | CDP/Bazaar v2 entry (same money fields) |
| `outline` / `sample` | Free eval URLs |
| `recover` | Stuck payment recovery |

### Unlock request

```http
POST /api/pay
Content-Type: application/json
X-PAYMENT: {"txHash":"0x…","skill":"agent-x402-first-buy"}

{"skill":"agent-x402-first-buy","txHash":"0x…"}
```

Response includes `sealed_pack.files` (and `sealed_packs` for bundles). Same `txHash` re-redeems forever.

### Proof ledger (`lvl-agent-purchase-proof-v2`)

- `confirmed.unlock_count` / `volume_usdc` — KV ledger only
- `recent_unlocks[]` — each with `txHash`, `explorer` (BaseScan)
- `activity.empty_state` — required when count is 0
- Never emit invented rows

### Ready probe (`/api/ready`)

Critical checks (any fail → `ready:false`, HTTP 503):

1. `catalog` — skill_count > 0  
2. `challenge_shape` — multi-skill probes; **payTo case-insensitive (EIP-55 safe)**  
3. `challenge_live_402` — live GET `/api/pay` returns 402 (optional soft-fail if self-fetch blocked)  
4. `sealed_pack` — locked or teaser present  
5. `x402_live` — payments enabled  

Optional: `kv_bound`.

---

## Endpoint map (machine)

| Path | Role |
|------|------|
| `/api/shop` | Unified entry: next_action, shelves, proof, fleet |
| `/api/catalog` | Searchable catalog |
| `/catalog.json` | Full static catalog |
| `/api/pay` | 402 challenge + unlock |
| `/api/recover` | Stuck payment recovery |
| `/api/proof` | Public unlock ledger |
| `/api/ready` | Truthful readiness |
| `/api/mcp` | MCP tools for marketplace |
| `/api/a2a` | A2A JSON-RPC |
| `/.well-known/agent.json` | A2A agent card |
| `/llms.txt` · `/.well-known/llms.txt` | Living machine contract |
| `/openapi.json` | OpenAPI 3.1 |
| `/status.json` | Brand + inventory + health authority |
| `/fleet.json` | Fleet map |
| `/contracts.json` | On-chain address allowlist |

Sister surfaces: music.lvlltd.com · swarm.lvlltd.com · studio.lvlltd.com · tesla-trek.com

---

## Code / config changes (this pass)

| Path | Change |
|------|--------|
| `functions/api/ready.js` | EIP-55 case-insensitive challenge_shape; multi-skill probes; live 402; money_safety |
| `scripts/test-challenge-shape.mjs` | Unit + live suite |
| `scripts/lib/canonical-skill.mjs` | `attachHonestQualityFields` → `quality_score` + `last_verified` + `sealed_pack_hash` |
| `scripts/classify-skill-depth.mjs` | Honest last_verified (no wall-clock invent) |
| `scripts/promote-quality-fields.mjs` | Offline promote onto catalog*.json |
| `functions/api/lib/capability-token.js` | P1 short-lived capability tokens (HMAC, scoped) |
| `functions/api/capability.js` | Capability discovery / verify / re-issue from license |
| `functions/api/lib/pack-integrity.js` | Content-addressed + delivery hashes |
| `functions/api/pay.js` | Issue capability + `trace_id`; X-CAPABILITY redeem; pack integrity |
| `functions/api/lib/revenue-ledger.js` | Persist optional `trace_id` |
| `functions/api/proof.js` | Surface real `trace_id` on public unlocks |
| `functions/api/packs.js` | Public `sealed_pack_hash` / version |
| `scripts/promote-sealed-hashes.mjs` | Catalog sealed_pack_hash from manifest |
| `scripts/test-p1-rails.mjs` | P1 unit + live suite |
| `public/status.json` | readiness + changelog |
| `docs/AGENT-RAILS-2026.md` | This roadmap |
| `package.json` | challenge-shape + p1-rails + promote scripts |

---

## Test plan

### Agent purchase flow

1. `GET /api/shop` → next_action  
2. `GET /api/catalog?q=x402`  
3. `GET /skills/agent-x402-first-buy/outline.json`  
4. `GET /api/pay?skill=agent-x402-first-buy` → 402, amount `50000`  
5. Transfer atomic USDC on Base to `payTo`  
6. `POST /api/pay` with `X-PAYMENT`  
7. Assert `sealed_pack.files` non-empty  
8. Re-POST same tx → same files (idempotent)  
9. `GET /api/proof` → row with matching txHash  

```bash
npm run test:agent-purchase
AGENT_PURCHASE_TX=0x… AGENT_PURCHASE_SKILL=aie-premium-access-token npm run test:agent-purchase
```

### Readiness probes

```bash
npm run test:challenge-shape:local
npm run test:challenge-shape
curl -sS https://lvlltd.com/api/ready | jq '.ready, .checks'
```

### Honesty constraints

- Unlock count must equal ledger length (no synthetic inflation)  
- Volume with zero unlocks is a hard fail  
- `quality_score` only from measured quality  
- `last_verified` null when unverified  
- Legacy treasury `0xabEB…` never appears as payTo  

---

## Residual risks & next layer

| Risk | Mitigation |
|------|------------|
| ETH gas friction blocks canary | P2 gas abstraction / sponsored canary path |
| Self-fetch 402 probe blocked on edge | challenge_shape remains hard gate; live probe optional |
| Catalog quality thin for stubs | quality gate + destub phase; demote outline_only |
| Escrow vs treasury confusion | contracts.json separates roles; skill payTo is treasury only |
| Multi-chain fragmentation | Keep Base primary; CAIP-2 fields already on challenges |
| Agent memory / orchestration depth | Sister brain + swarm; not on critical money path |
| Real-world oracles | Out of band; never invent oracle outputs as “unlocks” |

**Recommended next layer (post-P0)**

1. Sponsored gas for `$0.05` canary  
2. Capability tokens (short-lived, scoped) after verified pay  
3. Content-addressed sealed pack hashes on catalog  
4. Vector search `/api/catalog?semantic=`  
5. Super Alignment auditor hooks on high-stakes unlocks  
6. Deeper fleet orchestration (swarm.lvlltd.com) with proof-linked missions  

---

## Operator deploy checklist (P0)

```bash
npm run test:challenge-shape:local
npm run promote:quality-fields
npm run ci:check
# deploy Pages functions (ready.js) + static public/
npm run cf:deploy   # or project’s production deploy path
npm run test:challenge-shape
npm run test:agent-purchase
curl -sS https://lvlltd.com/api/ready | jq .
```

Confirm:

- [ ] `ready:true`  
- [ ] `challenge_shape.ok` with EIP-55 note  
- [ ] Canary 402 amount `50000`  
- [ ] `/api/proof` unlock_count matches reality  
- [ ] Catalog skills expose `quality_score` (and honest null `last_verified` where applicable)  

---

*Signature: ♾️ — verifiable, not inflated.*