> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celo.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started Building on MiniPay

A step-by-step guide to setting up, building, and testing your MiniPay Mini App.

***

## 1. Installing MiniPay

MiniPay is designed for mainstream adoption, making digital payments simple and easy to use.

#### Key Features:

* **Currency Display**: Balances appear in your local currency.
* **Stablecoin Support**: Only stablecoins (USDm, USDC, and USDT) are supported.
* **Simple Swaps**: The pocket swap feature allows for easy swaps between stablecoins by dragging one pocket into another.

<Note>
  MiniPay is only available on Celo and Celo Sepolia Testnet. Other blockchain
  networks are not supported.
</Note>

#### How to Access MiniPay:

* [**Opera Mini Browser**](https://www.opera.com/pl/products/minipay) (Android)
* [**Standalone App Android**](https://play.google.com/store/apps/details?id=com.opera.minipay)
* [**Standalone App iOS**](https://apps.apple.com/de/app/minipay-easy-global-wallet/id6504087257?l=en-GB)

#### Set Up MiniPay:

* **Install the MiniPay Standalone App:** Download for [Android](https://play.google.com/store/apps/details?id=com.opera.minipay) and [iOS](https://apps.apple.com/de/app/minipay-easy-global-wallet/id6504087257?l=en-GB)
* **Create an Account:** Sign up using your Google account and phone number.

## 2. Build Your MiniPay Mini App

#### For creating a new app:

* Use the [Celo Composer MiniPay Template](https://github.com/celo-org/minipay-template) to start building.

```bash theme={null}
npx @celo/celo-composer@latest create -t minipay
```

* Follow the [Quickstart Guide](/build-on-celo/quickstart) for a step-by-step tutorial.

#### For integrating an existing app:

* Follow the [Helpful Tips Guide](#helpful-tips-to-make-your-mini-app-minipay-compatible) to ensure your app is MiniPay compatible.

## 3. Get Testnet Tokens

Request CELO testnet tokens from the Celo [faucet](https://faucet.celo.org/celo-sepolia/) to test your Mini App. After you got the CELO tokens, you can exchange them for stablecoins like USDm, USDT and USDC in the [mento app](https://app.mento.org/).

## 4. Test your Mini App inside MiniPay

<Warning>
  You cannot test MiniPay using the Android Studio Emulator. Use an Android or
  iOS mobile device.
</Warning>

### Enable Developer Mode:

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

<Frame>
  <img src={"/img/doc-images/minipay/build-on-minipay/choose-settings.jpg"} style={{ width: 250 }} alt="Open MiniPay dApp store" />
</Frame>

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

<Frame>
  <img src={"/img/doc-images/minipay/build-on-minipay/activate-developer-mode.jpg"} style={{ width: 250 }} alt="Open MiniPay dApp test page" />
</Frame>

3. Return to **Settings**, then select **Developer Settings**.

<Frame>
  <img
    src={
  "/img/doc-images/minipay/build-on-minipay/choose-developer-settings.jpg"
}
    style={{ width: 250 }}
    alt="MiniPay dApp testing"
  />
</Frame>

4. Enable **Developer Mode** and toggle **Use Testnet** to connect to Sepolia L2 testnet.

<Frame>
  <img src={"/img/doc-images/minipay/build-on-minipay/choose-testnet.jpg"} style={{ width: 250 }} alt="MiniPay dApp testing" />
</Frame>

### Load Your Mini App:

1. In **Developer Settings,** tap **Load Test Page.**
2. Enter your **Mini App URL.**
   * If testing a local deployment, use [ngrok](#testing-local-development-with-minipay) to expose your localhost.

<Frame>
  <img src={"/img/doc-images/minipay/build-on-minipay/enter-url.jpg"} style={{ width: 250 }} alt="MiniPay dApp testing" />
</Frame>

6. Click **Go** to launch and test your Mini App.

<Frame>
  <img src={"/img/doc-images/minipay/build-on-minipay/site-tester-opening.jpg"} style={{ width: 250 }} alt="MiniPay dApp testing" />
</Frame>

***

## Helpful Tips to Make Your Mini App MiniPay Compatible

<Warning>
  MiniPay uses Custom [Fee Abstraction](/build-on-celo/fee-abstraction/overview) based
  transactions. We recommend using viem or wagmi as they provide native support
  for fee currency.
</Warning>

#### 1. Using Viem

```js theme={null}
import { createWalletClient, custom } from "viem";
import { celo, celoSepolia } from "viem/chains";

const client = createWalletClient({
  chain: celo,
  // chain: celoSepolia, // For Celo Sepolia Testnet
  transport: custom(window.ethereum),
});

const [address] = await client.getAddresses();
```

#### 2. Using Wagmi

<Note>
  These snippets use **wagmi v2** (the current major version). In v2, connectors
  are functions (e.g. `injected()`) rather than the classes used in v1
  (`new InjectedConnector()`), `WagmiConfig` is now `WagmiProvider`, and the
  config is built with `createConfig`.
</Note>

First, create your wagmi config and wrap your app in `WagmiProvider` (wagmi v2 also requires a TanStack Query provider):

```tsx theme={null}
// providers.tsx
"use client";

import { WagmiProvider, createConfig, http } from "wagmi";
import { celo } from "wagmi/chains";
import { injected } from "wagmi/connectors";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

export const config = createConfig({
  chains: [celo],
  connectors: [injected({ target: "metaMask" })],
  transports: {
    [celo.id]: http(),
  },
});

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </WagmiProvider>
  );
}
```

Then auto-connect on load using the connector from your config:

```tsx theme={null}
import { useEffect } from "react";
import { useConnect } from "wagmi";

const { connect, connectors } = useConnect();

useEffect(() => {
  // `connectors[0]` is the `injected()` connector registered in `createConfig`
  connect({ connector: connectors[0] });
}, [connect, connectors]);
```

This sets up the `injected` connector in `createConfig` and then uses the `connect` method from the `useConnect` hook. The `useEffect` ensures that the connection is established when the page loads.

In the Viem example, we're creating a wallet client that specifies the chain and a custom transport using `window.ethereum`. The `getAddresses` method then retrieves the connected addresses.

### Important Notes

Ensure the "Connect Wallet" button is hidden when your DApp is loaded inside the MiniPay app, as the wallet connection is implicit.

*Code Example to hide Connect Wallet button if the user is using MiniPay wallet*

```tsx theme={null}
import { useEffect, useState } from "react";
import { useConnect } from "wagmi";
import { injected } from "wagmi/connectors";

export default function Header() {
  // State variable that determines whether to hide the button or not.
  const [hideConnectBtn, setHideConnectBtn] = useState(false);
  const { connect } = useConnect();

  useEffect(() => {
    if (window.ethereum && window.ethereum.isMiniPay) {
      // User is using MiniPay so hide connect wallet button.
      setHideConnectBtn(true);

      connect({ connector: injected({ target: "metaMask" }) });
    }
  }, [connect]);

  return (
    <div className="absolute inset-y-0 right-0 flex items-center pr-2 sm:static sm:inset-auto sm:ml-6 sm:pr-0">
      {/* Conditional rendering of Connect Wallet button */}
      {!hideConnectBtn && (
        <ConnectButton
          showBalance={{
            smallScreen: true,
            largeScreen: false,
          }}
        />
      )}
    </div>
  );
}
```

* Always verify the existence of `window.provider` before initializing your web3 library to ensure seamless compatibility with the MiniPay wallet.
* When using `ngrok`, remember that the tunneling URL is temporary. You'll get a new URL every time you restart ngrok.
* Be cautious about exposing sensitive information or functionality when using public tunneling services like ngrok. Always use them in a controlled environment.
* MiniPay currently supports setting the `feeCurrency` property when running `eth_sendTransaction`. However, currency support is limited to `USDm`. More currencies might be supported in future.
* MiniPay only accepts legacy transactions at the moment. EIP-1559 properties won't be considered when handling requests.

## Testing Local Development with MiniPay

If you're developing your MiniApp locally (e.g., on `localhost:3000`), use `ngrok` to tunnel traffic over HTTP, for real-time testing.

#### Set Up ngrok

* **Install ngrok:** If you haven't already, install ngrok. You can find instructions on their [official website](https://ngrok.com/download).
* **Start Your Local Server:** Ensure your local development server is running. For instance, if you're using Next.js, you might run `npm run dev` to start your server at `localhost:3000`.
* **Tunnel Traffic with ngrok:** In your terminal, run the following command to start an ngrok tunnel:

```bash theme={null}
ngrok http 3000
```

This will provide you with a public URL that tunnels to your localhost.

For a more in depth guide, check out the official [ngrok setup](/build-on-celo/build-on-minipay/prerequisites/ngrok-setup).

* **Test in MiniPay:** Copy the provided ngrok URL and use it inside the MiniPay app to test your DApp.