Skip to main content
Breaking Changes in MiniKit v2:
  • SignatureTransfer is no longer supported. Please use Allowance Transfers documented below.
  • Standard ERC-20 approve() calls now work in mini apps. Approval will be automatically revoked after the transaction.
Allowance transfers are the recommended method for moving tokens in mini apps. World App automatically approves tokens to Permit2, so you can bundle the Permit2 approval and your contract call in a single sendTransaction for a better UX. Expiration should always be set to 0 as the approval will be consumed in the same transaction. Standard ERC-20 approve() also works if you prefer.
World App automatically approves new ERC-20 tokens to the Permit2 contract. Your contract only needs to call permit2.transferFrom — the token-level approval is already in place.

Result

If you are integrating through Wagmi, viem, or ethers with the World App EIP-1193 provider, the standard eth_sendTransaction call resolves to the MiniKit userOpHash, not a canonical transaction hash. Do not treat the returned value as a final transaction hash or pass it directly to waitForTransactionReceipt. If you need the final on-chain transaction hash, resolve the user operation status first.

Confirming the User Operation

The command resolves as soon as the user operation is submitted, so the first identifier you receive is userOpHash. You can either use the @worldcoin/minikit-react hook or poll the Developer Portal to check when the user operation is mined and get the final transaction_hash.
See GET /api/v2/minikit/userop/ for the full endpoint response shape.

Error Codes

Fallback Behavior

By default we intend for mini apps to be useable outside of World App. Fallbacks generally will not be needed for this command and you should instead follow the migration path outlined.

Allowlisting Contracts and Tokens

Before your mini app can send transactions, you must allowlist the contracts and tokens it interacts with. Navigate to Developer Portal > Mini App > Permissions and add:
  • Permit2 Tokens — every ERC-20 token your app transfers via Permit2
  • Contract Entrypoints — every contract your app calls directly
Developer Portal showing Permit2 token and contract entrypoint whitelisting

Developer Portal Whitelist

Transactions that touch non-whitelisted contracts or tokens will be blocked by the backend with an invalid_contract error.

Preview