stellar-x402-express

Express.js middleware implementation of the x402 Payment Protocol for the Stellar network. This package provides ready-to-use middleware for protecting Express routes with Stellar-based payments.

Installation

npm install stellar-x402-express

Overview

The stellar-x402-express package provides Express middleware for implementing the x402 Payment Protocol on the Stellar network. It handles:

• Route protection with Stellar payment requirements
• Payment validation and verification
• Transaction settlement on the Stellar network
• Proper HTTP 402 response handling

Quick Start

import express from 'express';
import { paymentMiddleware } from 'stellar-x402-express';

const app = express();

// Protect all routes with $0.01 USDC payment on Stellar testnet
app.use(paymentMiddleware(
  'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5', // Stellar address to receive payments
  {
    price: '$0.01',
    network: 'stellar-testnet'
  }
));

app.get('/api/data', (req, res) => {
  res.json({ data: 'Protected content' });
});

app.listen(3000, () => console.log('Server running on port 3000'));

Configuration

Simple Configuration

Protect all routes with a single price:

app.use(paymentMiddleware(
  'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
  {
    price: '$0.01',
    network: 'stellar-testnet'
  }
));

Advanced Configuration

Protect specific routes with different prices:

app.use(paymentMiddleware(
  'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
  {
    '/api/free/*': {
      price: '$0.00',
      network: 'stellar-testnet'
    },
    '/api/premium/*': {
      price: '$0.10',
      network: 'stellar-testnet',
      config: {
        description: 'Premium API access'
      }
    },
    '/api/enterprise/*': {
      price: '$1.00',
      network: 'stellar'
    }
  },
  {
    url: 'https://facilitator.example.com',
    createAuthHeaders: async () => ({
      verify: { 'Authorization': 'Bearer token' },
      settle: { 'Authorization': 'Bearer token' }
    })
  }
));

Stellar Networks

The middleware supports two Stellar networks:

• stellar-testnet: Stellar testnet (chainId: 1)

  • USDC Issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
  • RPC: https://soroban-testnet.stellar.org

• stellar: Stellar mainnet (chainId: 2)

  • USDC Issuer: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
  • RPC: https://soroban.stellar.org

Payment Flow

1. Client makes request to a protected route
2. Middleware returns 402 status with payment requirements
3. Client creates a Stellar transaction signing it with their keypair
4. Client retries request with X-PAYMENT header containing the signed transaction
5. Middleware verifies the transaction with facilitator
6. If valid, middleware signs the transaction as fee sponsor and settles it
7. Client proceeds to protected resource

Facilitator

The middleware requires a facilitator service to:

• Verify Stellar transactions before execution
• Sponsor transaction fees (acting as fee sponsor)
• Settle transactions on the Stellar network

By default, it uses the public x402.org facilitator for testnet. For production, provide your own:

{
  url: 'https://your-facilitator.com',
  createAuthHeaders: async () => ({
    verify: { /* auth headers */ },
    settle: { /* auth headers */ }
  })
}

Type Exports

export type {
  Money,
  Network,
  PaymentMiddlewareConfig,
  Resource,
  RouteConfig,
  RoutesConfig,
} from 'stellar-x402/types';

Integration with Stellar Wallet Kit

For a better client experience, integrate with Stellar Wallet Kit to allow users to connect their Stellar wallets:

// Client-side with Stellar Wallet Kit
import { WalletKit } from '@stellar/wallet-kit';

const walletKit = new WalletKit();
await walletKit.connect();

const tx = await client.preparePaymentHeader(paymentRequirements);
const signed = await walletKit.sign(tx);

Error Handling

The middleware returns standard HTTP 402 responses with error details:

{
  "x402Version": 1,
  "error": "insufficient_funds",
  "message": "Payment amount too low",
  "accepts": [
    {
      "scheme": "exact",
      "network": "stellar-testnet",
      "maxAmountRequired": "1000000",
      "payTo": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
      "asset": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
      ...
    }
  ]
}

License

Apache 2.0 - See LICENSE for details