A self-contained Bitcoin escrow system for phpBB forums. Sellers list items, buyers fund them on-chain, and an operator fee is collected automatically on each successful release.
- phpBB 3.3 or higher
- PHP 8.0 or higher with cURL and JSON extensions
- MySQL 5.7+ or MariaDB 10.2+ with InnoDB support
- Outbound HTTPS access from the server (for rate APIs and BlockCypher)
- A BlockCypher API account (free at blockcypher.com)
- A Bitcoin wallet with RPC or BlockCypher TX access for fund disbursement
- Cron access — cPanel, SSH (Linux), or Task Scheduler (Windows)
phpbb_bitcoin_escrow/
escrow.php Main controller
escrow_core.php Core engine — rate fetch, state machine, queries
escrow_cron.php CLI maintenance — blockchain polling, expiry, reminders
escrow_setup.php Guided setup wizard — run once, self-deletes
escrow_tpl/
escrow_body.html Master template — deployed to all forum styles on setup
.htaccess Blocks web access to escrow_cron.php (Apache)
README.md This file
INSTALL.md Step-by-step installation guide
OPERATOR_GUIDE.md Wallet integration and operational reference
Full instructions are in INSTALL.md. The short version:
- Upload all files to your phpBB root directory
- Log in as administrator and visit
escrow_setup.php - Follow the five-step wizard (tables, Bitcoin address, API token, fees, cron)
- Set up the cron job (see
INSTALL.mdfor Linux and Windows instructions)
Seller creates listing -> PENDING
Buyer claims listing -> WAITING_PAYMENT (unique BTC address generated via BlockCypher)
Buyer sends payment -> FUNDED (cron detects confirmed on-chain deposit)
Seller dispatches item
Buyer releases funds -> RELEASED (seller receives BTC minus configured operator fee)
Either party may open a dispute while FUNDED. Funds remain on-chain until an administrator resolves it via the admin panel.
release_funds() in escrow_core.php includes a safety gate that prevents
any funds from being disbursed until a wallet is configured. To enable
payouts, follow the instructions in OPERATOR_GUIDE.md to connect either
Bitcoin Core RPC or BlockCypher TX, then remove the throw new Exception
line from the method.
Option A — Bitcoin Core RPC (recommended, self-hosted)
composer require denpamusic/php-bitcoinrpcOption B — BlockCypher Transaction API
Sign and broadcast using the WIF key returned by generate_escrow_address().
Visit escrow.php?mode=admin at any time to:
- Update all system settings
- View and filter all transactions
- Override transaction status
- Resolve disputes
- Guided setup wizard with automatic database table creation
- Admin panel for all settings — no file editing required post-install
- Three-provider Bitcoin rate API with five-minute cache (CoinGecko, CoinCap, Blockchain.info)
- Unique per-transaction escrow addresses via BlockCypher
- QR code display for mobile wallet payments
- Copy-to-clipboard for escrow addresses
- Live countdown timer on payment expiry
- Buyer and seller star ratings after release
- Dispute system with admin resolution panel
- Email notifications on every state transition
- Expiry reminder emails 24 hours before deadline
- Rate limiting on listing creation
- Automatic expiry of stale transactions
- Pagination on marketplace listings
- Blockchain explorer links on all transaction hashes
- P2PKH, P2SH, and Bech32 address support
- CSRF protection on every form
- All input sanitised through phpBB database layer
- Admin notifications reach all ADMINISTRATORS group members
- Template auto-deployed to every installed forum style
- Cron file refuses HTTP requests (CLI-only check)
- All forms carry phpBB-compatible CSRF tokens
- SQL injection prevented throughout via phpBB db layer
- Output escaped with htmlspecialchars on all user-supplied data
- Operator address required before listings can be created
- BlockCypher token required before addresses can be generated
- Admin dispute notification reaches all administrators, not only founders
See LICENSE for terms.