Skip to content

Specification

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 FrameEmbed in a serialized form in the fc:frame meta tag in the HTML <head>. 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.

<meta name="fc:frame" content="<stringified Embed JSON>" />

Schema

PropertyTypeRequiredDescriptionConstraints
versionstringYesVersion of the embed.Must be "1" or "next"
imageUrlstringYesImage url for the embedMax 1024 characters. Must be 3:2 aspect ratio.
buttonobjectYesButton

Button Schema

PropertyTypeRequiredDescriptionConstraints
titlestringYesMini App name.Max length 32 characters
actionobjectYesActionMax length 1024 characters.

Action Schema

PropertyTypeRequiredDescriptionConstraints
typestringYesMini App name.Max length 32 characters
urlstringNoApp URL to open. If not provided, defaults to full URL used to fetch the document.Max length 1024 characters.
namestringNoName of the application
splashImageUrlstringNoURL of image to show on loading screen.Max length 32 characters. Must be 200x200px.
splashBackgroundColorstringNoHex color code to use on loading screen.Hex color code.
Example
{
  "version": "next",
  "imageUrl": "https://yoink.party/framesV2/opengraph-image",
  "button": {
    "title": "🚩 Start",
    "action": {
      "type": "launch_frame",
      "name": "Yoink!",
      "url": "https://yoink.party/framesV2",
      "splashImageUrl": "https://yoink.party/logo.png",
      "splashBackgroundColor": "#f5f0ec"
    }
  }
}

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

This SDK facilitates communication over a postMessage channel available in iframes and mobile WebViews.

Versioning

The SDK is versioned using Semantic Versioning. A What's New page is maintained to communicate developer impacting changes. A lower level changelog is maintained within the code base to document all changes.

API

  • context - provides information about the context the Mini App is running in

Actions

  • addFrame - Prompts the user to add the Mini App
  • close - Closes the Mini App
  • composeCast - Prompt the user to cast
  • ready - Hides the Splash Screen
  • signin - Prompts the user to Sign In with Farcaster
  • openUrl - Open an external URL
  • viewProfile - View a Farcaster profile

Wallet

Events

The SDK allows Mini Apps to subscribe to 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 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

Manfiests 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

PropertyTypeRequiredDescription
accountAssociationobjectYesVerifies domain ownership to a Farcaster account
frameobjectYesMetadata 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 from the account's custody address with the following payload:

{
  domain: string;
}

The domain value must exactly match the FQDN of where it is hosted.

Schema
PropertyTypeRequiredDescription
headerstringYesbase64 encoded JFS header
payloadstringYesbase64 encoded payload
signaturestringYesbase64 encoded signature
Example
{
  "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
  "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
  "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi"
}

frame

Metadata needed to by Hosts to distribute the Mini App.

PropertyTypeRequiredDescriptionConstraints
versionstringYesManifest version.Must be '1'.
namestringYesMini App name.Max length 32 characters
homeUrlstringYesDefault launch URLMax length 1024 characters.
iconUrlstringYesIcon image URLMax length 1024 characters.
Image must be 1024x1024px PNG, no alpha.
imageUrlstringNo[DEPRECATED] Default image to show if shared in a feed.Max length 1024 characters.
Image must be 3:2 aspect ratio.
buttonTitlestringNo[DEPRECATED] Default button title to show if shared in a feed.Max length 32 characters.
splashImageUrlstringNoURL of image to show on loading screen.Max length 32 characters. Must be 200x200px.
splashBackgroundColorstringNoHex color code to use on loading screen.Hex color code.
webhookUrlstringNoURL to which clients will POST events.Max length 1024 characters.
Must be set if the Mini App application uses notifications.
subtitlestringNoShort description under app nameMax 30 characters, no emojis or special characters
descriptionstringNoPromotional message for Mini App PageMax 170 characters, no emojis or special characters
screenshotUrlsarrayNoVisual previews of the appPortrait, 1284 x 2778, max 3 screenshots
primaryCategorystringNoPrimary category of appOne of: games, social, finance, utility, productivity, health-fitness, news-media, music, shopping, education, developer-tools, entertainment, art-creativity
tagsarrayNoDescriptive tags for filtering/searchUp to 5 tags, max 20 characters each. Lowercase, no spaces, no special characters, no emojis.
heroImageUrlstringNoPromotional display image1200 x 630px (1.91:1)
taglinestringNoMarketing taglineMax 30 characters
ogTitlestringNoOpen Graph titleMax 30 characters
ogDescriptionstringNoOpen Graph descriptionMax 100 characters
ogImageUrlstringNoOpen Graph promotional image1200 x 630px (1.91:1) PNG
Example
{
  "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:

{
  "accountAssociation": {
    "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
    "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
    "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi"
  },
  "frame": {
    "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 addFrame 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:

  • frame_added
  • frame_removed
  • notifications_enabled
  • notifications_disabled

The body looks like this:

Events use the JSON Farcaster Signature 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.

frame_added

This event may happen when an open frame calls actions.addFrame 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:

{
  "event": "frame-added",
  "notificationDetails": {
    "url": "https://api.warpcast.com/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}
type EventFrameAddedPayload = {
  event: 'frame_added';
  notificationDetails?: FrameNotificationDetails;
};

frame_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:

{
  "event": "frame-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:

{
  "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:

{
  "event": "notifications-enabled",
  "notificationDetails": {
    "url": "https://api.warpcast.com/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}
type EventNotificationsEnabledPayload = {
  event: 'notifications_enabled';
  notificationDetails: FrameNotificationDetails;
};

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:

PropertyTypeRequiredDescriptionConstraints
notificationIdstringYesAn ID that serves as 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
titlestringYesTitle of the notification.Max length 32 characters
bodystringYesBody of the notification.Max length 128 characters.
targetUrlstringYesURL to open when the user clicks the notification.Max length 1024 characters.
Must be on the same domain as the Mini App.
tokensstring[]YesArray 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:

PropertyTypeRequiredDescription
successTokensstring[]YesTokens for which the notification succeeded.
invalidTokensstring[]YesTokens which are no longer valid and should never be used again. This could happen if the user disabled notifications but for some reason the Mini App server has no record of it.
rateLimitedTokensstring[]YesTokens for which the rate limit was exceeded. Mini App server can try later.

Once a user has been notified, when clicking the notification the client app will:

  • Open targetUrl
  • Set the context to the notification, see NotificationLaunchContext

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