Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.startale.com/llms.txt

Use this file to discover all available pages before exploring further.

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
ConstraintValue
ProtocolHTTPS required (HTTP allowed for localhost in development only)
Timeout10 seconds
Maximum size10 KB
Maximum redirects3
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) sit flat inside frame, not nested under any sub-object. 
{
  "frame": {
    "version": "1",
    "name": "Your App Name",
    "tagline": "One-line pitch here",
    "subtitle": "Short descriptor",
    "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",
    "heroImageUrlAnimated": "https://your-app.com/hero.mp4",
    "ogImageUrl": "https://your-app.com/og.webp",
    "screenshotUrls": [],
    "primaryCategory": "games",
    "tags": ["game", "web3", "soneium"],
    "webhookUrl": "https://your-app.com/api/notify",
    "screenCompatibility": {
      "desktop": true,
      "landscapeOnly": false
    },
    "featuredBannerImageUrl": "https://your-app.com/banner.webp",
    "featuredBannerImageUrlAnimated": "https://your-app.com/banner.mp4",
    "projectWebsite": "https://your-app.com",
    "socialLinks": {
      "twitter": "https://x.com/yourapp",
      "discord": "https://discord.gg/abc123",
      "telegram": "https://t.me/yourapp"
    }
  }
}
An older miniapp top-level key is also accepted by the validator. Always use frame in new manifests.

​
Required fields

​
Validated automatically

The manifest parser rejects any manifest missing these three fields:
FieldTypeConstraints
frame.namestringDisplay name. Recommended ≤32 chars.
frame.iconUrlstringApp icon. See Media specs.
frame.homeUrlstringHTTPS launch URL. 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.
String-length recommendations come from the Farcaster Mini App spec.
FieldTypeNotes
frame.versionstringMust be "1"
frame.taglinestringOne-line pitch shown on the app card. Recommended ≤30 chars.
frame.subtitlestringShort descriptor below the app name. Recommended ≤30 chars, plain text only.
frame.primaryCategorystringOne value from Categories.
frame.heroImageUrlstringImage shown on the app grid card.
frame.splashImageUrlstringCentered icon on the loading screen.
frame.splashBackgroundColorstringHex color for the splash background.
frame.featuredBannerImageUrlstringFeatured rotation banner at the top of the explorer.
frame.projectWebsitestringHTTPS URL to your main project site.
frame.socialLinksobjectAt least one of twitter, discord, telegram, farcaster, website.
accountAssociationobjectOptional. See accountAssociation below.

​
Optional fields

FieldTypeNotes
frame.heroImageUrlAnimatedstringAnimated hero played on hover in the grid. MP4, max 4s, 1 MB.
frame.featuredBannerImageUrlAnimatedstringAnimated featured banner played on hover. MP4, max 4s, 2 MB.
frame.ogImageUrlstringSocial-preview image for X, Telegram, Discord, etc.
frame.screenshotUrlsstring[]Up to 3 portrait screenshots.
frame.tagsstring[]Recommended up to 5 tags, lowercase, ≤20 chars each. Used for explorer search and filtering.
frame.webhookUrlstringNotification endpoint. Required for push notifications.
frame.screenCompatibility.desktopbooleanWhen true, the iframe expands to full browser size on desktop. Default false (424×695 px frame).
frame.screenCompatibility.landscapeOnlybooleanWhen true, content rotates 90° when the viewport is portrait. Default false.

​
accountAssociation

Three base64url-encoded fields that prove your hostname is owned by a specific Farcaster account. Generate them with the Farcaster manifest tool. 
"accountAssociation": {
  "header": "<base64url>",
  "payload": "<base64url>",
  "signature": "<base64url>"
}
accountAssociation is required by the Farcaster spec and sits at the top level of the manifest, sibling to frame.
You can include accountAssociation for compatibility with other Farcaster clients (Warpcast, etc.). The Startale App does not validate or use it at registration time, it is ignored.

​
URL rules

Every URL in the manifest is validated. Failures reject the manifest.
RuleDetail
ProtocolHTTPS required. HTTP only for localhost and 127.0.0.1 in development.
Private IPv4 ranges blocked0.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 blockedLoopback (::1), link-local (fe80::/10), unique local (fc00::/7)
Localhost in productionBlocked
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:
  1. frame.featuredBannerImageUrl
  2. frame.imageUrl
  3. frame.heroImageUrl
  4. frame.splashImageUrl
  5. 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 Startale-specific fields (featuredBannerImageUrl, projectWebsite, socialLinks) flat inside your existing frame object. A single file works on all three platforms.