# x402 Stellar
Tools, examples, and references for the [x402 protocol](https://www.x402.org/) on the Stellar network.
## Repository Structure
```
x402-stellar/
├── examples/ # Example applications
│ ├── facilitator/ # Stellar facilitator service
│ └── simple-paywall/ # Paywall demo (server + client)
│ └── docker-compose.yml
├── Dockerfile # Multi-target Dockerfile
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
└── Makefile
```
## Prerequisites
- Node.js 22.23.4+
- pnpm 10+
## Quick Start
```bash
# Clone the repo
git clone https://github.com/stellar/x402-stellar.git
cd x402-stellar
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Copy env template and fill in your values
cp examples/simple-paywall/server/.env.example examples/simple-paywall/server/.env
```
### Running the Simple Paywall Example
You need three terminals:
**Terminal 1 -- Facilitator:**
```bash
cd examples/facilitator
cp .env.example .env # fill in FACILITATOR_STELLAR_PRIVATE_KEY
pnpm dev
```
**Terminal 2 -- Server:**
```bash
cd examples/simple-paywall/server
pnpm dev
```
**Terminal 3 -- Client:**
```bash
cd examples/simple-paywall/client
pnpm dev
```
Open [http://localhost:5173](http://localhost:5173) and navigate through Home → Try It. The page dynamically shows buttons for each configured network (testnet, mainnet, or both) based on which `TESTNET_*` / `MAINNET_*` env vars are set.
### Docker Compose (with ingress rewrite simulation)
To run the 3-service compose stack plus a local ingress simulator (production-style rewrite behavior):
```bash
docker compose \
-f examples/simple-paywall/docker-compose.yml \
-f examples/simple-paywall/docker-compose.ingress-sim.yml \
up -d --build
```
Then open [http://localhost:8099/x402-demo/try](http://localhost:8099/x402-demo/try).
This simulator rewrites:
- `/x402-demo(/|$)(.*)` → client `/$2`
- `/x402-demo/api(/|$)(.*)` → server `/$2`
It is useful for reproducing ingress-prefix issues locally. Full verification steps (including decoding `PAYMENT-REQUIRED.resource.url`) are in `examples/simple-paywall/INGRESS_SIMULATION.md`.
To stop:
```bash
docker compose \
-f examples/simple-paywall/docker-compose.yml \
-f examples/simple-paywall/docker-compose.ingress-sim.yml \
down
```
## Examples
| Example | Path | Description |
| ------------------ | -------------------------- | -------------------------------------------------------- |
| **Facilitator** | `examples/facilitator/` | Stellar facilitator service that processes x402 payments |
| **Simple Paywall** | `examples/simple-paywall/` | Express API with x402 middleware + React/Vite frontend |
## Development
```bash
make install # pnpm install
make build # pnpm build (turbo)
make dev # pnpm dev
make lint # pnpm lint
make typecheck # pnpm typecheck
make test # pnpm test
make check # format + lint + typecheck + test
make clean # remove dist/ and node_modules/ from examples
```
## Deployment
The Dockerfile is a multi-target build with targets for `facilitator`, `server`, and `client`. See `examples/simple-paywall/docker-compose.yml` for the compose configuration.
## Environment Variables
### Server
| Variable | Default | Description |
| ------------------ | -------------------------------- | ------------------------------------------- |
| `PORT` | `3001` | Server port |
| `NODE_ENV` | `development` | Environment |
| `LOG_LEVEL` | `info` | Pino log level |
| `CORS_ORIGINS` | `http://localhost:5173` | Allowed CORS origins (comma-separated) |
| `PAYWALL_DISABLED` | — | Set to `true` to disable the paywall |
| `PAYMENT_PRICE` | `0.01` | Price for protected content |
| `CLIENT_HOME_URL` | — | Client home page URL for paywall brand link |
| `TRUST_PROXY` | `loopback,linklocal,uniquelocal` | Express trust proxy setting |
### Per-Network (Testnet / Mainnet)
The server supports multiple Stellar networks simultaneously. Each network is configured with a `TESTNET_` or `MAINNET_` prefix. Provide at least one set to enable that network's `/protected/<network>` endpoint.
| Variable (replace `<NETWORK>_` with `TESTNET_` or `MAINNET_`) | Default | Description |
| ------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------- |
| `<NETWORK>_SERVER_STELLAR_ADDRESS` | _required per network_ | Stellar address to receive payments |
| `<NETWORK>_STELLAR_RPC_URL` | testnet RPC (testnet only) | Custom Soroban RPC URL (required for mainnet) |
| `<NETWORK>_FACILITATOR_URL` | — | x402 facilitator URL |
| `<NETWORK>_FACILITATOR_API_KEY` | — | Facilitator API key(s); comma-separate multiple keys for round-robin load balancing (optional) |
### Facilitator
| Variable | Default | Description |
| ------------------------------------- | -------------------------------- | ---------------------------------------- |
| `FACILITATOR_STELLAR_PRIVATE_KEY` | — | Facilitator wallet private key |
| `FACILITATOR_STELLAR_FEE_BUMP_SECRET` | — | Fee-bump signer secret (high-throughput) |
| `FACILITATOR_STELLAR_CHANNEL_SECRETS` | — | Channel account secrets, comma-separated |
| `TRUST_PROXY` | `loopback,linklocal,uniquelocal` | Express trust proxy setting |
| `MAX_TRANSACTION_FEE_STROOPS` | `50000` (library default) | Max fee in stroops accepted from clients |
### Client
| Variable | Default | Description |
| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
| `VITE_SERVER_URL` | `http://localhost:3001` | Server URL for the client SPA (build-time or runtime) |
| `VITE_APP_NAME` | `x402 on Stellar` | App name for the client SPA (build-time or runtime) |
| `VITE_PAYMENT_PRICE` | `0.01` | Payment price shown in the UI (build-time or runtime) |
| `VITE_BASE_ROUTE` | `/` | Rewrites asset paths and sets the SPA router basename for subpath serving (runtime only) |
| `VITE_PORT` | `5173` | Dev server port (build-time only) |
> **Note:** `VITE_SERVER_URL`, `VITE_APP_NAME`, and `VITE_PAYMENT_PRICE` can be overridden at container launch time (via `docker-entrypoint.sh` → `window.__CONFIG__`). `VITE_BASE_ROUTE` is runtime-only: at container startup, the entrypoint rewrites asset paths in `index.html` and injects the SPA router basename so the app works when served under a subpath (e.g. `/x402-demo/`). `VITE_PORT` only affects the Vite dev server and is not used in Docker. These variables are included in the root `.env.example` (commented out); alternatively, set them in the client's own `.env` file or pass them via the environment (e.g. `VITE_PORT=3000 pnpm dev`).
## High-Throughput Facilitator Setup (Recommended)
For production or high-volume scenarios, the facilitator supports **channel accounts** with a **fee-bump signer**. This is the recommended setup because it allows parallel transaction submission — each channel account maintains its own sequence number, and a dedicated fee-bump signer pays all fees.
### How It Works
On Stellar, a single account can only submit one transaction at a time because each transaction increments the account's sequence number. With 19 channel accounts + 1 fee-bump signer, the facilitator can submit up to 19 transactions in parallel:
- **Channel accounts** (inner-tx signers): Each holds its own sequence number. The facilitator uses round-robin selection to distribute transactions across them. Created with zero balance via sponsored reserves.
- **Fee-bump signer**: A separate funded account that wraps each inner transaction in a fee-bump transaction. It pays the network fees but does not manage sequence numbers.
### Setup
1. Generate and fund the accounts on testnet:
```bash
cd examples/facilitator
pnpm generate-channel-accounts
```
This will:
- Create a fee-payer keypair and fund it via Friendbot
- Generate 19 channel account keypairs
- Create all channel accounts on-chain with zero balance (using sponsored reserves)
- Save all keys to a timestamped `.env` file under `scripts/output/`
- Print the environment variables to add to your `.env`
2. Copy the output into your `.env`:
```bash
# examples/facilitator/.env
FACILITATOR_STELLAR_PRIVATE_KEY=S_YOUR_EXISTING_KEY
FACILITATOR_STELLAR_FEE_BUMP_SECRET=S_FEE_BUMP_SECRET_FROM_SCRIPT
FACILITATOR_STELLAR_CHANNEL_SECRETS=S_CH1,S_CH2,...,S_CH19
```
3. Start the facilitator — it auto-detects high-throughput mode:
```bash
pnpm dev
```
You should see a log line: `High-throughput mode: fee-bump signer + channel accounts`.
When the channel account variables are not set, the facilitator falls back to single-signer mode using `FACILITATOR_STELLAR_PRIVATE_KEY`.
### Testnet Reset Recovery
Stellar's public testnet resets periodically, wiping all accounts. Two utility scripts re-fund your accounts without regenerating keys:
```bash
cd examples/facilitator
# Re-fund accounts from your .env file
pnpm refund-accounts-from-env
# Re-fund all signers registered with x402.org
pnpm refund-accounts-from-remote
```
Both scripts skip accounts that are already funded. See `examples/facilitator/README.md` for details.
## Adding a New Example
1. Create a directory under `examples/` (e.g. `examples/my-example/`)
2. Add a `package.json` with name `@x402-stellar/my-example`
3. The workspace globs in `pnpm-workspace.yaml` will pick it up automatically
4. Run `pnpm install` from the root to link it