Quickstart

Protect an API endpoint with an x402 paywall in 5 minutes

Option 1: Express Middleware (Node.js / TypeScript)

Install the Express middleware package:

pnpm add @stellar-x402/core @stellar-x402/express

Protect an endpoint:

import express from 'express';
import { stellarX402Middleware } from '@stellar-x402/express';

const app = express();

app.use(
  '/api/v1/forecast',
  stellarX402Middleware({
    price: '0.01', // 0.01 USDC per call
    asset: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC', // Testnet USDC
    recipient: 'GCALKSGAZRJLSUEJT3M5W6LN4R7XQOLIRCOS6ZA6EDZVTZDBIIPPFKJ6',
    network: 'stellar:testnet',
    validitySeconds: 300,
  })
);

app.get('/api/v1/forecast', (req, res) => {
  res.json({
    location: 'San Francisco',
    temperature: 68,
    unit: 'Fahrenheit',
  });
});

app.listen(3000, () => {
  console.log('API listening on http://localhost:3000');
});

---

Option 2: Fastify Plugin

Install the Fastify package:

pnpm add @stellar-x402/core @stellar-x402/fastify

Register the plugin:

import Fastify from 'fastify';
import { fastifyX402 } from '@stellar-x402/fastify';

const fastify = Fastify();

await fastify.register(fastifyX402, {
  price: '0.005',
  asset: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC',
  recipient: 'GCALKSGAZRJLSUEJT3M5W6LN4R7XQOLIRCOS6ZA6EDZVTZDBIIPPFKJ6',
  network: 'stellar:testnet',
  paths: ['/api/v1/premium'],
});

fastify.get('/api/v1/premium', async () => ({
  status: 'paid',
  data: 'Exclusive market intelligence',
}));

await fastify.listen({ port: 3000 });

---

Option 3: Standalone Go Reverse Proxy

For backends written in Python, Go, Rust, or Java, run the Go reverse proxy in front of your upstream service:

# 1. Clone repository
git clone https://github.com/x402-stellar/gateway-app.git
cd gateway-app/proxy

# 2. Configure routes in config.yaml
cat <<EOF > config.yaml
listen_addr: ":8080"
network: "stellar:testnet"
routes:
  - path: "/api/v1/inference"
    upstream: "http://127.0.0.1:5000"
    asset: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
    price: "0.02"
    recipient: "GCALKSGAZRJLSUEJT3M5W6LN4R7XQOLIRCOS6ZA6EDZVTZDBIIPPFKJ6"
EOF

# 3. Start proxy daemon
go run cmd/gateway/main.go --config config.yaml

---

Making a Paid Call with the Client SDK

Autonomous clients use @stellar-x402/client to handle 402 responses, sign authorization entries within defined budget limits, and retry the request automatically:

import { StellarX402Client } from '@stellar-x402/client';

const client = new StellarX402Client({
  payerSecretKey: 'S...', // Agent Stellar private key
  maxSpendPerCall: '0.05', // Maximum allowed payment per request
  maxDailySpend: '2.00',   // Daily cumulative budget limit
  network: 'stellar:testnet',
});

// Automatically resolves 402 challenges and returns 200 OK data
const response = await client.fetch('http://localhost:3000/api/v1/forecast');
const data = await response.json();
console.log(data);