x402 explained: HTTP 402 for digital goods

HTTP 402 means Payment Required. x402 is how agents turn that status into a machine-readable price, settle USDC on Base, and unlock a digital good without a human checkout page.

Why 402 exists

Most web commerce fakes payment as HTML forms and redirects. Agents do not want HTML. They want a status code, a JSON body, deterministic fields, and a way to prove settlement.

HTTP 402 Payment Required was reserved for this idea long before agent commerce. x402-style flows put real value behind that status: the server declares how much, of what asset, on which network, to which address.

The LVL shape (what you will actually see)

On lvlltd.com the pay endpoint is the challenge surface. A typical agent probe looks like this:

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

Expect HTTP 402 for an unpaid skill challenge (not an error in the business sense). The body includes fields such as maxAmountRequired (atomic USDC units), payTo, network, asset, and asset contract. Headers may also carry payment-required payloads for clients that prefer headers.

Atomic amounts

USDC on Base uses 6 decimals. A $0.05 unlock is 50000 atomic units. A $0.99 unlock is 990000. Agents should not float-format money for chain transfers. Use the integer the challenge returns.

Settle, then prove

Read the 402 challenge for skill id S.
Transfer maxAmountRequired of USDC on Base to payTo.
POST /api/pay with a payment proof header or JSON body including txHash and skill.
On success, receive sealed_pack.files (or sealed packs for bundles).

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

What x402 is not

Not a credit card form inside the skill purchase itself (you may fund a wallet with a card elsewhere)
Not a guarantee of off-platform legal certification
Not a place to invent GMV; confirmed unlocks appear on /api/proof

Human path still uses the same economics

MetaMask buyers complete the same economic loop: see price, send USDC on Base, present tx proof, receive files. The UI is different. The settlement truth is not.

Related rails on LVL

Machine entry often starts at GET /api/shop rather than jumping straight to pay. Shop returns next_action hints, featured canaries, and pointers into catalog and proof. OpenAPI and protocols.json document the stack for crawlers that only speak schemas.

Practice: Hit the canary challenge URL above, then open How agents buy skills for the full sequence.

From status code to business logic

In ordinary REST design, 4xx means the client did something wrong. 402 is special: the client may have done everything right except pay. Treating 402 as a hard crash in agent code is a bug. Treating unknown 402 bodies as payable is also a bug. The middle path is structured parsing plus policy checks.

LVL's pay endpoint is the commercial boundary. Challenges should be deterministic for a given skill id and pricing config. If price changes, the challenge amount changes. Agents should not cache prices forever without re-challenging.

Headers and bodies

Some x402 ecosystems put requirements in headers; others put them in JSON bodies; LVL has used both body fields and payment-required style headers for compatibility. Your client should log the full response once in staging and map fields explicitly. Do not guess amount from listing HTML if the challenge body disagrees. The challenge wins.

curl -si "https://lvlltd.com/api/pay?skill=aie-premium-access-token" | head -n 40

Settlement asset details

USDC on Base is an ERC-20. Transfers are standard token transfers. maxAmountRequired is integer atomic units. Example: $24.99 becomes 24990000. Floating point in JavaScript is a footgun; use integer math or decimal libraries.

payTo may be treasury for first-party skills or escrow-related addresses for open market flows. Allowlist what your organization permits. A challenge that points to an unknown address should fail closed.

POST unlock semantics

After chain confirmation depth your policy accepts, POST the proof. Include skill id so the server knows which sealed pack to release. Wrong skill id with a valid tx may fail verification by design.

Server-side verification typically scans Base for the transfer matching amount and payee. That is why toy receipts and forged hashes fail. It is also why mainnet canaries cost real cents: the loop is real.

Relationship to OpenAPI and protocols.json

Human docs can drift. Machine schemas reduce drift. OpenAPI describes endpoints; protocols.json describes the stack LVL claims to speak (x402, MCP, A2A, and related). Agents that start from protocols.json then drop into pay challenges make fewer wrong assumptions than agents that only read marketing copy.

Human MetaMask is still x402 economics

When a human clicks Buy, the wallet signs a Base USDC transfer that satisfies the same commercial facts a bot would satisfy. UI sugar does not create a second payment universe. If you are debugging a human payment, the same fields matter: amount, asset, network, payTo, txHash, skill.

Failure taxonomy

402 with unexpected asset: abort
Transfer mined but unlock 4xx: retry unlock, verify explorer, support with txHash
Unlock 200 but empty files: treat as incident; re-redeem; do not re-pay blindly
Spend over budget: client-side governor should have blocked challenge acceptance

Build that taxonomy into your agent runbooks before you scale spend past canaries.

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.