> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uos.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# Manifest

> uos-app.json field reference for Mini Apps

Serve your manifest at:

```
https://<your-domain>/.well-known/uos-app.json
```

uOS fetches that URL server-side when you publish. Redirects are rejected (`redirect: 'error'`; 3xx responses fail). The response must be JSON, under 512 KB, within 5 seconds.

Example:

```json theme={null}
{
  "name": "Mpay",
  "slug": "mpay",
  "version": "1.0.0",
  "description": "Send tokens without paying gas. Gasless stablecoin and ERC-20 transfers powered by x402 and EIP-2612 permits.",
  "icon": "https://pay.mrdn.finance/mpay-app-icon.svg",
  "category": "Payments",
  "tags": ["payments", "x402", "gasless", "stablecoin"],
  "screenshots": ["https://pay.mrdn.finance/og-image.png"],
  "entry": {
    "type": "iframe",
    "url": "https://pay.mrdn.finance/"
  },
  "permissions": ["wallet:request", "wallet:sign"],
  "author": {
    "wallet": "0xYourWalletAddress"
  },
  "signature": "0x…"
}
```

## Fields

| Field              | Required               | Notes                                                                                                                                                           |
| ------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | yes                    | Display name (≤ 255 chars)                                                                                                                                      |
| `entry.type`       | yes                    | Must be `"iframe"`                                                                                                                                              |
| `entry.url`        | yes                    | Public `http:` or `https:` URL on the **same host** as the manifest. Localhost, private, link-local, and userinfo URLs are rejected                             |
| `author.wallet`    | for Dev Portal publish | EVM address; must match the wallet that signs in Dev Portal                                                                                                     |
| `slug`             | no                     | ≤ 64 chars                                                                                                                                                      |
| `version`          | no                     | Shown in the store (≤ 32 chars)                                                                                                                                 |
| `description`      | no                     | Store list and details (≤ 4000 chars; truncated if longer)                                                                                                      |
| `icon`             | no                     | `http:`, `https:`, or `data:image/…` URL (≤ 2048 chars). Other schemes are dropped                                                                              |
| `category`         | no                     | Defaults to `"Apps"` (≤ 64 chars)                                                                                                                               |
| `tags`             | no                     | Up to 16 strings (each ≤ 32 chars)                                                                                                                              |
| `screenshots`      | no                     | Up to 12 `http:` / `https:` / `data:image/…` URLs (each ≤ 2048 chars)                                                                                           |
| `permissions`      | no                     | From the allowlist below; unknown values are stripped                                                                                                           |
| `price.amountUsdc` | no                     | Non-negative decimal USDC string (for example `"5"` or `"5.5"`). Max `100000`. Extra fractional digits beyond 6 are truncated. Absent, `"0"`, or invalid → free |
| `author.did`       | no                     | Stored if present; reserved for later identity work                                                                                                             |
| `signature`        | no                     | Domain-association signature for the Verified badge                                                                                                             |

`authorVerified` in a raw manifest is ignored. uOS sets it only after signature verification at registration.

Unknown fields are not persisted.

## Permissions

Users see these in the App Store before install. Declare only what you use:

| Permission         | What the store shows                                                  | Runtime                                                                           |
| ------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `wallet:request`   | Read your connected wallet address and chain                          | Required for wallet reads                                                         |
| `wallet:sign`      | Request transactions and signatures (each one requires your approval) | Required for wallet writes                                                        |
| `filesystem:read`  | Read files from your uOS virtual filesystem                           | Scoped to `/apps/<your-app-id>/…`                                                 |
| `filesystem:write` | Write files to your uOS virtual filesystem                            | Same app-scoped directory                                                         |
| `network:fetch`    | Fetch external URLs through the uOS proxy                             | Host-mediated public http(s) only                                                 |
| `agents:call`      | Call uOS agents and MCP tools on your behalf                          | Declared but not implemented yet (`4100` without permission; `4200` when granted) |
| `storage:ipfs`     | Store data on IPFS through uOS                                        | Declared but not implemented yet (`4100` without permission; `4200` when granted) |

If a later publish **adds** permissions, the next open prompts for re-consent. New permissions stay disabled until the user approves. Removing permissions does not require re-consent. The domain-association `signature` does not cover permissions.

## Verified author

To show the **Verified** badge, sign this exact message with `author.wallet` and put the result in `signature`:

```
uOS Mini App Domain Association v1
domain: <manifest host, lowercase>
entry: <entry.url exactly as in the manifest>
wallet: <author.wallet, lowercase>
```

Example with viem:

```ts theme={null}
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AUTHOR_KEY);
const signature = await account.signMessage({
  message: [
    "uOS Mini App Domain Association v1",
    "domain: pay.mrdn.finance",
    "entry: https://pay.mrdn.finance/",
    `wallet: ${account.address.toLowerCase()}`,
  ].join("\n"),
});
```

Rules enforced at publish time:

* No `signature` → app registers as **Unverified** (still allowed)
* Invalid `signature` → **publish fails** (it will not silently become Unverified)
* Re-sign when `domain`, `entry.url`, or `author.wallet` changes (a new `version` alone does not require a new signature)
* Verification uses the same wallet verifier as the rest of uOS (EOA and smart-contract wallets via EIP-1271 / ERC-6492)

## Next

[Publish your app](/developers/publish) from Dev Portal, then optionally wire up the [App SDK](/developers/sdk).