Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.startale.com/llms.txt

Use this file to discover all available pages before exploring further.

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 }
FieldTypeDescription
user.fidnumberInternal 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.usernamestringThe user’s Startale display username.
user.displayNamestringDisplay name.
user.pfpUrlstringProfile photo URL.
location.typestringLaunch context. Always 'launcher' when opened from the Mini App grid.
client.platformTypestringHost platform identifier.
client.clientFidnumberInternal Startale client identifier. Present for protocol compatibility, not a Farcaster account ID.
client.safeAreaInsetsobject{ top, bottom, left, right } in px; use for notch-safe layout.
features.hapticsbooleanWhether the host supports haptic feedback. Use before calling haptic actions.
features.cameraAndMicrophoneAccessbooleanWhether the host permits camera/mic access.
startale.starPointsnumberThe user’s current STAR Points balance.
startale.eoaWalletsstring[]Addresses verified as linked to the user’s smart account.
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[] }
}

const context = (await sdk.context) as StartaleContext

const starPoints = context.startale?.starPoints ?? 0
const eoaWallets = context.startale?.eoaWallets ?? []
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[] }
}

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

​
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:
  1. Detect the asset using eoaWallets and a read-only contract call.
  2. Inform the user that they need to transfer the asset to their smart account.
  3. 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, 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.