Build mini apps for Hypersnap
For developers. Quilcast, November 2026.
Hypersnap is the Farcaster network that Quilibrium runs, and Hypersnap clients such as Quilcast run standard Farcaster mini apps. The SDK, the manifest and the notification format are all the same as elsewhere. What differs is how your server checks who someone is. The usual checks look things up on Optimism, and accounts created on Hypersnap were never registered there, so this page shows checks that ask a Hypersnap node instead, with Snapchain (the network the Farcaster app uses) as an optional second place to look. Cast actions are mini apps too, so all of this applies to them as well, and Build a cast action covers what's specific to them.
What's different on Hypersnap
- New accounts live only on Hypersnap. Since Hypersnap forked from Snapchain on November 12, 2026, accounts are registered on Hypersnap itself, with no Optimism transaction and no ETH. Their FIDs start at 232 (4,294,967,296), so store FIDs as 64-bit integers or JavaScript numbers, never as 32-bit ones. Accounts registered on Optimism before the fork exist on both networks.
- Keys are added without gas. Apps add signers with a Hypersnap message instead of a KeyRegistry transaction on Optimism. Hypersnap's shuttle relays those key changes, and casts, to Snapchain for accounts that exist on both networks.
- Anyone can read the network. A Hypersnap node answers the usual hub API under
/v1and Neynar-shaped reads under/v2/farcaster, with CORS open, so your page can call it straight from the browser. Quilcast useshttps://haatz.quilibrium.com, and you can too.
const NODE = 'https://haatz.quilibrium.com'
const { user } = await fetch(`${NODE}/v2/farcaster/user?fid=${fid}`).then((r) => r.json())
const { cast } = await fetch(`${NODE}/v2/farcaster/cast?type=hash&identifier=${hash}`).then((r) => r.json())
Sign in
sdk.actions.signIn({ nonce }) works as it does in any client, and returns a Sign In With Farcaster message and its signature. On your server, check the signature and your nonce, and then check that the address that signed is the FID's custody address. @farcaster/auth-client's usual setup does that last step on Optimism, which can't see accounts created on Hypersnap. This version checks Hypersnap first and Snapchain after it, and needs only viem:
import { createPublicClient, http } from 'viem'
import { optimism } from 'viem/chains'
import { parseSiweMessage } from 'viem/siwe'
const HYPERSNAP = 'https://haatz.quilibrium.com'
const SNAPCHAIN = 'https://crackle.farcaster.xyz:3381' // optional: Optimism accounts registered after the fork
const client = createPublicClient({ chain: optimism, transport: http() })
/** Whether `address` is the custody address of `fid`. */
async function ownsFid(address, fid) {
address = address.toLowerCase()
const u = await fetch(`${HYPERSNAP}/v2/farcaster/user?fid=${fid}`).then((r) => (r.ok ? r.json() : null), () => null)
if (u?.user?.custody_address?.toLowerCase() === address) return true
const e = await fetch(`${SNAPCHAIN}/v1/onChainIdRegistryEventByAddress?address=${address}`).then((r) => (r.ok ? r.json() : null), () => null)
return Number(e?.fid) === fid && e?.idRegisterEventBody?.to?.toLowerCase() === address
}
/** The FID a sign-in proves, or null. `nonce` is the one you gave the app, `domain` your host. */
export async function verifySignIn({ message, signature }, { nonce, domain }) {
const m = parseSiweMessage(message)
const fid = Number(m.resources?.find((r) => r.startsWith('farcaster://fid/'))?.slice('farcaster://fid/'.length))
if (!fid || m.nonce !== nonce || m.domain !== domain || (m.expirationTime && m.expirationTime < new Date())) return null
if (!(await client.verifyMessage({ address: m.address, message, signature }))) return null
return (await ownsFid(m.address, fid)) ? fid : null
}
Quilcast signs in with the custody address. Some Snapchain clients sign with an "auth address" instead, a key the account adds on Optimism for this purpose. If you need those too, check them with @farcaster/auth-client as well.
Notifications
Notifications use the standard flow. Your manifest has a webhookUrl, the client POSTs signed events to it when someone turns notifications on or off, each notifications_enabled or miniapp_added event carries a { url, token }, and you POST notifications to that url. Sending is the same everywhere, and only the webhook needs care.
Each event is a JSON Farcaster Signature: it names an FID and a key, and is signed by that key. @farcaster/miniapp-node's parseWebhookEvent checks the signature, then asks you whether that key belongs to that FID. The verifiers it ships with only accept keys added on Optimism through the KeyRegistry. Quilcast signs events with the account's own gasless signer instead, so that every account can turn notifications on for free, and accounts created on Hypersnap have no other kind of key. So hand parseWebhookEvent a check that reads the account's signers from a Hypersnap node, which lists gasless keys and keys added on Optimism alike:
import { parseWebhookEvent } from '@farcaster/miniapp-node'
const NODES = [
'https://haatz.quilibrium.com', // Hypersnap: every account, and keys from both kinds
'https://crackle.farcaster.xyz:3381', // Snapchain (optional): app keys added on Optimism after the fork
]
/** Whether `appKey` is one of `fid`'s current keys, the way parseWebhookEvent asks. */
export async function verifyAppKey(fid, appKey) {
for (const node of NODES) {
const r = await fetch(`${node}/v1/signersByFid?fid=${fid}`).then((r) => (r.ok ? r.json() : null), () => null)
const s = r?.signers?.find((s) => s.key.toLowerCase() === appKey.toLowerCase())
if (s && (!s.expiresAt || s.expiresAt * 1000 > Date.now())) return { valid: true, appFid: Number(s.requestFid || fid) }
}
return { valid: false }
}
app.post('/webhook', async (req, res) => {
let data
try {
data = await parseWebhookEvent(req.body, verifyAppKey)
} catch {
return res.status(401).json({ error: 'bad event' }) // 401 lets a client retry with another key
}
const { fid, event } = data
if (event.event === 'miniapp_added' || event.event === 'notifications_enabled') {
if (event.notificationDetails) saveToken(fid, event.notificationDetails) // { url, token }
} else forgetTokens(fid) // miniapp_removed, notifications_disabled
res.json({ ok: true })
})
- Answer 401 when you refuse a key. If your webhook refuses an event Quilcast signed with a gasless signer, Quilcast sends it again signed with a key added on Optimism, which it adds with a small transaction the first time. That fallback is how webhooks that only know Optimism keys keep working, but accounts created on Hypersnap can't use it.
- Gasless keys expire when they go unused for a while (
expiresAt), and the check above treats an expired key as gone. Tokens you already saved keep working: a token is checked by the client that issued it, not by key. - Hypersnap only: remove the Snapchain line. You then still accept every Hypersnap account and every Optimism account registered before the fork, but not app keys that the Farcaster app adds on Optimism after it.
To send, POST { notificationId, title, body, targetUrl, tokens } to the token's url, exactly as the Farcaster guide describes. In Quilcast, notifications show up in the Mini apps tab of Notifications, and as a push when the person has push turned on. Build a cast action walks through Remind me, which sends notifications end to end and works in any client.
Which network knows what
- Accounts created on Hypersnap (FID 232 and up), their keys and their casts exist only on Hypersnap.
- Accounts registered on Optimism before the fork exist on both networks. Keys they add without gas, such as Quilcast's, show up on both, because Hypersnap's shuttle relays them.
- Accounts and keys added on Optimism after the fork, such as the app keys the Farcaster app adds for notifications, show up only on Snapchain, because Hypersnap no longer reads Optimism.
So a check that reads Hypersnap first and Snapchain second accepts everyone, and a Hypersnap-only check accepts everyone except Farcaster app users who joined, or turned notifications on, after the fork.
Test it in Quilcast
- Serve your app over https on a public address (a tunnel such as
cloudflared tunnel --url http://localhost:5173works while you build). - In Quilcast, open Mini apps, paste the link and tap Open. A cast action can also be added at
https://quilcast.com/actions?add=your-host. - Turn notifications on from the app (
sdk.actions.addMiniApp()) or with the bell next to it on the Mini apps page. Your webhook should receive an event signed by a key thatverifyAppKeyaccepts.
Build a cast action · About Quilcast · Privacy policy · Terms of use