← Back to Docs

Server Architecture

A composable reverse proxy that works with any video CDN.

Design Philosophy

The x402 video server is designed to be fully composable. It is a transparent reverse proxy that sits between viewers and your existing video infrastructure. No vendor lock-in, no proprietary formats.

Key Principle: The proxy does not store or transcode videos. It only handles authentication and payment, then forwards requests to your actual video CDN.

How It Works

1. Manifest Interception

When a viewer requests a video manifest (.m3u8), the proxy:

  • Fetches the manifest from your CDN
  • Rewrites segment URLs to point back to the proxy
  • Counts segments to calculate the total price
  • Returns the modified manifest (free - no payment)

2. Segment Protection

When a viewer requests a video segment (.ts/.m4s), the proxy:

  • Checks for a valid JWT access token
  • If no token: returns 402 Payment Required
  • If paid: issues JWT and proxies the segment
  • If has token: validates and proxies the segment

CDN Compatibility

The proxy works with any video CDN that serves HLS or DASH content:

Mux✅ Tested
Cloudflare Stream✅ Compatible
AWS MediaConvert + CloudFront✅ Compatible
Bunny.net Stream✅ Compatible
Self-hosted (nginx-rtmp)✅ Compatible
Any HLS/DASH source✅ Compatible

URL Rewriting

The proxy rewrites absolute URLs in manifests to route through itself. This is how it intercepts segment requests:

Before (Original Manifest)
#EXTINF:4,
https://stream.mux.com/v1/chunk/abc123/0.ts
#EXTINF:4,
https://stream.mux.com/v1/chunk/abc123/1.ts
After (Rewritten Manifest)
#EXTINF:4,
http://localhost:4000/assets/__cdn__stream.mux.com/v1/chunk/abc123/0.ts
#EXTINF:4,
http://localhost:4000/assets/__cdn__stream.mux.com/v1/chunk/abc123/1.ts

The __cdn__ prefix encodes the original CDN hostname, allowing the proxy to route requests to the correct origin.

Running Your Own Server

Quick Start
# Clone the repository
git clone https://github.com/your-org/x402-video
cd x402-video/server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start the server
npm run dev

Configuration Options

VariableDescriptionDefault
ORIGIN_BASE_URLYour video CDN base URLRequired
WALLET_ADDRESSDefault payment recipientRequired
ASSET_PRICEPrice per segment$0.01
NETWORKBlockchain networkbase-sepolia
JWT_SECRETToken signing keyRandom (dev)
PORTServer port4000

Using a Different CDN

To use the proxy with a different video provider:

  1. Set ORIGIN_BASE_URL to your CDN base URL
    ORIGIN_BASE_URL=https://customer-xyz.cloudflarestream.com
  2. Configure authentication if your CDN requires it (signed URLs, tokens, etc.)
  3. Test with a video - the proxy will automatically rewrite URLs and protect segments
Note: If your CDN uses signed URLs with short expiry, you may need to handle re-signing in the proxy. Contact us for guidance.

Scaling Considerations

🔄 Stateless Design

JWT validation is stateless. Run multiple proxy instances behind a load balancer.

💾 No Session Storage

No database required. JWT tokens contain all access information.

🌐 CDN Caching

Manifests can be cached at the edge. Segments require per-request validation.

🔐 Same JWT_SECRET

All instances must share the same JWT_SECRET to validate tokens across instances.

API Endpoints

GET
/healthHealth check endpoint
GET
/assets/{playbackId}.m3u8Video manifest (free)
GET
/assets/.../segment.tsVideo segment (paid)
Back to Docs