x402 Payment Protocol

Overview

This sample demonstrates how to pair Openfort's embedded wallet infrastructure with Coinbase's x402 payment protocol to enable seamless HTTP-based USDC micropayments for API access and content monetization. The project showcases a complete paywall implementation with modular architecture for easy integration into your own stack.

Complete source code for the x402 payment protocol integration with Openfort embedded wallets, React, and Vite.

View Sample Code

GitHub Repository

Project Structure

x402/
├── server/                      # Node.js API broken into config, routes, services
│   ├── app.js                   # Assembles middleware + routes
│   ├── config/
│   │   └── environment.js       # Environment parsing & payment defaults
│   ├── integrations/
│   │   └── openfortClient.js    # Openfort Node client creator
│   ├── routes/
│   │   ├── protectedContent.js  # /api/protected-content endpoint (402 handler)
│   │   ├── shieldSession.js     # /api/protected-create-encryption-session endpoint
│   │   └── health.js            # /api/health endpoint
│   └── services/
│       ├── paymentDecoder.js    # X-Payment header parsing
│       └── paymentRequirements.js # Payment requirement builder
├── src/                         # React + Vite application
│   ├── App.tsx                  # Mounts the paywall experience
│   ├── features/paywall/        # Complete paywall UI + hooks
│   │   ├── PaywallExperience.tsx # Orchestrates auth → payment → unlock
│   │   ├── components/          # Auth, wallet, payment, success views
│   │   └── hooks/
│   │       ├── usePaymentFlow.ts # Payment state machine
│   │       └── useUsdcBalance.ts # USDC balance polling
│   ├── integrations/
│   │   ├── openfort/            # React providers & config helpers
│   │   └── x402/                # Protocol helpers (types, encoding, balance)
│   └── types/                   # Global ambient types (window.x402)
├── server.js                    # Node entry that boots the HTTP server
├── package.json                 # Project dependencies
└── README.md                    # Project documentation

Key Features

Modular Node.js server with environment-driven configuration
Dedicated x402 helpers for payload selection and encoding
Smart-account UX using Openfort React SDK (providers, wallet creation, recovery flows)
React feature module for complete paywall journey with explicit state management
USDC payments on Base and Base Sepolia networks
Automatic USDC balance polling and network switching
HTTP 402 status code implementation for payment-gated content

Component	Technology
Frontend	React 18 + Vite
Backend	Node.js (built-in http module)
Blockchain	Base / Base Sepolia
Payment Token	USDC
Key Libraries	`@openfort/react`, `@openfort/openfort-node`, `wagmi`, `viem`
Payment Protocol	x402 (HTTP 402 Payment Required)
Styling	Tailwind CSS

Quick Start

Clone the repository using gitpick:

pnpx gitpick openfort-xyz/recipes-hub/tree/main/x402 openfort-x402
cd openfort-x402

Prerequisites

Node.js 18+
pnpm package manager
Openfort dashboard project with Shield credentials
WalletConnect Project ID
Basic understanding of HTTP status codes and the x402 protocol

Get Credentials

You'll need to configure credentials for both frontend and backend.

Openfort Dashboard

Go to Openfort Dashboard
Create an account or sign in
Get your API keys:
- Publishable Key (pk_test_...) - Frontend
- Secret Key (sk_test_...) - Backend
- Shield Keys
Create a Policy and get the Policy ID (pol_...)

Configure Environment

Create frontend/.env.local:

VITE_OPENFORT_PUBLISHABLE_KEY=pk_test_...
VITE_SHIELD_PUBLISHABLE_KEY=...
VITE_POLICY_ID=pol_...
VITE_CREATE_ENCRYPTED_SESSION_ENDPOINT=http://localhost:3007/api/protected-create-encryption-session
VITE_WALLET_CONNECT_PROJECT_ID=your-wallet-connect-project-id
VITE_OPENFORT_THEME=
VITE_X402_RESOURCE_URL=http://localhost:3007/api/protected-content
VITE_X402_DEFAULT_AMOUNT=0.1

Create backend/.env.local:

PORT=3007
OPENFORT_SECRET_KEY=
OPENFORT_SHIELD_PUBLISHABLE_KEY=
OPENFORT_SHIELD_SECRET_KEY=
OPENFORT_SHIELD_ENCRYPTION_SHARE=
PAY_TO_ADDRESS=
X402_NETWORK=base-sepolia
X402_RESOURCE=http://localhost:3007/api/protected-content
X402_DESCRIPTION=Access to premium content
X402_MIME_TYPE=application/json
X402_MAX_AMOUNT=100000
X402_TIMEOUT=300
X402_ASSET_ADDRESS=
X402_ASSET_NAME=USDC
X402_ASSET_VERSION=1
CORS_ORIGINS=http://localhost:5173,http://localhost:3007

Install & Start

# Install and start backend
cd backend
pnpm i
pnpm dev
 
# In a new terminal, install and start frontend
cd frontend
pnpm i
pnpm dev

Visit http://localhost:5173 to see the paywall in action.

What is x402?

x402 is an open payment standard developed by Coinbase that leverages the HTTP 402 Payment Required status code to enable services to charge for API access and content directly over HTTP. This protocol allows:

Accountless Payments: No need for user accounts or sessions
Programmatic Access: Clients can automatically pay for resources
Privacy First: Minimal data sharing required
Crypto-Native: Fast and efficient blockchain-based payments
Flexible Monetization: Pay-per-use model for APIs and content

How It Works

Request Protected Content: Client requests a protected resource from the server
402 Response: Server responds with HTTP 402 status code and payment requirements (amount, network, payTo address)
Authenticate & Pay: User authenticates with Openfort Shield and sends USDC payment to the specified address
Content Unlocked: After transaction confirmation, client retries request with transaction hash and receives the content

The sample includes complete implementations of both the payment-protected server endpoints and the client-side payment flow with React hooks and UI components.

Use Cases

API Monetization: Charge per API call or data access
Content Paywalls: Micropayments for articles, videos, or premium content
AI Services: Pay-per-query for AI models and agents
Data Access: Monetize database queries or data feeds
Compute Resources: Pay-as-you-go cloud computing