Test your Mini App inside CrackPay

A Mini App has no wallet in an ordinary browser tab. Test it inside CrackPay with Developer mode, which loads any URL as an unreviewed test app.

Get CrackPay

CrackPay is a web app; there is nothing to install.

1. Open www.crackpay.xyz on your phone or computer.
2. Tap Get started, pick a handle and save the passkey your device offers.
3. Add a few dollars of USDC: tap Add money, or have another CrackPay user pay your handle. CrackPay runs on Arc mainnet, so this is real USDC. A dollar or two covers plenty of testing.

Enable Developer mode

1. Open Settings.
2. Scroll to About and tap the Version row seven times. From the third tap it counts down.
3. A Developer settings card appears. Open it.
4. Switch on Developer mode.

Use test net shows which network this CrackPay runs on and is locked. www.crackpay.xyz runs on Arc mainnet (chain 5042), so test payments move real USDC: keep amounts small. Your app should read the chain from the provider and work on both networks; see Arc network.

Load your Mini App

1. In Developer settings, tap Open URL…
2. Enter your Mini App's URL and tap Load.

Your app opens inside CrackPay under a red Test app · not reviewed bar, connected to your account. The last five URLs you loaded are listed under Open URL… for one tap reloading.

Which URLs work

CrackPay is a secure page, and browsers will not show an http:// page inside it. Your app must be reachable at a public HTTPS address.

Where your app is	What to load
Deployed on Vercel, Netlify or similar	The deployment URL. Preview deployments work if they are public.
Your own domain	https://app.example.com
A local dev server, through a tunnel	The tunnel's HTTPS URL. The easiest way to test on a phone.
A local dev server on your network	Its HTTPS network address, see below
The same computer you browse CrackPay on	http://localhost:<port> is the one exception

Local testing with a tunnel

1. Start your dev server: npm run dev (note the port, for example 5173).
2. Expose it: ngrok http 5173, or cloudflared tunnel --url http://localhost:5173.
3. Copy the HTTPS forwarding URL and load it in Developer settings.

If you use Vite, allow the tunnel's host or requests are blocked:

vite.config.ts

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

Local testing without a tunnel

Your dev server must serve HTTPS:

• Vite: add @vitejs/plugin-basic-ssl and run vite --host.
• Next.js: next dev --experimental-https -H 0.0.0.0.

On the device you test with, open the network address (for example https://192.168.1.20:5173) once in a normal tab and accept the certificate warning, then load it in CrackPay. Both devices must be on the same network.

:::warning Preview deployments behind a login Vercel preview deployments are often protected by Vercel Authentication and sent with X-Frame-Options: DENY. CrackPay cannot show them. Turn off Deployment Protection for previews, or test a public deployment or a tunnel. :::

Test app versus listed app

	Test app	Listed app
May call	Any contract	Only the contracts in its listing
The confirmation shows	The raw contract address and a warning	Your app's name
Who can open it	Whoever turned on Developer mode and loaded the URL	Every CrackPay user

Test with the contracts you will list, and follow the rules for listed apps. A call that works only because test apps are unrestricted will fail after listing.

Debugging inside CrackPay

• Log Mini App messages. In Developer settings → Debugging, switch it on. Every request your app makes, and CrackPay's answer, is printed in the browser console of the CrackPay page.
• Wallet environment. Shows the network, chain ID, RPC, CrackPay version and Mini App protocol version.
• Your app's console. Your app is a frame in a normal browser page. Open the developer tools and pick your frame in the console's context selector. On a phone use Chrome remote debugging or Safari Web Inspector.

Troubleshooting

Symptom	Cause	Fix
A blank frame	Your server refuses to be framed	Remove X-Frame-Options; allow CrackPay in frame-ancestors. See Deployment.
"That address is not secure"	You entered an http:// URL	Use HTTPS
"Blocked request" from Vite	The tunnel host is not allowed	Add it to server.allowedHosts
Your app shows "Connect wallet" inside CrackPay	It does not use the SDK, or reads window.ethereum too early	Use @crackpay/miniapp-sdk and await the provider. See Wallet connection.
The provider is null inside CrackPay	The SDK does not trust this CrackPay host	Pass hostOrigins if you test against your own CrackPay
Error 4100	A listed app called outside its listing	See Error codes
Amounts off by 10¹²	6-decimal and 18-decimal USDC mixed up	See Arc network