Networks and assets
Supported blockchains, native coins, tokens, and confirmation counts.
Billium currently supports 7 blockchain networks and a curated set of native coins, stablecoins, and governance tokens on each. Every asset is matched to its network — you can't accept USDT generically, you accept USDT on Ethereum or USDT on Tron or USDT on Polygon.
Supported networks
| Network | Native coin | XPUB? | Typical block time |
|---|---|---|---|
Bitcoin (BTC) | BTC | ✅ | ~10 min |
Ethereum (ETH) | ETH | ❌ | ~12 s |
Polygon (POL) | POL (formerly MATIC) | ❌ | ~2 s |
BNB Chain (BNB) | BNB | ❌ | ~3 s |
Cronos (CRO) | CRO | ❌ | ~6 s |
TRON (TRX) | TRX | ❌ | ~3 s |
Litecoin (LTC) | LTC | ✅ | ~2.5 min |
Each network has a mainnet and a testnet configuration wired into the backend, but testnet support is currently for internal QA only — all production API keys hit mainnet. See Authentication for details on the sandbox situation.
Supported assets per network
The tokens below are the only assets Billium's matching engine knows about. Each entry is an accepted (cryptocurrency, network) pair.
| Asset | Bitcoin | Ethereum | Polygon | BNB | Cronos | TRON | Litecoin |
|---|---|---|---|---|---|---|---|
| BTC | ✅ | ||||||
| ETH | ✅ | ||||||
| POL | ✅ | ||||||
| BNB | ✅ | ||||||
| CRO | ✅ | ||||||
| TRX | ✅ | ||||||
| LTC | ✅ | ||||||
| USDT | ✅ | ✅ | ✅ | ✅ | ✅ | ||
| USDC | ✅ | ✅ | ✅ | ✅ | ✅ | ||
| DAI | ✅ | ✅ | ✅ | ✅ | |||
| UNI | ✅ | ✅ | ✅ | ✅ | |||
| SHIB | ✅ |
If you need a token or network that isn't on this list, open an issue or email support. Adding a well-known ERC-20 on a network we already monitor is typically a few hours of work; adding a new chain is a bigger project.
Confirmations
Billium doesn't hardcode a confirmation count per network — instead, it's configurable per wallet. When you register a wallet you pass requiredConfirmations, and Billium waits for that many confirmations on every payment before marking the invoice as PAID (or UNDERPAID / OVERPAID).
Sensible defaults by network:
| Network | Suggested confirmations | Wall-clock finality |
|---|---|---|
| Bitcoin | 1–3 | 10–30 min |
| Litecoin | 3–6 | 8–15 min |
| Ethereum | 12 | ~2.5 min |
| Polygon | 32 | ~1 min |
| BNB Chain | 15 | ~45 s |
| Cronos | 20 | ~2 min |
| TRON | 20 | ~1 min |
Higher values reduce the risk of a reorg reversing a payment after you've already fulfilled the order; lower values give the customer a faster "paid" experience. Match the number to the value of the invoice — a $5 digital download doesn't need the same assurance as a $50,000 B2B invoice.
Reorg handling
Chain reorganizations (reorgs) happen: a block that was included in the canonical chain gets replaced by a longer fork, and any transactions in that block are "un-confirmed". Billium detects this automatically:
- Billium periodically re-checks payments that have been waiting in
PENDING_CONFIRMATIONlonger than expected and queries the chain directly for the transaction. - If the transaction is no longer findable on the canonical chain, the payment is reverted — the invoice status goes back to
AWAITING_PAYMENTand a newinvoice.updatedevent fires. Your webhook handler should be prepared for this edge case. - If the transaction is still there but confirmation count is lagging, Billium keeps waiting.
In the very unusual case that a transaction remains stuck in PENDING_CONFIRMATION for more than 48 hours (dropped from mempool, replaced by RBF, or on a deep fork), Billium expires the invoice automatically. 48 hours is intentionally generous to survive long periods of Bitcoin mempool congestion.
Because reorgs can revert a payment after you've seen invoice.paid, you should make any fulfillment action idempotent and ideally reversible. In practice this means: deliver digital goods immediately on invoice.paid, but hold off on physical shipping or irreversible actions until the invoice has been paid for at least the network's finality window.
Which chains support xpub wallets?
Only Bitcoin and Litecoin. See Wallets → XPUB_WALLET for the full derivation flow. All other chains use DIRECT_WALLET — a single address shared across invoices, disambiguated by the matching algorithm.