Build a cast action

For developers. Quilcast, November 2026.

A cast action is a button in the ⋯ menu under every cast in Quilcast. People pick the actions they want, and each one does something with the cast it's tapped on: it can check it, tip its author, remind you about it later, reply to it, or anything else a small web app can do.

An action is a Farcaster mini app that declares a castShareUrl in its manifest. That is the same share extension other Farcaster clients show in their share sheet, so a single app works as a Quilcast cast action and as a share target everywhere else, and a mini app that already has a share extension is already a cast action. To make sign-in and notifications work for accounts created on Hypersnap too, see Build mini apps for Hypersnap.

How it works

  1. Someone adds your action, either from the official list at quilcast.com/actions or from your own link, https://quilcast.com/actions?add=yourapp.com.
  2. Your action's name and icon then show up in the ⋯ menu under every cast they see.
  3. When they tap it, Quilcast opens your castShareUrl as a mini app, with the cast in the query string and in the SDK context.
  4. Your app does its job (shows something, asks a question, sends a token, writes a reply) and closes when it's done.

1. Declare it in your manifest

Add castShareUrl to /.well-known/farcaster.json on your domain:

{
  "accountAssociation": { "header": "…", "payload": "…", "signature": "…" },
  "miniapp": {
    "version": "1",
    "name": "Remind me",
    "iconUrl": "https://remind.example.com/icon.png",
    "homeUrl": "https://remind.example.com/",
    "castShareUrl": "https://remind.example.com/share",
    "subtitle": "A nudge about a cast later",
    "splashImageUrl": "https://remind.example.com/icon.png",
    "splashBackgroundColor": "#0d0c11",
    "webhookUrl": "https://remind.example.com/webhook"
  }
}

2. Read the cast

Quilcast opens your castShareUrl with three query parameters, the same ones the share extension spec defines, which means your server can read them before any script runs:

https://remind.example.com/share?castHash=0x5415e243853e…&castFid=2417&viewerFid=12152

Inside the app, the mini app SDK context has the whole cast:

import { sdk } from '@farcaster/miniapp-sdk'

const ctx = await sdk.context
await sdk.actions.ready()

if (ctx.location?.type === 'cast_share') {
  const { hash, text, author, embeds, channelKey, timestamp } = ctx.location.cast
  // author: { fid, username?, displayName?, pfpUrl? }
  // ctx.user is the person who tapped your action
}

Other Farcaster clients send the same shape when someone shares a cast to your app, so you write this once.

3. Do something

Everything a mini app can do in Quilcast, an action can do too. The calls you'll want most are these:

Close when you're done (sdk.actions.close()), so a quick action feels like a menu item rather than a separate app.

4. Send notifications

An action that comes back later, such as a reminder, a price alert or a watch on a thread, uses the same mini app notifications as any Farcaster mini app. A cast action only needs a small part of that flow, though: there's no home screen to build and no user database to keep, just a token, the thing you'll say, and a time.

  1. Add a webhookUrl to your manifest. Quilcast only offers notifications for apps whose manifest has one, and so do other clients. It has to answer 200, but a cast action can leave the events it receives alone (see step 4).
  2. Get a token when someone uses the action. If they already turned notifications on for your app, the context has it. If not, sdk.actions.addMiniApp() asks them to add your app with notifications, and its result has the token once they're on. Ask from a tap, at the moment the action needs it.
  3. Hand the token to your server with whatever the notification needs, such as the cast's hash and when to send it.
  4. Send it. When the time comes, your server POSTs to the token's url. The answer says which tokens worked. Stop using one that comes back in invalidTokens, because that's how a client tells you notifications were turned off or the app was removed, which means a cast action doesn't need to read or verify webhook events at all. Send one in rateLimitedTokens again later: Quilcast takes one notification per token every 30 seconds and 100 a day.
  5. Handle the tap. Tapping the notification opens its targetUrl in your app, with location.type set to notification in the context, and from there sdk.actions.viewCast({ hash }) takes the person to the cast.
// in the action, when someone picks a time
const ctx = await sdk.context
let notify = ctx.client.notificationDetails       // { url, token } once they're on
if (!notify) notify = (await sdk.actions.addMiniApp()).notificationDetails
if (!notify) return show('Reminders come as notifications, so they need to be on.')
await fetch('/api/remind', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ token: notify.token, url: notify.url, hash: ctx.location.cast.hash, at: Date.now() + 3 * 3600e3 }),
})

// on your server, when it's due
const r = await fetch(reminder.url, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    notificationId: `remind-${reminder.id}`,   // the same id twice within a day is shown once, so retries are safe
    title: 'Reminder',                          // at most 32 characters
    body: '@dwr: the cast you asked about',     // at most 128
    targetUrl: `https://remind.example.com/?castHash=${reminder.hash}`,   // on your own domain
    tokens: [reminder.token],                   // up to 100 per request
  }),
})
const { result } = await r.json()   // { successfulTokens, invalidTokens, rateLimitedTokens }

// the webhook: acknowledge the events; an invalid token tells you the rest
app.post('/webhook', (req, res) => res.json({ ok: true }))

If you'd rather learn about tokens from the webhook, for example to notify people who added your app without using the action, verify each event first with @farcaster/miniapp-node's parseWebhookEvent. Pass it the Hypersnap-aware key check from Build for Hypersnap, though, not the stock one: the stock check only knows keys added on Optimism, so it refuses events from Quilcast and from every account created on Hypersnap.

In Quilcast, notifications from cast actions land in the Mini apps tab of Notifications, and they also arrive as a push when the person has turned push on for mini apps on the Mini apps page. Tapping one opens your app on its targetUrl.

Quilcast signs those events with the person's own Farcaster signer, so turning notifications on costs nothing and works for every account, including ones created on Hypersnap. A webhook that checks keys on Hypersnap (and, optionally, Snapchain) accepts them. If your webhook refuses the event because it only accepts keys added on Optimism, Quilcast sends it again signed with an on-chain app key, which it adds with a small transaction the first time. Accounts created on Hypersnap don't have one, so check keys on Hypersnap if you want to reach them.

A mini app you already have

An existing mini app becomes a cast action once its manifest has a castShareUrl, with no separate app needed. Everyone who has added it in Quilcast finds the action in their ⋯ menu without doing anything, and anyone who adds it later gets the action along with it. Notification tokens belong to your domain, so the token someone gave your mini app already works for notifications about what they did in the action, and the other way round.

5. One-click actions

Some jobs don't need a window. "Remind me in 1 day" or "Save to my reading list" should just happen, with a short confirmation. A one-click action is a ⋯ menu entry that runs your server instead of opening your app: the client sends a signed request to your URL and shows your reply as a toast. Add a placeholder and the client first asks for one line of text, so "Remind me in…" with 1 week as its placeholder lets people type how long, without opening anything.

Your mini app adds them, and the person confirms each one. Remind me, for example, offers "Add to the ⋯ menu" next to its durations:

import { sdk, miniAppHost } from '@farcaster/miniapp-sdk'

if ((await sdk.getCapabilities()).includes('actions.addCastAction')) {
  const r = await miniAppHost.addCastAction({
    name: 'Remind me in 1 day',                          // the menu label, up to 30 characters
    url: 'https://remind.example.com/api/action?in=1d',  // https, on your app's own origin
    // placeholder: '1 week',                            // ask for one line of text first
  })
  // r: { added: true } or { added: false, reason: 'rejected_by_user' | 'invalid' | 'limit' }
}

miniAppHost is the SDK's own channel to the client, so this needs nothing beyond @farcaster/miniapp-sdk. In TypeScript, cast it to any first, because the call isn't in the SDK's types yet. A client that doesn't have one-click actions doesn't list the capability, and then your app works as before.

When someone taps the entry, the client POSTs to your url with a JSON Farcaster Signature as the body, the same format as webhook events, signed with one of the person's Farcaster keys. Its payload is:

{
  "type": "cast_action",                   // never a webhook event
  "url": "https://remind.example.com/api/action?in=1d",   // the URL this was meant for
  "cast": { "hash": "0x5415e243853e…", "fid": 2417 },
  "input": "1 week",                       // only with a placeholder: what they typed
  "notificationDetails": { "url": "…", "token": "…" },   // only when notifications from you are on
  "timestamp": 1795038000000               // milliseconds
}

Check it with @farcaster/miniapp-node and the Hypersnap-aware verifyAppKey, then reply with { message }:

import { verifyJsonFarcasterSignature } from '@farcaster/miniapp-node'

const URL_OF_THIS = 'https://remind.example.com/api/action'

app.options('/api/action', (req, res) => res.set(CORS).sendStatus(204))
app.post('/api/action', async (req, res) => {
  res.set(CORS)   // { 'access-control-allow-origin': '*', 'access-control-allow-headers': 'content-type' }
  let fid, p, url
  try {
    const v = await verifyJsonFarcasterSignature(req.body, verifyAppKey)
    fid = v.fid
    p = JSON.parse(Buffer.from(v.payload).toString())
    url = new URL(p.url)
  } catch {
    return res.status(401).json({ message: 'Could not check who you are.' })
  }
  // written as "not within 5 minutes", so a missing timestamp (NaN) is refused too
  if (p.type !== 'cast_action' || url.origin + url.pathname !== URL_OF_THIS || !(Math.abs(Date.now() - p.timestamp) < 300e3))
    return res.status(401).json({ message: 'That request is not for this action.' })
  if (!p.notificationDetails) return res.status(400).json({ message: 'Turn notifications on for Remind me first.' })
  const days = url.searchParams.get('in') === '1d' ? 1 : parseDays(p.input)
  await saveReminder({ fid, cast: p.cast, at: Date.now() + days * 86400e3, notify: p.notificationDetails })
  res.json({ message: `I'll remind you in ${days} day${days === 1 ? '' : 's'}.` })
})

One-click actions are Quilcast's addition to mini apps, not part of the Farcaster spec. They're small on purpose, so that any Hypersnap client can support them (see For client developers), and they're built only from things clients already do: the mini app channel, the cast menu, and JSON Farcaster Signatures.

Examples

Quilcast's own actions are small, framework-free pages that you can read and copy. Their source is in actions/ in the Quilcast repo.

Spam check

spamcheck.quilcast.com doesn't ask anything. It reads castHash and castFid, asks the free spam.quilcast.com API, and shows two numbers:

const hash = cast.hash.replace(/^0x/, '')
const scores = await fetch(`https://spam.quilcast.com/scores?h=${hash}`).then((r) => r.json())
const users = await fetch(`https://spam.quilcast.com/users?fid=${cast.author.fid}`).then((r) => r.json())
// scores[hash] and users[fid] are 0…1, or missing while the model hasn't read them yet

Tip

tip.quilcast.com offers $1, $5, $10 or any amount, then hands the rest to the host:

const USDC_ON_BASE = 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
const r = await sdk.actions.sendToken({
  token: USDC_ON_BASE,
  amount: String(5 * 1e6),          // base units: USDC has 6 decimals
  recipientFid: cast.author.fid,
})
if (r.success) { /* r.send.transaction is the hash */ }

Remind me

remind.quilcast.com is the notifications flow above, end to end. It offers 1 hour to 30 days or any number of minutes, hours, days or weeks, and asks to turn notifications on the first time someone uses it. When the reminder is due, the Quilcast server sends it to the token's URL, and tapping it opens the action again with the cast and an Open the cast button. The page is actions/remindme/ and the server part, which keeps the reminders and sends them, is server/remind.mjs.

Trust

For client developers

Any Hypersnap or Farcaster client can run the same cast actions. The open kind is the standard share extension: open the mini app at its castShareUrl with castHash, castFid and viewerFid, and set location to { type: 'cast_share', cast }. One-click actions take four more things:

  1. Answer addCastAction({ name, url, placeholder }) on the mini app channel, the way the client answers addMiniApp, and list actions.addCastAction in getCapabilities. Accept the call only from the app on screen, with a url on https and on the app's own origin, a name of 1 to 30 characters and a placeholder of at most 40. Ask the person in your own UI, showing the name and the host, and keep at most 10 entries per app.
  2. List the entries in the cast menu. On a tap, ask for one line of text if the entry has a placeholder.
  3. Send the request. Build the payload above, with the person's notification token for that origin when they have notifications on. Sign it as a JSON Farcaster Signature ({ fid, type: 'app_key', key } header) with a key the network lists for the account. Quilcast uses the account's gasless signer. Then POST it to the URL.
  4. Show the reply as a toast: the entry's name, then the message cut to 80 characters, as plain text. Give up after 10 seconds, and remove an app's entries when the app is removed.

Test it

  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. Open https://quilcast.com/actions?add=your-tunnel-host and tap Add.
  3. Open any cast's ⋯ menu and tap your action. Quilcast caches manifests for ten minutes, so to pick up a changed manifest, remove the action and add it again after that.

Get on the official list

The list at quilcast.com/actions lives in src/actions.json. To add yours, open a pull request (or an issue) on git.borodutch.com/backmeupplz/quilcast with one line: its castShareUrl, name, icon and a short description. We list actions that work, do what their description says, and don't ask for a wallet signature that the job doesn't need. Until it's listed, share your quilcast.com/actions?add= link, which works for anyone.

About Quilcast · Privacy policy · Terms of use