# 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.
*

By [ChainHacker](https://paragraph.com/@chainhacker) · 2025-10-19

betswirl, sdk, devtools, farcaster, mini-app, web3

---

  

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:

![](https://storage.googleapis.com/papyrus_images/bea9a404a725e992b21b17c8ebe66daf35fc7d52ef9844fae02389d1d6300a14.png)

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.

![](https://storage.googleapis.com/papyrus_images/c0e5b1c17ab4b8cff927c87816fd35cde84873708da9d4511f5f8595d67b2fc1.png)

* * *

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

![](https://storage.googleapis.com/papyrus_images/bc1661646de18bc923ffb7b96dcd32f7a1e1678d249e7bd21a0f0d10d413a461.png)

* * *

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](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)**

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"
    
    ![](https://storage.googleapis.com/papyrus_images/b5c0684db80fef3f09e610ed55493e7db961338b5ce57b2a87a8baa2c162d02b.png)
    

**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

![](https://storage.googleapis.com/papyrus_images/158deaf9ca12b745c93cc0e661d2b3d467444c35ee6977d0a34d78bacb970499.png)

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

1.  Visit: [https://farcaster.xyz/~/developers/mini-apps/manifest](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.

### 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://your-app-name.vercel.app)

[https://farcaster.xyz/chainhacker/0x25932720](https://farcaster.xyz/chainhacker/0x25932720)

![](https://storage.googleapis.com/papyrus_images/42f184376815e9d357804f35e69794efe7765e3712af1bf45d8b9fed9c9f6928.png)

  

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

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..."
          }
        }
    

![](https://storage.googleapis.com/papyrus_images/ac78be57a6165cf0ce75b1e1ffd57913e3bc7a0715f53458af8a1a54b3d5d1b3.png)

### 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.

![](https://storage.googleapis.com/papyrus_images/ebd90bd14bc6068f6d0d07b0f1143833b4f6eb699fc5be22d80e82ba8fd8453a.png)

**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
---------

*   [BetSwirl SDK Documentation](https://github.com/BetSwirl/sdk)
    
*   [Farcaster Mini Apps Docs](https://miniapps.farcaster.xyz/)
    
*   [The Demo You Just Forked](https://github.com/BetSwirl/miniapp-ui-react-demo)
    
*   [Vercel Deployment Docs](https://vercel.com/docs)
    

* * *

_Built with BetSwirl SDK and a surprising amount of environment variables._

---

*Originally published on [ChainHacker](https://paragraph.com/@chainhacker/your-own-mini-app-in-30-minutes)*