How to make your x402 endpoint payable from browser-based agents

Browser-based AI agents face specific technical barriers when attempting to pay for API access using the x402 protocol. Without proper Cross-Origin Resource Sharing (CORS) configuration, these agents cannot complete the payment handshake required to unlock your service. This guide outlines the precise steps to ensure your endpoint is compatible with client-side payments.

Configure Access-Control-Allow-Origin

The first requirement is allowing cross-origin requests. Your server must include the Access-Control-Allow-Origin header in the 402 response. This header tells the browser that the resource can be shared with other origins. You may use a wildcard (*) to allow all origins, or specify particular domains for stricter security. Without this header, the browser will block the agent from reading the payment requirements.

Example configuration:

Access-Control-Allow-Origin: *

Expose Payment Headers in CORS

Browser agents need to read specific headers returned by your server to understand how to pay. You must list these headers in the Access-Control-Expose-Headers response header. Specifically, you must expose the PAYMENT-REQUIRED header, which contains the quote for the payment. You should also expose the PAYMENT-RESPONSE header: after a successful payment, your server uses it to send the settlement receipt back to the agent. If these headers are not exposed, the agent can't read the price or confirm its payment went through.

Example configuration:

Access-Control-Expose-Headers: PAYMENT-REQUIRED, PAYMENT-RESPONSE

Handle OPTIONS Preflight Requests

The paid retry carries a custom payment header, so the browser always sends a CORS preflight (OPTIONS) first, even for GET and POST requests. This is the step most x402 endpoints miss. Your server must respond to OPTIONS requests with a 2xx status code. This response must include the Access-Control-Allow-Origin header to permit the origin. If your endpoint uses a method other than GET, HEAD or POST, list it in Access-Control-Allow-Methods. Additionally, you must declare which headers the client is permitted to send in the actual request using Access-Control-Allow-Headers.

For x402 v2, you must allow the PAYMENT-SIGNATURE header. For x402 v1, you must allow the X-PAYMENT header. You must also allow the Content-Type header if your endpoint accepts JSON bodies. This ensures the browser sends the correct payment credentials without being blocked by security policies.

Example configuration for an OPTIONS response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: PAYMENT-SIGNATURE, Content-Type

*Note: For x402 v1, replace PAYMENT-SIGNATURE with X-PAYMENT.*

Verify Browser Agent Compatibility

Lumière PayCheck provides a tool to verify if your endpoint is correctly configured for browser-based agents. The tool checks every endpoint for the necessary CORS headers and displays the result as 'Browser agents' on the endpoint's page. This status indicates whether the configuration is sufficient or if fixes are needed. If something is missing, the page lists the exact headers to add. This check never affects your endpoint's grade: server-side agents can pay you either way.

Common mistakes

* Missing Expose Headers: Developers often set Access-Control-Allow-Origin but forget to list PAYMENT-REQUIRED and PAYMENT-RESPONSE in Access-Control-Expose-Headers. This prevents the browser agent from reading the payment quote or sending the response. * Assuming GET or POST skips the preflight: the payment header always triggers one, so an endpoint that never answers OPTIONS can't be paid from a browser. * Incorrect Preflight Headers: Forgetting to include the specific payment header (PAYMENT-SIGNATURE for v2 or X-PAYMENT for v1) in the Access-Control-Allow-Headers during the OPTIONS preflight will cause the browser to block the payment request. * Ignoring Method Restrictions: Failing to list non-standard HTTP methods (those other than GET, HEAD, and POST) in Access-Control-Allow-Methods will result in a failed preflight for PUT, DELETE, or PATCH requests.

For the full documentation, visit https://lumierepaycheck.org/docs

--- Source used (for checking): https://lumierepaycheck.org/docs/

A browser agent can pay only if: the 402 response has Access-Control-Allow-Origin (for example *); a quote sent in the PAYMENT-REQUIRED header is listed in Access-Control-Expose-Headers (also expose PAYMENT-RESPONSE); and the CORS preflight (OPTIONS) answers 2xx with Access-Control-Allow-Origin and allows the payment header in Access-Control-Allow-Headers: PAYMENT-SIGNATURE for x402 v2, X-PAYMENT for v1, plus Content-Type for JSON bodies. Methods other than GET, HEAD and POST must be in Access-Control-Allow-Methods. Server-side agents don't need any of this. Lumière PayCheck checks every endpoint for this and shows the result as 'Browser agents' on the endpoint's page, with the fix. It never changes the grade.