repository·main·Indexed 42 days ago
https://github.com/farcasterxyz/miniappsA suite of tools and SDKs for building Farcaster Mini Apps, including the @farcaster/frame-sdk, @farcaster/frame-node for backend signature verification, and @farcaster/create-mini-app for project scaffolding. The repository also provides automated codemods via the miniapp-migrate CLI to migrate existing Frame-based codebases to the Mini App standard, updating imports, API methods, and TypeScript types.
postMessage API. This is a minimal implementation used to show how these two entities interact without the abstraction of higher-level SDKs.Neynar provides several managed services for building and managing Farcaster mini apps:
npx @neynar/create-farcaster-mini-app@latest.Mini Apps can interact with a user's EVM wallet via an EIP-1193 Ethereum Provider API exposed at sdk.wallet.getEthereumProvider().
While you can use the provider directly, it is highly recommended to use Wagmi for type-safe, high-level interactions. The Farcaster client handles wallet selection and connection, so your app does not need to show a wallet selection dialog.
The package provides utility methods for handling secure backend operations for Mini Apps.
parseWebhookEvent: Parses and verifies incoming webhook events. Requires a VerifyAppKey method.verifyJsonFarcasterSignature: Verifies a JSON Farcaster Signature payload. Requires a VerifyAppKey method.createJsonFarcasterSignature: Creates a JSON Farcaster Signature payload.To verify signatures, you must provide a VerifyAppKey method that validates that a specific app key is valid for a given FID (Farcaster ID).
You can use the built-in verifyAppKeyWithNeynar method to handle this verification via Neynar. This requires the NEYNAR_API_KEY environment variable to be set in your environment.
The Farcaster Mini App SDK allows you to interact with a user's Solana wallet by leveraging the Wallet Standard.
Depending on your application type, you can use different interfaces:
For detailed implementation steps, refer to the Guide on interacting with Solana wallets.
Mini App notifications allow you to send in-app messages to users who have added your app to their Farcaster client (e.g., Warpcast) and enabled notifications.
The Workflow:
url in a database.POST request to the stored url including the token and content.targetUrl and sets the context.location to a MiniAppLocationNotificationContext type of 'notification'.You can interface with the user's Solana wallet directly through the Wallet Standard or via Wallet Adapter's non-React (core) integrations.
To ensure the Farcaster wallet registers correctly with Wallet Standard, you must import the integration package in your app entry point:
import '@farcaster/mini-app-solana';Important: If you are using Wallet Adapter without the FarcasterSolanaProvider component, you are responsible for manually selecting the user's Farcaster wallet before attempting any wallet operations.
If your Mini App provides optional support for certain features, you should detect them at runtime using the SDK instead of declaring them as requirements in the manifest. This allows your app to gracefully degrade or provide different experiences based on the host's capabilities.
getChains() to retrieve an array of supported CAIP-2 blockchain identifiers.getCapabilities() to retrieve an array of supported SDK method paths.disableNativeGestures flag to prevent the app from closing unexpectedly.Tunnel domains (e.g., from ngrok or cloudflared) are intended for development only. Using them has the following limitations:
addMiniApp() will fail when using tunnel domains.For production: Always deploy your app to a permanent domain that matches your manifest.
Mini Apps are rendered in a vertical modal.
424x695px.The codemods automate several key areas of the migration:
Converts imports from Frame SDKs to Mini App SDKs.
- import { frameHost } from '@farcaster/frame-sdk'
+ import { miniAppHost } from '@farcaster/miniapp-sdk'
- import { FrameContext } from '@farcaster/frame-core'
+ import { MiniAppContext } from '@farcaster/miniapp-core'Renames host and context methods.
- const context = await frameHost.getFrameContext()
+ const context = await miniAppHost.getMiniAppContext()
- frameHost.addFrame({ url: 'https://example.com' })
+ miniAppHost.addMiniApp({ url: 'https://example.com' })Updates type definitions.
- const context: FrameContext = { ... }
+ const context: MiniAppContext = { ... }
- export interface MyFrameHost extends FrameHost { ... }
+ export interface MyMiniAppHost extends MiniAppHost { ... }Updates event listener strings.
- sdk.on('frame_added', handler)
+ sdk.on('miniapp_added', handler)
- if (event.type === 'frame_removed') { ... }
+ if (event.type === 'miniapp_removed') { ... }Updates farcaster.json files to include both frame and miniapp properties for backward compatibility.
{
"accountAssociation": { ... },
"frame": {
"version": "1",
"name": "My App",
...
}
+ "miniapp": {
+ "version": "1",
+ "name": "My App",
+ ...
+ }
}