You're here because you want BetSwirl casino games in your Farcaster mini-app. Maybe you've seen them elsewhere, maybe you just like the idea of on-chain dice rolling. Either way, this guide documents the exact path from zero to deployed mini-app, with all the stumbles and fixes included.

What you're building: A fully functional Farcaster mini-app with integrated BetSwirl casino games (starting with dice, expandable to more).

Time required: 30 minutes if everything goes smoothly, 45 if you hit the same TypeScript snags I did.

Prerequisites:

• Node.js 18+ (node --version should return v18.0.0 or higher)

• A Farcaster account (you'll need this for testing)

• Basic familiarity with terminal commands

• Patience for one or two build errors (we'll fix them together)

The fastest path is forking the BetSwirl demo. Yes, you could start from scratch with npx create-onchain --mini, but why make life harder?

git clone https://github.com/BetSwirl/miniapp-ui-react-demo.git my-app
cd my-app
npm install

What just happened: You've cloned a pre-configured Farcaster mini-app with BetSwirl components already integrated. The heavy lifting of provider setup, chain configuration, and component integration is done.

Verify it works:

npm run dev

Your terminal should light up with something like:

Navigate to http://localhost:3000. You should see a dice game. If yes, you're already 40% done. If no, check that port 3000 isn't already occupied.

Note: Ignore the @farcaster/frame-sdk is deprecated warning - it's from a dependency, not your code.

Time to give your app some personality. Create a .env file with these contents:

NEXT_PUBLIC_URL=https://your-app-name.vercel.app
NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME='Your App Name'
NEXT_PUBLIC_APP_ICON=$NEXT_PUBLIC_URL/icon.png
NEXT_PUBLIC_APP_HERO_IMAGE=$NEXT_PUBLIC_URL/hero.png
NEXT_PUBLIC_APP_DESCRIPTION='Your tagline here'
NEXT_PUBLIC_APP_SUBTITLE='BetSwirl Games'
NEXT_PUBLIC_APP_SPLASH_IMAGE=$NEXT_PUBLIC_URL/splash.png
NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR=#8B5CF6
NEXT_PUBLIC_APP_PRIMARY_CATEGORY=games
NEXT_PUBLIC_APP_TAGLINE='Roll the dice, spin the wheel!'

Pro tip: Pick your URL now, even before deployment. You'll claim it on Vercel later. Keep it short and memorable - my-lucky-dice or mini-vegas work great.

Restart your dev server to load the new environment:

npm run dev

Before we ship this to production, let's make sure Farcaster will know what to do with it.

curl http://localhost:3000/.well-known/farcaster.json | jq

You should see JSON with your app configuration. The accountAssociation fields will be empty - that's normal, we're not VIP yet.

{
  "accountAssociation": {
    "header": "",
    "payload": "",
    "signature": ""
  },
  "frame": {
    "version": "1",
    "name": "My Little Casino",
    "subtitle": "BetSwirl Games",
    "description": "Knock yourself out!",
    "iconUrl": "https://my-little-casino.vercel.app/icon.png",
    "splashImageUrl": "https://my-little-casino.vercel.app/splash.png",
    "homeUrl": "https://my-little-casino.vercel.app",
    "webhookUrl": "https://my-little-casino.vercel.app/api/webhook",
    "primaryCategory": "games",
    "heroImageUrl": "https://my-little-casino.vercel.app/hero.png",
    "tagline": "Roll the dice, spin the wheel!"
  }
}

What you're looking for:

• Your app name appears correctly

• Description and tagline are there

• primaryCategory is set to "games"

• URLs point to your chosen domain

If it looks good, we're ready to go live.

npm i -g vercel

Enter your email, click the verification link. Welcome to the deployment club.

vercel --prod

The interrogation begins:

• Set up and deploy? → Y (we're committed now)

• Which scope? → Select your username (it's probably your email)

• Link to existing project? → N (this is fresh)

• Project name? → your-app-name (or press Enter for auto-naming)

• Directory? → Press Enter (current directory)

• Override settings? → N (trust the defaults)

Deployment takes about 2 minutes. Perfect time for a coffee refill.

You'll get a URL that looks like:

Production: https://your-app-name-gclocssni-ets-projects.vercel.app

Don't worry, we'll make it prettier.

Your app is live but it doesn't know who it is. Time to fix that.

Option A: Via Dashboard (Recommended for sanity)

1. Go to your Vercel dashboard: https://vercel.com

2. Click your project

3. Navigate to Settings → Environment Variables

4. Add all variables from your .env file

5. Click "Save"

   

Option B: Via CLI (For terminal purists)

vercel env add NEXT_PUBLIC_URL production
# Enter: https://your-app-name.vercel.app
vercel env add NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME production
# Enter: Your App Name
# ... repeat for each variable (yes, all of them)

Redeploy with Identity Crisis Resolved

vercel --prod --force

That auto-generated URL is embarrassing. Let's fix it:

vercel alias set [that-long-ugly-url] your-app-name.vercel.app

Example:

vercel alias set https://your-app-name-gclocssni.vercel.app your-app-name.vercel.app

Now you have https://your-app-name.vercel.app - much better for sharing at parties.

curl https://your-app-name.vercel.app/.well-known/farcaster.json | jq

If this returns JSON, you're golden. If it returns HTML, your environment variables didn't stick - go back to Step 5.

1. Visit: https://farcaster.xyz/~/developers/mini-apps/manifest

2. Enter your domain: your-app-name.vercel.app (no https://, it's not invited)

3. Click "Refresh" or press Enter

You'll see two things:

• Mini App Configuration: Should show " Mini App configuration is valid"

• Account Association: Will show " No valid account association" (that's fine for now)

Below the validation, you'll see a preview of your mini-app with an "Open" button. Click it to test your games.

Note: The "Generate account association" button is for Step 8. Your app works without it - association just lets users save it to their mini-apps list.

Open Warpcast and create a new cast:

Check out my new mini-app: https://your-app-name.vercel.app

https://farcaster.xyz/chainhacker/0x25932720

The URL automatically embeds as a playable mini-app. Your followers can roll dice directly from their feed. You've made it.

When you test your manifest in Step 7, you'll likely see "No valid account association" and a "Generate account association" button. Let's fix that.

1. Click "Generate account association" on the validator page

2. Scan the QR code with Warpcast on your phone

3. Sign the message in Warpcast (you're basically autographing your app)

4. Return to the validator page - you'll see something like this:

   {
     "accountAssociation": {
       "header": "eyJmaWQiOjY3OTYzNSwidHlwZS...",
       "payload": "eyJkb21haW4iOiJteS1saXR0bGU...",
       "signature": "4dSikmqgOc6bOjgdPjsirfRPvVBJWs..."
     }
   }

Add these three values to your Vercel environment:

vercel env add FARCASTER_HEADER production
# Paste the header value (the long eyJ... string)
vercel env add FARCASTER_PAYLOAD production
# Paste the payload value
vercel env add FARCASTER_SIGNATURE production
# Paste the signature value

vercel --prod --force

Return to the manifest validator and click "Refresh". You should see:

• "Associated with your account"

• A "Transfer ownership" button appears

Your app is now officially associated with your Farcaster account.

What this unlocks: Users can now save your mini-app to their personal collection and launch it anytime from their mini-apps list.

Your environment variables aren't deployed. Go back to Step 5, add them in Vercel dashboard, and redeploy with --force.

Open browser console (F12). If you see provider errors, the BetSwirl SDK might not be initializing. Check that app/providers.tsx exists and matches the demo repo.

If you hit a Vercel auth page when accessing your manifest, your deployment protection is on. Either:

• Make the deployment public in Vercel settings

• Or add the bypass token to your URL (check Vercel docs)

Make sure your manifest is accessible publicly. Test with:

curl -I https://your-app-name.vercel.app/.well-known/farcaster.json

Should return HTTP/2 200, not 404 or 30x.

You now have:

• A live Farcaster mini-app

• Integrated BetSwirl games

• Shareable in any cast

• Account association (if you did Step 8)

• Bragging rights

Customize the games: Modify bet limits in the game components, add more games from the BetSwirl SDK.

Make it yours: Update app/theme.css with your brand colors, swap out the placeholder images in /public.

Go multi-game: Import additional components from @betswirl/ui-react:

import { DiceGame, RouletteGame, CoinFlipGame } from "@betswirl/ui-react"

Track everything: Add analytics to see how users interact with your games.

Get paid: Contact BetSwirl about their affiliate program for revenue sharing.

• BetSwirl SDK Documentation

• Farcaster Mini Apps Docs

• The Demo You Just Forked

• Vercel Deployment Docs

Built with BetSwirl SDK and a surprising amount of environment variables.