Publishing your app
Publishing Mini Apps involves providing information like who developed the app, how it should be displayed, and what its capabilities are.
Since Farcaster is a decentralized network with multiple clients, publishing is
done by hosting a manifest file at /.well-known/farcaster.json
on the domain
your app is hosted on rather than submitting information directly to a single
entity.
Published Mini Apps can be discovered in App Stores.
Steps
Choose a domain
A Mini App is associated with a single domain (i.e. rewards.warpcast.com). This domain serves as the identifier for your app and can't be changed later so you should choose a stable domain.
There's no limit on the number of apps you can create. You can create a separate domain specifically for development purposes if needed.
Host a manifest file
Host a manifest file on your chosen domain at /.well-known/farcaster.json
.
For now we'll create an empty file:
touch public/.well-known/farcaster.json
Define your application configuration
A Mini App has metadata that is used by Farcaster clients to host your app. This
data is specified in the frame
property of the manifest and has the following properties:
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 |
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) |
Here's an example farcaster.json
file:
{
"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",
}
}
Verifying ownership
A Mini App is owned by a single Farcaster account. This lets users know who they are interacting with and developers get credit for their work.
Verification is done by placing a cryptographically signed message in the
accountAssociation
property of your farcaster.json
.
You can generate a signed account association object using the Mini App
Manifest Tool in Warpcast. Take
the output from that tool and update your farcaster.json
file.
Here's an example farcaster.json
file for the domain yoink.party
with the
account association:
{
"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"
}
}