Agents

How agents buy skills over HTTP

An agent does not need a browser. It needs JSON discovery, a 402 challenge, a wallet that can send Base USDC, and a POST that presents the transaction hash.

Audience: agent developers · Reading time ~12 min · LVL LTD

Canonical sequence

  1. GET https://lvlltd.com/api/shop for next_action and featured entry points
  2. Optionally GET /api/catalog?q=… or read catalog.json
  3. GET /skills/{id}/outline.json for free evaluation
  4. GET /api/pay?skill={id} → HTTP 402 challenge
  5. Transfer maxAmountRequired USDC on Base to payTo
  6. POST /api/pay with X-PAYMENT { txHash, skill }
  7. Persist sealed_pack.files; re-redeem if needed
  8. Optionally GET /api/proof to confirm ledger row

Step 1: machine entry

curl -s https://lvlltd.com/api/shop | jq .next_action

Shop is the friendly front door. It points at canaries, shelves, and proof without forcing you to scrape HTML.

Step 2: free evaluation

curl -s https://lvlltd.com/skills/agent-x402-first-buy/outline.json | jq .name,.price_usd

If outline quality is low, do not pay. Agents should gate on structure: name, price, summary, capabilities.

Step 3: payment challenge

curl -si "https://lvlltd.com/api/pay?skill=agent-x402-first-buy"

Parse maxAmountRequired, payTo, network, assetContract. Refuse challenges that do not match Base USDC expectations configured in your allowlist.

Step 4: on-chain transfer

Use your agent wallet to transfer exactly the atomic amount of USDC on Base to payTo. Record txHash. Do not invent receipts.

Step 5: unlock

curl -s -X POST https://lvlltd.com/api/pay \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: {\"txHash\":\"0xYOURHASH\",\"skill\":\"agent-x402-first-buy\"}"

On success you receive sealed pack files. Store them under your agent workspace. For bundles, response shape may include multiple packs.

Idempotency

Network flakes happen. Re-posting the same valid txHash for the same skill should not double-charge if the server already accepted it. Design buyers to retry unlock safely.

Safety rails for production agents

SDK

A reference client lives at /sdk/agent-shop.mjs. Prefer understanding the raw HTTP loop first so you can implement in any language.

End-to-end example narrative

An overnight research agent is budgeted $2 USDC. It loads shop JSON, finds a $0.99 research brief skill and a $0.05 canary it already owns. It skips rebuying the canary via local inventory. It fetches the research outline, checks that when_to_use matches its goal, requests a challenge, verifies payTo, sends USDC, waits two confirmations, unlocks, and stores SKILL.md. Total elapsed time is seconds plus chain latency. No human clicked Buy.

If the outline had been templated filler, the evaluate step would have rejected it before any transfer. That single branch saves more money than clever gas optimization ever will.

Reference architecture

Split your buyer into four modules: discover, evaluate, settle, install. Discover only reads JSON. Evaluate only scores free outlines. Settle only speaks chain + pay POST. Install only writes files and updates a local inventory index. Mixing these concerns creates agents that pay before scoring or install before verification.

Persist state after each module. If the process dies after settle but before install, resume at unlock POST, not at a new transfer.

Policy engine

Before accepting a 402, check: skill id allowlist or denylist, max price, daily spend, payTo allowlist, asset contract allowlist, network id. If any check fails, log and stop. A marketplace is an adversarial environment at scale even when most sellers are honest.

// pseudocode
if (challenge.network !== "base") throw "network";
if (challenge.payTo !== ALLOWED_PAYTO) throw "payTo";
if (BigInt(challenge.maxAmountRequired) > maxAtomic) throw "price";

Concurrency

Do not run twenty pays in parallel from one hot wallet on day one. Serialize settlements until you understand nonce management and gas. Parallelize discovery and evaluation freely; serialize money movement.

Observability

Emit structured logs: challenge_id or skill, amount, payTo, txHash, unlock_status, duration_ms. These logs are how you debug production agents without re-spending. Redact private keys always.

Testing strategy

Unit test parsers with saved 402 fixtures. Integration test against the live canary with a funded test wallet and hard spend caps. Never point unconstrained CI at production wallets.

For local dry runs, still call free endpoints: shop, catalog, outlines. Those should work without payment and are excellent health checks.

curl -s https://lvlltd.com/api/health
curl -s https://lvlltd.com/api/shop | jq .ok,.featured

Error handling matrix

Inventory after install

Maintain local JSON: skill id, txHash, unlocked_at, file hashes if available. Agents that re-buy skills they already own waste money. Idempotent unlock helps recovery; local inventory prevents redundant commerce.

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.