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
- 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. - Your action's name and icon then show up in the ⋯ menu under every cast they see.
- When they tap it, Quilcast opens your
castShareUrlas a mini app, with the cast in the query string and in the SDK context. - 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"
}
}
castShareUrlmust be an absolute https URL on the same origin as the manifest. Quilcast ignores one that points elsewhere.nameis the menu label, so keep it short: two words is ideal, and the mini app spec allows 32 characters.iconUrlis a square PNG (1024×1024 without transparency is what Farcaster clients want), drawn at 18 px in the menu.subtitle(ordescription) is the line shown under the name when someone adds your action by link.- Quilcast doesn't require
accountAssociation, but other Farcaster clients do, so sign your domain anyway. webhookUrlis only needed if you send notifications (see Send notifications below).
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:
sdk.actions.sendToken({ token, amount, recipientFid })sends a token to the cast's author. Quilcast finds the author's verified address, shows who and how much, and the person's wallet confirms it.sdk.actions.composeCast({ text, parent: { type: 'cast', hash } })opens the composer with a reply to the cast, which the person can edit before they send it.sdk.actions.addMiniApp()asks to add your app, with notifications, and returnsnotificationDetailswhen they're turned on.sdk.actions.signIn({ nonce })returns a Sign In With Farcaster message and signature that prove who the person is (see Trust, below).sdk.wallet.getEthereumProvider()gives you an EIP-1193 provider for anything else on chain. Quilcast checks each request and asks the person first.sdk.actions.viewCast,viewProfile,openUrl,openMiniApp,swapToken,viewToken,setPrimaryButtonandcloseare all available as well, and so is haptics on phones.
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.
- Add a
webhookUrlto your manifest. Quilcast only offers notifications for apps whose manifest has one, and so do other clients. It has to answer200, but a cast action can leave the events it receives alone (see step 4). - 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. - Hand the token to your server with whatever the notification needs, such as the cast's hash and when to send it.
- 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 ininvalidTokens, 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 inrateLimitedTokensagain later: Quilcast takes one notification per token every 30 seconds and 100 a day. - Handle the tap. Tapping the notification opens its
targetUrlin your app, withlocation.typeset tonotificationin the context, and from theresdk.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'}.` })
})
- Reply within 10 seconds, with JSON. The
messageis plain text: the client shows it as a toast after your action's name and cuts it at 80 characters. Any status other than 2xx is shown as a failure, with yourmessagewhen there is one. - Answer CORS. A client may send the request straight from the person's browser, as Quilcast does, so allow any origin and the
content-typeheader, and answer theOPTIONSpreflight. - Check all three: the
type, theurland thetimestamp. That way a request signed for another action, or a webhook event, is refused even though its signature is valid. - People can remove an entry from the client's list of actions at any time, and removing your app removes all of its entries.
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
- The context isn't proof. Anyone can open your URL with any
castHashorviewerFid, andsdk.context.useris whatever the host says. Before you spend, store or post anything for someone, have them sign in withsdk.actions.signIn({ nonce })and verify the result on your server: check the Sign In With Ethereum signature and your nonce, then check that the signing address is the FID's custody address on Hypersnap. Build for Hypersnap has the whole check, which works for accounts created on Hypersnap too. - Read the cast from the network when it matters. The cast in the context is a convenience. If your action depends on what it says, fetch it by hash from a Hypersnap node, for example
https://haatz.quilibrium.com/v2/farcaster/cast?type=hash&identifier=0x…. - What Quilcast guards. Your app runs in a sandboxed frame on your own origin. Adding an action only reads your manifest, through Quilcast's server, so nothing about a person or a cast reaches you until they tap it. Every wallet request is shown to the person before their wallet sees it, and Quilcast refuses requests that could take over a Farcaster account. Quilcast reviews the actions on its official list, but not the ones people add by link, and it tells them so.
- What a one-click action can and can't do. The signed request says only that this account tapped this entry on this cast at this time, with this text. The client writes it, and your app only chose the URL when the entry was added. It isn't a Farcaster message, so it can't post, like, follow or move money for anyone, and a one-click action never opens a window or reaches a wallet. To do more, open your mini app. What a tap shares with your server is the account's FID, the cast, the text typed, your own notification token (when notifications from you are on) and the device's IP address.
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:
- Answer
addCastAction({ name, url, placeholder })on the mini app channel, the way the client answersaddMiniApp, and listactions.addCastActioningetCapabilities. Accept the call only from the app on screen, with aurlon https and on the app's own origin, anameof 1 to 30 characters and aplaceholderof at most 40. Ask the person in your own UI, showing the name and the host, and keep at most 10 entries per app. - List the entries in the cast menu. On a tap, ask for one line of text if the entry has a placeholder.
- 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. - Show the reply as a toast: the entry's name, then the
messagecut to 80 characters, as plain text. Give up after 10 seconds, and remove an app's entries when the app is removed.
Test it
- Serve your app over https on a public address (a tunnel such as
cloudflared tunnel --url http://localhost:5173works while you build). - Open
https://quilcast.com/actions?add=your-tunnel-hostand tap Add. - 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.