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 and returns the data — all in a single call.

The Nanopay/Gateway Architecture

To negotiate x402 paywalls instantly and with zero gas fees, Modexia uses the Circle Gateway Nanopay architecture. Instead of broadcasting an on-chain transaction for every API call, you deposit a small amount of USDC into the Gateway once. The SDK then generates off-chain EIP-3009 signatures (cryptographic IOUs) to pay for APIs at wire speed.

1

Activate & Deposit (Once)

Your agent activates the gateway and deposits a small USDC buffer (e.g., $10) from its main on-chain wallet.

2

Agent Request

Your agent calls client.nanopay(url) to request a remote API resource.

3

Server Returns 402 & Instant Payment

If the server responds with HTTP 402 Payment Required, the SDK automatically fetches a cryptographically secure EIP-3009 signature using your Gateway balance and retries the request instantly.

Python Example (Recommended)

python
from modexia import ModexiaClient

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

# 1. Activate the gateway (safe to call multiple times)
client.nanopay_activate()

# 2. Ensure the gateway has funds for micro-transactions
balance = client.nanopay_balance()
if float(balance.available) < 1.0:
    client.nanopay_deposit(5.0)  # Move 5 USDC into Gateway

# 3. Fetch data. The SDK handles the 402 negotiation seamlessly.
response = client.nanopay("https://api.premium-finance-index.xyz/quant-feed")

if response.success:
    feed = response.data
    print(feed)

Auto-Refill Config

You can configure auto-refill via the dashboard (or the /api/v2/nanopay/settings route). When enabled, the Gateway will automatically pull funds from your main wallet when your Gateway balance runs low during a nanopay() call.

Paywall Header Format

The x402 protocol requires the API provider'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..."

Alternative: On-Chain Negotiation (v1)

If you prefer not to use the Gateway, you can use the older client.smart_fetch(url) method. Instead of off-chain signatures, this method executes a standard on-chain client.transfer() when it encounters a 402. While fully functional, this may incur higher gas fees and slower execution times for frequent micro-transactions.

python
# Uses the main wallet and standard on-chain transfers
response = client.smart_fetch("GET", "https://api.premium-finance-index.xyz/quant-feed")

feed = response.json()