FAQ

Who covers gas fees for transactions?

World App sponsors gas fees for most transactions on Worldchain, subject to transaction minimums and restrictions. When someone verifies their identity with World ID and uses the World App, their transactions on Worldchain are automatically covered by the network. This means users don’t need to hold or spend ETH to interact with mini apps, send tokens, or perform on-chain actions. The sponsorship is handled behind the scenes with a paymaster contract that pays the gas fees whenever a verified user initiates a transaction.

Do I need approval to launch a Mini App?

Yes. After development, submit your Mini App for review through the Developer Portal. Approval is required before it’s publicly listed.

How does Send transaction command work?

The Send Transaction command is designed to execute on-chain transactions from the Mini App. When developers invoke this command, they supply a chainId and one or more transactions containing the target contract address, optional encoded function call (data), and optional value. For security, World App requires that any smart contract or token interactions are pre-approved (whitelisted) in the Developer Portal to prevent unauthorized transfers. In cases where ERC-20 tokens are involved, instead of directly calling the approve function (which could expose the contract to front-running or manipulation), permits like Permit2 are used. Permit2 enables users to sign a transaction off-chain that allows a specific allowance without sending an approval transaction, reducing friction and gas costs while providing a secure, non-custodial mechanism for token transfers.

How does Sign Message command work?

The Sign Message command prompts the user to cryptographically sign an arbitrary message using their wallet’s private key. When you call the command (for example, await MiniKit.signMessage({ message: "Hello" })), World App generates a standardized payload that may include a nonce, timestamp, and other context to prevent replay attacks. The user’s wallet then signs this message using ECDSA, producing a signature that proves the user controls the wallet, all without exposing the private key. This signed message can be sent back to your backend for verification, ensuring the integrity of user actions and serving as secure off-chain authorization for various operations.

Can I use the simulator to test transactions on mini apps?

No, mini app needs to be developed on mainnet (we don’t support testnet). Gas is covered in the World App, so there’s only deployment costs for you to develop on mainnet. Deploy “test” contracts to mainnet, and then redeploy “prod” mainnet contracts.

How do I debug send transaction failed simulation?

Use the Get Transaction Debug URL endpoint to get the debug URL for the transaction.

How do I check how commands work and it’s implementation?

Check the Prod QA App to check commands and the minikit-js repository.

How do I test my mini app on mobile?

Remember that minikit ONLY works inside World App, so in order to test your mini app commands you must open it in World App

To test your Mini App directly on your phone, expose your app publicly using ngrok or any other tunneling service. After the URL is generated, go to the Developer Portal to configure it.

Example:

ngrok http http://localhost:3000

Why does my command fail when triggered immediately on page load?

This happens due to a race condition where MiniKit hasn’t finished installing when you try to call a command. Since MiniKit uses a client-side component to install the provider onto the Window object, triggering a command in a separate useEffect hook right after page load can fail.

Solution: Include any commands you want to trigger on initialization inside the same useEffect hook where you install MiniKit:

"use client";

import { useEffect, ReactNode } from "react";
import { MiniKit } from "@worldcoin/minikit-js";

export const MiniKitProvider = ({ children }: { children: ReactNode }) => {
  useEffect(() => {
    const { success } = MiniKit.install();

    if (!success) return;

    // Add any commands you wish to trigger on start here to prevent race conditions
    void MiniKit.getPermissions();
  }, []);

  return <>{children}</>;
};

What security considerations should I keep in mind when building Mini Apps?

MiniKit is purely a communication channel between the client and the app. Your application should never trust any payloads it receives on the client side by default.

World ID verification via IDKit, Pay, and Wallet Auth operations should be verified on your backend. Never rely solely on client-side validation for sensitive operations, as client-side data can be manipulated. Always implement server-side verification to ensure the integrity and authenticity of user actions.