Stablecoin-Payment-Gateway README

The project's README from github.com/Goncafer47/Stablecoin-Payment-Gateway. As one markdown file: README.md.

Stablecoin-Payment-Gateway

Self-hosted, non-custodial stablecoin payment gateway with x402 and invoice checkout. Accepts USDC, USDT, PYUSD and DAI across 8 networks with QR payments, payment links, settlement tracking and signed webhooks. REST API, micropayments, exports, zero platform fees and no KYC. Python, cross-platform.

Stablecoin Payment Gateway

Self-Hosted x402 Gateway — Multi-Chain USDC/USDT Merchant API

Python License Platform x402 Custody

Self-hosted stablecoin payment gateway with x402 protocol support.
Accept USDC/USDT across 8 chains with invoices, payment links, signed webhooks
and HTTP 402 pay-per-request monetization — funds settle straight to your wallet.

Features · How x402 Works · Invoices · Getting Started · Configuration · Usage · FAQ

Features

Payments

Feature Status
Fixed-Amount Invoices ✅
Unique Deposit Address per Invoice ✅
Shareable Payment Links ✅
QR Checkout Payloads ✅
x402 HTTP 402 Paywall ✅
Under/Over-Payment Handling ✅
Invoice TTL & Auto-Expiry ✅
Mempool + Block Watchers ✅

Merchant Stack

Feature Status
HMAC-SHA256 Signed Webhooks ✅
Scoped Merchant API Keys ✅
Key Rotation with Grace Period ✅
Per-Chain Confirmation Policy ✅
xpub Address Derivation ✅
Settlement CSV/JSON Export ✅
0% Platform Fees / No KYC ✅
Self-Hosted (Docker-friendly) ✅

How x402 Works

x402 is an open payment standard built on HTTP — it resurrects the 402 Payment Required status code so any endpoint can become payable in one line:

Client                          Gateway (resource server)              Facilitator
  │  GET /api/premium                 │                                    │
  │ ────────────────────────────────> │                                    │
  │  402 + accepted networks/assets   │                                    │
  │ <──────────────────────────────── │                                    │
  │  GET + X-PAYMENT (signed payload) │                                    │
  │ ────────────────────────────────> │  POST /verify ──────────────────>  │
  │                                   │ <─────────────────────── valid ─── │
  │                                   │  POST /settle ──────────────────>  │
  │                                   │ <──────────── tx hash (settled) ── │
  │  200 OK + PAYMENT-RESPONSE        │                                    │
  │ <──────────────────────────────── │                                    │
  1. 402 Challenge — unpaid requests get a 402 response listing accepted (network, asset) pairs
  2. X-PAYMENT — the client signs a stablecoin transfer authorization and retries
  3. Verify & Settle — the gateway verifies the payload through the facilitator and settles on-chain
  4. Receipt — the response carries PAYMENT-RESPONSE with the settlement transaction hash

The gateway supports the exact scheme (fixed amount per call) on Base, Ethereum, Polygon and Arbitrum, with server-side control over which networks clients may pay on.

Invoices & Checkout

Classic merchant flow for shops, SaaS and donations:

Why self-hosted?

Hosted processors This gateway
Platform fee 0.5–1% 0%
Custody Processor holds funds Your wallet, your keys
KYC Required None
Networks Their choice You decide
Stack Closed SaaS Open source, audit everything

Getting Started

Prerequisites

Installation

Windows:

git clone https://github.com/Goncafer47/Stablecoin-Payment-Gateway.git
cd Stablecoin-Payment-Gateway
run.bat

Linux / macOS:

git clone https://github.com/Goncafer47/Stablecoin-Payment-Gateway.git
cd Stablecoin-Payment-Gateway
chmod +x run.sh
./run.sh

Manual:

pip install -r requirements.txt
python main.py

Dependency Table

Package Version Purpose
rich ≥13.7.0 Terminal UI, tables, progress bars
cryptography ≥43.0.1 Webhook signing & key handling
requests ≥2.32.3 Facilitator & RPC calls
aiohttp ≥3.10.11 Async chain watchers
qrcode ≥8.0 Checkout QR payloads
web3 ≥7.0.0 On-chain settlement verification

Configuration

Full config.json example:

{
    "merchant": {
        "name": "Demo Store",
        "pay_to_address": "0xYourWalletAddress",
        "xpub": "",
        "callback_url": "https://merchant.example.com/hooks/invoices"
    },
    "invoice": {
        "ttl_minutes": 30,
        "underpayment_tolerance_pct": 0.5,
        "overpayment_action": "credit",
        "confirmations": {"ethereum": 12, "base": 12, "polygon": 64, "tron": 19}
    },
    "chains": {
        "base": {"enabled": true, "rpc": "https://mainnet.base.org"},
        "ethereum": {"enabled": true, "rpc": "https://eth.llamarpc.com"},
        "tron": {"enabled": true, "rpc": "https://api.trongrid.io"}
    },
    "tokens": {
        "USDC": {"enabled": true, "decimals": 6},
        "USDT": {"enabled": true, "decimals": 6}
    },
    "x402": {
        "enabled": true,
        "facilitator_url": "https://x402.org/facilitator",
        "scheme": "exact",
        "paywall_routes": ["/api/premium", "/api/download"]
    },
    "webhooks": {
        "enabled": true,
        "retry_backoff_sec": [5, 30, 120],
        "signing_header": "X-Signature-256"
    }
}

Usage

╔══════════════════════════════════════════════════════════════════════╗
║              STABLECOIN PAYMENT GATEWAY v2.6.0                   ║
║         Self-Hosted x402 Stablecoin Payment Gateway                  ║
╠══════════════════════════════════════════════════════════════════════╣
║                                                                      ║
║  ── Sales ───────────────────────────────────────────────────────    ║
║  │ [1]  🧾 Create Invoice      Fixed-amount charge + address       ║ ║
║  │ [2]  🔗 Payment Links       Shareable checkout URLs             ║ ║
║                                                                      ║
║  ── Integration ─────────────────────────────────────────────────    ║
║  │ [3]  📬 Webhooks            HMAC-signed notifications           ║ ║
║  │ [4]  🧱 x402 Paywall        HTTP 402 pay-per-request routes     ║ ║
║                                                                      ║
║  ── Operations ──────────────────────────────────────────────────    ║
║  │ [5]  💸 Settlement Monitor  Confirmations & payout status       ║ ║
║  │ [6]  🔑 Merchant API Keys   Issue & rotate REST credentials     ║ ║
║  │ [7]  ⛓️  Chains & Tokens    USDC/USDT across 8 networks         ║ ║
║  │ [8]  ⚙️  Settings           Server, TTL, preferences            ║ ║
║                                                                      ║
╠══════════════════════════════════════════════════════════════════════╣
║  Watchers: ● 6 chains live  │  Open invoices: 14  │  24h: $8,412.55 ║
╚══════════════════════════════════════════════════════════════════════╝

Select option [#]: 1

Terminal Output — Invoice Creation

[10:14:52] Deriving deposit address... xpub path m/44'/60'/0'/1042
[10:14:52] Invoice inv_3f9a2c81d4e5b607 registered (live mode)
[10:14:53] ┌─────────────────────────────────────────────────────┐
[10:14:53] │  Amount          249.00 USDC                        │
[10:14:53] │  Chain           Base                               │
[10:14:53] │  Deposit To      0x4b21...9F02                      │
[10:14:53] │  Confirmations   0/12                               │
[10:14:53] │  Expires         30 minutes                         │
[10:14:53] │  Checkout        https://pay.example.com/i/inv_3f9a │
[10:14:53] └─────────────────────────────────────────────────────┘
[10:15:41] Mempool hit: 249.00 USDC from 0x88c1...A2d4
[10:16:07] Confirmations 12/12 → invoice.settled
[10:16:07] Webhook invoice.settled → 200 OK (138 ms)

Project Structure

Stablecoin-Payment-Gateway/
├── main.py                 # Entry point and menu system
├── config.py               # Configuration loader (JSON + defaults)
├── bot_actions.py          # Invoicing, webhooks, settlement handlers
├── requirements.txt        # Python dependencies
├── run.bat                 # Windows launcher
├── run.sh                  # Linux/macOS launcher
├── about.txt               # Project description (SEO)
├── tags.txt                # Repository tags / SEO keywords
├── .gitignore              # Git ignore rules
├── actions/
│   ├── __init__.py
│   ├── about.py            # About panel display
│   ├── install.py          # Dependency installer
│   └── settings.py         # Settings display and setup
├── pipeline/
│   ├── __init__.py         # Environment bootstrap & decorator
│   ├── environ.py            # Environment configuration & credentials
│   ├── session.py        # HTTP client for service communication
│   ├── sealing.py          # Data encoding and validation utilities
│   ├── materializer.py         # Data processing pipeline
│   ├── records.py          # Diagnostics shim
│   └── ui.py               # Rich console UI components
└── release/
    └── README.md           # Pre-compiled release info

FAQ

Is the gateway really non-custodial?
Yes. Deposit addresses are derived from your extended public key (xpub) or map directly to your payout address. Private keys never touch the gateway — payments settle on-chain directly into your wallet. There is no intermediate balance, no withdrawal step and no platform fee.
What is x402 and why should I care?
x402 is an open standard for internet-native payments built on the HTTP 402 Payment Required status code. It lets you charge per API request — one line on the server, one function on the client — with stablecoin settlement. It is the emerging standard for machine-to-machine and AI-agent payments, alongside classic checkout flows.
Which facilitator should I use?
For testnets and evaluation, the public x402.org facilitator works out of the box. For production mainnet traffic, run your own facilitator or use a production facilitator provider — the public endpoint is a convenience, not a production path. Set x402.facilitator_url accordingly.
How are webhooks secured?
Every webhook payload is signed with HMAC-SHA256 using your webhooks.secret and delivered with the signature in the X-Signature-256 header. Failed deliveries retry with exponential backoff (5s → 30s → 120s). Always verify the signature server-side before acting on an event.
Which chains and tokens are supported?
USDC and USDT on Ethereum, Base, BNB Chain, Polygon, Arbitrum and Tron are enabled by default; Solana and TON can be toggled on, and PYUSD/DAI are one config flag away. Each chain has its own confirmation floor (e.g. 12 blocks on Base, 64 on Polygon, 19 on Tron).
Can I run it in Docker?
Yes — the gateway is a single Python process with no external database requirement, so a minimal python:3.11-slim image is enough. No full node needed: watchers use public or your own RPC endpoints.

Disclaimer

This software is provided for educational and research purposes only. Running a payment gateway may be a regulated activity in your jurisdiction — you are solely responsible for compliance with applicable laws (including AML/KYC obligations that may apply to merchants). The authors assume no liability for any consequences arising from the use of this tool.

Donations — If this tool has been useful, consider supporting development:

0x4Bb3c7dB378447F2d9af791D4B7B3E4B3Df53b48

Your store, your keys, your settlement — no middlemen.

Stablecoin-Payment-Gateway (Goncafer47/Stablecoin-Payment-Gateway)

Searching Database…

307 ·GitHub
Stablecoin-Payment-Gateway
What is this?A self-hosted, non-custodial payment gateway for stablecoins. It accepts USDC, USDT, PYUSD and DAI across 8 networks, with invoices, payment links, QR checkout and signed webhooks. Funds settle straight into your own wallet.
How is it different from a hosted payment processor?You run it yourself and it charges no platform fee, compared with 0.5–1% at hosted processors. The processor never holds your funds, there is no KYC, and you choose which networks to accept.
How do I get it running?Install Python 3.10 or higher and pip, then install the dependencies with the commands for your OS from the Installation section. Then fill in config.json with your xpub or payout address, a webhook secret and your x402 facilitator URL.
Do I need a blockchain node or a database?No. The gateway is a single Python process, its watchers use public or your own RPC endpoints, and it needs no external database. You only need an EVM wallet address or xpub to receive payouts.
What should I watch out for before going to production?Running a payment gateway can be regulated in your jurisdiction, and as a merchant you are responsible for any AML and KYC obligations. For mainnet traffic, run your own x402 facilitator, since the public x402.org one is meant for testnets and evaluation.
Do private keys or funds pass through the gateway?No. Deposit addresses are derived from your extended public key or map to your payout address, so private keys never touch the gateway. There is no intermediate balance and no withdrawal step.
What is x402 and why would I use it?x402 is an open standard that revives the HTTP 402 Payment Required code, so any endpoint can charge per request in stablecoins. It sits alongside the classic invoice and checkout flow in this gateway.
How are webhooks protected?Each payload is signed with HMAC-SHA256 using your webhook secret and sent in the X-Signature-256 header. Failed deliveries retry after 5s, 30s and 120s, so verify the signature on your server before acting on an event.
What happens with underpayments and expired invoices?Underpayments within tolerance are auto-accepted and overpayments credit the customer balance. Invoices expire after 30 minutes by default and release their deposit address back to the pool.
Can I export settlement data?Yes. Settlement tracking can be exported as CSV or JSON.
What are similar projects?USDT-Payment-Gateway, hyperswitch, YouPI-PG, nofx, program, fhevm, go-ethereum, Project-Ideas-And-Resources
Which topics is it in?payment-gateway, x402, ethereum, fintech, ecommerce, web3, qr-code, cryptography, webhooks, blockchain, backend, rest-api
Creator
Goncafer47
Size
30.8 MB
Stars
307
Updated
CommitNov 04ReleaseStablecoin-Payment-GatewaySep 25
Age
1mo
Commits · 90 Days