Your site, in every casa.

Level 0 · 0 minutes

It already works.

If your site works with MetaMask, Xverse, Magic Eden or Unisat, it works in Casa Tookan. No SDK to install, no special case in your code.

1. Open your site in the app

   In Casa Tookan, go to Browse and type your URL.

2. Connect and sign, as usual

   Every request opens Casa Tookan's signing sheet. It shows your site and the casa that signs, so you have no UI to build.

   EVM Bitcoin Counterparty

   connect.jsCopy

   const [address] = await window.ethereum.request({ method: 'eth_requestAccounts' });
   const signature = await window.ethereum.request({
     method: 'personal_sign',
     params: ['Welcome to Orb Quest!', address],
   });

3. Follow the casa

   The user can switch casa from the address bar at any time, and your page gets the usual event. Each casa also has its own localStorage, so sessions don't mix.

   connect.jsCopy

   window.ethereum.on('accountsChanged', ([next]) => setPlayer(next));

window.addEventListener('eip6963:announceProvider', (e) => {
  if (e.detail.info.rdns === 'com.everdreamsoft.casatookan') useProvider(e.detail.provider);
});
window.dispatchEvent(new Event('eip6963:requestProvider'));

// Just want to know you're inside Casa Tookan?
const inCasaTookan = window.casaTookan?.isCasaTookan === true;

Level 1 · One link

Bring players straight in.

Someone visiting your site in Safari or Chrome has no wallet there. One button opens the same page inside Casa Tookan.

<a id="open-casa" href="#">Open in Casa Tookan</a>
<script>
  document.getElementById('open-casa').href =
    'casatookan://browse/' + encodeURIComponent(location.href);
</script>

Level 2 · 5 minutes

Become an app.

Your site probably has a web manifest already. Add one wallet member and Casa Tookan shows your site as an app, not a plain website.

1 2 3 4 5 6 7

1. 1
   Banner · wallet.heroImageUrl, 1200×630
2. 2
   Icon · icons, 1024×1024 opaque
3. 3
   Name · name, 32 characters
4. 4
   Subtitle · wallet.subtitle, 30 characters
5. 5
   Category · the first of your categories
6. 6
   Chains · wallet.chains
7. 7
   Description · description, 170 characters

The Dev Playground’s page, drawn from its manifest with Casa Tookan’s layout by the validator. Your manifest fills every one of these.

• Your name and iconIn the address bar and the signing sheet
• A splash screenYour art on your colour while you load
• A card in Browse › AppsWith your banner, one tap away
• Clear requirementsA notice instead of a broken page

1. Fill in your app

   Only the name is required. The JSON updates as you type.

   Name 32 characters Subtitle 30 characters Category None gamescollectiblesfinancesocialutilitymarketplaceart-creativityeducationdeveloper-tools Splash background

   Chains you need

   Bitcoin Counterparty Ethereum Base Kaia I'll call ready()

   Whole manifest Only wallet

   For a site without a manifest yet.

   site.webmanifestCopy

   W3C standard, you may have it alreadywallet, what you add

2. Publish it

   Use either of these. Casa Tookan checks both and uses the first one that has a wallet member.

   Where	When to choose it
   Your existing manifest, linked by <link rel="manifest"> on your home page	You already have one. Keep the link in the served HTML, not added by a script.
   /.well-known/wallet-app.json	You'd rather keep it separate. Same JSON, served on its own.

   Serve it as application/json. Put the images next to it: an opaque icon of 1024×1024, a banner of 1200×630, a splash of 200×200. These are Farcaster's sizes, so one set serves both.

3. Allow browsers to read it

   Send Access-Control-Allow-Origin: * on everything under /.well-known/, 404s included, and on your images. The phone app doesn't need it, but the validator and Casa Tookan on the web do. Without it, a missing farcaster.json looks like a network failure.

   Apache nginx

   .htaccessCopy

   # THE_REQUEST, not REQUEST_URI: still /.well-known/ after a rewrite to index.php
   <If "%{THE_REQUEST} =~ m#\s/\.well-known/#">
     Header always set Access-Control-Allow-Origin "*"
   </If>

4. Check it

   The validator loads your live manifest, tests every image and shows your app the way Casa Tookan will draw it. Casa Tookan reads manifests once per launch, so restart the app to see a change.

Level 3 · One line

Lift the curtain on cue.

Declare wallet.ready in your capabilities. Your splash then stays up until your first screen is drawn, so players never see a half-loaded page.

await loadAssets();
renderTitleScreen();
window.wallet?.ready();   // the splash fades, your game is there

Level 4 · 30 minutes

Log in from anywhere.

From a normal browser or a native game, send the player to Casa Tookan with a challenge. They come back with their Bitcoin and Ethereum addresses, each proven by a signature. No password, no extension.

1. Send the player to Casa Tookan

   Your server makes a random, single-use challenge. Your page opens the link.

   login.jsCopy

   const { challenge } = await fetch('/auth/challenge').then((r) => r.json());
   
   location.href = 'casatookan://x-callback-url/getaddress'
     + '?x-success=' + encodeURIComponent('https://orbquest.game/auth/casa')
     + '&msg=' + encodeURIComponent(challenge);

2. The player approves

   They see your site on the signing sheet, pick a casa and tap Sign in. Casa Tookan then opens your callback with address, msg and sig:

   https://orbquest.game/auth/casa?address=…&msg=…&sig=…Copy

   address = chain:bitcoin;1Ca5a…T00k;;separator;;chain:ethereum;0x1614…1313
   sig     = chain:bitcoin;H8k2…=;;separator;;chain:ethereum;0x5f1c…1b

3. Verify on your server

   Check that the challenge is yours and unused, then check both signatures. Watch out: the EVM one is not personal_sign.

   verify.jsCopy

   import bitcoinMessage from 'bitcoinjs-message';
   import { recoverAddress, keccak256, toUtf8Bytes } from 'ethers';
   
   // "chain:bitcoin;1Ca5…;;separator;;chain:ethereum;0x16…" → { bitcoin, ethereum }
   const entries = (s) => Object.fromEntries(s.split(';;separator;;').map((e) => {
     const i = e.indexOf(';');
     return [e.slice('chain:'.length, i), e.slice(i + 1)];
   }));
   
   export function verifyCasaLogin(query, expectedChallenge) {
     const p = new URLSearchParams(query);
     const msg = p.get('msg');
     if (msg !== expectedChallenge) throw new Error('challenge');   // then burn it
     const addr = entries(p.get('address'));
     const sig = entries(p.get('sig'));
   
     // Bitcoin: BIP-137, signed by the Legacy address.
     if (!bitcoinMessage.verify(msg, addr.bitcoin, sig.bitcoin)) throw new Error('bitcoin');
   
     // EVM: raw secp256k1 over keccak256(msg), not EIP-191.
     const signer = recoverAddress(keccak256(toUtf8Bytes(msg)), sig.ethereum);
     if (signer.toLowerCase() !== addr.ethereum.toLowerCase()) throw new Error('ethereum');
   
     return addr;
   }

Level 5 · An afternoon Preview

Know your players.

A Casa Estates ID is one account per player, across devices and recovery phrases. Key your saves on a stable number; ask for addresses only when you need them. Built for games that hand out rewards.

1. Declare it in your manifest

   Inside your wallet member:

   site.webmanifest · walletCopy

   "capabilities": { "required": ["casatookan:identity.ceid"] },
   "extensions": {
     "casatookan": {
       "identity": { "reason": "Your CEID keeps your progress across devices." }
     }
   }

2. Sign the player in

   signin.jsCopy

   if (window.casaTookan?.ceid?.available) {
     const { nonce } = await fetch('/auth/nonce').then((r) => r.json());
     const { token } = await window.casaTookan.ceid.signIn({ nonce });
     await fetch('/auth/casa', { method: 'POST', body: token });
   }

3. Verify the token on your server

   server.js · joseCopy

   import { createRemoteJWKSet, jwtVerify } from 'jose';
   
   const JWKS = createRemoteJWKSet(new URL('https://ctserver.everdreamsoft.com/.well-known/jwks.json'));
   
   const { payload } = await jwtVerify(token, JWKS, {
     issuer: 'https://ctserver.everdreamsoft.com',
     audience: 'https://orbquest.game',
     clockTolerance: 60,
   });
   // check payload.nonce, then key the player on payload.ceid

Before you ship

Six checks. Your ticks are saved in this browser.

• Connect, sign and send once inside Casa Tookan's browser, on iOS and on Android.
• Switch casa from the address bar: your page follows accountsChanged.
• Your manifest passes the validator, images and CORS included.
• The splash ends on your first screen: not before, and not 10 seconds later.
• Login callbacks are https://, and each challenge is single-use.
• Signatures and tokens are verified on your server, never only in the page.

Toolbox