feat: Add BasePay — USDC payments guide for Base ecosystem

[osr21]

Summary

This PR adds a practical guide for BasePay — an open-source USDC stablecoin payments dApp built natively on Base Mainnet. The guide documents four production-ready payment patterns that any developer can fork, reuse, or build on.

Live app: https://base-pay.replit.app
Source: https://github.com/osr21/basepay-dapp
Network: Base Mainnet (Chain ID 8453)
All 4 contracts source-verified on BaseScan ✅

---

What this guide covers

Pattern	Contract	Value to Base ecosystem
Single USDC transfer	BasePayRouter	Instant, non-custodial payments with 0.30% fee
Batch payment	BatchPay	Payroll, airdrops, splits — 200 recipients in one tx
Escrow	Escrow	Trustless milestone payments with configurable timeout
Subscriptions	SubscriptionManager	Recurring pull-payment SaaS / memberships on-chain

---

Why this adds value to Base

For users

• Near-zero fees: A batch of 50 USDC payments costs under $0.05 on Base — making payroll and splits economically practical for the first time
• 2-second finality: Fast enough for real-time payment UX
• Non-custodial: Funds never pass through a centralised intermediary
• Native USDC: Circle's official USDC, no bridging risk

For developers

• Four verified, open-source contracts they can fork and reuse under MIT licence
• Production wagmi v2 + viem code patterns for every payment flow
• Security best-practices baked in: exact approvals (never uint256.max), Blockaid-aware UX, bounded subscription allowances

For the Base ecosystem

• Demonstrates that Base is viable for real-world commercial payment rails — subscriptions, escrow, and payroll — not just DeFi speculation
• Increases USDC utility and velocity on Base
• Provides reference implementations that lower the barrier for the next wave of payment dApps

---

Contracts (all source-verified)

Contract	Address
BasePayRouter	0x2d7ba7ed34f8fa16fe4d0d11b51306dc753812c8
BatchPay	0x82569caf7847040a03ad2c6545ade5af2bdcf47c
Escrow	0x5b3241a47acfda41f15dfd7260339e2a88d52318
SubscriptionManager	0x546093b0476b4b7909cd84f3a0fef813c421d14a

---

Changes

• Added docs/apps/guides/usdc-payments-with-basepay.mdx — a Mintlify-compatible guide covering all four payment patterns with Solidity interfaces, wagmi v2 code samples, and security notes

The guide follows the existing format used in docs/apps/guides/ and is ready to slot into the nav config under apps > guides.

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/2	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[osr21]

Update — June 2026: Swap feature added + production bugs documented

Since opening this PR, BasePay has added a gasless USDC ↔ EURC swap via Aerodrome Finance. Full technical documentation (including three production bugs discovered and fixed during development): docs/GASLESS_SWAP.md

Key findings that may be valuable for a Base troubleshooting guide:

• eth_estimateGas false-reverts with two-step relay flows — simulation runs against pending state, so a second transaction that depends on a first transaction's confirmed state will always fail at estimation. Bypass with an explicit gas override.
• Production server clock can lag Base's block.timestamp — a 5-minute deadline is too tight for production environments with any server clock drift. 2 hours works reliably.
• Aerodrome is the only active EURC/USDC venue on Base Mainnet — Uniswap V3 has zero liquidity for this pair; worth noting for developers building multi-dex routing.