Paywall Your API
Add x402 payment requirements to any Express endpoint in 5 minutes
Install
npm install @402md/gatewayCreate a gateway
import express from 'express'
import { create402Gateway } from '@402md/gateway'
const app = express()
const gateway = create402Gateway({
apiKey: process.env.FOUROHTWOM_API_KEY!
})Get your API key from the 402.md dashboard. Store it in an environment variable — never commit it to source control.
Apply middleware
Choose the middleware that matches your commerce type:
app.post('/api/analyze', gateway.payPerCall('0.05'), (req, res) => {
const result = analyzeSentiment(req.body.text)
res.json(result)
})app.post('/api/subscribe', gateway.subscription({
price: '49.00',
durationDays: 30,
accessUrl: 'https://dashboard.example.com'
}), (req, res) => {
res.json({
accessUrl: 'https://dashboard.example.com',
expiresAt: req.x402.expiresAt
})
})app.post('/api/buy/:productId', gateway.product({
price: '99.99',
requiresShipping: true
}), (req, res) => {
const order = createOrder(req.body)
res.json({ orderId: order.id })
})app.post('/api/design', gateway.service({
price: '25.00'
}), (req, res) => {
const job = startDesignJob(req.body)
res.json({ jobId: job.id })
})Access payment data
After the middleware verifies payment, req.x402 contains the payment details:
| Field | Type | Middleware |
|---|---|---|
txHash | string | All |
amount | string | All |
type | string | subscription, product, service |
durationDays | number | subscription |
requiresShipping | boolean | product |
Register your skill and test
- Create a skill in the 402.md dashboard and link it to your API endpoint
- Use Base Sepolia for testing:
const gateway = create402Gateway({
apiKey: process.env.FOUROHTWOM_API_KEY!,
apiBaseUrl: 'https://api-testnet.402.md'
})- Test with the Agent SDK or any x402-compatible client
What agents see
When an agent calls your endpoint without a payment header, the gateway returns HTTP 402:
{
"price": "0.05",
"description": "Payment required for API access",
"network": "base"
}The agent then signs a USDC payment and retries the request with an X-402-Payment header. The gateway verifies the payment via the 402.md API, and your handler runs normally.