$ npm install @space-meridian/x402-expressExpress middleware integration for the x402 Payment Protocol. This package allows you to easily add paywall functionality to your Express.js applications using the x402 protocol.
npm install x402-express
import express from "express";
import { paymentMiddleware, Network } from "x402-express";
const app = express();
// Configure the payment middleware
app.use(paymentMiddleware(
"0xYourAddress",
{
"/protected-route": {
price: "$0.10",
network: "base-sepolia",
config: {
description: "Access to premium content",
}
}
}
));
// Implement your route
app.get("/protected-route",
(req, res) => {
res.json({ message: "This content is behind a paywall" });
}
);
app.listen(3000);
The paymentMiddleware function accepts three parameters:
payTo: Your receiving address (0x${string})routes: Route configurations for protected endpointsfacilitator: (Optional) Configuration for the x402 facilitator servicepaywall: (Optional) Configuration for the built-in paywallSee the Middleware Options section below for detailed configuration options.
The middleware supports various configuration options:
type RoutesConfig = Record<string, Price | RouteConfig>;
interface RouteConfig {
price: Price; // Price in USD or token amount
network: Network; // "base" or "base-sepolia"
config?: PaymentMiddlewareConfig;
}
interface PaymentMiddlewareConfig {
description?: string; // Description of the payment
mimeType?: string; // MIME type of the resource
maxTimeoutSeconds?: number; // Maximum time for payment (default: 60)
outputSchema?: Record<string, any>; // JSON schema for the response
customPaywallHtml?: string; // Custom HTML for the paywall
resource?: string; // Resource URL (defaults to request URL)
}
type FacilitatorConfig = {
url: string; // URL of the x402 facilitator service
createAuthHeaders?: CreateHeaders; // Optional function to create authentication headers
};
For more on paywall configuration options, refer to the paywall README.
type PaywallConfig = {
cdpClientKey?: string; // Your CDP Client API Key
appName?: string; // Name displayed in the paywall wallet selection modal
appLogo?: string; // Logo for the paywall wallet selection modal
sessionTokenEndpoint?: string; // API endpoint for Coinbase Onramp session authentication
};
Note: Onramp integration is completely optional. Your x402 paywall will work perfectly without it. This feature is for users who want to provide an easy way for their customers to fund their wallets directly from the paywall.
When configured, a "Get more USDC" button will appear in your paywall, allowing users to purchase USDC directly through Coinbase Onramp.
Add a session token endpoint to your Express app:
import express from "express";
import { POST } from "x402-express/session-token";
const app = express();
// Add the session token endpoint
app.post("/api/x402/session-token", POST);
Add sessionTokenEndpoint to your middleware configuration. This tells the paywall where to find your session token API:
app.use(paymentMiddleware(
payTo,
routes,
facilitator,
{
sessionTokenEndpoint: "/api/x402/session-token",
cdpClientKey: "your-cdp-client-key",
}
));
Important: The sessionTokenEndpoint must match the route you created above. You can use any path you prefer - just make sure both the route and configuration use the same path. Without this configuration, the "Get more USDC" button will be hidden.
Add your CDP API keys to your environment:
# .env
CDP_API_KEY_ID=your_secret_api_key_id_here
CDP_API_KEY_SECRET=your_secret_api_key_secret_here
Once set up, your x402 paywall will automatically show a "Get more USDC" button when users need to fund their wallets.
"Missing CDP API credentials"
CDP_API_KEY_ID and CDP_API_KEY_SECRET are set"Failed to generate session token"
API route not found
app.post("/your-path", POST)sessionTokenEndpoint configurationimport { POST } from "x402-express/session-token"sessionTokenEndpoint: "/api/custom/onramp", add app.post("/api/custom/onramp", POST)