Build a Casa Tookan app

At a glance

What each part of the manifest changes for the user.

The manifest

At https://<your-domain>/.well-known/casatookan.json. Only version and app.name are required; every other field is read leniently — one that fails its check is ignored, the rest still applies.

{
  "version": "1",
  "app": {
    "name": "Orb Quest",
    "iconUrl": "https://orbquest.game/icon.png",
    "homeUrl": "https://orbquest.game/play",
    "heroImageUrl": "https://orbquest.game/hero.png",
    "splashImageUrl": "https://orbquest.game/splash.png",
    "splashBackgroundColor": "#101820",
    "subtitle": "Duel with your orbs",
    "description": "A card game played with your Counterparty assets.",
    "primaryCategory": "games",
    "tags": ["cards", "counterparty"],
    "chains": {
      "required": ["bip122:000000000019d6689c085ae165831e93"],
      "optional": ["eip155:8453"]
    },
    "capabilities": {
      "required": ["provider.counterparty", "casatookan.ready"],
      "optional": []
    }
  }
}

version is "1": any 1.x is read as v1, another major version is ignored.

Fields of app

URLs must be http(s) — use https.

association — planned

Proof that the domain belongs to you, in the shape of Farcaster’s accountAssociation:

• header — base64url JSON { "type": "casatookan", "address": "…" }, a casa address (legacy Bitcoin, or EVM);
• payload — base64url JSON { "domain": "your-domain" };
• signature — base64url signature of header + "." + payload by that address: BIP-137 for Bitcoin, EIP-191 for EVM.

Stored by Casa Tookan, not verified yet. It will be required for anything scoped to your domain.

Images

The icon sits on light and dark backgrounds: give it its own background rather than transparency. Without a banner, Browse falls back to your Farcaster manifest’s images (3:2 ones are cropped to 1.91:1), then to your icon over a blurred copy of itself.

Chains

CAIP-2 ids. Anything else is ignored.

Capabilities

A required chain or capability Casa Tookan lacks shows the user a dismissible notice — your app still opens. Optional ones are informative.

In the page

Injected before your own scripts. Signing goes through the standard providers above: there is no Casa Tookan-specific signing API.

window.casaTookan = {
  isCasaTookan: true,
  version: '1',
  ready(),   // hide the splash screen
};

if (window.casaTookan?.isCasaTookan) {
  // running inside Casa Tookan
}

window.addEventListener('load', () => {
  renderFirstScreen();
  window.casaTookan?.ready();
});

How Casa Tookan reads it

Farcaster mini apps

Casa Tookan also reads /.well-known/farcaster.json and hosts mini apps built on @farcaster/miniapp-sdk when the active casa owns a Farcaster account: context, Sign In With Farcaster, the wallet, haptics. Serve both manifests and they are merged field by field, casatookan.json first — you only need a casatookan.json to override what differs in Casa Tookan, or to declare Bitcoin and Counterparty.

Not supported: adding the mini app and its notifications (no notification server), posting casts (handed to farcaster.xyz).

Validator

Applies the same rules as the app. Paste your manifest, or load it from your domain — that needs your server to send Access-Control-Allow-Origin; Casa Tookan itself doesn’t.