> ## 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.

# Manifest

> Every Mini App publishes a manifest at /.well-known/farcaster.json. Required fields, Startale extensions, and validation rules.

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](#url-rules).

<Tip>
  Validate your manifest before submitting at [app.startale.com/developers/manifest](https://app.startale.com/developers/manifest).
</Tip>

## 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`.

```json theme={null}
{
  "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](/miniapps/media-specs). |
| `frame.homeUrl` | string | HTTPS 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.

| Field                                  | Type    | Notes                                                                                                                             |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `frame.version`                        | string  | Must be `"1"`                                                                                                                     |
| `frame.primaryCategory`                | string  | One value from [Categories](/miniapps/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. |

## 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.

## Banner fallback chain

When the Startale App displays your banner, it tries fields in this priority order:

1. `startale.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 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.