<div align="center">

💰 x402proxy

Monetize your API in Minutes • Automatically accept x402 Payments • Simple Config, Zero Code Changes Required

</div>

---

🚀 What is x402proxy?

A plug-and-play proxy that automatically takes care of all the x402 payment logic for you.

Set up in minutes in front of any existing API and start selling one-time access to your endpoints. A simple JSON config file lets you customize which endpoints to monetize, how much they cost, and where you get paid.

🚦 Getting Started

📋 Prerequisites

• Docker

That's it! No complex dependencies or setup required.

---

<div align="center">

⚡ Quick Start

🚀 Get up and running in under 60 seconds

</div>

📥 Step 1: Download Starter Config

curl -o custom-config.json https://raw.githubusercontent.com/zachalam/x402proxy/refs/heads/main/custom-config.json

🐳 Step 2: Run with Docker

docker run -p 8080:8080 \
  -v $(pwd)/custom-config.json:/app/config.json:ro \
  ghcr.io/zachalam/x402proxy:latest

✅ That's it! Your instance of x402proxy is now running and accepting x402 payments. 🎉

---

✨ Key Features

| Feature | Description | |---------|-------------| | 🌐 Multi-chain support | Works with Ethereum, Base, Solana, and more | | 💰 Direct payments | Paywall any URL; payment straight to your wallet | | 🏗️ Flexible pricing | Set one-time global or per-route pricing | | 🔌 Plug & play | Works with any standard x402 facilitator |

📊 How It Works

Simple architecture, powerful results. Clients make requests, payments are verified via x402 facilitator, and your API gets protected automatically.

---

⚙️ Configuration

📝 Config File Location

The application loads configuration strictly from /app/config.json inside the container.

⚠️ Important: If this file is not mounted, the container will exit with an error.

🔧 Configuration Fields

| Field | Description | |-------|-------------| | facilitatorUrl | The X402 facilitator URL | | network | Blockchain network (e.g., "base-sepolia") | | paymentAddress | Receiving wallet address | | defaultPrice | Default payment price for all routes | | protectedEndpoints | Map of protected endpoints with prices and forwarding URLs |

📄 Sample Configuration

Here's a complete example configuration file (custom-config.json):

{
  "facilitatorUrl": "https://x402.org/facilitator",
  "network": "base-sepolia",
  "paymentAddress": "0x5629562956295629562956295629562956295629",
  "defaultPrice": "$0.05",
  "protectedEndpoints": {
    "GET /cat": {
      "forwardTo": "https://api.thecatapi.com/v1/images/search"
    },
    "GET /dog": {
      "price": "$0.10",
      "forwardTo": "https://api.thedogapi.com/v1/images/search"
    },
    "GET /fact": {
      "price": "$0.15",
      "forwardTo": "https://catfact.ninja/fact"
    },
    "GET /joke": {
      "price": "$0.20",
      "forwardTo": "https://official-joke-api.appspot.com/random_joke"
    }
  }
}

💡 Tip: For large protectedEndpoints configurations, file mounting is recommended (no size limits).

---

🐳 GitHub Container Registry

🔄 Automatic Builds

The application is automatically built and pushed to GitHub Container Registry (ghcr.io) on every push to the main branch.

Each push creates a new version tagged with an auto-incremented version number and also tagged as latest.

📦 Pull & Run Latest Image

# Pull the latest image
docker pull ghcr.io/zachalam/x402proxy:latest

# Run with default port (config must be mounted to /app/config.json)
docker run -p 8080:8080 \
  -v $(pwd)/custom-config.json:/app/config.json:ro \
  ghcr.io/zachalam/x402proxy:latest

# Run with custom external port
docker run -p 4020:8080 -e PORT=8080 \
  -v $(pwd)/custom-config.json:/app/config.json:ro \
  ghcr.io/zachalam/x402proxy:latest

---

💻 Local Development

🚫 Without Docker

Perfect for quick local testing and development:

# Install dependencies
npm install

# Run in development mode with nodemon (hot reload)
npm run dev

# Run in production mode
npm start

📍 The application will be available at http://localhost:3000

---

🐳 With Docker (Recommended)

Use Docker for a consistent development environment with hot reload:

# Build and run the development container with hot reload
docker-compose up

# Run in detached mode (background)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

📍 The application will be available at http://localhost:3000

⚠️ Note: You must mount your config to /app/config.json. If the file is missing, the container will exit with an error.

---

🏗️ Architecture

| Environment | Details | |-------------|---------| | Development (docker-compose.yml) | Uses nodemon for hot reload, mounts source code as volume | | Production (Dockerfile) | Optimized image with only production dependencies, runs as non-root user |

---

📄 License

This project is licensed under the ISC License.

---

<div align="center">

⭐ Star this repo if you find it useful!

Built with ❤️ for the x402 ecosystem

Report Bug • Request Feature • Contribute

</div>