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

> x402 lets an HTTP endpoint charge per request: an unpaid call gets `402 Payment Required` with payment requirements, the client pays in a stablecoin and retries. `/.well-known/x402` is a discovery document listing those paid endpoints so indexers and agents can find them. Publish it only if you really sell per-request access.

Checked 2026-09-30 against Agent-Readiness Grade 1.3.0. HTML version: https://grade.agentexchange.work/fix/x402-manifest

## 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).

## Why it matters for AI agents and crawlers

[x402](https://www.x402.org/) 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](https://docs.x402.org/extensions/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](https://github.com/Merit-Systems/x402scan/blob/main/docs/DISCOVERY.md) 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:

```json
{
  "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
# 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
<?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](https://nextjs.org/docs/app/api-reference/config/next-config-js/headers) before the filesystem, `public/` included.

next.config.js:

```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](https://developers.cloudflare.com/workers/static-assets/headers/) in the deployed directory:

_headers:

```text
/.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](https://www.x402.org/)):

Express-style middleware:

```js
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.

```sh
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.

Re-grade: https://grade.agentexchange.work/grade?url=example.com&fresh=1

## 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

- [x402: an open standard for internet-native payments](https://www.x402.org/) (x402)
- [Bazaar (Discovery Layer)](https://docs.x402.org/extensions/bazaar) (x402 docs)
- [x402scan Discovery & Registration Spec](https://github.com/Merit-Systems/x402scan/blob/main/docs/DISCOVERY.md) (x402scan)
- [headers in next.config.js](https://nextjs.org/docs/app/api-reference/config/next-config-js/headers) (Next.js)
- [Workers static assets: headers and the _headers file](https://developers.cloudflare.com/workers/static-assets/headers/) (Cloudflare)

## Related

- [openapi.json](https://grade.agentexchange.work/fix/openapi-json.md): Your API described at /openapi.json; one of four files for the agent-surface point.
- [MCP endpoint and census](https://grade.agentexchange.work/fix/mcp-endpoint.md): An MCP endpoint at /mcp, and a listing among hosts that sell to agents through x402.
- [agent-card.json](https://grade.agentexchange.work/fix/agent-card-json.md): The A2A agent card at /.well-known/agent-card.json; one of four files for the agent-surface point.
- [All fix guides](https://grade.agentexchange.work/fix)