Runtime context

When your Mini App runs inside the Startale App, the host populates sdk.context with three layers: Farcaster-standard fields, client/device metadata, and a startale extension object with Startale-specific user data.

Full context shape

const context = await sdk.context

// Farcaster-standard user identity
context.user       // { fid, username, displayName, pfpUrl }
context.location   // { type: 'launcher' }
context.client     // { platformType, clientFid, added, safeAreaInsets }

// Device capabilities
context.features   // { haptics: boolean, cameraAndMicrophoneAccess: boolean }

// Startale-specific
context.startale   // { starPoints, eoaWallets, language }

Field	Type	Description
`user.fid`	`number`	Internal Startale identifier. Present for protocol compatibility, not a Farcaster account ID. Do not use this to identify users; use the smart account address from `eth_requestAccounts` instead.
`user.username`	`string`	The user’s Startale display username.
`user.displayName`	`string`	Display name.
`user.pfpUrl`	`string`	Profile photo URL.
`location.type`	`string`	Launch context. Always `'launcher'` when opened from the Mini App grid.
`client.platformType`	`string`	Host platform identifier.
`client.clientFid`	`number`	Internal Startale client identifier. Present for protocol compatibility, not a Farcaster account ID.
`client.safeAreaInsets`	`object`	`{ top, bottom, left, right }` in px; use for notch-safe layout.
`features.haptics`	`boolean`	Whether the host supports haptic feedback. Use before calling haptic actions.
`features.cameraAndMicrophoneAccess`	`boolean`	Whether camera/mic access is available. `true` only in a secure context (HTTPS) on a device with media devices. Check before requesting access. See SDK actions.
`startale.starPoints`	`number`	The user’s current STAR Points balance.
`startale.eoaWallets`	`string[]`	Addresses verified as linked to the user’s smart account.
`startale.language`	`string`	The Startale App edition the user is in, as a code (`'en'` for Global, `'ja'` for Japan). It is not simply a UI language toggle, see Reading the app edition.

Identifying users. Use the smart account address (retrieved via eth_requestAccounts) as the primary user identifier in your backend. user.fid and client.clientFid are internal protocol placeholders and are not stable user identifiers.

Reading context

sdk.context is a Promise. The bridge between your Mini App and the host is asynchronous, so you must await it before reading any field. The startale object is a Startale extension not included in the official @farcaster/miniapp-sdk TypeScript types. Cast the result to access it with full type safety:

import { sdk } from '@farcaster/miniapp-sdk'

type StartaleContext = {
  user?: { username?: string; displayName?: string; pfpUrl?: string }
  client?: { safeAreaInsets?: { top: number; bottom: number; left: number; right: number } }
  features?: { haptics?: boolean; cameraAndMicrophoneAccess?: boolean }
  startale?: { starPoints?: number; eoaWallets?: string[]; language?: 'en' | 'ja' }
}

const context = (await sdk.context) as StartaleContext

const starPoints = context.startale?.starPoints ?? 0
const eoaWallets = context.startale?.eoaWallets ?? []
const language   = context.startale?.language ?? 'en'
const username   = context.user?.username ?? ''

In React, read context once on mount inside a useEffect:

import { useEffect, useState } from 'react'
import { sdk } from '@farcaster/miniapp-sdk'

type StartaleContext = {
  user?: { username?: string; pfpUrl?: string }
  features?: { haptics?: boolean; cameraAndMicrophoneAccess?: boolean }
  client?: { safeAreaInsets?: { top: number; bottom: number; left: number; right: number } }
  startale?: { starPoints?: number; eoaWallets?: string[]; language?: 'en' | 'ja' }
}

export function useStartaleContext() {
  const [context, setContext] = useState<StartaleContext | null>(null)

  useEffect(() => {
    sdk.context
      .then((raw) => setContext(raw as StartaleContext))
      .catch(console.error)
  }, [])

  return context
}

function App() {
  const context = useStartaleContext()

  const starPoints = context?.startale?.starPoints ?? 0
  const eoaWallets = context?.startale?.eoaWallets ?? []
  const username   = context?.user?.username ?? ''

  return <Dashboard starPoints={starPoints} eoaWallets={eoaWallets} username={username} />
}

The startale type cast is necessary today because the Startale context extensions are not yet part of the upstream @farcaster/miniapp-sdk type definitions. The cast is safe; the host always populates these fields when your Mini App runs inside the Startale App.

STAR Points

STAR Points are the Startale App’s user-engagement currency. Users earn them through daily activities in the Mission Center and through USDSC usage inside the app, and the balance is treated as a proof of contribution toward future token rewards. Mini Apps see the balance through sdk.context.startale.starPoints and can use it as an eligibility signal, for example, gating bonus content or rewarding power users. For the full earning rules and the latest mission catalog, link users to the Startale App page.

Reading user STAR Points

import { sdk } from '@farcaster/miniapp-sdk'

const context = await sdk.context
const points = context.startale?.starPoints ?? 0

console.log(`User has ${points} STAR Points`)

Reading the app edition

startale.language tells you which edition of the Startale App the user is running at the moment your Mini App loads: Global ('en') or Japan ('ja'). The host decides this, including any residency and compliance checks, before your Mini App ever sees it. Use it to pick the content or feature set your Mini App shows, for example JP-only copy or anything gated on Japan compliance requirements. Don’t run your own geo or residency checks for this: if startale.language says 'ja', the host has already confirmed the user’s edition, and any JP content it’s willing to show them is already vetted for that edition. Edition and display language happen to match today, so you can also use the same field to pick your Mini App’s own UI translation if it has one:

import { sdk } from '@farcaster/miniapp-sdk'

const context = await sdk.context
const edition = context.startale?.language ?? 'en' // 'en' = Global, 'ja' = Japan

if (edition === 'ja') {
  // show Japan-edition content
}

i18n.changeLanguage(edition) // optional: also use it for your own i18n

Discovering linked EOAs

eoaWallets is the canonical way to discover personal wallets the user has linked to their Startale account. Each address has been verified server-side via SIWE. Common use cases:

Restoring user progress from an existing user base.
Granting NFT utility based on assets held in a personal wallet.
Co-marketing eligibility checks (“are you an existing player of project X?”).

import { sdk } from '@farcaster/miniapp-sdk'
import { createPublicClient, http, erc721Abi } from 'viem'
import { soneium } from 'viem/chains'

const context = await sdk.context
const eoaAddresses = context.startale?.eoaWallets ?? []

const publicClient = createPublicClient({
  chain: soneium,
  transport: http(),
})

for (const address of eoaAddresses) {
  const balance = await publicClient.readContract({
    address: NFT_CONTRACT_ADDRESS,
    abi: erc721Abi,
    functionName: 'balanceOf',
    args: [address as `0x${string}`],
  })
  if (balance > 0n) {
    // User holds the NFT in this linked EOA
  }
}

EOAs are read-only

You can read balances and onchain state for any address in eoaWallets. You cannot sign or send transactions from a linked EOA inside a Mini App, the active signer is always the user’s smart account. If a user holds assets in a linked EOA that they want to use inside your Mini App:

Detect the asset using eoaWallets and a read-only contract call.
Inform the user that they need to transfer the asset to their smart account.
The transfer must happen outside the Mini App, on your project’s standalone website where MetaMask connects directly.

See Wallet integration for the full constraint surface.

Sandbox simulation gap

The Mini App sandbox simulates sdk.context.startale.starPoints as 100 and populates location, client.platformType, and client.safeAreaInsets with default values. sdk.context.startale.eoaWallets, sdk.context.startale.language, user, and features are not populated. Test EOA-discovery features, identity-dependent logic, and capability checks against a staging or production Startale App, not the local sandbox.

Overview

Manifest

Runtime

Notifications

Ship it

Full context shape

Reading context

STAR Points

Reading user STAR Points

Reading the app edition

Discovering linked EOAs

EOAs are read-only

Sandbox simulation gap

​Full context shape

​Reading context

​STAR Points

​Reading user STAR Points

​Reading the app edition

​Discovering linked EOAs

​EOAs are read-only

​Sandbox simulation gap

Full context shape

Reading context

STAR Points

Reading user STAR Points

Reading the app edition

Discovering linked EOAs

EOAs are read-only

Sandbox simulation gap