Manifest

Every Mini App publishes a manifest at a fixed path. The Startale App fetches this file to register, display, and launch your Mini App.

Location

GET https://<your-domain>/.well-known/farcaster.json

Constraint	Value
Protocol	HTTPS required (HTTP allowed for `localhost` in development only)
Timeout	10 seconds
Maximum size	10 KB
Maximum redirects	3

Private IP addresses and reserved ranges are blocked at fetch time. See URL rules.

Validate your manifest before submitting at app.startale.com/developers/manifest.

Top-level structure

Use the frame key. It is the Farcaster standard, so a single farcaster.json file works on Startale, Farcaster, and Base without rename. Startale-specific fields (featuredBannerImageUrl, projectWebsite, socialLinks, screenCompatibility) live under a root-level startale key, sibling to frame.

{
  "frame": {
    "version": "1",
    "name": "Your App Name",
    "tagline": "One-line pitch here",
    "iconUrl": "https://your-app.com/icon.webp",
    "homeUrl": "https://your-app.com",
    "splashImageUrl": "https://your-app.com/splash.png",
    "splashBackgroundColor": "#1a1a2e",
    "heroImageUrl": "https://your-app.com/hero.webp",
    "primaryCategory": "games",
    "tags": ["game", "web3", "soneium"],
    "webhookUrl": "https://your-app.com/api/notify"
  },
  "startale": {
    "manifestVersion": "2.3",
    "screenCompatibility": {
      "desktop": true,
      "landscapeOnly": false
    },
    "featuredBannerImageUrl": "https://your-app.com/banner.webp",
    "projectWebsite": "https://your-app.com",
    "socialLinks": {
      "twitter": "https://x.com/yourapp",
      "discord": "https://discord.gg/abc123",
      "telegram": "https://t.me/yourapp"
    }
  }
}

Required fields

Validated automatically

The manifest parser rejects any manifest missing these three fields:

Field	Type	Constraints
`frame.name`	string	Display name. Recommended ≤32 chars.
`frame.iconUrl`	string	App icon. See Media specs.
`frame.homeUrl`	string	Canonical origin URL: scheme + host only, no path or query string. Recommended ≤1024 chars.

Required for submission review

The following fields are not parser-enforced but are required for your Mini App to pass review, appear correctly in the explorer, and qualify for featured placement. A manifest missing any of these will be rejected during manual review.

Field	Type	Notes
`frame.version`	string	Must be `"1"`
`frame.primaryCategory`	string	One value from Categories.
`frame.heroImageUrl`	string	Image shown on the app grid card.
`startale.featuredBannerImageUrl`	string	Featured rotation banner at the top of the explorer.
`startale.screenCompatibility.desktop`	boolean	`true` = full browser on desktop; `false` = default 424×695 px portrait frame. Omitting it shows a Missing flag in the validator.

One homeUrl per app, even across language editions. A localized or JP-specific build must declare the same homeUrl as the global edition, not a variant with a language path or query string (/jp, ?lang=ja). Notifications derive your senderId from this field trimmed to a bare origin, so a differing or non-bare homeUrl breaks manifest resolution and subscriptions for that build. See Notifications for how senderId is used.

Optional fields

Field	Type	Notes
`frame.tagline`	string	One-line pitch shown on the app card. Max 30 chars.
`frame.splashImageUrl`	string	Centered icon on the loading screen. 200×200px, PNG/JPG/WebP, max 50KB.
`frame.splashBackgroundColor`	string	Hex color for the splash background.
`frame.tags`	string[]	Up to 5 tags, lowercase alphanumeric + hyphens, ≤20 chars each. Used for explorer search and filtering.
`frame.webhookUrl`	string	Notification endpoint. Required for push notifications.
`startale.manifestVersion`	string	Startale manifest spec version. Use `"2.3"` for new manifests.
`startale.projectWebsite`	string	HTTPS URL to your main project site.
`startale.socialLinks`	object	Object with `twitter`, `discord`, `telegram`, `farcaster`, `website` keys.
`startale.screenCompatibility.landscapeOnly`	boolean	When `true`, content rotates 90° when the viewport is portrait. Default `false`.

URL rules

Every URL in the manifest is validated. Failures reject the manifest.

Rule	Detail
Protocol	HTTPS required. HTTP only for `localhost` and `127.0.0.1` in development.
Private IPv4 ranges blocked	`0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `198.18.0.0/15`, `240.0.0.0/4`
Private IPv6 ranges blocked	Loopback (`::1`), link-local (`fe80::/10`), unique local (`fc00::/7`)
Localhost in production	Blocked

The same rules apply to every image URL in the manifest. When the Startale App displays your banner, it tries fields in this priority order:

startale.featuredBannerImageUrl
frame.imageUrl
frame.heroImageUrl
frame.splashImageUrl
frame.iconUrl

Provide featuredBannerImageUrl (2400×1260 px) for the best result.

Reusing a Farcaster or Base manifest

If your Mini App is already live on Farcaster or Base, your existing farcaster.json works on Startale unchanged. Add a root-level startale key (sibling to frame) with the Startale-specific fields (featuredBannerImageUrl, projectWebsite, socialLinks, screenCompatibility). A single file works on all three platforms.

Overview

Runtime

Notifications

Ship it

Manifest

Location

Top-level structure

Required fields

Validated automatically

Required for submission review

Optional fields

URL rules

Banner fallback chain

Reusing a Farcaster or Base manifest

​Location

​Top-level structure

​Required fields

​Validated automatically

​Required for submission review

​Optional fields

​URL rules

​Banner fallback chain

​Reusing a Farcaster or Base manifest

Location

Top-level structure

Required fields

Validated automatically

Required for submission review

Optional fields

URL rules

Banner fallback chain

Reusing a Farcaster or Base manifest