> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/mini-apps-platform/04-manifest.md). # Manifest Every mini-app bundle ships with a `based.json` at its root. The manifest is parsed and validated by the host at install time and re-validated at boot time. Anything not declared in the manifest is denied at runtime. ## Full schema (annotated example) ```json { "id": "com.partner.cool-yield", "version": "1.4.2", "name": "Cool Yield", "shortName": "Yield", "description": "Earn yield on USDC by staking into the Cool vault.", "icon": "assets/icon.png", "splash": "assets/splash.png", "entry": "main.js", "runtime": "js", "targetSdkVersion": "1.0", "minHostVersion": "2.5.0", "permissions": { "auth": ["userId", "addresses", "proof"], "signing": ["evm", "message"], "network": ["api.coolyield.io", "*.coolyield.io"], "storage": "5MB", "deepLinks": ["coolyield://*"], "openMiniApps": ["com.based.swap"], "clipboard": ["read", "write"] }, "theme": { "inherit": "tenant", "overrides": { "accent": "#00FF88", "accentText":"#001100" } }, "supportedChains": ["ethereum", "base", "arbitrum"], "category": "defi", "tags": ["yield", "staking", "usdc"], "developer": { "name": "Cool Yield Inc.", "url": "https://coolyield.io", "supportEmail": "support@coolyield.io" }, "signature": { "algorithm": "ed25519", "publicKeyId": "based-platform-2026-04", "value": "base64-encoded-sig" } } ``` ## Required fields | Field | Type | Notes | | ------------------ | ------------------ | ----------------------------------------------------------------------------------------------- | | `id` | reverse-DNS string | Globally unique; immutable across versions. Must match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`. | | `version` | semver | The bundle's own version. Strictly increasing per `id`. | | `name` | string | Human-readable. Used in confirmation sheets, kill messages, list UIs. | | `entry` | path | Relative to bundle root. Must end in `.js`. | | `runtime` | enum | `"js"` for v1. Reserved: `"sdui"`. | | `targetSdkVersion` | `.` | The SDK version the partner tested against. | | `minHostVersion` | semver | Host refuses to run if its own version is lower. | | `permissions` | object | See **Permissions** below. Empty `{}` is valid (some mini-apps need nothing). | ## Optional fields | Field | Type | Default | Notes | | ----------------- | ---------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shortName` | string | `name` | Used where space is limited (badges, app drawer). | | `description` | string | empty | One-paragraph user-facing description. | | `icon` | path | none | PNG/SVG. Required for any mini-app that ships to users; can be omitted in dev. | | `splash` | path | none | Optional splash image shown during cold boot. | | `theme` | object | `{ "inherit": "tenant" }` | See **Theme** below. | | `supportedChains` | array | `[]` | Informational. Used to filter mini-apps in the UI when the user has only certain chains. | | `category` | enum | `"general"` | One of `defi`, `gaming`, `commerce`, `social`, `tools`, `general`. | | `tags` | array of strings | `[]` | Free-form tags for search/discovery. | | `developer` | object | none | Required for mini-apps shipped to production. | | `signature` | object | none | Required for mini-apps shipped to production. See [`09-distribution-and-updates.md`](/docs/integrations/mini-apps-platform/09-distribution-and-updates.md). | ## Permissions The `permissions` object is the heart of the manifest. Every key corresponds to a category in the [Permission catalog](/docs/integrations/mini-apps-platform/03-host-contract.md#permission-catalog). ### `permissions.auth` ```json "auth": ["userId", "addresses", "proof"] ``` Array of strings drawn from `{"userId", "addresses", "proof"}`. Each maps directly to the corresponding `auth.*` permission. ### `permissions.signing` ```json "signing": ["evm", "message"] ``` Array drawn from `{"evm", "hl", "solana", "message"}`. **Asking for `signing.*` requires `auth.addresses` to be granted as well** — the host enforces this. ### `permissions.network` ```json "network": ["api.coolyield.io", "*.coolyield.io", "ipfs.io"] ``` Array of domain patterns. Rules: * Exact match: `"api.coolyield.io"` matches `https://api.coolyield.io/anything`. * Wildcard: `"*.coolyield.io"` matches `app.coolyield.io`, `data.coolyield.io`, but **not** `coolyield.io` itself (use both forms if you need both). * Schemes: only `https://` is allowed. `http://` is rejected at validation time. `ws://` and `wss://` are not yet supported (planned). * IPs: not allowed in v1. * The special token `"$host"` resolves to the host's own first-party domains and is reserved (denied to all third-party manifests). ### `permissions.storage` ```json "storage": "5MB" ``` A size string: `"512KB"`, `"1MB"`, `"5MB"`, `"20MB"`. Capped at 50MB. The host reserves the right to evict storage of inactive mini-apps under disk pressure (with a 30-day grace period). ### `permissions.deepLinks` ```json "deepLinks": ["coolyield://*", "https://coolyield.io/r/*"] ``` URL patterns that this mini-app may push via `nav.openDeepLink`. The host's *router* still has to know how to handle these — the manifest only declares intent. Custom schemes are limited to one prefix per mini-app, registered via the developer dashboard (out of scope for this doc). ### `permissions.openMiniApps` ```json "openMiniApps": ["com.based.swap", "com.partner.bridge"] ``` Array of mini-app ids that this mini-app may launch via `nav.openMiniApp`. The launched mini-app must accept inter-mini-app launches (declared on its side via `permissions.acceptsLaunchFrom`, see below). ### `permissions.acceptsLaunchFrom` ```json "acceptsLaunchFrom": ["com.partner.cool-yield", "*"] ``` Array of mini-app ids allowed to launch this mini-app. `"*"` means anyone. Useful for utility mini-apps (swap, bridge) that want to be embeddable. ### `permissions.clipboard` ```json "clipboard": ["read", "write"] ``` ### `permissions.notifications.local` Grants `based.notifications.show(...)` — host-rendered system banners. Title is auto-prefixed `[]` and the icon is taken from the manifest registry; both are enforced server- side (mini-app code can't override them). ```json "notifications": { "local": true } ``` For partner-driven remote pushes (sent from the partner's backend while the app is closed), no manifest declaration is needed — those flow through the gateway with a separate `mp_*` API key, which is a server-side credential, not a mini-app permission. ### `permissions.liveActivity` Grants `based.liveActivity.start/update/end(...)` — iOS Live Activities + Android Live Updates. Templates are compiled into the host (`progress` / `status` / `countdown`); partners pick a template, never ship layout code. ```json "liveActivity": true ``` The host registers the per-activity push-to-LA token (iOS) or FCM token (Android) with the gateway on behalf of the user, so partner backends can drive background updates without ever seeing the token. See [`17-partner-api.md`](/docs/integrations/mini-apps-platform/17-partner-api.md) for the gateway endpoints. ### `permissions.gyro.read` ```json "gyro": ["read"] ``` Grants `based.gyro.read()`. The native `` UiNode does NOT require this permission — it reads sensors directly inside the renderer. ## Theme ```json "theme": { "inherit": "tenant", "overrides": { "accent": "#00FF88", "accentText": "#001100" } } ``` * `inherit`: must be `"tenant"`. Reserved for future modes. * `overrides`: a flat map of token → hex color. Only **allowlisted** tokens may be overridden: | Token | Purpose | | ---------------------- | ------------------------------------------------------------------------- | | `accent` | The mini-app's brand accent. Used on primary buttons inside the mini-app. | | `accentText` | Text color on accent. | | `chartUp`, `chartDown` | Chart series colors. | All other tokens (background, surface, text, success/error/warning, dialog backgrounds, etc.) are owned by the tenant theme and cannot be overridden. This guarantees the mini-app looks at home in both Based and Hyena. Overrides are applied as a `ThemeExtension` scoped to the mini-app's container widget. ## Validation rules The host validates the manifest in two stages. ### Static validation (at bundle install) 1. JSON parses cleanly. 2. All required fields present. 3. All field types correct. 4. `id` regex matches. 5. `version` is valid semver and strictly greater than the previously installed version (if any) for the same `id`. 6. `permissions` keys are all known. 7. `permissions.signing` does not appear without `permissions.auth.addresses`. 8. `permissions.network` patterns are syntactically valid. 9. `permissions.storage` quota is within bounds. 10. `theme.overrides` keys are all in the allowlist. 11. `signature` (when present) verifies against a trusted public key. Any failure → installation rejected. The user sees a host-rendered error. ### Boot-time validation 1. `minHostVersion` ≤ current host version. 2. `targetSdkVersion` ≤ current SDK version. 3. Bundle hasn't been tampered with (re-verify signature). 4. Mini-app id is not on the kill list (see `09`). ## Permission grant model There are two grant tiers in v1. | Tier | What it means | UX | | --------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------- | | **Manifest-declared** | The mini-app *requests* this. | Listed on the install / first-launch consent sheet. | | **Per-action confirmation** | The user must approve every individual sensitive action. | Modal sheet at call time (signing, opening external deep links). | Manifest-declared permissions become **active** when the user first launches the mini-app and accepts the consent sheet. The user can revoke at any time from the mini-app's settings page (host-rendered, lists every granted permission with toggles). Per-action confirmations are non-bypassable: even an "auto-trust" toggle would not skip them for `signing.*` or `nav.openDeepLink` for external schemes. ## Future fields (placeholders, not implemented) These are reserved in the schema but rejected by the validator until implemented: * `runtime: "sdui"` — server-driven UI fallback (Option B). * `permissions.camera`, `permissions.location` — sensor access. * `nativeExtensions` — first-party-only native module extension surface. Read [`05-js-runtime.md`](/docs/integrations/mini-apps-platform/05-js-runtime.md) next.