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)

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

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

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.

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

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

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

Why Playwright + Synpress?

Before we jump into code, let's talk about why this combo works well. Playwright gives you a solid foundation for browser automation with great debugging tools, while Synpress adds Web3-specific features – MetaMask integration, wallet caching, and transaction handling.

Getting Started: The Setup Dance

First things first, let's get everything installed. It's surprisingly straightforward:

npm install @synthetixio/synpress

Now, here's where it gets interesting. Your basic test setup looks something like this:

import { testWithSynpress } from '@synthetixio/synpress';
import { MetaMask, metaMaskFixtures } from '@synthetixio/synpress/playwright';
import basicSetup from './wallet-setup/metamask.setup';

const test = testWithSynpress(metaMaskFixtures(basicSetup));
let metamask: MetaMask;
const { expect } = test;

This setup tells Synpress to use MetaMask in your tests with your specified configuration.

sdk/packages/ui-react/test/wallet-setup/basic.setup.ts at main · BetSwirl/sdk

SDK to interact with BetSwirl's smart-contracts. Contribute to BetSwirl/sdk development by creating an account on GitHub.

https://github.com

Writing Tests: Connect That Wallet!

Let's start with something every Web3 app needs – connecting a wallet. Here's what a basic test looks like:

test.describe('My Awesome DApp Tests', () => {
  test('should connect wallet successfully', async ({ page }) => {
    // Navigate to your app
    await page.goto('http://localhost:3000');    
    // Click that connect button
    await page.click('[data-testid="connect-wallet"]');
    
    // Synpress handles the MetaMask popup automatically

    // Check if we're connected
    await expect(page.locator('[data-testid="wallet-address"]')).toBeVisible();
  });
});

What I love about this is how clean it is. No wrestling with popup windows or iframe nightmares – Synpress handles all that for you.

The Transaction Test: Where Things Get Real

Once you've mastered wallet connection, it's time for the main event – testing transactions:

test('should send tokens successfully', async ({ page }) => {
    // Navigate to coin toss game
    await page.goto("/coinToss.html")

    // Connect wallet
    const connectButton = page.getByTestId("ockConnectButton")
    await connectButton.click()

    // Find and click play button
    const playButton = page.locator('button:has-text("Place Bet")')
	// Click play button
    await playButton.click()
	await metamask.confirmTransaction()
  
    // Verify success
      const resultModal = page.locator('[role="dialog"]').filter({ hasText: /You (won|lost)/i })
      const hasResultModal = await resultModal.isVisible({ timeout: 10000 }).catch(() => false)
});

sdk/packages/ui-react/tests/coinToss.spec.ts at main · BetSwirl/sdk

SDK to interact with BetSwirl's smart-contracts. Contribute to BetSwirl/sdk development by creating an account on GitHub.

https://github.com

Debugging: When Tests Go Wrong (And They Will)

Let's be real – tests won't work perfectly the first time. Here are essential debugging techniques:

1. The Debug Flag

DEBUG=synpress:* npm test

This gives you detailed logs about what's happening under the hood.

2. Slow Things Down

When a test fails and you need to see what's happening:

SLOW_MO=1000 npm test

This adds a 1-second delay between actions, making it easier to follow the test execution.

3. Screenshots on Failure

Add this to your test for automatic failure documentation:

test.afterEach(async ({ page }, testInfo) => {
  if (testInfo.status !== 'passed') {
    await page.screenshot({ path: `screenshots/${testInfo.title}.png` });
  }
});

The Setup Script That Wouldn't Quit

Here's a fun one that had me pulling my hair out. When running pnpm test:e2e-setup, the process would just... hang. Forever. No errors, no timeout, just an eternal loading state staring back at me.

The setup script looked innocent enough:

test("Setup wallet", async ({ context, metamask }) => {
  await metamask.connectToDapp()
  await metamask.switchNetwork('base')
  // ... rest of setup
})

After what felt like hours of staring at a frozen terminal, I finally ran it with debug flags:

DEBUG=synpress:* pnpm test:e2e-setup

And there it was! The debug logs revealed MetaMask was showing a network switch confirmation dialog that the script couldn't handle:

synpress:metamask Switching to network: base
synpress:metamask Waiting for network switch confirmation...
[hanging here forever]

The solution? Remove the network switch from the setup entirely. The cached wallet doesn't need to be on a specific network – let each test handle its own network requirements. Sometimes the simplest solutions are the best ones.

Writing Better Tests

Here's what separates good e2e tests from great ones:

1. Test user journeys, not implementation details – Think "user connects wallet and sends tokens" not "button click triggers function X"

2. Keep tests independent – Each test should work on its own. No test should depend on another test running first.

3. Use data-testid attributes – They're more stable than CSS selectors:

   <button data-testid="connect-wallet">Connect</button>

4. Be generous with assertions – But not too generous. Check what matters, ignore what doesn't.

Wrapping Up

E2E testing with Playwright and Synpress might seem daunting at first, but it's genuinely worth the investment. Start small – maybe just test your wallet connection flow. Then gradually add more complex scenarios.

Remember: done is better than perfect. Tests don't need to cover every edge case right away. They just need to catch the obvious breaks while you focus on building features.

The best part? Once you have a solid test suite, you can refactor with confidence, ship features faster, and actually enjoy your weekends without worrying about production issues.

Happy testing!

From Storybook to npm

Last week we had two games (CoinToss and Dice) living happily in our Storybook demo. This week? They're on npm, ready to drop into any React app.

📦 @betswirl/ui on npm

The 5-Minute Integration Challenge

We wanted to prove that integrating BetSwirl games could be stupidly simple. So we set ourselves a challenge: from zero to deployed casino dApp in 5 minutes. Here's what happened.

Minute 1: Create the App

npm create vite@latest betswirl-ui-react-demo -- --template react-ts
cd betswirl-ui-react-demo
npm install

Vite + React + TypeScript. The holy trinity of modern web dev.

Minute 2: Install BetSwirl

npm install @betswirl/ui

One package. All the games. All the Web3 complexity handled.

Minute 3: Wire Up the Providers

Remember our provider jungle from the Storybook days? We cleaned it up:

// main.tsx
// Full code: https://github.com/chainhackers/betswirl-ui-react-demo/blob/main/src/main.tsx
// ... imports for React, Wagmi, OnchainKit, BetSwirl
import '@betswirl/ui/styles.css'  // Don't forget this!

const queryClient = new QueryClient()
const config = createConfig({
  chains: [base],
  transports: { [base.id]: http() },
})

const onChainKitConfig: AppConfig = {
  wallet: {
    display: "modal",
  }
}

createRoot(document.getElementById('root')!).render(
  <WagmiProvider config={config}>
    <QueryClientProvider client={queryClient}>
      <OnchainKitProvider chain={base} config={onChainKitConfig}>
        <BetSwirlSDKProvider initialChainId={base.id}>
          <App />
        </BetSwirlSDKProvider>
      </OnchainKitProvider>
    </QueryClientProvider>
  </WagmiProvider>
)

Same providers we've been using, but now they're properly packaged and documented.

Minute 4: Add a Game

// App.tsx
// Full code: https://github.com/chainhackers/betswirl-ui-react-demo/blob/main/src/App.tsx
import { CoinTossGame } from '@betswirl/ui'

function App() {
  return (
    <div className="App">
      <h1>My Casino dApp</h1>
      <div style={{ margin: '2rem 0' }}>
        <CoinTossGame />
      </div>
    </div>
  )
}

That's it. The game handles wallet connection, betting, on-chain randomness, everything.

Minute 5: Deploy to Vercel

Push to GitHub, connect to Vercel, click deploy. Done.

🎮 Live Demo
💻 GitHub Repo

Beyond the 5 Minutes: All Games Live

Want to see all three games in action? Check out our full demo showcasing CoinToss, Dice, and our latest addition:

🎰 Play All Games Demo
⚡ Edit on StackBlitz

What's Different Now?

Remember our first post about "stuffing an elephant into a telephone booth"? Well, we found a way. The components are:

• Self-contained: All Web3 logic bundled

• Theme-aware: Light/dark/custom themes just work

• Mobile-ready: Finally sorted the responsive layouts

• TypeScript-first: Full type safety, autocomplete heaven

What's Next?

• Keno

• Token Selector: v0.2.0 target

For the Builders

If you're thinking about adding games to your dApp:

1. Try the demo first: See if the UX fits your vibe

2. Check your audience: BetSwirl supports multiple chains, but components work with one chain at a time

3. Revenue share is automatic: 30% of house edge to you, handled on-chain (see docs)

4. Join our Discord: We're helping early integrators personally

Ship It Culture

A few weeks ago, we were picking cat backgrounds in Figma. Now we have a production npm package ready for integration. The lesson? Ship early, iterate in public, see what happens.

Ready to build?

npm install @betswirl/ui

Need help?

• Twitter: @ChainHackerClan

• Farcaster channel: /betswirl

• Discord: Join the BetSwirl builders

Brainpower Bonus

We got backup: a core dev from BetSwirl joined the party and walked us through how to structure React hooks for cleaner, custom UI integration. Hooks, providers, separation of concerns—it clicked. Expect a blog post or recipe guide soon, especially for those building skins and extensions.

Visual Boost

We added a bunch of new backgrounds—ranging from tasteful to completely chaotic—and started putting Playwright + Synpress to work for proper E2E tests. It’s no longer just a weekend project; we’re locking in real infra.

The Game

Pick a number from 1 to 99 and bet that the dice will roll under it. Pick 20? You’ve got a 20% chance of winning ~5x. Pick 80? You’ve got an 80% chance of winning ~1.25x. Classic high risk vs low risk.

One SDK, Two Games

DiceGame follows the same architecture as CoinToss. Same GameFrame, same theming system, same usePlaceBet logic behind the scenes. Swapping games is as simple as changing one component name. Yes, you can render both in the same app.

Who’s It For?

We’ve seen interest from memecoin communities, token projects, and even DeFi dashboards. The use case is always the same: plug in a game, give users something fun to do, and earn a revenue share without building a casino from scratch.

Each game call is fully on-chain, randomness is handled by Chainlink VRF, and users can verify every outcome.

Where We Are Now

Storybook hosts both games with full theme toggles and wallet integration. Want to test them? Go for it. The SDK is nearly package-ready—we're preparing the npm release and polishing the final DX.

Coming Up

• 📦 npm packaging + docs

• 💱 Token selector (currently only ETH)

• 🎯 Next games: Roulette + Keno

• 📱 Farcaster frame experiments

We’re still early, but getting more confident with each release. Curious what the web will do with on-chain games this easy to drop in.

Try the games: Storybook link

Want to build with us? Ping us anytime:
Twitter: https://x.com/ChainHackerClan
Farcaster: https://farcaster.xyz/chainhacker

What We Shipped

After last week’s layout and styling adventures, we wrapped the entire game flow into two clean exports:

• A single hook: usePlaceBet

• A React component: <CoinTossGame />

All the on-chain complexity — randomness, wallet checks, error handling, event listening — is baked in. Just import and go.

Example: Integration is Tiny

Here's all it takes to wire up the game component in your app:

const config = createConfig({
  chains: [base],
  transports: { [base.id]: http() },
})

export function CoinTossGamePage() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={new QueryClient()}>
        <OnchainKitProvider chain={base}>
          <BettingConfigProvider value={{ affiliate: "0x0" }}>
            <CoinTossGame />
          </BettingConfigProvider>
        </OnchainKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

That’s it. If your wallet is connected, you can play. If not, OnchainKit handles it.

Developer Notes

• Most stable: Desktop browsers with browser wallets (e.g. Coinbase Wallet, MetaMask)

• Mobile: Coming soon — we’re starting Farcaster Frame support!

• Also keeping an eye on Base minikit — hoping to plug into that as well.

Next Up

In the coming week:

• 📦 Publish the first npm package for easy component installs

• 🎨 Polish token selection and mobile layout

• 📱 Begin Farcaster frame integration using Base minikit

The component is real, live, and working—no mockups. And it’s not just for meme sites. Anyone building with on-chain vibes can plug this in and start earning from gameplay.

More soon!

Trying to fit a decentralized Web3 casino into every corner of the internet is like stuffing an elephant into a telephone booth. BetSwirl, already killing it in decentralized gaming, is making it possible with reusable components. Now, developers can slap these components into any webpage and bring decentralized gaming to their users without breaking a sweat. Here’s the scoop on how they’re doing it.

Cooking Up the Vibe

We kicked off with our imaginary memecoin hats on, dreaming up quirky backgrounds—wacky cats, space apes, and more—to set the stage for the memecoiners’ vibe. The first token in the mix? Just ETH on Base, keeping it simple yet powerful.

Storybook Magic

As components piled up, Storybook became our hero. It let us test "CoinToss" in light and dark themes, tweak designs live, and deploy demos in a snap—perfect for keeping the team in sync.

Styling Showdowns

Enter Coinbase’s OnchainKit for wallet magic—and a styling clash with Tailwind CSS. Overlapping styles broke our design until Tailwind layers stepped in. By isolating OnchainKit’s styles, we kept "CoinToss" looking sharp.

Lessons Learned

• Integrate Early: Digging into OnchainKit docs sooner would’ve saved us rework.

• Layer Up: Tailwind layers are our new go-to for CSS peace.

• Hackathon Mode: Rapid prototyping catches hiccups fast.

Sneak Peek

Try It Yourself

Want to embed "CoinToss" in your own project? We’ve made it simple! We’ll be dropping documentation with step-by-step instructions on adding the game to any web page, and we’ll share the link to our example page once it’s live. Just remember, adding tokens to the bankroll is handled exclusively by the BetSwirl team.

What’s Next?

"CoinToss" is just the start—a reusable piece pre-set with chains like Base and tokens like BETS. We’re diving into OnchainKit, Base minikit, and Farcaster miniapps next. Ready to play? Check us out on GitHub, embed "CoinToss" yourself, or toss us your ideas. Join the ride!

Happy hacking!