Skip to main content

​
Overview

This quickstart guide will get you running the simplest demo - a basic HTTP paywall using the x402 protocol. You’ll see how an AI agent or API client can autonomously make a payment to access a protected endpoint.
Time to complete: ~5 minutes
What you’ll build: A payment-protected API endpoint

​
What You’ll Learn

By the end of this guide, you’ll have:
  • A running Express server with x402 payment protection
  • Understanding of the 402 Payment Required flow
  • Ability to test payments with curl

​
Prerequisites

Before starting, make sure you have:

Node.js 18+

Download from nodejs.org

Git

Install from git-scm.com
You don’t need testnet tokens or a Crossmint API key for this basic demo. The server will return payment requirements without actually settling transactions.

​
Step 1: Clone the Repository

1

Clone and navigate

git clone https://github.com/Crossmint/crossmint-agentic-finance.git
cd crossmint-agentic-finance
2

Navigate to the ping demo

cd ping
The ping demo is the simplest example - just one protected endpoint.

​
Step 2: Configure the Server

1

Copy the environment template

cp .env.example .env
2

Edit the configuration

Open .env and set your EVM address to receive payments:
.env
PAY_TO=0xYourAddressHere
Don’t have an EVM address? Use 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb (testnet address) for now.

​
Step 3: Install and Run

1

Install dependencies

npm install
2

Start the server

npm run dev
You should see:
Server running at http://localhost:3000

​
Step 4: Test the Payment Flow

Now let’s test the payment-protected endpoint. Open a new terminal window:
1

Make a request without payment

curl -i -H "Accept: application/json" http://localhost:3000/ping
You’ll receive a 402 Payment Required response with payment details:
{
  "error": "Payment Required",
  "payment": {
    "amount": "1000",
    "currency": "USDC",
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "base-sepolia"
  }
}
2

Understanding the response

The 402 response tells the client:
  • How much to pay (1000 = 0.001 USDC with 6 decimals)
  • What token to use (USDC)
  • Where to send it (to address)
  • Which blockchain network (base-sepolia)

​
What Just Happened?

The x402 protocol extends HTTP with payment requirements. When a client tries to access a protected resource:
  1. Server returns 402 Payment Required with payment details
  2. Client signs a payment authorization (EIP-712 signature)
  3. Client retries request with X-PAYMENT header
  4. Server verifies signature and settles payment on-chain
  5. Server returns the protected resource
  • Native to HTTP: The 402 status code was reserved since HTTP/1.1 (1997) for payments
  • Automatic handling: Clients can automatically detect and handle payment requirements
  • No custom protocols: Works with standard HTTP tools and libraries
  • AI-friendly: Agents can understand and respond to 402 without special training
The ping server uses x402-express middleware:
import { paymentMiddleware } from "x402-express";

app.use(paymentMiddleware(payTo, {
  "GET /ping": { price: "$0.001", network: "base-sepolia" }
}));

app.get("/ping", (_req, res) => {
  res.json({ message: "pong" });
});
The middleware intercepts requests and returns 402 until payment is verified.

​
Next Steps

Now that you’ve seen the basic payment flow, you can:

Generate Payment Headers

Learn how to create valid payment signatures and make successful requests

Explore More Demos

Try the weather API demo with dynamic pricing

Build an Agent

Create an autonomous agent that makes payments

Deploy to Production

Learn how to deploy to production with mainnet

​
Common Issues

If port 3000 is already in use, you can change it by editing src/server.ts:
const port = 3001; // Change to any available port
Make sure you’re using Node.js 18 or higher:
node --version
# Should show v18.0.0 or higher
If you’re behind a corporate firewall, try using HTTPS:
git clone https://github.com/Crossmint/crossmint-agentic-finance.git

​
Learn More

x402 Protocol

Deep dive into the payment protocol

Smart Wallets

Learn about Crossmint smart wallets

API Reference

Explore the x402-express API

Build docs developers (and LLMs) love

Get started for freeTalk to us