Skip to main content
farcaster.json
{
  "accountAssociation": {
    "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0",
    "payload": "eyJkb21haW4iOiJhcHAuZXhhbXBsZS5jb20ifQ",
    "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj"
  },
  "baseBuilder": {
    "allowedAddresses": ["0x..."]
  },
  "miniapp": {
    "version": "1",
    "name": "Crypto Portfolio Tracker",
    "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": "Easy to manage",
    "description": "Track and manage your cryptocurrency portfolio.",
    "screenshotUrls": [
      "https://ex.co/s1.png",
      "https://ex.co/s2.png",
      "https://ex.co/s3.png"
    ],
    "primaryCategory": "finance",
    "tags": ["finance"],
    "heroImageUrl": "https://ex.co/og.png",
    "tagline": "Save instantly",
    "ogTitle": "Example Mini App",
    "ogDescription": "Easy to manage portfolio.",
    "ogImageUrl": "https://ex.co/og.png",
    "noindex": true
  }
}
Set "noindex": true for development or staging environments to prevent search indexing.

Implementation

  1. Create the manifest file in your project at /public/.well-known/farcaster.json. It needs to be accessible at https://your-domain.com/.well-known/farcaster.json
  2. Update the required and optional fields in the miniapp object
  3. Ensure all changes are live so that the Manifest file is available at your app’s url
  4. Navigate to the Base Build Account association tool
  5. Paste your domain in the App URL field (ex: sample-url.vercel.app) and click “Submit”
  6. Click on the “Verify” button that appears and sign the manifest with your wallet to generate the accountAssociation fields
  7. Copy the generated accountAssociation fields (header, payload, and signature) and paste them into your manifest file, replacing the empty values in the accountAssociation object
Changes to the manifest take effect when you redeploy your Mini App and repost it. The platform re-indexes the updated configuration and applies changes to search, discovery, and embed rendering.

Schema

accountAssociation

Proves domain ownership for your Mini App.

header
string
required
Encoded header for the association payload.
payload
string
required
Encoded payload containing your domain.
signature
string
required
Signature over the payload.

baseBuilder

This verifies ownership and connects your Base Build account.This address should be the address of the wallet used when importing your mini app to Base Build.

allowedAddresses
string
required
This verifies ownership and connects your Base Build account.

Identity & Launch

Defines your Mini App’s core identity and the URL users land on when they open it.

version
string
required
Manifest version. Must be "1".
name
string
required
Mini App name. Max 32 chars.
homeUrl
string
required
Default launch URL. HTTPS URL, max 1024 chars.
iconUrl
string
required
Icon 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.

splashImageUrl
string
required
Loading image. HTTPS URL, recommended 200×200px.
splashBackgroundColor
string
required
Loading background color. Hex code (e.g., #000000).
Determines how your Mini App is indexed, categorized, and surfaced across Base App discovery features.

primaryCategory
string
required
Controls 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.
tags
string[]
required
Search/filter tags. Up to 5; ≤ 20 chars each; lowercase; no spaces/emojis/special chars.
noindex
boolean
Exclude from search results. true = exclude, default = include.

Display Information

Provides the descriptive text, screenshots, and promotional images shown on your Mini App’s profile.

subtitle
string
Short description under name. Max 30 chars; avoid emojis/special chars.
description
string
Promo text for app page. Max 170 chars; avoid emojis/special chars.
tagline
string
Marketing tagline. Max 30 chars.
heroImageUrl
string
Large promo image. 1200×630px (1.91:1), PNG/JPG.
screenshotUrls
string[]
Visual previews. Max 3; portrait 1284×2778px recommended.

Notifications

Notification endpoint.

webhookUrl
string
POST events endpoint. HTTPS URL, max 1024 chars. Required if using notifications.

Embeds & Social Sharing

Configures how your Mini App appears when shared in feeds or on social platforms.

ogTitle
string
Open Graph title. Max 30 chars.
ogDescription
string
Open Graph description. Max 100 chars.
ogImageUrl
string
Open Graph image. 1200×630px (1.91:1), PNG/JPG.