> ## Documentation Index > Fetch the complete documentation index at: https://docs.neynar.com/llms.txt > Use this file to discover all available pages before exploring further. # Specification > Specification for Farcaster Mini Apps A Mini App is a web application that renders inside a Farcaster client. ## Mini App Embed The primary discovery points for Mini Apps are social feeds. Mini App Embeds are an OpenGraph-inspired metadata standard that lets any page in a Mini App be rendered as a rich object that can launch user into an application. mini app embed ### Versioning Mini App Embeds will follow a simple versioning scheme where non-breaking changes can be added to the same version but a breaking change must accompany a version bump. ### Metatags A Mini App URL must have a MiniAppEmbed in a serialized form in the `fc:miniapp` meta tag in the HTML ``. For backward compatibility of legacy Mini Apps, the `fc:frame` meta tag is also supported. When this URL is rendered in a cast, the image is displayed in a 3:2 ratio with a button underneath. Clicking the button will open a Mini App to the provided action url and use the splash page to animate the transition. ```html theme={"system"} ``` ### Schema | Property | Type | Required | Description | Constraints | | -------- | ------ | -------- | ----------------------- | ---------------------------------------------- | | version | string | Yes | Version of the embed. | Must be "1" | | imageUrl | string | Yes | Image url for the embed | Max 1024 characters. Must be 3:2 aspect ratio. | | button | object | Yes | Button | | #### Button Schema | Property | Type | Required | Description | Constraints | | -------- | ------ | -------- | -------------- | ------------------------ | | title | string | Yes | Mini App name. | Max length 32 characters | | action | object | Yes | Action | | #### Action Schema | Property | Type | Required | Description | Constraints | | --------------------- | ------ | -------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | type | string | Yes | The type of action. | One of: `launch_miniapp`, `view_token`. `launch_frame` is supported for backward compatibility. | | url | string | No | App URL to open. If not provided, defaults to full URL used to fetch the document. | Max length 1024 characters. | | name | string | Yes | | Name of the application | | splashImageUrl | string | No | URL of image to show on loading screen. | Max 1024 characters. Must be 200x200px. | | splashBackgroundColor | string | No | Hex color code to use on loading screen. | Hex color code. | ##### Example ```json theme={"system"} { "version": "1", "imageUrl": "https://yoink.party/framesV2/opengraph-image", "button": { "title": "🚩 Start", "action": { "type": "launch_miniapp", "name": "Yoink!", "url": "https://yoink.party/framesV2", "splashImageUrl": "https://yoink.party/logo.png", "splashBackgroundColor": "#f5f0ec" } } } ``` ## App Surface ![App Surface](https://github.com/user-attachments/assets/66cba3ca-8337-4644-a3ac-ddc625358390) ### Header Hosts should render a header above the Mini App that includes the name and author specified in the manifest. Clients should show the header whenever the Mini App is launched. ### Splash Screen Hosts should show a splash screen as soon as the app is launched. The icon and background must be specified in the Mini App manifest or embed meta tags. The Mini App can hide the splash screen once loading is complete. splash schematic ### Size & Orientation A Mini App should be rendered in a vertical modal. Mobile Mini App sizes should be dictated by device dimensions while web Mini App sizes should be set to 424x695px. ## SDK Mini Apps can communicate with their Host using a JavaScript SDK. At this time there is no formal specification for the message passing format, Hosts and Apps should use the open-source NPM packages that can be found in the [farcasterxyz/miniapps](https://github.com/farcasterxyz/miniapps) repo. This SDK facilitates communication over a `postMessage` channel available in iframes and mobile WebViews. ### Versioning The SDK is versioned using [Semantic Versioning](https://semver.org/). A [What's New page](/miniapps/sdk/changelog) is maintained to communicate developer impacting changes. A [lower level changelog](https://github.com/farcasterxyz/miniapps/blob/main/packages/miniapp-sdk/CHANGELOG.md) is maintained within the code base to document all changes. ### API * [context](/miniapps/sdk/context) - provides information about the context the Mini App is running in #### Actions * [addMiniApp](/miniapps/sdk/actions/add-miniapp) - Prompts the user to add the Mini App * [close](/miniapps/sdk/actions/close) - Closes the Mini App * [composeCast](/miniapps/sdk/actions/compose-cast) - Prompt the user to cast * [ready](/miniapps/sdk/actions/ready) - Hides the Splash Screen * [signin](/miniapps/sdk/actions/sign-in) - Prompts the user to Sign In with Farcaster * [openUrl](/miniapps/sdk/actions/open-url) - Open an external URL * [viewProfile](/miniapps/sdk/actions/view-profile) - View a Farcaster profile * [viewCast](/miniapps/sdk/actions/view-cast) - View a specific cast * [swapToken](/miniapps/sdk/actions/swap-token) - Prompt the user to swap tokens * [sendToken](/miniapps/sdk/actions/send-token) - Prompt the user to send tokens * [viewToken](/miniapps/sdk/actions/view-token) - View a token #### Wallet * [getEthereumProvider](/miniapps/sdk/wallet) - [EIP-1193 Ethereum Provider](https://eips.ethereum.org/EIPS/eip-1193) * [getSolanaProvider](/miniapps/sdk/solana) - Experimental Solana provider ### Events The SDK allows Mini Apps to [subscribe to events](/miniapps/sdk/events) emitted by the Host. ## Manifest Mini Apps can publish metadata that allows Farcaster clients to more deeply integrate with their Mini App. This file is published at `/.well-known/farcaster.json` and the [Fully Qualified Domain Name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) where it is hosted uniquely identifies the Mini App. The Manifest contains data that allows Farcaster clients to verify the author of the app, present the Mini App in discovery surfaces like app stores, and allows the Mini App to send notifications. ### Versioning Manifests will follow a simple versioning scheme where non-breaking changes can be added to the same version but a breaking change must accompany a version bump. ### Schema | Property | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------------------------ | | accountAssociation | object | Yes | Verifies domain ownership to a Farcaster account | | miniapp (or frame) | object | Yes | Metadata about the Mini App | #### accountAssociation The account association verifies authorship of this domain to a Farcaster account. The value is set to the JSON representation of a [JSON Farcaster Signature](https://github.com/farcasterxyz/protocol/discussions/208) from the account's custody address or a valid auth address with the following payload: ```json theme={"system"} { domain: string; } ``` The `domain` value must exactly match the FQDN of where it is hosted. The `header.type` must be `"custody"` or `"auth"`. ##### Schema | Property | Type | Required | Description | | --------- | ------ | -------- | ------------------------- | | header | string | Yes | base64 encoded JFS header | | payload | string | Yes | base64 encoded payload | | signature | string | Yes | base64 encoded signature | ##### Example ```json theme={"system"} { "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0", "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9", "signature": "D7urCIelYBtFc12UkEw/VOE1rkGKMdmDqAP/6s7sLWNfjhyug8pQCTM68XVJ8Gal6eBZxvtFE4RpVwqDtnLrzhs=" } ``` #### frame Metadata needed to by Hosts to distribute the Mini App. | Property | Type | Required | Description | Constraints | | --------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | version | string | Yes | Manifest version. | Must be '1'. | | name | string | Yes | Mini App name. | Max length 32 characters | | homeUrl | string | Yes | Default launch URL | Max length 1024 characters. | | iconUrl | string | Yes | Icon image URL | Max length 1024 characters. Image must be 1024x1024px PNG, no alpha. | | splashImageUrl | string | No | URL of image to show on loading screen. | Max length 32 characters. Must be 200x200px. | | splashBackgroundColor | string | No | Hex color code to use on loading screen. | Hex color code. | | webhookUrl | string | No | URL to which clients will POST events. | Max length 1024 characters. Must be set if the Mini App application uses notifications. | | subtitle | string | No | Short description under app name | Max 30 characters, no emojis or special characters | | description | string | No | Promotional message for Mini App Page | Max 170 characters, no emojis or special characters | | screenshotUrls | array | No | Visual previews of the app | Portrait, 1284 x 2778, max 3 screenshots | | primaryCategory | string | No | Primary category of app | One of: `games`, `social`, `finance`, `utility`, `productivity`, `health-fitness`, `news-media`, `music`, `shopping`, `education`, `developer-tools`, `entertainment`, `art-creativity` | | tags | array | No | Descriptive tags for filtering/search | Up to 5 tags, max 20 characters each. Lowercase, no spaces, no special characters, no emojis. | | heroImageUrl | string | No | Promotional display image | 1200 x 630px (1.91:1) | | tagline | string | No | Marketing tagline | Max 30 characters | | ogTitle | string | No | Open Graph title | Max 30 characters | | ogDescription | string | No | Open Graph description | Max 100 characters | | ogImageUrl | string | No | Open Graph promotional image | 1200 x 630px (1.91:1) PNG | | noindex | boolean | No | Whether to exclude the Mini App from search results | true - to exclude from search results, false - to include in search results (default) | | requiredChains | array | No | [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) IDs of required chains ([more info](/miniapps/sdk/detecting-capabilities)) | Only chains listed in `chainList` [here](https://github.com/farcasterxyz/miniapps/blob/main/packages/frame-core/src/schemas/manifest.ts) are supported | | requiredCapabilities | array | No | List of required capabilities ([more info](/miniapps/sdk/detecting-capabilities)) | Each entry must be a path to an SDK method. Full list in `miniAppHostCapabilityList` [here](https://github.com/farcasterxyz/miniapps/blob/main/packages/miniapp-core/src/types.ts) | | canonicalDomain | string | No | Canonical domain for the frame application | Max length 1024 characters. Must be a valid domain name without protocol, port, or path (e.g., app.example.com). | ### Example ```json theme={"system"} { "version": "1", "name": "Yoink!", "iconUrl": "https://yoink.party/logo.png", "homeUrl": "https://yoink.party/framesV2/", "imageUrl": "https://yoink.party/framesV2/opengraph-image", "buttonTitle": "🚩 Start", "splashImageUrl": "https://yoink.party/logo.png", "splashBackgroundColor": "#f5f0ec", "webhookUrl": "https://yoink.party/api/webhook" } ``` ### Example Example of a valid farcaster.json manifest: ```json theme={"system"} { "accountAssociation": { "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0", "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9", "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi" }, "miniapp": { "version": "1", "name": "Yoink!", "iconUrl": "https://yoink.party/logo.png", "homeUrl": "https://yoink.party/framesV2/", "imageUrl": "https://yoink.party/framesV2/opengraph-image", "buttonTitle": "🚩 Start", "splashImageUrl": "https://yoink.party/logo.png", "splashBackgroundColor": "#f5f0ec", "webhookUrl": "https://yoink.party/api/webhook" } } ``` ### Caching Farcaster clients may cache the manifest for a Mini App but should provide a way for refreshing the manifest file. ## Adding Mini Apps Mini Apps can be added to their Farcaster client by users. This enables the user to quickly navigate back to the app and the app to send notifications to the user. Mini Apps can prompt the user to add the app during an interaction with the [addMiniApp](/miniapps/sdk/actions/add-miniapp) action. Hosts may also let users add Mini Apps from discovery surfaces like app stores or featured notifications. Before a user adds a Mini App the Host should display information about the app and a reminder that the app will be able to notify the user. When a user adds a Mini App the Host must generate the appropriate Server Events and send them to the Mini App's `webhookUrl` if one was provided. After a user adds a Mini App, the Host should make it easy to find and launch the Mini App by providing a top-level interface where users can browse and open added apps. ### Server Events The Host server POSTs 4 types of events to the Mini App server at the `webhookUrl` specified in its Mini App manifest: * `miniapp_added` * `miniapp_removed` * `notifications_enabled` * `notifications_disabled` Events use the [JSON Farcaster Signature](https://github.com/farcasterxyz/protocol/discussions/208) format and are signed with the app key of the user. The final format is: ``` { header: string; payload: string; signature: string; } ``` All 3 values are `base64url` encoded. The payload and header can be decoded to JSON, where the payload is different per event. #### miniapp\_added This event may happen when an open frame calls `actions.addMiniApp` to prompt the user to favorite it, or when the frame is closed and the user adds the frame elsewhere in the client application (e.g. from a catalog). Adding a frame includes enabling notifications. The Host server generates a unique `notificationToken` and sends it together with the `notificationUrl` that the frame must call, to both the Host client and the frame server. Client apps must generate unique tokens for each user. Webhook payload: ```json theme={"system"} { "event": "miniapp_added", "notificationDetails": { "url": "https://api.farcaster.xyz/v1/frame-notifications", "token": "a05059ef2415c67b08ecceb539201cbc6" } } ``` ```ts theme={"system"} type EventMiniAppAddedPayload = { event: 'miniapp_added'; notificationDetails?: MiniAppNotificationDetails; }; ``` #### miniapp\_removed A user can remove a frame, which means that any notification tokens for that fid and client app (based on signer requester) should be considered invalid: Webhook payload: ```json theme={"system"} { "event": "miniapp_removed" } ``` #### notifications\_disabled A user can disable frame notifications from e.g. a settings panel in the client app. Any notification tokens for that fid and client app (based on signer requester) should be considered invalid: Webhook payload: ```json theme={"system"} { "event": "notifications_disabled" } ``` #### notifications\_enabled A user can enable frame notifications (e.g. after disabling them). The client backend again sends a `notificationUrl` and a `token`, with a backend-only flow: Webhook payload: ```json theme={"system"} { "event": "notifications_enabled", "notificationDetails": { "url": "https://api.farcaster.xyz/v1/frame-notifications", "token": "a05059ef2415c67b08ecceb539201cbc6" } } ``` ```ts theme={"system"} type EventNotificationsEnabledPayload = { event: 'notifications_enabled'; notificationDetails: MiniAppNotificationDetails; }; ``` ### Notifications A Mini App server can send notifications to one or more users who have enabled them. The Mini App server is given an authentication token and a URL which they can use to push a notification to the specific Farcaster app that invoked the Mini App. This is private and must be done separately for each Farcaster client that a user may use. The Mini App server calls the `notificationUrl` with the following JSON body: | Property | Type | Required | Description | Constraints | | -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | notificationId | string | Yes | Identifier that is combined with the FID to form an idempotency key. When the user opens the Mini App from the notification this ID will be included in the context object. | Maximum length of 128 characters | | title | string | Yes | Title of the notification. | Max length 32 characters | | body | string | Yes | Body of the notification. | Max length 128 characters. | | targetUrl | string | Yes | URL to open when the user clicks the notification. | Max length 1024 characters. Must be on the same domain as the Mini App. | | tokens | string\[] | Yes | Array of notification tokens to send to. | Max 100 tokens. | The response from the client server must be an HTTP 200 OK with the following JSON body: | Property | Type | Required | Description | | ----------------------- | --------- | -------- | ------------------------------------------------- | | result | object | Yes | Result object containing success and error arrays | | result.successfulTokens | string\[] | Yes | Array of tokens that were successfully sent | | result.failedTokens | object\[] | Yes | Array of objects with token and error reason | Once a user has been notified, when clicking the notification the client app will: * Open `targetUrl` * Set the context to the notification, see `NotificationLaunchContext` #### Idempotency A host MUST deduplicate notification requests using `(FID, notificationId)` as an idempotency that is valid 24 hours. This allows Apps to safely retry notification requests. #### Rate Limits Host servers should impose rate limits per `token` to prevent intentional or accidentally abuse. The recommended rate limits are: * 1 notification per 30 seconds per `token` * 100 notifications per day per `token` #### Displaying notifications Hosts should display a user's Mini App notifications from their UI as follows: notifications schematic #### Controls Hosts should provide controls for the user to toggle their notification settings for their apps. * Users should be able to navigate to settings for any Mini App they've added and be able to enable or disable notifications from this menu * Users should be able to disable notifications for a Mini App directly from a notification from that Mini App