Deploy Your Own BetSwirl Affiliate Mini-App in 30 Minutes

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)

Step 1: Fork First, Ask Questions Later

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.

Step 2: Environment Configuration - Your App's Identity

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

Step 3: The Manifest Sanity Check

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.

Step 4: Deploy to Vercel (The Point of No Return)

Install Vercel CLI

npm i -g vercel

Create Your Vercel Account

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

The Big Deploy

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.

Step 5: Environment Variables - The Tedious But Necessary Part

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

Option A: Via Dashboard (Recommended for sanity)

Go to your Vercel dashboard: https://vercel.com
Click your project
Navigate to Settings → Environment Variables
Add all variables from your .env file
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

Step 6: Claim Your Pretty URL

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.

Step 7: The Moment of Truth - Farcaster Integration

Verify Your Manifest is Public

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.

Test in the Official Validator

Visit: https://farcaster.xyz/~/developers/mini-apps/manifest
Enter your domain: your-app-name.vercel.app (no https://, it's not invited)
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.

Go Live in a Cast

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.

Step 8: Account Association (Make It Official)

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.

Generate Your Association Keys

Click "Generate account association" on the validator page
Scan the QR code with Warpcast on your phone
Sign the message in Warpcast (you're basically autographing your app)

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

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

Add to Vercel Environment

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

Final Deployment

vercel --prod --force

Verify Association

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.

Troubleshooting Common Hiccups

"My manifest returns HTML instead of JSON"

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

"The dice game won't load"

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.

"Vercel keeps asking for authentication"

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)

"My app won't embed in casts"

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.

Victory Lap - What You've Built

You now have:

A live Farcaster mini-app
Integrated BetSwirl games
Shareable in any cast
Account association (if you did Step 8)
Bragging rights

Next Steps

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.

Resources

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

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)

Step 1: Fork First, Ask Questions Later

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

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.

Step 2: Environment Configuration - Your App's Identity

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

Step 3: The Manifest Sanity Check

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.

Step 4: Deploy to Vercel (The Point of No Return)

Install Vercel CLI

npm i -g vercel

Create Your Vercel Account

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

The Big Deploy

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.

Step 5: Environment Variables - The Tedious But Necessary Part

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

Option A: Via Dashboard (Recommended for sanity)

Go to your Vercel dashboard: https://vercel.com
Click your project
Navigate to Settings → Environment Variables
Add all variables from your .env file
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

Step 6: Claim Your Pretty URL

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.

Step 7: The Moment of Truth - Farcaster Integration

Verify Your Manifest is Public

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.

Test in the Official Validator

Visit: https://farcaster.xyz/~/developers/mini-apps/manifest
Enter your domain: your-app-name.vercel.app (no https://, it's not invited)
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.

Go Live in a Cast

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.

Step 8: Account Association (Make It Official)

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.

Generate Your Association Keys

Click "Generate account association" on the validator page
Scan the QR code with Warpcast on your phone
Sign the message in Warpcast (you're basically autographing your app)

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

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

Add to Vercel Environment

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

Final Deployment

vercel --prod --force

Verify Association

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.

Troubleshooting Common Hiccups

"My manifest returns HTML instead of JSON"

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

"The dice game won't load"

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.

"Vercel keeps asking for authentication"

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)

"My app won't embed in casts"

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.

Victory Lap - What You've Built

You now have:

A live Farcaster mini-app
Integrated BetSwirl games
Shareable in any cast
Account association (if you did Step 8)
Bragging rights

Next Steps

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.

Resources

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

Step 1: Fork First, Ask Questions Later

Step 2: Environment Configuration - Your App's Identity

Step 3: The Manifest Sanity Check

Step 4: Deploy to Vercel (The Point of No Return)

Install Vercel CLI

Create Your Vercel Account

The Big Deploy

Step 5: Environment Variables - The Tedious But Necessary Part

Step 6: Claim Your Pretty URL

Step 7: The Moment of Truth - Farcaster Integration

Verify Your Manifest is Public

Test in the Official Validator

Go Live in a Cast

Step 8: Account Association (Make It Official)

Generate Your Association Keys

Add to Vercel Environment

Final Deployment

Verify Association

Troubleshooting Common Hiccups

"My manifest returns HTML instead of JSON"

"The dice game won't load"

"Vercel keeps asking for authentication"

"My app won't embed in casts"

Victory Lap - What You've Built

Next Steps

Resources

No comments yet

ChainHacker

Deploy Your Own BetSwirl Affiliate Mini-App in 30 Minutes

A step-by-step guide to launching BetSwirl games as a Farcaster mini-app in 30 minutes.

Step 1: Fork First, Ask Questions Later

Step 2: Environment Configuration - Your App's Identity

Step 3: The Manifest Sanity Check

Step 4: Deploy to Vercel (The Point of No Return)

Install Vercel CLI

Create Your Vercel Account

The Big Deploy

Step 5: Environment Variables - The Tedious But Necessary Part

Step 6: Claim Your Pretty URL

Step 7: The Moment of Truth - Farcaster Integration

Verify Your Manifest is Public

Test in the Official Validator

Go Live in a Cast

Step 8: Account Association (Make It Official)

Generate Your Association Keys

Add to Vercel Environment

Final Deployment

Verify Association

Troubleshooting Common Hiccups

"My manifest returns HTML instead of JSON"

"The dice game won't load"

"Vercel keeps asking for authentication"

"My app won't embed in casts"

Victory Lap - What You've Built

Next Steps

Resources

No comments yet