Quests as blinks

Let members complete a Solana quest from a blink in an X post, a wallet or a link. Serve the quest as a Solana Action from your app, test it, and register your domain so it unfurls on X.

A blink is a card with a button, shown in an X post, a wallet or a web page, that opens the member's wallet to sign a transaction. Serve a quest as a Solana Action and members complete it from the card: they press the button, sign, and see their points, without opening your app.

Your app serves the Action from its own domain. Domino adds the quest's memo to the transaction your code builds, and checks the quest once the member signs. Domino doesn't host Action endpoints for you or register domains with blink clients.

This is experimental: a minor release can change it.

What members see

WhereWhat happens
XA post with your Action's link shows the card in the feed for members whose wallet or browser extension renders blinks, once your domain is in Dialect's registry. Without it, the post shows a plain link.
Discord, Telegram and anywhere elseA link to https://dial.to/?action=solana-action:<your Action URL> opens Dialect's page for the card, where the member connects a wallet and signs.
Your websiteYour pages work as blinks wherever your actions.json maps them to an Action, and you can embed the card with Dialect's blinks SDK.

In each, the member sees the quest's title, description and image, presses the button and signs in their wallet. The card then shows the points, the quest's reason when its check rejects, or a note to check the app in a minute when Domino takes longer than about 45 seconds to decide. A wallet no member linked gets a Link your wallet button to your app, and Check again once they did.

Serve a quest as an Action

You need a quest members submit without input, trigger: manual(), whose check accepts the transaction your Action builds. Complete a quest from a signed Solana transaction describes the memo, ctx.action and what Domino refuses.

Give the server a key

The Action calls Domino with a key that holds Read and Ingest.

  • A hosted app already has one: its own key. Call the handler as action(request, env) in the Worker, and it builds its client from the bindings.
  • Your own server: in Console, open Settings → API keys in the environment your members sign in to, the one your app login key names, and create a key with Read and Ingest. A key from another environment looks for members there, so every wallet reads as unlinked. A personal key expires after 30 days, so for production ask an organization admin for a service key. Keep it on the server.

Serve the quest

defineQuestAction() from @domino-sdk/relay/server returns one handler for the Action's GET, POST and OPTIONS. Your build returns the unsigned transaction the member signs; the helper appends the quest's SPL Memo and changes nothing else.

The Solana template serves its devnet memo quest this way, in app/api/actions/post-a-memo/route.ts. The card asks for a memo, and the transaction posts it from the member's wallet. Simplified, without its imports and the check for a missing key:

const action = defineQuestAction({
  quest: "post-a-memo",
  chain: devnet, // "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
  linkUrl: "/quests", // where an unlinked wallet signs in, which links it
  management: createManagementClient({
    baseUrl: "https://relay.domino.run",
    getToken: async () => process.env.DOMINO_MANAGEMENT_KEY!,
  }),
  metadata: {
    icon: "/icon.svg",
    actions: [
      {
        label: "Post memo",
        href: "/api/actions/post-a-memo?memo={memo}",
        parameters: [{ name: "memo", label: "Your memo, such as gm", required: true }],
      },
    ],
  },
  async build({ account, params }) {
    const memo = String(params.memo ?? "").trim()
    if (!memo) throw new QuestActionRefusal("Write a memo to post.")

    const { value: blockhash } = await createSolanaRpc("https://api.devnet.solana.com")
      .getLatestBlockhash()
      .send()

    return pipe(
      createTransactionMessage({ version: 0 }),
      (message) => setTransactionMessageFeePayer(address(account), message),
      (message) => setTransactionMessageLifetimeUsingBlockhash(blockhash, message),
      (message) =>
        appendTransactionMessageInstruction(
          getAddMemoInstruction({ memo, signers: [createNoopSigner(address(account))] }),
          message
        )
    )
  },
})

export { action as GET, action as POST, action as OPTIONS }

The quest's check reads the wallet's devnet transactions that called the Memo program and the wallet signed. The quest's own memo is a Memo call, so the check accepts the blink's transaction unchanged. In a Next.js app, set the route's maxDuration to 60 seconds or more: after the member signs, the handler waits up to about 45 seconds for Domino's answer.

Every option, response and error is in Serve the quest as a blink.

Serve actions.json

Blink clients read /actions.json at your domain's root to learn which URLs are Actions. actionsJson() serves every path under /api/actions/ as itself:

// app/actions.json/route.ts
import { actionsJson } from "@domino-sdk/relay/server"

export const GET = actionsJson()
export const OPTIONS = GET

Pass your own { pathPattern, apiPath } rules to map your pages, such as /swap, to an Action URL.

Example: swap into your token

On mainnet, the transaction is the action you reward. Here the Action builds a swap into your token from your aggregator's instructions, and the quest pays for swaps of at least a minimum:

const action = defineQuestAction({
  quest: "swap-into-our-token",
  linkUrl: "/profile",
  metadata: {
    title: "Swap into OUR",
    actions: [
      { label: "Swap 0.1 SOL", href: "/api/actions/swap?amount=100000000" },
      { label: "Swap 1 SOL", href: "/api/actions/swap?amount=1000000000" },
    ],
  },
  async build({ account, params }) {
    // Your code: ask your aggregator for the swap's instructions, such as Jupiter's
    // /swap/v2/build, and assemble them into a kit message with the member as fee payer.
    return swapMessage({ wallet: account, from: "SOL", to: ourToken, amount: String(params.amount) })
  },
})

Build from instructions rather than a ready-signed transaction: the helper refuses a transaction that already carries a signature, and a market maker's quote can't take another instruction. A swap with many accounts needs an address lookup table to stay inside Solana's 1,232 bytes with the memo; the helper refuses a transaction it would push over.

The quest checks the swap itself, from the transaction the member signed:

export default defineQuest({
  key: "swap-into-our-token",
  title: "Swap into OUR",
  settings: settings.object({
    program: settings.solanaProgram({ label: "Swap program", default: "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" }),
    minimum: settings.amount({ label: "Minimum OUR", default: "1000000", decimals: 6 }),
  }),
  trigger: manual(),
  completion: keyed((ctx) =>
    ctx.action?.kind === "solana-transaction" ? ctx.action.signature : "app"
  ),
  budgets: [budget({ key: "swaps", scope: "member", period: "week", limit: 3, cost: 1 })],
  rewards: [points(community, 50)],
  async evaluate({ action, wallet, settings, now }) {
    if (action?.kind !== "solana-transaction") {
      return decision.reject({ reason: "Swap from the blink." })
    }

    const read = await wallet.transactions?.({
      program: settings.program,
      since: now - 24 * 60 * 60 * 1000,
      afterActivation: true,
    })
    const swap = read?.transactions.find(
      (tx) =>
        tx.signature === action.signature &&
        tx.signer &&
        BigInt(received(tx, ourToken)) >= BigInt(settings.minimum)
    )

    return swap
      ? decision.accept()
      : decision.reject({ reason: "The swap didn't bring in enough OUR." })
  },
})

Guard against farming

The blink builds an honest transaction, but anyone can sign their own transaction with the quest's memo and send its signature to your Action. Domino still runs the quest's check on every one, so the check is the guard, as for any Solana transaction quest:

  • Check the signer. Count a transaction only when the member's wallet signed it (tx.signer).
  • Require a minimum. A tiny swap or a split deposit costs almost nothing; compare received() with a settings.amount() value.
  • Cap each member. Key completions on the signature and add a member budget, so one member can't earn without limit.

Host the Action

The Action must answer on a public HTTPS address, with /actions.json at that domain's root.

Where your app runsWhat to do
A hosted app on *.domino.pageUse transparent routing: legacy routing refuses POST, so a blink can't reach the handler. Staging is never public, so blink clients can't load it: try a running preview, or the live app.
Your own domain on a hosted appAdd a custom domain. It serves the live app.
Your own server, such as VercelServe the routes as above and give the server its key.

Test it

Test before you post, and before you ask for registration.

Read the card

Open the Action URL in a browser or with curl. GET answers the card as JSON, with Access-Control-Allow-Origin: *, X-Action-Version and X-Blockchain-Ids. Open /actions.json too.

Inspect it

Paste the Action URL into the Blinks Inspector. It shows the GET and POST responses and their headers, and lets you try each button's inputs.

Sign with a wallet

Open https://dial.to/?action=solana-action:<your Action URL> and complete the quest with a wallet a member linked, on the quest's cluster. Dialect's page renders unregistered Actions with a warning, so this works before registration. Then try a wallet no member linked, to see Link your wallet.

Make it unfurl on X

X shows the card only for Actions in Dialect's registry. Registering your domain is your step: submit your Action to Dialect as Dialect's registry guide describes. Review is manual. Until it passes, share the dial.to link instead.

Register the domain members will see, such as your custom domain. Domino doesn't register domains with Dialect, and doesn't serve shared Action endpoints for projects.

Where next

On this page