How to lint an x402 listing from code or CI with an API

POST an x402 listing, or the URL of a live x402 endpoint, to /v1/x402/lint. It returns the problems found, a 0 to 100 score and a suggested description that includes a "Use when" sentence. The rules are the same as in the free x402 listing lint browser tool.

Why it matters: 94.4% of 34,062 Bazaar listings have no "use when" sentence (see State of the x402 Bazaar), and the checklist for getting listed and featured is in How to get an x402 endpoint listed and featured in the CDP Bazaar.

What it checks

Description: present; at most 500 characters (an error above 500, a warning above 450, because CDP rejects longer ones at settle time); and a "use when" style sentence (a warning if missing). Resource URL: present, absolute and https. mimeType: present (error) and shaped like type/subtype (warning). outputSchema (or extensions.bazaar in v2): present and not empty. Each accepts entry: an amount (maxAmountRequired or amount) that is a positive whole-number string, a network, an asset, and a payTo that is an EVM (0x plus 40 hex) or Solana address.

The score is 100, less 20 per error and 5 per warning, never below 0. Each problem has a stable code (for example description_too_long, missing_use_when, output_schema_missing, pay_to_invalid), a severity of error or warning and a message that includes the fix. v1 and v2 listings both work.

Request

Send exactly one of listing or url; both or neither is a 422.

listing is an x402 PaymentRequired object (v1 or v2), a bare accepts entry or a Bazaar discovery item, as JSON. It may also be a string holding the JSON text or the base64 PAYMENT-REQUIRED header value. At most 1 MB.

curl -s -X POST https://tanod.dev/v1/x402/lint \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"listing": {"x402Version": 2, "resource": {"url": "https://api.example.com/v1/weather", "description": "Weather forecast for a city.", "mimeType": "application/json"}, "accepts": [{"scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "10000", "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"}]}}'

url is an https x402 endpoint. It is fetched once (GET, or POST if GET answers 405) and its 402 response is linted, reading the PAYMENT-REQUIRED header first and the body otherwise. The response then also has http_status, method and read_from (header or body).

curl -s -X POST https://tanod.dev/v1/x402/lint \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://api.example.com/v1/weather"}'

URL safety limits. https only, on port 443, with a plain public host name: no user info, no fragment, no IP address, no internal names such as .local or .internal. The name must resolve to public addresses only, and the connection goes to the address that was checked. Redirects are never followed, the wait is 10 seconds and the reply is capped at 256 kB. An endpoint that is unreachable, blocked, redirects, answers anything but 402 or has a body that is not JSON is a 422 and is not charged. The fetched text is only linted, never run.

Response

{
  "source": "listing",
  "url": null,
  "problems": [
    {
      "code": "missing_use_when",
      "severity": "warning",
      "message": "When-to-use sentence: No \"use when\" sentence found. Fix: Add one, for example: ..."
    }
  ],
  "score": 95,
  "errors": 0,
  "warnings": 1,
  "checks_passed": 9,
  "description_length": 28,
  "suggested_description": "Weather forecast for a city. Use when an agent needs weather data from this endpoint.",
  "suggested_length": 85,
  "checked_at": "2026-10-09T08:00:00Z",
  "note": "Automated checks of the listing rules Tanod knows ..."
}

suggested_description keeps your original text, adds a "Use when ..." sentence if there is none and is at most 500 characters. It is a draft to review, not a rewrite of your meaning. Results are automated checks of the rules Tanod knows (the Coinbase CDP 500-character limit, the Bazaar https requirement, required fields); the facilitator or catalog may apply others.

Doing this by hand? Use the free x402 listing lint in your browser: nothing is uploaded and it never contacts your endpoint.

Related guides: How to get an x402 endpoint listed and featured in the CDP Bazaar, State of the x402 Bazaar, How to get your x402 API listed in the directories agents search. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.