# x402lint — Conformance scanner for x402 sellers — lint your origin against what x402scan, Bazaar, AgentCash and agent buyers actually require. Per-call USDC pricing, no signup. (v0.1.0)

> x402lint grades x402 seller origins A-F on 25 conformance checks (protocol surface, agent docs, directory standing) and tells you exactly what to fix. Free status lookups; paid full scans. Results cached 24h; scanning is read-only (GET/HEAD, no real payments are made against the target).

## Base URL
- API: https://api.x402lint.dev
- This document: https://api.x402lint.dev/llms.txt  ·  Extended: https://api.x402lint.dev/llms-full.txt
- Discovery (JSON): https://api.x402lint.dev/discovery
- OpenAPI 3.1: https://api.x402lint.dev/openapi.json
- x402 manifest: https://api.x402lint.dev/.well-known/x402
- Agent card (A2A): https://api.x402lint.dev/.well-known/agent-card.json
- Terms: https://api.x402lint.dev/terms.txt

## Free endpoints (no auth, no payment)

| Method | Path | Description |
|--------|------|-------------|
| GET | /v1/status | Free. Returns whether an origin has been scanned, scan freshness, and the grade summary (grade, score, pass/warn/fail counts) — no per-check findings. Real data from prior scans; full findings require POST /v1/scan. (rate limit: 10/min) |
| GET | /v1/checks | Free. High-level summary of the conformance checks x402lint runs, grouped into categories with counts and descriptions. Full per-check findings, evidence, and one-line fixes are delivered in the paid scan result (POST /v1/scan). (rate limit: 10/min) |
| GET | /v1/directory | Free. Paginated list of origins x402lint has scanned and graded, with conformance grade, auto-collected UNVERIFIED third-party branding, and ecosystem legitimacy signals. Sort by recency (default) or grade; filter by category, verification, or host substring. A grade measures protocol conformance only and is NOT an endorsement or a safety/legitimacy assessment. (rate limit: 30/min) |
| GET | /v1/featured | Free. Origins that scored an A on their most recent scan within the last 30 days, recency-ranked. Featured placement is a free consequence of a recent A-grade scan; it expires 30 days after the scan (re-scan to refresh). Conformance only — NOT an endorsement. (rate limit: 30/min) |
| GET | /v1/project | Free. The public directory record for one origin (grade, branding, legitimacy signals, verification + featured status). 404 uncharged if the origin is unknown or has opted out. (rate limit: 30/min) |
| POST | /v1/verify/start | Free. Begin domain-control verification of an origin you operate. Returns a one-time token to place at /.well-known/x402lint-challenge on that origin, then call POST /v1/verify/confirm. (rate limit: 10/min) |
| POST | /v1/verify/confirm | Free. x402lint fetches /.well-known/x402lint-challenge over HTTPS and, if it matches the unexpired token from /v1/verify/start, marks the origin owner-verified. (rate limit: 10/min) |
| POST | /v1/listing | Free. For owner-verified origins only (else 403). Opt the origin out of the public directory (listed=false) and/or suppress auto-collected branding (suppressEnrichment=true). (rate limit: 10/min) |

## Paid endpoints (x402 V2, USDC on Base, per-call)

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| POST | /v1/scan | $0.15 | Paid ($0.15). Runs all 25 checks against the origin (read-only GET/HEAD probes) or serves a <24h cached result. Returns grade, score, per-check status + evidence + fix instructions, and a shareable report URL. Unreachable/broken origins are a valid graded result (F). 504 processing responses and errors are never charged. |
| GET | /v1/report | $0.02 | Paid ($0.02). Returns the full cached scan report (same shape as POST /v1/scan) if a fresh (<24h) result exists; otherwise 404 uncharged with a pointer to POST /v1/scan. Cheap path for agents polling a known origin. |

## How to pay (x402)
Each paid call answers a 402 challenge; sign an x402 `exact` USDC authorization for one advertised rail (Base) and retry. Standard @x402 V2 clients send the `PAYMENT-SIGNATURE` header; legacy clients send `X-PAYMENT`. Prices are USD, settled as USDC (6 decimals).

## Links
- Docs: https://api.x402lint.dev/llms.txt
- Full: https://api.x402lint.dev/llms-full.txt
- OpenAPI: https://api.x402lint.dev/openapi.json
- Discovery: https://api.x402lint.dev/discovery
- Agent card: https://api.x402lint.dev/.well-known/agent-card.json
- Website: https://x402lint.dev

## Check catalog
GET /v1/checks returns a high-level summary of the 25 conformance checks grouped into three categories: protocol & payment surface (8), discovery & agent docs (12), and ecosystem standing (5), each with a count and description. The summary is versioned (checksVersion). Full per-check findings, evidence, and one-line fixes come with the paid scan (POST /v1/scan).