Mini Apps

Appearance

Test your Mini App inside MiniPay ​

In this guide, you will learn how to test your Mini App inside MiniPay. Follow the steps below to get started.

Installing MiniPay ​

  1. Install MiniPay on your device.

  2. Create an account: Sign up using your Google or Apple account and phone number.

Test inside MiniPay ​

Enable Developer Mode: ​

  1. Open the MiniPay app on your phone and navigate to settings.

  2. In the About section, tap the Version number repeatedly until the confirmation message appears.

  3. Return to Settings, then select Developer Settings.

  4. Enable Developer Mode and toggle Use Testnet to connect to Celo Sepolia testnet (Chain ID 11142220). For production testing, leave testnet off to use Celo Mainnet.

Load Your Mini App: ​

  1. In Developer Settings, tap "Load test page".

  2. Enter your Mini App URL.

    TIP

    For local development, use ngrok to expose your localhost. See How do I run ngrok? below. Add allowedHosts in Vite so the dev server accepts the ngrok host.

  3. Click Load to launch and test your Mini App.

Local testing ​

  1. Start your dev server (e.g. npm run dev or pnpm dev). Note the port (e.g. 5173).
  2. Expose it with ngrok (see below): ngrok http 5173.
  3. Copy the HTTPS Forwarding URL from ngrok and paste it into MiniPay's "Load test page" field.
  4. Ensure your Vite config has allowedHosts for ngrok so the dev server accepts requests (see "Blocked request" below).

Sandbox vs production ​

  • Testnet (Celo Sepolia): Use Developer Mode's "Use Testnet" to test with fake funds and avoid mainnet fees.
  • Mainnet (Celo): Turn testnet off to test with real Celo and stablecoins. Use small amounts.

Debugging inside MiniPay ​

  • Console: If your Mini App opens in a WebView that supports remote debugging, use your IDE or browser devtools to attach and view console.log / errors.
  • Common errors: "window.ethereum is required" means the app is not running inside MiniPay—load it via "Load test page". "Blocked request" usually means Vite needs allowedHosts for your ngrok domain.

Troubleshooting ​

Q: How do I run ngrok? ​

A: Ngrok is a command line interface (CLI) that runs on your local machine. It lets you expose your local server to the rest of the internet. So, once it's running, everyone can access your local environment.

  1. First, you need to install and configure ngrok. Follow ngrok's quickstart guide to learn how.

  2. When you're ready, start ngrok by running:

    bash
    ngrok http [port] #replace [port] with the port used by your localhost

  3. Use the Forwarding URL you see in your terminal to access your local Mini App inside MiniPay.

    ngrok                                                     (Ctrl+C to quit)

Session Status                online
Account                       inconshreveable (Plan: Free)
Version                       3.0.0
Region                        United States (us)
Latency                       78ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://84c5df474.ngrok-free.dev -> http://localhost:8080

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Q: Seeing a Blocked request error? ​

A: If you're using Vite, make sure to allow the host you're using. Here's an example of the changes to make to vite.config.ts when using ngrok.

tsx
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react()],
  server: {
    allowedHosts: [".ngrok.app", ".ngrok-free.dev", ".ngrok-free.app"], 
  },
});