Documentation
Wallet setup
The one thing to understand: this software can only ever
receive; it cannot spend. You give it either a single receiving address, or an extended
public key (xpub) — never a private key or seed phrase. If you ever paste something
starting with xprv, the server refuses it. There is no signing code anywhere in this product,
and the repository ships with an automated check (scripts/check-no-custody.sh) that fails the
build if any ever appears.
After adding an xpub wallet, use Wallets → Verify addresses in the admin: it shows the first three addresses the server will use. Compare them with your own wallet app — they must match exactly. That is your proof that funds can only land in your wallet.
Two modes
| Mode | What you provide | Behavior |
|---|---|---|
| xpub (recommended) | An extended public key | A fresh address per invoice (standard path m/0/i). Cleanest matching, best privacy. |
| Single address | One receiving address | All invoices share it. Each invoice gets a unique "cent-dust" amount (e.g. 100.0143 instead of 100) so concurrent payments can be told apart. |
The single-address caveat, honestly stated: matching relies on the payer sending the
exact amount within the invoice window. If two customers both ignore the amount and send a round
100, the first observed transaction wins and the second appears as a "late payment" for you to
resolve manually in the dashboard. With an xpub this ambiguity cannot happen. Both modes never lose funds —
everything arriving is recorded and shown.
USDC on Base
- Hardware wallets (Ledger/Trezor): create a dedicated account for the store; export the account-level xpub (Ledger Live: Account → ⚙ → Advanced → xpub).
- MetaMask and most software wallets cannot export an xpub — use single address mode with a dedicated receiving address instead.
- Base is an Ethereum L2: the same address format (0x…), and your USDC arrives on the Base network.
USDT on Tron
- Most Tron wallets (TronLink, Trust Wallet, exchanges' Tron deposit addresses) don't expose an xpub — single address mode is the normal choice here. Create a dedicated address (T…) and paste it in.
- If your wallet does provide a TIP-32 account xpub, xpub mode works the same as on Base.
Testnet vs mainnet
With TESTNET=true, Base means Base Sepolia and Tron means Nile
— same addresses, worthless test tokens. Do a full test payment on testnet, then flip
TESTNET=false in deploy/.env and do one small real payment before going live.
Safety checklist
- Prefer a fresh wallet/account for the store rather than your personal one.
- Never share your seed phrase with anyone — this software never asks for it.
- After setup, run the Verify addresses check and pay one small test invoice end-to-end.