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

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 })
})

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

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

  1. Serve your app over https on a public address (a tunnel such as cloudflared tunnel --url http://localhost:5173 works while you build).
  2. 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.
  3. 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 that verifyAppKey accepts.

Build a cast action · About Quilcast · Privacy policy · Terms of use