Fix x402 manifest: list your paid endpoints at /.well-known/x402

What the grade checks

• GET https://example.com/.well-known/x402 with a 7-second timeout. It counts when the answer is HTTP 200 and valid JSON; the evidence shows how many paid resources it lists (resources, accepts or endpoints).
• HTML from a catch-all route does not count, and neither does a binary content type such as application/octet-stream, which many hosts send for a path without an extension.
• Any one of /.well-known/x402, agent-card.json, openapi.json or mcp-registry-auth earns the agent-surface point.

The agent-surface point of the machine-readable surfaces area (shared with three other files). The full scoring rules are on the methodology page.

Why it matters for AI agents and crawlers

x402 is an open standard for internet-native payments: the server answers 402 with payment requirements, and the client pays and retries with no account or API key.

The x402 documentation defines discovery through the Bazaar: facilitators that support it expose a /discovery/resources catalog of services that declared the bazaar extension in their route configuration.

/.well-known/x402 is a simpler convention: x402scan's discovery spec reads it after OpenAPI, in the form {"version": 1, "resources": [...]} with optional ownershipProofs, and says the live 402 answer is authoritative over static metadata. List only routes that really answer 402 with a parseable challenge.

How to fix it

1. Write the document

   List the full URL of every paid route.

   .well-known/x402

   {
     "version": 1,
     "resources": [
       "https://example.com/api/report",
       "https://example.com/api/lookup"
     ]
   }

2. Serve it as JSON

   The path has no file extension, so set the content type explicitly.

   Static site

   Save the file as .well-known/x402 in the web root and tell the server it is JSON.

   nginx, or Apache .htaccess in .well-known

   # nginx
   location = /.well-known/x402 { default_type application/json; }
   
   # Apache (.htaccess inside the .well-known folder)
   <Files "x402">
     ForceType application/json
   </Files>

   WordPress

   Upload the file and add the server rule above; on managed hosts without server access, answer the path from a must-use plugin instead:

   wp-content/mu-plugins/x402-manifest.php

   <?php
   add_action( 'init', function () {
       $path = strtok( $_SERVER['REQUEST_URI'] ?? '', '?' );
       if ( '/.well-known/x402' !== $path ) {
           return;
       }
       header( 'Content-Type: application/json' );
       echo wp_json_encode( array(
           'version'   => 1,
           'resources' => array( 'https://example.com/api/report' ),
       ) );
       exit;
   } );

   Next.js

   Save it as public/.well-known/x402 and set the header in next.config.js; Next.js checks headers before the filesystem, public/ included.

   next.config.js

   module.exports = {
     async headers() {
       return [
         { source: '/.well-known/x402', headers: [{ key: 'Content-Type', value: 'application/json' }] },
       ]
     },
   }

   Cloudflare

   With static assets or Pages, add a _headers file in the deployed directory:

   _headers

   /.well-known/x402
     Content-Type: application/json

3. Make the listed routes answer 402

   Each listed URL must answer an unpaid request with HTTP 402 and payment requirements. The x402 middleware does it with one entry per route (from x402.org):

   Express-style middleware

   app.use(paymentMiddleware({
     "GET /api/report": { accepts: [/* networks, assets and prices */], description: "Full report" },
   }));

How to verify

Check the manifest's content type, then that a listed route asks for payment.

shell

curl -s -o /dev/null -w "%{http_code} %{content_type}\n" https://example.com/.well-known/x402
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/api/report

200 application/json for the manifest and 402 for the unpaid route.

Then re-grade your site: the result lists the evidence for this check.

Questions

Is /.well-known/x402 part of the x402 standard?

Not in the x402 documentation we read on 2026-09-30. It is a discovery convention used by x402scan; the standard's own discovery layer is the Bazaar, a catalog kept by facilitators.

How do routes get into the Bazaar?

Declare the bazaar extension in the route configuration and settle payments through a facilitator that supports Bazaar discovery; the catalog is built from what those facilitators record.

I don't sell per request. Should I publish an empty manifest?

There is no need. A manifest with an empty list is valid JSON and counts here, but it offers agents nothing to buy; an agent card or openapi.json describes you better.

Sources

Primary documentation, read 2026-09-30. Vendors change these pages; follow the link before relying on a detail.

• x402: an open standard for internet-native payments (x402)
• Bazaar (Discovery Layer) (x402 docs)
• x402scan Discovery & Registration Spec (x402scan)
• headers in next.config.js (Next.js)
• Workers static assets: headers and the _headers file (Cloudflare)

Related

• openapi.json: Your API described at /openapi.json; one of four files for the agent-surface point.
• MCP endpoint and census: An MCP endpoint at /mcp, and a listing among hosts that sell to agents through x402.
• agent-card.json: The A2A agent card at /.well-known/agent-card.json; one of four files for the agent-surface point.
• All fix guides · All generators · Graded sites · How the grade works