Docsx402 Paywall Protocol

x402 Paywall Protocol

Modexia natively supports the x402 protocol — an open standard for machine-to-machine payments over HTTP. When your AI agent requests a paywalled resource and receives an HTTP 402 Payment Required response, the SDK automatically negotiates payment, settles in USDC, and returns the data — all in a single call.

How It Works

1

Agent Request

Your agent calls client.smart_fetch(method, url) to request a remote API resource.

2

Server Returns 402

If the server responds with HTTP 402 Payment Required and a WWW-Authenticate header containing the price and recipient address, the SDK parses the payment demand automatically.

3

Automatic Payment

The SDK pays the requested amount via transfer(), deducting from the agent's balance. It then retries the original request with a payment-proof authorization header.

4

Data Returned

The server validates the payment proof and returns the premium resource data. Your agent receives the response in a single synchronous call — no manual intervention required.

Python Example

python
from modexia import ModexiaClient

client = ModexiaClient(api_key="mx_test_...")

# This API charges $0.01 per request.
# smart_fetch handles the 402 negotiation automatically.
response = client.smart_fetch("GET", "https://api.premium-finance-index.xyz/quant-feed")

# Payment happened behind the scenes — just use the data
feed = response.json()
print(feed)

Paywall Header Format

The x402 protocol requires the server's 402 response to include a WWW-Authenticate header in this format:

http
HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 amount="0.01" destination="0xTargetProviderEVMAddress..."

Spending Policy Protection

If a malicious server returns an inflated price in its 402 response, Modexia's spending policies (dailyLimit, hourlyLimit, maxPerRequest) will block the payment and raise a ModexiaPaymentError. Your agent's funds are always protected.