Skip to main content
By the end of this guide you will have a working Mini App running inside the Startale Mini App sandbox, signed in with the host wallet.

​
Prerequisites

  • Node.js 20 or later, plus pnpm.
  • An existing web application or a fresh Vite + React project.
If you do not have a project, scaffold one: 
pnpm create vite@latest my-miniapp --template react-ts
cd my-miniapp
pnpm install

​
1. Install the SDKs

pnpm add @startale/app-sdk @farcaster/miniapp-sdk @farcaster/miniapp-wagmi-connector wagmi viem @tanstack/react-query

​
2. Configure wagmi with the Startale connector

src/wagmi.ts
import { startaleConnector } from '@startale/app-sdk'
import { http, createConfig } from 'wagmi'
import { soneium } from 'wagmi/chains'

export const config = createConfig({
  chains: [soneium],
  connectors: [startaleConnector()],
  transports: {
    [soneium.id]: http(),
  },
})
The Startale connector replaces the default Farcaster wallet. Inside the Startale App, connections route to the user’s smart account.

​
3. Initialize the Farcaster SDK

src/App.tsx
import { useEffect } from 'react'
import { sdk } from '@farcaster/miniapp-sdk'

export function App() {
  useEffect(() => {
    sdk.actions.ready()
  }, [])

  return <Game />
}
sdk.actions.ready() tells the host the Mini App has loaded.

​
4. Add the manifest

Create public/.well-known/farcaster.json. Once it is hosted, validate it at app.startale.com/developers/manifest.
public/.well-known/farcaster.json
{
  "frame": {
    "version": "1",
    "name": "My Mini App",
    "tagline": "Predict, win, claim",
    "subtitle": "Prediction markets on Soneium",
    "iconUrl": "https://my-miniapp.com/icon.webp",
    "homeUrl": "https://my-miniapp.com",
    "splashImageUrl": "https://my-miniapp.com/splash.png",
    "splashBackgroundColor": "#0c0c0f",
    "heroImageUrl": "https://my-miniapp.com/hero.webp",
    "primaryCategory": "games",
    "featuredBannerImageUrl": "https://my-miniapp.com/banner.webp",
    "projectWebsite": "https://my-miniapp.com",
    "socialLinks": {
      "twitter": "https://x.com/myminiapp"
    }
  }
}
See Manifest for every field, Media specs for image requirements.

​
5. Sign the manifest (optional)

accountAssociation is part of the Farcaster spec and links your domain to a Farcaster account. The Startale App does not validate or use it at registration time, it is ignored. You can include it for compatibility with other Farcaster clients such as Warpcast. If you need it, open the Farcaster manifest tool, enter your hostname (no https:// prefix), and follow the steps. Paste the resulting object into your manifest as a sibling of frame: 
{
  "accountAssociation": {
    "header": "...",
    "payload": "...",
    "signature": "..."
  },
  "frame": {
    /* ... */
  }
}

​
6. Add the embed meta tag

In the <head> of every page you want shareable, add the tag below. Validate it at app.startale.com/developers/embed. 
<meta name="fc:miniapp" content='{"version":"1","imageUrl":"https://my-miniapp.com/preview.png","button":{"title":"Open","action":{"type":"launch_frame","name":"My Mini App","url":"https://my-miniapp.com","splashImageUrl":"https://my-miniapp.com/splash.png","splashBackgroundColor":"#0c0c0f"}}}' />
See Embed for the full schema.

​
7. Preview and test

Open app.startale.com/developers/preview to preview your Mini App instantly without any local setup. For a fully local environment, clone and run the Startale Mini App sandbox: 
git clone https://github.com/StartaleGroup/miniapp-sandbox.git
cd miniapp-sandbox
pnpm install
pnpm dev
Register your local Mini App in src/pages/configMiniApps.ts: 
export const MINI_APPS: MiniAppConfig[] = [
  { url: 'http://localhost:5173/' },
]
Start your Mini App dev server (pnpm dev in your project), open the sandbox at localhost:3100, and launch your Mini App.

​
Where to next

Read user context

STAR Points and verified linked EOAs.

Wallet constraints

Which RPC methods are available inside the host.

Submit your project

QA, deadlines, and the intake form.

Sandbox details

What the sandbox simulates and what it does not.