> ## 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.

# SDK actions

> Call host actions from inside your Mini App: closing the frame, opening URLs, adding to home, requesting camera access, and haptic feedback.

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:

```ts theme={null}
import { sdk } from '@farcaster/miniapp-sdk'
```

## Checking supported capabilities

Before calling optional actions, query the host for what it supports:

```ts theme={null}
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.

```tsx theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

<Warning>
  URLs with non-http/https protocols (e.g. `javascript:`, `data:`) are rejected by the host without throwing an error. Always use full `https://` URLs.
</Warning>

## 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.

```ts theme={null}
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:

```ts theme={null}
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.

```ts theme={null}
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

Requests camera and microphone permissions from the host. Resolves when the host has processed the request.

```ts theme={null}
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.

| 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.