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.

The Startale App exposes a set of host actions through @farcaster/miniapp-sdk. These let your Mini App communicate with the host shell: close the frame, open external URLs, add the app to the user’s home, and trigger haptic feedback. Import the SDK and call actions directly: 
import { sdk } from '@farcaster/miniapp-sdk'

​
Checking supported capabilities

Before calling optional actions, query the host for what it supports: 
const capabilities = await sdk.getCapabilities()
// ['wallet.getEthereumProvider', 'actions.addMiniApp', 'actions.ready', 'actions.openUrl', 'actions.close']

​
actions.ready

Required. Call this once on mount to signal the host that your Mini App has fully loaded. The host shows a loading screen until ready() is called. 
import { useEffect } from 'react'
import { sdk } from '@farcaster/miniapp-sdk'

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

  return <YourApp />
}
If ready() is never called, the host will display a timeout error to the user after 15 seconds.

​
actions.close

Closes the Mini App frame and returns the user to the Startale App home screen. 
import { sdk } from '@farcaster/miniapp-sdk'

function CloseButton() {
  return (
    <button onClick={() => sdk.actions.close()}>
      Back to Startale
    </button>
  )
}

​
actions.openUrl

Opens a URL in the device’s default browser. The host validates that the URL uses http: or https:. Other protocols are silently blocked. 
import { sdk } from '@farcaster/miniapp-sdk'

sdk.actions.openUrl('https://your-project.com/terms')
Use this for links that need to leave the Mini App context: terms of service, external dashboards, social profile pages.
URLs with non-http/https protocols (e.g. javascript:, data:) are rejected by the host without throwing an error. Always use full https:// URLs.

​
actions.addMiniApp

Adds the Mini App to the user’s home screen inside the Startale App. Returns { result: {} } on success and fires a miniAppAdded SDK event you can listen to. 
import { sdk } from '@farcaster/miniapp-sdk'

async function handleAddToHome() {
  const result = await sdk.actions.addMiniApp()
  // result: { result: {} }
}
Listen for the miniAppAdded event on the SDK if you want to react to the user saving your app: 
import { sdk } from '@farcaster/miniapp-sdk'

sdk.on('miniAppAdded', () => {
  console.log('User added this Mini App to their home')
})

​
Haptic feedback

Three haptic actions are available. Check sdk.context.features.haptics before calling them. On platforms that do not support haptics, the calls are no-ops. 
import { sdk } from '@farcaster/miniapp-sdk'

const context = await sdk.context
const hasHaptics = context.features?.haptics ?? false

if (hasHaptics) {
  // Light tap, use for UI selections
  await sdk.actions.impactOccurred({ style: 'light' })

  // Notification, use for success, warning, or error feedback
  await sdk.actions.notificationOccurred({ type: 'success' })

  // Selection change, use when a picker or slider value changes
  await sdk.actions.selectionChanged()
}
ActionWhen to use
impactOccurredButton taps, drag start/end, collision feedback
notificationOccurredTransaction confirmed, error state, achievement unlocked
selectionChangedScroll picker moved, toggle changed

​
actions.requestCameraAndMicrophoneAccess

Requests camera and microphone permissions from the host. Resolves when the host has processed the request. 
import { sdk } from '@farcaster/miniapp-sdk'

const context = await sdk.context
if (context.features?.cameraAndMicrophoneAccess) {
  await sdk.actions.requestCameraAndMicrophoneAccess()
}

​
Actions not supported in Startale App

The following actions exist in the Farcaster Mini App protocol but are not applicable inside the Startale App. Calling them will not throw, but they return immediately with no effect or a not_supported error.
ActionReturn valueWhy
sdk.actions.signIn(){ error: { type: 'rejected_by_user' } }Startale uses wallet-based auth, not SIWF
sdk.actions.composeCast(){ cast: null }Farcaster social feature, not available
sdk.actions.viewCast()no-opFarcaster social feature, not available
sdk.actions.viewProfile()no-opFarcaster social feature, not available
sdk.actions.sendToken(){ success: false, reason: 'send_failed' }Not yet supported in Startale App
sdk.actions.swapToken(){ success: false, reason: 'swap_failed' }Not yet supported in Startale App
For token transfers and swaps, use direct contract calls via eth_sendTransaction or wallet_sendCalls with the appropriate calldata.