---
description: Understand the x402 request, payment authorization, and settlement flow used by Monetization Gateway.
title: x402 protocol
image: https://developers.cloudflare.com/monetization-gateway/x402/og.png?v=6739b69a1ba2dde5
---

[Skip to content](#main-content)

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/monetization-gateway/llms.txt  
> Use this file to discover all available pages before exploring further.

# x402 protocol

Last updated Sep 30, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/monetization-gateway/x402/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/)

[x402 ↗︎](https://www.x402.org/) is an HTTP payment protocol. Monetization Gateway uses x402 version 2 to request and settle payments within an HTTP exchange.

The protocol uses two client-facing headers. Each header contains Base64-encoded JSON.

| Header | Direction | Purpose |
| --- | --- | --- |
| `PAYMENT-REQUIRED` | Gateway to client | Describes the resource and accepted payment options. |
| `PAYMENT-SIGNATURE` | Client to Gateway | Provides the signed payment authorization. |

## Request a protected resource

The client first requests the resource without payment:

```http
GET /premium-data HTTP/1.1
Host: api.example.com
```

Monetization Gateway responds with `402 Payment Required`. The `PAYMENT-REQUIRED` header contains the encoded payment requirements:

```http
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <BASE64_ENCODED_PAYMENT_REQUIRED>
```

After Base64 decoding, a fixed-price response has this general structure:

```json
{
	"x402Version": 2,
	"resource": {
		"url": "https://api.example.com/premium-data",
		"description": "Premium data",
		"mimeType": "application/json"
	},
	"accepts": [
		{
			"scheme": "exact",
			"network": "<CAIP_2_NETWORK>",
			"asset": "<ASSET_IDENTIFIER>",
			"amount": "25000",
			"payTo": "<RECEIVING_WALLET>",
			"maxTimeoutSeconds": 3600,
			"extra": {}
		}
	]
}
```

The `accepts` array tells the client how it can pay. Important fields include:

| Field | Description |
| --- | --- |
| `scheme` | Payment scheme. Monetization Gateway uses `exact` for fixed pricing and `upto` for variable pricing. |
| `network` | Blockchain network identifier in CAIP-2 format. |
| `asset` | Asset identifier used for payment. |
| `amount` | Fixed charge or maximum authorized charge in atomic units. |
| `payTo` | Receiving wallet configured by the seller. |
| `maxTimeoutSeconds` | Maximum time allowed for payment authorization. |

## Authorize payment

The client selects an accepted option and signs a payment authorization. It then repeats the request with a `PAYMENT-SIGNATURE` header:

```http
GET /premium-data HTTP/1.1
Host: api.example.com
PAYMENT-SIGNATURE: <BASE64_ENCODED_PAYMENT_PAYLOAD>
```

The signed payload binds the authorization to the selected payment requirements. Use an x402 client library to create this payload instead of constructing it manually.

To implement a paying client, refer to [x402 payments](https://developers.cloudflare.com/agents/tools/payments/x402/). To pay from a Cloudflare Agent, refer to [Pay from Agents SDK](https://developers.cloudflare.com/agents/tools/payments/x402/pay-from-agents-sdk/).

## Validate at the origin (Cloudflare-specific)

After verifying the client authorization, Monetization Gateway forwards the request to your origin. It adds a `PAYMENT-CONTEXT` header containing a signed JSON Web Token (JWT).

Your origin must validate this token before serving the paid resource. Variable-price origins also return the actual charge in `PAYMENT-SETTLEMENT`. These headers are between Monetization Gateway and your origin. They are not x402 client headers.

For validation and settlement requirements, refer to [Payment validation](https://developers.cloudflare.com/monetization-gateway/configuration/payment-validation/).

## Return the resource

After successful settlement, Monetization Gateway returns the origin response.

If verification or settlement fails, the Gateway does not serve the protected resource. Clients should inspect the HTTP status and x402 response before retrying.

Was this helpful?

YesNo

## On this page

[![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/monetization-gateway/x402/#page","headline":"x402 protocol","description":"Understand the x402 request, payment authorization, and settlement flow used by Monetization Gateway.","url":"https://developers.cloudflare.com/monetization-gateway/x402/","inLanguage":"en","image":"https://developers.cloudflare.com/monetization-gateway/x402/og.png?v=6739b69a1ba2dde5","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```