Guides
How agents pay (x402)
Verivyx implements the x402 protocol (version 2). An agent that wants a protected resource receives a machine-readable 402 Payment Required, settles a USDC payment on Stellar, and retries — no human, no API key, no account. This page is the complete protocol reference; for the runnable narrative see the Playground.
The flow
- The agent requests a protected URL and receives
402 Payment Requiredwith aPAYMENT-REQUIREDheader — a base64 payload describing exactly how to pay. - The agent picks one of the offered requirements, signs a USDC payment that satisfies it, and retries the request with a
PAYMENT-SIGNATUREheader. - Verivyx verifies the payment on Stellar, the
paywall_corecontract splits it between creator and platform, and the content is returned with200 OKplus aPAYMENT-RESPONSEheader.
# 1. Request the protected resource
GET https://your-domain.com/article
→ 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi4u # x402 requirements (base64)
# 2. Sign a USDC payment, then retry with the signature
GET https://your-domain.com/article
PAYMENT-SIGNATURE: <signed x402 payload> # base64
→ 200 OK # content unlocked
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLi4u # settlement result (base64)HTTP headers
| Header | Direction | Meaning |
|---|---|---|
PAYMENT-REQUIRED | Response (402) | Base64 of the PaymentRequired body — how to pay. |
X-Payment-Required | Response (402) | Same payload; backward-compatible alias. |
PAYMENT-SIGNATURE | Request (retry) | Base64 of the signed payment payload (x402 v2). |
X-PAYMENT | Request (retry) | Legacy alias for the signed payload; also accepted. |
PAYMENT-RESPONSE | Response (200) | Base64 of the settlement result (transaction hashes, split). |
The 402 body (PaymentRequired)
The decoded PAYMENT-REQUIRED header is a JSON PaymentRequired object. It advertises one or more accepts[] options — pay any one of them.
| Field | Type | Description |
|---|---|---|
x402Version | number | Protocol version. Always 2. |
error | string | Human-readable reason the request was rejected. |
resource | object | The resource being gated — { url, mimeType }. |
accepts[] | array | The payment options (see below). Satisfy one to unlock. |
extensions | object | Verivyx adds a facilitator hint: { scheme, url, version } pointing at the hydrate endpoint to retry against. |
Each accepts[] entry
| Field | Description |
|---|---|
scheme | Payment scheme. Verivyx uses exact (pay the exact amount). |
network | CAIP-2 network id, e.g. stellar:testnet. |
amount | Price in atomic USDC units (also mirrored as maxAmountRequired). |
asset | The USDC asset: a Soroban contract id, or classic USDC:<issuer>. |
payTo | Destination: the paywall contract (Soroban) or the creator account (classic). |
maxTimeoutSeconds | How long the quote is valid before it must be re-fetched. |
extra | Split details (distribution / splitPayments), areFeesSponsored, domain, and paywallContract. |
Payment rails
Every 402 advertises two equivalent rails so any x402 client can pay:
| Soroban USDC | Classic USDC | |
|---|---|---|
| Asset | Soroban USDC contract (SAC) | USDC:<issuer> |
| Pays to | paywall_core contract | Creator's Stellar account |
| Split | On-chain by the contract | Two payment operations |
| Network gas | Sponsored by Verivyx — no XLM needed | Paid by the agent |
Amounts are always atomic, 7-decimal units: 1 USDC = 10,000,000. A 0.05 USDC price is 500000.
Status codes
| Code | When |
|---|---|
200 | Payment accepted (or already paid / verified human) — content returned. |
402 | Payment required, or the supplied payment was invalid — body carries fresh requirements. |
404 | Domain not registered with Verivyx. |
502 | Fail-closed: the upstream content could not be fetched (content_unavailable) — never leaks partial content. |
Standards & compatibility
- Verivyx is x402 v2-compliant and interoperates with generic x402 clients — see the x402 specification and the reference implementation from Coinbase's x402 project.
- Payments settle on Stellar in USDC; networks are identified with CAIP-2 ids (
stellar:testnet,stellar:pubnet). - Both the standard header (
PAYMENT-SIGNATURE) and the legacy alias (X-PAYMENT) are accepted, so older clients keep working.
What can pay today
Any spec-compliant x402 client can pay a Verivyx paywall right now. The fastest way to see a real end-to-end payment is the Playground, where a sandboxed agent pays both a demo paywall and a real protected post on testnet and shows every step on-chain. To wire an AI agent up directly, use the x402 MCP server.