stellar x402-stellar Checks
Architecture
pnpm 10.7.0 monorepo with Turborepo. Filter: --filter='@x402-stellar/*'.
| Package | Role |
|---|---|
packages/paywall |
React paywall bundled to HTML (esbuild+tsup) |
examples/facilitator |
Express: Stellar payment verify/settle |
examples/simple-paywall/server |
Express: x402 payment middleware |
examples/simple-paywall/client |
React/Vite SPA |
vendors/x402/typescript/ |
4 pre-built vendor packages (never modify) |
Build order (turbo handles this): paywall -> server (server imports paywall).
Endpoints:
| Service | Port | Routes |
|---|---|---|
| Facilitator | 4022 | POST /verify, POST /settle, GET /supported, GET /health |
| Server | 3001 | GET /health, GET /networks, GET /protected/:network (paywalled) |
| Client | 5173 | SPA (dev, configurable via VITE_PORT), 8080 (docker) |
Full Check
make check # install -> format -> lint -> typecheck -> test -> build
Expected: all 4 packages pass. 101 tests total (66 server + 35 facilitator), all green.
packages/paywall/src/gen/template.ts formatting diffs are expected (auto-generated).
After make check passes, also verify the Docker Compose build succeeds:
docker compose -f examples/simple-paywall/docker-compose.yml build
This catches issues that only surface in the container environment (e.g. missing
files in COPY instructions, pnpm patches not available at install time). The
Docker build must pass before considering a change fully verified.
Scenario Checks
| Changed | Run |
|---|---|
packages/paywall/ |
pnpm build && pnpm test |
| Facilitator routes/config | pnpm typecheck && pnpm test --filter=@x402-stellar/facilitator |
| Server routes/middleware | pnpm typecheck && pnpm test --filter=@x402-stellar/simple-paywall-server |
| Client SPA | pnpm build --filter=@x402-stellar/simple-paywall-client + manual browser check |
package.json / deps |
pnpm install && make check + docker compose -f examples/simple-paywall/docker-compose.yml build |
| Quick lint + types only | pnpm typecheck && pnpm lint |
Smoke Tests
smoke-test.sh tests all endpoints: health, facilitator routes, 402 paywall, client SPA, security headers, and error leak prevention.
# Local (default ports)
.opencode/skills/x402-stellar-checks/scripts/smoke-test.sh
# Remote / all-in-one deploy
.opencode/skills/x402-stellar-checks/scripts/smoke-test.sh https://my-app.example.com
# Custom ports
FACILITATOR=http://host:4022 SERVER=http://host:3001 CLIENT=http://host:8080 \
.opencode/skills/x402-stellar-checks/scripts/smoke-test.sh
Docker Verification
Multi-stage Dockerfile at repo root. Targets: facilitator, server, client.
Full docker compose test
docker-smoke-test.sh builds, starts, waits for healthy, runs smoke tests, then tears down.
.opencode/skills/x402-stellar-checks/scripts/docker-smoke-test.sh # docker compose (3 containers)
Compose file: examples/simple-paywall/docker-compose.yml (reads secrets from ../../.env).
Environment Setup
cp .env.example .env # then fill in secrets
Per-service examples: examples/facilitator/.env.example, examples/simple-paywall/server/.env.example.
Minimum required variables:
FACILITATOR_STELLAR_PRIVATE_KEY-- facilitator Stellar secret keyTESTNET_SERVER_STELLAR_ADDRESS-- server Stellar public address for testnet paymentsCLIENT_STELLAR_PRIVATE_KEY-- client Stellar secret key (payer)
Per-network server variables use TESTNET_ or MAINNET_ prefixes (e.g. TESTNET_FACILITATOR_URL, MAINNET_SERVER_STELLAR_ADDRESS). Provide at least one set.
Generate testnet keypairs: https://laboratory.stellar.org/#account-creator
Local Development
pnpm install && pnpm dev
Facilitator: http://localhost:4022 | Server: http://localhost:3001 | Client: http://localhost:5173