Docsx402 Paywall Protocol

x402 Paywall Protocol

Modexia natively supports the x402 protocol — an open-source standard enabling frictionless machine-to-machine payments over HTTP. When your autonomous AI agent requests a paywalled API resource (HTTP 402 Payment Required), the SDK intercepts the payload, seamlessly negotiates the requested transaction cost server-side in stable value, pays the invoice via the Gateway, and finally natively returns the underlying resource data in a single synchronized tool loop.

How It Works Architecture

1

Agent Request Initiated

Your script execution loop automatically calls the client.smart_fetch(url) SDK function to request an arbitrary remote external server resource endpoint.

2

Server Emits HTTP 402 Paywall Demand

If the external server responds with the standard HTTP 402 Payment Required HTTP protocol error accompanied by a strictly formatted WWW-Authenticate response header demanding the invoice cost and cryptocurrency recipient destination address, the internal Modexia SDK automatically parses it natively.

3

SDK Transparent Transaction

The Modexia SDK pays the specific requested amount via the Gateway utilizing transfer() automatically, consuming the agent's balance implicitly. The SDK subsequently silently retries the original payload HTTP invocation infused sequentially with an authorization payment-verification proof header token payload validating settlement confirmation.

4

Response Data Decoded

The fully decrypted target premium resource data payload is seamlessly returned to your agent logic function execution via a singular synchronized blocking thread. Zero human or explicit manual agent conditional intervention loops are required programmatically.

Python Code Example Request

python
from modexia import ModexiaClient

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

# This target API actively charges $0.01 internally per HTTP invocation fundamentally.
# We utilize 'smart_fetch' instead of requests.get
response = client.smart_fetch("https://api.premium-finance-index.xyz/quant-feed")

# The SDK paid automatically natively over HTTP 402 conditionally — you simply parse the data logically
feed = response.json()
print(feed)

Under-The-Hood Architecture (Paywall Header Implementation Format Constraint)

As per the x402 open-source HTTP paradigm specification, the Modexia Python SDK expects inherently that the external target architecture's 402 HTTP server response rigidly includes a WWW-Authenticate index header structured securely imitating this strictly standardized format parameter string fundamentally.

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

Paywall Spending Policy Enforcement Controls

If an external remote server maliciously returns absurdly inflated or infinite x402 payment pricing parameters in their HTTP headers attempting to drain your agent's wallet natively via automated SDK recursive calls unexpectedly structurally, Modexia's infrastructure layer limits (Spending Policies — dailyLimit, hourlyLimit, maxPerRequest) will universally categorically block the subsequent automatic transfer() payment attempt server-side and trigger a native synchronous ModexiaPaymentError universally instantly securely natively.