Skip to Content
x402 ProtocolGetting Started

Getting started with x402

Prerequisites

  1. An Inzi account with an API key (sk_live_...) — sign up at inzipay.com 
  2. A Node.js API (Express or Fastify)

Install

npm install @inzi/x402

Example: paywall an API endpoint

import express from 'express'
import { x402 } from '@inzi/x402/express'
 
const app = express()
 
// $0.01 USDC on Base per request
app.get('/api/premium-data', x402({
  apiKey: process.env.INZI_API_KEY,
  amount: '0.01',
  asset: 'USDC',
  network: 'base',
  description: 'Access premium data',
}), (req, res) => {
  // Payment verified — serve content
  console.log('Paid by:', req.x402Payment.payerAddress)
  res.json({ data: 'premium content' })
})
 
app.listen(3000)

How the client pays

An x402-compatible client (AI agent, SDK, or manual):

  1. Makes request → gets 402 + X-PAYMENT-REQUIRED header
  2. Reads the requirements (amount, token, payTo address)
  3. Sends USDC on Base to the payTo address
  4. Retries with X-PAYMENT header containing Base64-encoded { txHash, chain, token, amount, payerAddress, payTo }
  5. Gets 200 OK + the actual response

Client example (Node.js)

// 1. First request — get requirements
const res = await fetch('https://api.example.com/api/premium-data')
// res.status === 402
 
const requirements = JSON.parse(
  Buffer.from(res.headers.get('X-PAYMENT-REQUIRED'), 'base64').toString()
)
// { payTo: "0x...", maxAmountRequired: "0.01", asset: "USDC", network: "base" }
 
// 2. Pay on-chain (using ethers.js, viem, etc.)
const txHash = await sendUSDC(requirements.payTo, requirements.maxAmountRequired)
 
// 3. Retry with payment proof
const payment = Buffer.from(JSON.stringify({
  txHash,
  chain: 'base',
  token: 'USDC',
  amount: '0.01',
  payerAddress: myAddress,
  payTo: requirements.payTo,
})).toString('base64')
 
const dataRes = await fetch('https://api.example.com/api/premium-data', {
  headers: { 'X-PAYMENT': payment },
})
// dataRes.status === 200
const data = await dataRes.json()

The SDK handles all header encoding/decoding. The client just needs to send a transaction and pass the proof.

Dashboard

All x402 payments appear in your Inzi dashboard  alongside regular checkout payments. You can also call GET /api/v1/x402/payments to list them programmatically.

Settlement

x402 funds accumulate in Inzi’s facilitator wallet. Call POST /api/v1/x402/settle to trigger settlement to your configured wallet address, or wait for automatic batch settlement.

Overview