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

Property	Type	Required	Description	Constraints
version	string	Yes	Version of the embed.	Must be "1" or "next"
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	Max length 1024 characters.

Action Schema

Property	Type	Required	Description	Constraints
type	string	Yes	Mini App name.	Max length 32 characters
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	No		Name of the application
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.

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

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

ethProvider - EIP-1193 Ethereum Provider

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

Property	Type	Required	Description
accountAssociation	object	Yes	Verifies domain ownership to a Farcaster account
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 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

Property	Type	Required	Description
header	string	Yes	base64 encoded JFS header
payload	string	Yes	base64 encoded payload
signature	string	Yes	base64 encoded signature

Example

{
  "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0",
  "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9",
  "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi"
}

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.
imageUrl	string	No	[DEPRECATED] Default image to show if shared in a feed.	Max length 1024 characters. Image must be 3:2 aspect ratio.
buttonTitle	string	No	[DEPRECATED] Default button title to show if shared in a feed.	Max length 32 characters.
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

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:

Property	Type	Required	Description	Constraints
notificationId	string	Yes	An 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
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
successTokens	string[]	Yes	Tokens for which the notification succeeded.
invalidTokens	string[]	Yes	Tokens 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.
rateLimitedTokens	string[]	Yes	Tokens 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