You're connected!

Address: {address}

) } return ( ) } ``` :::note Your Mini App won't need to show a wallet selection dialog that is common in a web based dapp, the Farcaster client hosting your app will take care of getting the user connected to their preferred crypto wallet. ::: #### Send a transaction You're now ready to prompt the user to transact. They will be shown a preview of the transaction in their wallet and asked to confirm it: Follow [this guide from Wagmi](https://wagmi.sh/react/guides/send-transaction#_2-create-a-new-component) on sending a transaction (note: skip step 1 since you're already connected to the user's wallet). :::: ### Troubleshooting #### Transaction Scanning Modern crypto wallets scan transactions and preview them to users to help protect users from scams. New contracts and applications can generate false positives in these systems. If your transaction is being reported as potentially malicious use this [Blockaid Tool](https://report.blockaid.io/verifiedProject) to verify your app with Blockaid. ## What's New ### April 22, 2025 (0.0.36) * Added `noindex` field to manifest (see [discussions/204](https://github.com/farcasterxyz/miniapps/discussions/204)) ### April 16, 2025 (0.0.35) * Introduced new manifest metadata fields (see [discussions/191](https://github.com/farcasterxyz/miniapps/discussions/191)) * Deprecated `imageUrl` and `buttonTitle` (see [discussions/194](https://github.com/farcasterxyz/miniapps/discussions/194)) * Made `url` optional in `actionLaunchFrameSchema` - when not provided, it defaults to the current webpage URL (including query parameters) (see [discussions/189](https://github.com/farcasterxyz/miniapps/discussions/189)) ### April 6, 2024 (0.0.34) * Increased URL max length to 1024 characters ## Context When your app is opened it can access information about the session from `sdk.context`. This object provides basic information about the user, the client, and where your app was opened from: ```ts export type FrameContext = { user: { fid: number; username?: string; displayName?: string; pfpUrl?: string; }; location?: FrameLocationContext; client: { clientFid: number; added: boolean; safeAreaInsets?: SafeAreaInsets; notificationDetails?: FrameNotificationDetails; }; }; ``` ### Properties #### `location` Contains information about the context from which the Mini App was launched. ```ts export type CastEmbedLocationContext = { type: 'cast_embed'; embed: string; cast: { fid: number; hash: string; }; }; export type NotificationLocationContext = { type: 'notification'; notification: { notificationId: string; title: string; body: string; }; }; export type LauncherLocationContext = { type: 'launcher'; }; export type ChannelLocationContext = { type: 'channel'; channel: { /** * Channel key identifier */ key: string; /** * Channel name */ name: string; /** * Channel profile image URL */ imageUrl?: string; }; }; export type LocationContext = | CastEmbedLocationContext | NotificationLocationContext | LauncherLocationContext | ChannelLocationContext; ``` ##### Cast Embed Indicates that the Mini App was launched from a cast (where it is an embed). ```ts > sdk.context.location { type: "cast_embed", cast: { fid: 3621, hash: "0xa2fbef8c8e4d00d8f84ff45f9763b8bae2c5c544", } } ``` ##### Notification Indicates that the Mini App was launched from a notification triggered by the frame. ```ts > sdk.context.location { type: "notification", notification: { notificationId: "f7e9ebaf-92f0-43b9-a410-ad8c24f3333b" title: "Yoinked!", body: "horsefacts captured the flag from you.", } } ``` ##### Launcher Indicates that the Mini App was launched directly by the client app outside of a context, e.g. via some type of catalog or a notification triggered by the client. ```ts > sdk.context.location { type: "launcher" } ``` #### `user` Details about the calling user which can be used to customize the interface. This should be considered untrusted since it is passed in by the application, and there is no guarantee that it was authorized by the user. ```ts export type AccountLocation = { placeId: string; /** * Human-readable string describing the location */ description: string; }; export type UserContext = { fid: number; username?: string; displayName?: string; /** * Profile image URL */ pfpUrl?: string; location?: AccountLocation; }; ``` ```ts > sdk.context.user { "fid": 6841, "username": "deodad", "displayName": "Tony D'Addeo", "pfp": "https://i.imgur.com/dMoIan7.jpg", "bio": "Building @warpcast and @farcaster, new dad, like making food", "location": { "placeId": "ChIJLwPMoJm1RIYRetVp1EtGm10", "description": "Austin, TX, USA" } } ``` ```ts type User = { fid: number; username?: string; displayName?: string; pfp?: string; bio?: string; location?: { placeId: string; description: string; }; }; ``` #### client Details about the Farcaster client running the Mini App. This should be considered untrusted * `clientFid`: the self-reported FID of the client (e.g. 9152 for Warpcast) * `added`: whether the user has added the Mini App to the client * `safeAreaInsets`: insets to avoid areas covered by navigation elements that obscure the view * `notificationDetails`: in case the user has enabled notifications, includes the `url` and `token` for sending notifications ```ts export type SafeAreaInsets = { top: number; bottom: number; left: number; right: number; }; export type ClientContext = { clientFid: number; added: boolean; notificationDetails?: FrameNotificationDetails; safeAreaInsets?: SafeAreaInsets; }; ``` ```ts > sdk.context.client { clientFid: 9152, added: true, safeAreaInsets: { top: 0, bottom: 20, left: 0, right: 0, }; notificationDetails: { url: "https://api.warpcast.com/v1/frame-notifications", token: "a05059ef2415c67b08ecceb539201cbc6" } } ``` ```ts type FrameNotificationDetails = { url: string; token: string; }; type SafeAreaInsets = { top: number; bottom: number; left: number; right: number; }; type ClientContext = { clientFid: number; added: boolean; safeAreaInsets?: SafeAreaInsets; notificationDetails?: FrameNotificationDetails; }; ``` ##### Using safeAreaInsets Mobile devices render navigation elements that obscure the view of an app. Use the `safeAreaInsets` to render content in the safe area that won't be obstructed. A basic usage would to wrap your view in a container that adds margin: ```

...your app view

``` However, you may want to set these insets on specific elements: for example if you have tab bar at the bottom of your app with a different background, you'd want to set the bottom inset as padding there so it looks attached to the bottom of the view. ## Client Events When a user interacts with your app events will be sent from the Farcaster client to your application client. Farcaster clients emit events to directly to your app client while it is open that can be used to update your UI in response to user actions. To listen to events, you have to use `sdk.on` to register callbacks ([see full example](https://github.com/farcasterxyz/frames-v2-demo/blob/20d454f5f6b1e4f30a6a49295cbd29ca7f30d44a/src/components/Demo.tsx#L92-L124)). Listeners can be cleaned up with `sdk.removeListener()` or sdk.removeAllListeners()\`. ### Events #### frameAdded The user added the Mini App. #### frameRemoved The user removed the Mini App. #### notificationsEnabled The user enabled notifications after previously having them disabled. #### notificationsDisabled The user disabled notifications. import { Caption } from '../../../components/Caption'; ## Wallet ![users taking onchain action from app](/transaction-preview.png) A user minting an NFT using the Warpcast Wallet. The SDK exposes an [EIP-1193 Ethereum Provider ](https://eips.ethereum.org/EIPS/eip-1193) at `sdk.wallet.ethProvider`. You can interact with this object directly or use it with ecosystem tools like [Wagmi](https://wagmi.sh/) or [Ethers](https://docs.ethers.org/v6/). For more information: * [EIP-1193 Ethereum Provider API](https://eips.ethereum.org/EIPS/eip-1193) * [Guide on interacting with wallets](/docs/guides/wallets) import { Caption } from '../../../../components/Caption'; ## addFrame Prompts the user to add the app. ![adding a mini app in Warpcast](/add_frame_preview.png) A users discover an app from their social feed, adds it, and then sees it from their apps screen ### Usage ```ts twoslash import { sdk } from '@farcaster/frame-sdk' await sdk.actions.addFrame() ``` ### Return Value `void` ### Errors #### `RejectedByUser` Thrown if a user rejects the request to add the Mini App. #### `InvalidDomainManifestJson` Thrown an app does not have a valid `farcaster.json`. import { Caption } from '../../../../components/Caption'; ## close Closes the mini app. ![closing the app](/close_preview.png) Close the app with `close`. ### Usage ```ts twoslash import { sdk } from '@farcaster/frame-sdk' await sdk.actions.close() ``` ### Return Value `void` import { Caption } from '../../../../components/Caption'; ## composeCast Open the cast composer with a suggested cast. The user will be able to modify the cast before posting it. ![composing a cast](/compose_cast_action.png) An app prompts the user to cast and includes an embed. ### Usage ```ts twoslash /** * Cryptographically secure nonce generated on the server and associated with * the user's session. */ const text = "I just learned how to compose a cast"; const embeds = ["https://miniapps.farcaster.xyz/docs/sdk/actions/compose-cast"] as [string]; // ---cut--- import { sdk } from '@farcaster/frame-sdk' await sdk.actions.composeCast({ text, embeds, }) ``` ### Parameters #### text (optional) * **Type:** `string` Suggested text for the body of the cast. Mentions can be included using the human-writeable form (e.g. @farcaster). #### embeds (optional) * **Type:** `[] | [string] | [string, string]` Suggested embeds. Max two. #### parent (optional) * **Type:** `{ type: 'cast'; hash: string }` Suggested parent of the cast. #### close (optional) * **Type:** `boolean` Whether the app should be closed when this action is called. If true the app will be closed and the action will resolve with no result. ### Return Value The cast posted by the user, or `undefined` if set to close. ```ts twoslash import { sdk } from "@farcaster/frame-sdk"; // ---cut--- const result = await sdk.actions.composeCast({ // ^? text: "I just learned how to compose a cast", embeds: ["https://miniapps.farcaster.xyz/docs/sdk/actions/compose-cast"] }) ``` import { Caption } from '../../../../components/Caption'; ## openUrl Opens an external URL. If a user is on mobile `openUrl` can be used to deeplink users into different parts of the Farcaster client they are using. ![opening a url](/open_url_preview.png) Opening an external url with `openUrl`. ### Usage ```ts twoslash const url = 'https://farcaster.xyz'; //---cut--- import { sdk } from '@farcaster/frame-sdk' await sdk.actions.openUrl(url) ``` ### Return Value \`void import { Caption } from '../../../../components/Caption'; ## ready Hides the Splash Screen. Read the [guide on loading your app](/docs/guides/loading) for best practices. ![calling ready to hide the splash screen](/ready_preview.png) Dismiss the Splash Screen with ready. ### Usage ```ts twoslash import { sdk } from '@farcaster/frame-sdk' await sdk.actions.ready() ``` ### Parameters #### disableNativeGestures (optional) * **Type:** `boolean` * **Default:** `false` Disable native gestures. Use this option if your frame uses gestures that conflict with native gestures like swipe to dismiss. ### Return Value `void` import { Caption } from '../../../../components/Caption'; ## signIn Request a [Sign in with Farcaster (SIWF)](https://docs.farcaster.xyz/developers/siwf/) credential from the user. See the guide on [authenticating users](/docs/guides/auth). ![signing in a user](/sign_in_preview.png) A users opens an app and is automatically signed in ### Usage ```ts twoslash /** * Cryptographically secure nonce generated on the server and associated with * the user's session. */ const nonce = 'securenonce'; // ---cut--- import { sdk } from '@farcaster/frame-sdk' await sdk.actions.signIn({ nonce }) ``` ### Parameters #### nonce * **Type:** `string` A random string used to prevent replay attacks, at least 8 alphanumeric characters. ### Return Value The SIWF message and signature. ``` type SignInResult = { signature: string; message: string; } ``` :::note This message must be sent to your server and verified. See the guide on [authenticating with Farcaster](/docs/guides/loading) for more information. ::: import { Caption } from '../../../../components/Caption'; ## viewProfile Displays a user's Farcaster profile. ![viewing a profile from an app](/view_profile_preview.png) Viewing a profile and follow a user from an app. ### Usage ```ts twoslash const fid = 6841; // ---cut--- import { sdk } from '@farcaster/frame-sdk' await sdk.actions.viewProfile({ fid }) ``` ### Parameters #### fid * **Type:** `number` Farcaster ID of the user who's profile to view. ### Return Value `void`