What you’ll learn
By the end of this guide, you’ll be able to:
  • Define a complete farcaster.json manifest that meets Base App requirements.
  • Map each manifest property to its role in search, discovery, and embeds.
  • Validate images, text, and URLs against required constraints.
  • Link your manifest to your domain using accountAssociation.
  • Control indexing for staging and production with noindex.

​
Overview

Your /.well-known/farcaster.json file is the manifest for your Mini App. It contains all the metadata Base App uses to:
  • Display your app in search results and category listings
  • Generate rich, clickable embeds when your app is shared
  • Show your app in users’ saved apps for quick access
If the manifest is missing, incomplete, or invalid, your app won’t appear in Base App discovery features.

​
Location

Serve your manifest over HTTPS at:
Terminal
https://your-domain.com/.well-known/farcaster.json
Serve with Content-Type: application/json and ensure the file is publicly accessible (no auth).

​
How Base App uses Manifest

  • Search indexing: Your app appears in search after it has been shared at least once. Indexing typically completes in ~10 minutes.
  • Category placement: primaryCategory determines where your app appears in category browsing. tags improve cross-surface visibility and filtering.
  • Embeds: Open Graph fields (ogTitle, ogDescription, ogImageUrl) and heroImageUrl power compelling feed previews that drive clicks.
  • Saved apps: name and iconUrl appear when users save your Mini App for quick access.
If your Mini App does not show in search, follow the debugging guide here.

​
Example manifest

farcaster.json
{
  "accountAssociation": {
    "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0",
    "payload": "eyJkb21haW4iOiJhcHAuZXhhbXBsZS5jb20ifQ",
    "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj"
  },
  "baseBuilder": {
    "allowedAddresses": ["0x..."]
  },
  "frame": {
    "version": "1",
    "name": "Example Mini App",
    "homeUrl": "https://ex.co",
    "iconUrl": "https://ex.co/i.png",
    "splashImageUrl": "https://ex.co/l.png",
    "splashBackgroundColor": "#000000",
    "webhookUrl": "https://ex.co/api/webhook",
    "subtitle": "Fast, fun, social",
    "description": "A fast, fun way to challenge friends in real time.",
    "screenshotUrls": [
      "https://ex.co/s1.png",
      "https://ex.co/s2.png",
      "https://ex.co/s3.png"
    ],
    "primaryCategory": "social",
    "tags": ["example", "miniapp", "baseapp"],
    "heroImageUrl": "https://ex.co/og.png",
    "tagline": "Play instantly",
    "ogTitle": "Example Mini App",
    "ogDescription": "Challenge friends in real time.",
    "ogImageUrl": "https://ex.co/og.png",
    "noindex": true
  }
}
For a visual mapping of how fields render, see the Mini App specification reference.

​
Field reference

​
Top-level fields

PropertyTypeRequiredDescription
accountAssociationobjectYesProves domain ownership for your Mini App.
frameobjectYesContains all metadata used by Base App.
baseBuilderobjectYesThis verifies ownership and connects your Base Build account.

​
accountAssociation fields

PropertyTypeRequiredDescription
headerstringYesEncoded header for the association payload.
payloadstringYesEncoded payload containing your domain.
signaturestringYesSignature over the payload.

​
baseBuilder fields

PropertyTypeRequiredDescription
allowedAddressesstringYesThis verifies ownership and connects your Base Build account.

​
frame fields

​
Identity & Launch

Defines your Mini App’s core identity and the URL users land on when they open it.
PropertyTypeRequiredDescriptionConstraints
versionstringYesManifest version.Must be "1".
namestringYesMini App name.Max 32 chars.
homeUrlstringYesDefault launch URL.HTTPS URL, max 1024 chars.
iconUrlstringYesIcon image URL.HTTPS URL, PNG 1024×1024; transparent background discouraged.

​
Loading Experience

Controls the splash screen visuals and colors shown while your Mini App loads.
PropertyTypeRequiredDescriptionConstraints
splashImageUrlstringYesLoading image.HTTPS URL, recommended 200×200px.
splashBackgroundColorstringYesLoading background color.Hex code (e.g., #000000).
Determines how your Mini App is indexed, categorized, and surfaced across Base App discovery features.
PropertyTypeRequiredDescriptionConstraints
primaryCategorystringYesControls where your app appears in category browsing.One of: games, social, finance, utility, productivity, health-fitness, news-media, music, shopping, education, developer-tools, entertainment, art-creativity.
tagsstring[]YesSearch/filter tags.Up to 5; ≤ 20 chars each; lowercase; no spaces/emojis/special chars.
noindexbooleanNoExclude from search results.true = exclude, default = include.
requiredChainsstring[]NoCAIP-2 chain IDs.Supported: eip155:8453 (Base mainnet), eip155:84532 (Base Sepolia).

​
Display Information

Provides the descriptive text, screenshots, and promotional images shown on your Mini App’s profile.
PropertyTypeRequiredDescriptionConstraints
subtitlestringNoShort description under name.Max 30 chars; avoid emojis/special chars.
descriptionstringNoPromo text for app page.Max 170 chars; avoid emojis/special chars.
taglinestringNoMarketing tagline.Max 30 chars.
heroImageUrlstringNoLarge promo image.1200×630px (1.91:1), PNG/JPG.
screenshotUrlsstring[]NoVisual previews.Max 3; portrait 1284×2778px recommended.

​
Embeds & Social Sharing

Configures how your Mini App appears when shared in feeds or on social platforms.
PropertyTypeRequiredDescriptionConstraints
ogTitlestringNoOpen Graph title.Max 30 chars.
ogDescriptionstringNoOpen Graph description.Max 100 chars.
ogImageUrlstringNoOpen Graph image.1200×630px (1.91:1), PNG/JPG.
imageUrl (deprecated)stringNoLegacy default feed image.Prefer ogImageUrl.
buttonTitle (deprecated)stringNoLegacy feed button text.Prefer embed button config in OG.

​
Advanced Capabilities

Specifies technical integrations, event handling, and special permissions your Mini App requires.
PropertyTypeRequiredDescriptionConstraints
webhookUrlstringNoPOST events endpoint.HTTPS URL, max 1024 chars. Required if using notifications.
Choose your primaryCategory carefully — it determines where your app appears in Base App’s category browsing and rankings.

​
Validation checklist

  • Manifest is served over HTTPS at /.well-known/farcaster.json
  • All required fields are present
  • Image sizes match the constraints (icon, OG, hero, screenshots)
  • Text fields respect character and formatting limits
  • "noindex": true is used only for staging/development
Test your manifest with a simple curl to confirm accessibility and headers: curl -sI https://your-domain.com/.well-known/farcaster.json.

​
Development vs. production

  • Set "noindex": true for development or staging environments to prevent search indexing.
  • Remove or set "noindex": false for production so users can discover your app.
Your app appears in search after the first share is detected. Indexing usually completes in ~10 minutes.

​
Common issues

  • Missing required fields → app won’t index in search
  • Image format/size mismatches → broken or distorted embeds
  • Invalid primaryCategory → app won’t appear in category browsing
  • Overlong strings → truncation or rejection at indexing
  • Manifest not publicly accessible → discovery fails

​
Next steps