# Quests as blinks (/docs/build/blinks)



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](https://solana.com/docs/tools/actions) 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 [#what-members-see]

| Where                                   | What happens                                                                                                                                                                                                |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **X**                                   | A 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 else** | A 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 website**                        | Your pages work as blinks wherever your [`actions.json`](#3-serve-actionsjson) 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.

```mermaid
sequenceDiagram
    participant M as Member's wallet
    participant B as Blink (X, dial.to)
    participant A as Your app
    participant D as Domino
    B->>A: GET the Action
    A->>D: Read the quest
    A-->>B: Card
    B->>A: POST with the member's address
    A-->>B: Your transaction plus the quest's memo
    B->>M: Sign
    M-->>B: Signature
    B->>A: POST the signature
    A->>D: Submit it, wait for the check
    A-->>B: Points or the reason
```

## Serve a quest as an Action [#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](/docs/build/wallets#complete-a-quest-from-a-signed-solana-transaction) describes the memo, `ctx.action` and what Domino refuses.

### 1. Give the server a key [#1-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](/docs/start/existing-app#5-call-domino-from-your-backend). Keep it on the server.

### 2. Serve the quest [#2-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](/docs/start/solana) 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:

```text
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](/docs/build/wallets#serve-the-quest-as-a-blink).

### 3. Serve actions.json [#3-serve-actionsjson]

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:

```ts
// 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 [#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:

```text
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:

```text
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 [#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](/docs/build/wallets#check-on-chain-actions-on-solana):

* **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 [#host-the-action]

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

| Where your app runs                 | What to do                                                                                                                                                                                                                                   |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A hosted app on `*.domino.page`** | Use [transparent routing](/docs/build/hosted-app#choose-a-routing-mode): 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 app** | Add a [custom domain](/docs/build/hosted-app#use-your-own-domain). It serves the live app.                                                                                                                                                   |
| **Your own server**, such as Vercel | Serve the routes as above and give the server its key.                                                                                                                                                                                       |

## Test it [#test-it]

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

### 1. Read the card [#1-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.

### 2. Inspect it [#2-inspect-it]

Paste the Action URL into the [Blinks Inspector](https://www.blinks.xyz/inspector). It shows the `GET` and `POST` responses and their headers, and lets you try each button's inputs.

### 3. Sign with a wallet [#3-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 [#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](https://docs.dialect.to/blinks/blinks-provider/blink-registry) 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 [#where-next]

- [Complete a quest from a signed Solana transaction](/docs/build/wallets#complete-a-quest-from-a-signed-solana-transaction) — The memo, `ctx.action` and Domino's refusals.
- [Serve the quest as a blink](/docs/build/wallets#serve-the-quest-as-a-blink) — Every option and response of `defineQuestAction()`.
- [In-person quests with Solana Pay](/docs/build/solana-pay) — The same quest at an event's stations, from a printed QR code a mobile wallet scans.
- [Start from create-solana-dapp](/docs/start/solana) — The template with the devnet blink.
- [Build on Solana](/docs/build/solana) — Every Solana guide in one place.
