Skip to content

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.

discover mini apps

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:

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
noindexbooleanNoWhether to exclude the Mini App from search resultstrue - 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.

verified author

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"
  }
}