x402 Payment Gateway Template
github.com/azep-ninja/x402-gateway-template- Category
- Developer Tools
- Rank
- No. 945Tools index
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Business & Commerce
- Interfaces
- Web · CLI · API · SDK
- Builder
- @azep-ninja
- GitHub
- 94 stars
- Date
About
A production-ready, self-hosted payment gateway that implements the x402 protocol for HTTP-native micropayments. Enables APIs to accept stablecoin payments (USDC) per-request without API keys, subscriptions, or intermediaries.
What it does
It sits in front of an existing API and turns payment authorization into backend access. A client receives payment requirements, signs a token transfer, then retries. The gateway validates the signature, records replay state, settles the transfer, adds internal backend authentication, and returns the backend response with payment information.
Why it's ranked here
This is a strong implementation template, not merely a protocol sketch. It includes local and facilitator settlement paths, automatic network discovery, replay controls, retry protection, service discovery, health reporting, container packaging, and several deployment guides. The main reservation is verification maturity: the supplied project structure and package scripts show no automated test suite.
What's good
Backend isolation is the clearest strength. Existing services receive ordinary authenticated requests and need no payment-specific changes. Networks activate only when their RPC configuration exists, limiting accidental advertisement. Redis tracks nonces and cached retry responses, while an optional credit system compensates callers when settlement succeeds but the backend later fails. The settlement wallet pays gas while funds move directly to the configured recipient.
Tradeoffs
Operators must manage a settlement private key, recipient addresses, RPC providers, native gas balances, backend credentials, and Redis. Solana adds a fee-payer key, while some EVM networks depend on external facilitators with different token decimals or protocol behavior. Redis failures deliberately produce mixed degradation behavior. The supplied repository also lacks an automated test script or visible test directory, which raises the burden of validating payment edge cases before deployment.
How to use it well
Use it when an existing JSON API needs machine-oriented, paid access and your team can operate wallets, RPC connections, Redis, and container infrastructure. Start with one configured network, validate settlement and retry behavior, then add chains selectively. Keep secrets in the deployment platform's secret manager. It does not provide the underlying API, a client wallet, checkout pages, subscription billing, or general merchant accounting.
Technical notes+
src/index.js builds the Express 5 HTTP service, exposes /health, /accepted, and /.well-known/x402, then wraps configured routes with x402PaymentMiddleware. src/middleware/x402.js verifies EIP-712 authorizations with viem, submits transferWithAuthorization, supports facilitator-based EVM settlement, and uses @x402/svm for Solana. src/config/routes.js filters ALL_NETWORKS by configured RPC variables and exposes them through SUPPORTED_NETWORKS. src/utils/redis.js stores nonce, idempotency, and credit state; nonce reads fail open, pending writes fail closed, and credit counters use Lua for atomic updates. src/proxy.js injects backend authentication but also logs the complete serialized request body, which may require hardening for sensitive payloads. package.json has start and watch-mode development scripts but no test script. Dockerfile runs Node 20 as a non-root user and defines an HTTP health check.
Observed
- License
- MIT
- Primary language
- JavaScript using ES modules
- Packaging
- npm application with production dependencies declared in package.json
- Interface
- Self-hosted HTTP API and reverse gateway built with Express 5
- Deployment surface
- Docker image with guides for GCP Cloud Run, AWS ECS/Fargate, Railway, Fly.io, Render, and general Docker hosting
- Runtime
- Node.js 20 in the supplied container definition
- Tests
- No test script or test directory appears in the supplied package manifest and repository structure
Read from README.md, package.json, src/index.js, src/proxy.js, src/utils/redis.js, src/config/routes.js, src/middleware/x402.js, docs/deploy-aws.md, docs/deploy-gcp.md, docs/deploy-paas.md, LICENSE, llms.txt, Dockerfile, .env.example, cloudbuild.yaml.
What it can do
Accept USDC micropayments per API request
API request with USDC payment → Payment validation and API access
Implement x402 protocol for HTTP-native payments
HTTP request → HTTP 402 status code with payment requirements
Process stablecoin payments without intermediaries
USDC payment transaction → Direct payment confirmation
Enable API access without API keys or subscriptions
Payment-authenticated request → API response without credential verification
Support multiple blockchain networks
Payment on various blockchain networks → Cross-chain payment validation
Deploy self-hosted payment gateway
Docker configuration and Node.js environment → Running payment gateway instance
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.