Prerequisites
- A web app (any framework) reachable over HTTPS; for local development use
ngrok http 3000to exposelocalhost - viem or wagmi — both support Celo’s fee-currency transactions natively
- Testnet funds: CELO from the Celo Sepolia faucet, swapped to a stablecoin in the Mento app
- To scaffold:
npx @celo/celo-composer@latest create -t minipay(the MiniPay template), or follow the MiniPay quick start
What is Celo-specific
Stablecoins are the only assets
MiniPay holds USDm, USDC and USDT — no CELO balance is shown to the user. Price and settle in one of these.Gas is paid in the user’s stablecoin
MiniPay uses fee abstraction: the user never holds CELO, and the wallet pays gas in the stablecoin the user holds the most of. You may setfeeCurrency on eth_sendTransaction, but MiniPay can override it. Do not build flows that assume a CELO balance, and do not show a “buy CELO for gas” step.
To show a fee estimate in the user’s currency, estimate gas and gas price in that token. The JSON-RPC methods accept the fee currency directly:
Detect MiniPay and skip the connect button
Inside MiniPay the wallet is already connected through the injected provider, andwindow.ethereum.isMiniPay is true. Hide your connect-wallet UI and connect the injected connector on load:
window.ethereum before initialising any web3 library; the provider is injected by the host. Wallet-connection details and error handling: Wallet connection.
Resolve MiniPay phone numbers to addresses
MiniPay maps phone numbers to addresses through SocialConnect and ODIS. To look a number up you act as an issuer: an account that has verified the user owns the number (for example by SMS), has a data encryption key (DEK) registered on the Accounts contract, and holds ODIS quota.FederatedAttestations, OdisPayments) and listed on Core contracts. The MiniPay reference for this is Phone number lookup.
Deeplinks
Deeplinks open a MiniPay screen from your Mini App or from outside (WhatsApp, a web page). The host islink.minipay.xyz; users without the app get an install prompt.
Reference: Deeplinks.
Test inside MiniPay
You cannot test in an Android emulator; use a phone.- In the MiniPay app open Settings → About and tap the Version number until developer mode is confirmed.
- Back in Settings → Developer Settings, enable Developer Mode and, for Celo Sepolia, Use Testnet.
- Tap Load Test Page, enter your app’s HTTPS URL (the
ngrokURL for local development), and tap Go.
The MiniPay developer docs
Everything below lives at docs.minipay.xyz and is maintained by the MiniPay team. Getting started- What are Mini Apps?
- Quick start — scaffold a Mini App with the Celo agent skills
- Test your Mini App inside MiniPay
- Project setup and Setting up a React app
- FAQ
- Wallet connection — injected provider, auto-connect, connection state, errors
- UI and container integration
- Interacting with smart contracts
- Best practices
- Deployment
- Submit your Mini App to the discovery page
- Building for MiniPay and Availability
- Design standards — including user-facing terminology
- Examples
- Retrieve balance
- Send a transaction — USDC, USDT, USDm with wagmi
- Gas estimation
- Transaction status
- Phone number lookup
- Chain switching
- Deeplinks
- Custom methods: overview, getExchangeRate, scanQrCode, requestContact
Funding and programs
- Building in public? Register for Build With Celo programs at celopg.eco.
- Raising? Send a deck or product demo to team@verda.ventures.
- Grants and accelerators: Fund your project.
Related
- Fee abstraction - How gas in stablecoins works and the adapter addresses for USDC and USDT
- Fee currency contracts - Token and adapter addresses per network
- Build with local stablecoins - Mento stablecoins beyond USDm
- SocialConnect - Phone-number to address mapping
- Celo Composer - Scaffold a MiniPay-ready app