dApp connections & deep links
The connection and signature sheets put the casa first: its color, its house, its name, its address. Casa remembers, on this device, which casa connected to which site. It suggests the right casa but never switches on its own, and it picks the right Bitcoin address. The same sheet answers the in-app browser, WalletConnect and apps that log in through a casatookan:// link.
Flow
Example wallet: three casas in two estates, plus imported keys. “Casa Yodark” owns the Farcaster account @yodark and has already connected to Velocimon. The active casa is “Ma Casa”.
Connect to Velocimon?
The casa is the hero of the sheet. Nothing changes without the user: the active casa stays selected, and Casa offers, in one tap, the casa that already knows the site.
Velocimon will see the address of the casa you choose.
The choice happens in the same sheet (‹ Back), without losing the request. Each row says what is special about it here. An incompatible casa stays visible with the reason, instead of disappearing.
Sign in to Velocimon
After “Use it”, a toast confirms the switch and lets the user undo it. The button names the identity (@yodark), not a vague action such as “Approve”.
Sign in to Velocimon
Velocimon signs you in with a Farcaster account.
No disabled button without an explanation: the primary action becomes the fix. When no casa owns a Farcaster account, it becomes “Import your Farcaster account” (recovery phrase).
Connect to ORBital?
bc1q9h7…kx4z
Lower fees, works with most sites
1BvBM…NVN2
Older sites and Counterparty
bc1p5d…8x2q
Ordinals and inscriptions
With no history, SegWit is preselected. Each type shows the start of its address (bc1q, 1, bc1p), so the user can compare it with what the site displays.
Connect to ORBital?
1Ca5a…T00k
12 cards · 0.0042 BTC
bc1qx2…7mnp
Empty
bc1pw8…q0lz
Empty
When Legacy holds coins or Counterparty assets and SegWit is empty, Legacy is preselected, with the reason in plain sight (“12 cards · 0.0042 BTC”). The user can always change it.
Casa YodarkSignature request
Signatures and transactions come from a site that already knows an address: the casa is locked, there is no “Change”. To switch account, tap the casa pill in the address bar.
Saved on this iPhone only. Kept when you remove an estate, so you can still see which address a site knows.
The index is local to the device and survives the removal of an estate: a vanished casa stays listed in grey, with its last known name.
Ethereum · @yodark
Connected 5 Oct · used 3 days ago
Ethereum · estate removed 1 Oct
Connected 12 Aug
Disconnecting stops Casa from answering this site with that address. The site may still remember it on its own servers.
The user sees exactly which address the site knows. “Disconnect” ends the connection, “Forget” erases the row of a vanished casa.
Sign in to ctserver.everdreamsoft.com
An app or a web page asks for the casa’s addresses with getaddress. Same sheet, same rules: the requester is named by its callback (an app scheme, or the host of an https page), the casa can be changed, and the answer is remembered in Connected sites.
Rules
What Casa preselects in each situation. It never switches casa without a tap from the user.
| Situation | Preselected casa | What the user sees |
|---|---|---|
| The active casa is already connected to the site | The active casa | Green chip “Connected here since…”. No suggestion. |
| The active casa is new to the site, another casa knows it | The active casa | Chip “First time on this site” and a single suggestion: the casa used most recently on this site, with “Use it”. The others are marked in the picker. |
| No casa knows the site | The active casa | Chip “First time on this site”, no suggestion. |
| The known casa belongs to a removed estate | The active casa | No suggestion (it can no longer sign). It stays visible in Settings › Connected sites. |
| Farcaster sign-in, the casa does not own the account | The active casa | A warning, and the primary button “Use <casa that owns the account>”. When no casa owns one: “Import your Farcaster account”. |
| The site asks for Ethereum and the casa is a Bitcoin-only key (or the reverse) | — | The row stays in the picker, disabled, with the reason. |
| Signature or transaction from a connected site | The connected casa, locked | No “Change”: the site expects this address. The account is switched from the casa pill in the address bar, and the site then receives accountsChanged. |
| Bitcoin address already chosen for this site and this casa | The same type | The remembered choice, which can be changed. |
| Bitcoin address, first time | Legacy when it holds BTC or Counterparty assets and SegWit is empty. SegWit otherwise. | The reason under the choice (“12 cards · 0.0042 BTC”). Taproot is never preselected. |
Where it applies
One sheet and one connection index serve every way a site or an app can reach the wallet.
In-app browser
- The injected providers (EIP-1193, sats-connect, web3XCP) open the sheet for every connection, signature and transaction.
- Casa pill: always shown at the right of the address bar with the active casa’s house; a green dot marks a casa connected to the open site. Tapping it switches the casa this site sees.
WalletConnect
- Sessions use the same sheet and the same index. The site is identified by the metadata of the pairing (origin, name, icon).
- Recorded with
via: "walletconnect".
casatookan:// links
- Web3 logins from other apps and web pages (
getaddress,signForAddress) use the same sheet. See Deep links. - Recorded with
via: "deeplink", under the app’s scheme (sogapp://) or the page’s origin. - Signing with another casa does not change the active casa: the app gets that casa’s addresses, the wallet stays put.
Connection index
Stored on the device (AsyncStorage), outside the vault and the estates. A casa is identified by its address, never by its index, which moves when an estate is removed. Its name, color and estate are copied at connection time, so a vanished casa can still be shown. The index starts empty: connections made before it existed are not migrated, so each casa is “First time” once per site.
// key: "dappConnections.v1"
{
"https://farcaster.velocimon.com": {
"origin": "https://farcaster.velocimon.com",
"name": "Velocimon",
"icon": "https://farcaster.velocimon.com/…/icon.png",
"via": "browser", // "browser" | "walletconnect" | "deeplink"
"connections": [{
"chain": "evm", // "evm" | "bitcoin"
"address": "0x1614…1313", // stable identity
"btcPurpose": null, // "segwit" | "legacy" | "taproot"
"farcasterFid": 399250,
"casa": { // copied at connection time
"name": "Casa Yodark",
"color": "#9B59B6",
"estateName": "Farcaster estate",
"ghost": false // imported key
},
"connectedAt": "2026-10-05T18:12:00Z",
"lastUsedAt": "2026-10-05T19:40:00Z",
"disconnectedAt": null
}]
}
}
How it is used
- When a site loads: the connections of its origin are looked up. When the active casa has one, the bridge answers
eth_accountsandgetAddressesdirectly, without asking again. - Live or vanished casa: the address is matched against the accounts of the estates present. No match = “From a removed estate”.
- Update: every approved connection, signature or transaction refreshes
lastUsedAtand the casa snapshot (name, color). - Erasing: “Disconnect” sets
disconnectedAt, “Forget” removes the row. Deleting the wallet erases the whole index. - Never in the index: keys or balances. Only what is needed to recognise a casa.
Deep links
Casa registers the casatookan:// scheme on iOS and Android. Other apps and web pages use it to open a dApp in the wallet or to log a user in with a signed challenge (the web3XCP x-callback-url protocol of the original Casa Tookan). The wallet must be unlocked: while it is locked, browse and getaddress links are ignored and not queued.
| Link | Parameters | Effect |
|---|---|---|
casatookan://browse/{url} | url: the page to open, URL-encoded. | Opens the page in the in-app dApp browser. |
casatookan://x-callback-url/getaddress?x-success={callback}&msg={message} | x-success: where the answer goes (see below).msg: the challenge to sign, URL-encoded. | Web3 login on Bitcoin + Ethereum: the signer sheet asks the user, then Casa signs msg with the chosen casa and calls the callback. |
casatookan://x-callback-url/signForAddress?chain={chains}&x-success={callback}&msg={message} | chain: comma-separated chain ids, e.g. bitcoin,base. bitcoin or any EVM chain enabled in the wallet (ethereum, base, polygon…). | Same as getaddress, on the chains listed, in that order. |
Where the answer goes: x-success
An app scheme
x-success=myapp(letters, digits,+ . -).- Casa opens
myapp://sendaddress?address=…&msg=…&sig=…. - Values are written raw, not URL-encoded, exactly like the original Casa Tookan, so existing web3XCP apps keep working. Split the query on
&address=,&msg=,&sig=rather than with a URL parser.
A web page
x-success=https://example.com/login, URL-encoded in the link.- Casa opens
https://example.com/login?address=…&msg=…&sig=…in the browser. An existing query string is kept (&is used), and so is a#fragment. - Each value is URL-encoded (base64 signatures contain
+and/): read them withURLSearchParams. - https only.
http://and any other target are refused: the signature would travel in clear.
The answer
address = chain:bitcoin;1Ca5a…T00k;;separator;;chain:ethereum;0x1614…1313 msg = the challenge, unchanged sig = chain:bitcoin;H8k2…=;;separator;;chain:ethereum;0x5f1c…1b
Format
- One
chain:{id};{value}entry per chain, in the requested order, joined by;;separator;;. Theaddressandsigentries line up. - The addresses are those of the casa the user approved in the sheet, which may differ from the active casa.
Bitcoin signature
- BIP-137 signed message, base64.
- Signed by the casa’s Legacy (P2PKH) address, the one that holds Counterparty assets, path
m/0'/0/{casa}. Verify it with any BIP-137 verifier against the returned address.
EVM signature
- Raw secp256k1 signature of
keccak256(utf8(msg)), serialized0x{r}{s}{v}withv = 27 + recid. It is not EIP-191:personal_signverifiers will reject it. - Recover the signer from the keccak digest directly (e.g. ethers
SigningKey.recoverPublicKey(keccak256(toUtf8Bytes(msg)), sig)) and compare with the returned address, pathm/44'/60'/0'/0/{casa}.
Approval and history
- The login opens the same signer sheet as the browser (step 10 above): the requester is named by its scheme or by the host of its https page, the casa can be changed, and “Cancel” sends no answer.
- The answer is remembered in Settings › Connected sites, under the scheme (
sogapp://) or the page’s origin, with the Legacy Bitcoin address and the Ethereum address that were shared. - An unsupported chain id in
chain, a missingx-successor an empty chain list makes the link invalid: nothing is shown and nothing is sent.
Tester
Open the deep link tester on the phone where Casa is installed. It builds every link above, returns to itself with Casa’s answer (x-success = its own URL), decodes it and verifies the Ethereum signature.