SDK actions

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.requestCameraAndMicrophoneAccess']

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()
}

Action	When to use
`impactOccurred`	Button taps, drag start/end, collision feedback
`notificationOccurred`	Transaction confirmed, error state, achievement unlocked
`selectionChanged`	Scroll picker moved, toggle changed

actions.requestCameraAndMicrophoneAccess

Use this to enable the camera and microphone inside your Mini App. The flow has three steps, in order:

Check the feature flag. Read context.features.cameraAndMicrophoneAccess. It is true only when the host runs your Mini App in a secure context (HTTPS) on a device that exposes media devices. If it is false, hide or disable your capture UI, getUserMedia would otherwise fail opaquely.
Call sdk.actions.requestCameraAndMicrophoneAccess(). This signals the host that your Mini App is about to use the camera/mic. Always await it before requesting a stream.
Call navigator.mediaDevices.getUserMedia(...). This is the call that actually opens the stream and triggers the browser’s native permission prompt.

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

async function startCapture() {
  const context = await sdk.context
  if (!context.features?.cameraAndMicrophoneAccess) return

  await sdk.actions.requestCameraAndMicrophoneAccess()
  const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
  // attach `stream` to a <video> element, audio analyser, etc.
}

The browser permission prompt

When you call getUserMedia, the browser shows its own native permission dialog asking the user to allow camera and microphone access. This dialog is rendered by the browser, not by your Mini App and not by the Startale App. You cannot style it, move it, or pre-fill the answer.

If the user allows, getUserMedia resolves with a MediaStream.
If the user denies (or has previously blocked the origin), getUserMedia rejects with a DOMException whose name is NotAllowedError (or SecurityError). Handle this and show a recoverable state.
The browser remembers the choice per origin, so the prompt usually appears only on first use.

Tell the user the prompt is coming before you call getUserMedia. The native dialog appears abruptly and out of your control, so a user who isn’t expecting it is far more likely to dismiss it. A short line of in-app copy (“Your browser will ask for camera and microphone access”) next to the button that starts capture is enough.

Releasing the stream

Stop every track when you’re done so the camera/mic indicator turns off, and clean up on unmount:

for (const track of stream.getTracks()) track.stop()

A complete working example (feature check, permission request, live preview, a mic level meter, denial handling, and cleanup) lives in the mustard-demo-miniapp reference app (src/CameraSection.tsx).

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.

Action	Return value	Why
`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-op	Farcaster social feature, not available
`sdk.actions.viewProfile()`	no-op	Farcaster 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.

Overview

Manifest

Runtime

Notifications

Ship it

Checking supported capabilities

actions.ready

actions.close

actions.openUrl

actions.addMiniApp

Haptic feedback

actions.requestCameraAndMicrophoneAccess

The browser permission prompt

Releasing the stream

Actions not supported in Startale App

​Checking supported capabilities

​actions.ready

​actions.close

​actions.openUrl

​actions.addMiniApp

​Haptic feedback

​actions.requestCameraAndMicrophoneAccess

​The browser permission prompt

​Releasing the stream

​Actions not supported in Startale App

Checking supported capabilities

actions.ready

actions.close

actions.openUrl

actions.addMiniApp

Haptic feedback

actions.requestCameraAndMicrophoneAccess

The browser permission prompt

Releasing the stream

Actions not supported in Startale App