Solana “Actions” & Blinks: Transacting from Any App (and X)

TL;DR: A Solana Action is an HTTP endpoint that, when called by a wallet or Action-aware client, returns a serialized transaction payload (or an instruction bundle) tailored to the caller. A Blink is a shareable link or embed that points to that Action and renders a “Do the thing” button swap → sign, mint → sign, tip → sign, inside compatible contexts (sites, chats, and X). You keep the business logic server-side, you personalize the transaction to the user/wallet at request time, and you let wallets handle signing/broadcast. The big wins: shorter funnels, higher conversion, and portable distribution. The hard parts: replay protection, calldata validation, price slippage checks, rate limiting, and analytics that respect privacy.

What Are Solana Actions & “Blinks” (Blockchain Links)?

Think of an Action as a lightweight transaction API for your product. Instead of asking users to navigate to a full dApp, connect a wallet, pick options, and click through modals, you expose a single endpoint. The wallet (or a Blink-enabled client) calls it with minimal parameters (e.g., “mint 1”, “swap 0.3 SOL to USDC”), your server constructs a transaction tailored to that wallet’s address and current network conditions (recent blockhash, slippage limits, dynamic fees), returns it, and the wallet signs and sends.

A Blink is the shareable wrapper: an onchain link that clients can render as an interactive card with a button. Post it on X, drop it into Discord, paste it into an article, compatible clients show a preview (“Mint Now”, “Swap SOL→USDC”, “Tip Creator”), and clicking routes the user straight to a wallet to review and sign. It’s the “anywhere commerce” moment for onchain actions.

Architecture & Request Flow

At a high level, an Action looks like a standard HTTPS endpoint (GET or POST) behind your domain. A Blink is a URL that points to that endpoint, optionally decorated with metadata so clients render a “call-to-action” card. When a user clicks the Blink, a wallet or Action-aware client fetches the endpoint, your server builds a transaction targeted to the requester’s wallet, and the wallet presents, simulates, and signs.

Action Response Shape (Conceptual)

Different frameworks/SDKs exist, but the response generally includes:

• Display metadata (label, description, icon) for clients that render cards/buttons.
• Transaction payload: a base64-encoded signed-by-server-where-needed (or partially signed) Solana transaction with a fresh blockhash and the user’s wallet set as the fee payer or payer of specific accounts.
• Post-action links (success/fail), optional simulate first flag, and a valid-until timestamp to prevent replay.

// Example JSON (illustrative)
{
  "type": "action",
  "version": "1",
  "title": "Swap SOL → USDC",
  "icon": "https://yourcdn.com/icons/swap.svg",
  "description": "Best price routed. Max slippage 0.5%.",
  "transaction": {
    "network": "mainnet-beta",
    "encoded": "<base64-serialized-transaction>",
    "validUntil": 1735689600  // unix timestamp
  },
  "links": {
    "success": "https://yourapp.com/success?tx={signature}",
    "fail": "https://yourapp.com/fail"
  }
}

Hands-On Examples: Swap, Tip, and NFT Mint

Below we outline three common Actions with code you can adapt. We’ll assume a Node/TypeScript server (Next.js API route or Cloudflare Worker) and @solana/web3.js. In production you would also wire price APIs/routers, a cache, and your allowlists.

A) “Swap SOL→USDC” Action (Best-Effort Routing)

This Action takes an input amount in SOL, fetches a price route (via your chosen aggregator), builds a swap transaction, and returns it as a Blink-ready response. Keep heavy logic server-side: slippage bounds, fee payer rules, and per-wallet caps.

// pages/api/actions/swap-sol-usdc.ts (illustrative)
import { Connection, PublicKey, Transaction, SystemProgram } from "@solana/web3.js";
// import your router SDK (Jupiter/Helius/YourRouter)

const RPC = process.env.SOLANA_RPC!;
const connection = new Connection(RPC, "confirmed");

export default async function handler(req, res) {
  try {
    const { wallet, amount } = req.method === "POST" ? req.body : req.query;
    if (!wallet || !amount) return res.status(400).json({ error: "wallet and amount required" });

    const user = new PublicKey(wallet);
    const lamports = BigInt(Math.floor(parseFloat(String(amount)) * 1e9)); // SOL → lamports

    // 1) Preflights & caps
    if (lamports < 1000000n) return res.status(400).json({ error: "min 0.001 SOL" });
    // rate-limit by IP/wallet outside this snippet

    // 2) Fetch route from your DEX router (pseudo)
    const route = await getBestRouteSOLtoUSDC(lamports); // slippage 0.5%, etc.

    // 3) Build transaction (pseudo; replace with router builder)
    const { transaction } = await route.build({
      userPublicKey: user,
      slippageBps: 50,
    });

    transaction.feePayer = user;
    transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;

    const encoded = transaction.serialize({ requireAllSignatures: false }).toString("base64");
    const validUntil = Math.floor(Date.now() / 1000) + 60; // 60s validity

    return res.status(200).json({
      type: "action",
      version: "1",
      title: "Swap SOL → USDC",
      icon: "https://yourcdn.com/icons/swap.svg",
      description: "Best price routed. Max slippage 0.5%.",
      transaction: { network: "mainnet-beta", encoded, validUntil },
      links: {
        success: "https://yourapp.com/swap/success?tx={signature}",
        fail: "https://yourapp.com/swap/fail"
      }
    });
  } catch (e) {
    console.error(e);
    return res.status(500).json({ error: "internal_error" });
  }
}

B) “Tip the Creator” Action (SOL or USDC)

A dead-simple Action: send 0.05 SOL (or any amount) to a recipient. You can publish different Blinks for preset values and track each with UTM tags.

// pages/api/actions/tip.ts (illustrative)
import { Connection, PublicKey, SystemProgram, Transaction } from "@solana/web3.js";
const RPC = process.env.SOLANA_RPC!;
const connection = new Connection(RPC, "confirmed");
const CREATOR = new PublicKey(process.env.CREATOR_ADDRESS!);

export default async function handler(req, res) {
  try {
    const { wallet, amount } = req.method === "POST" ? req.body : req.query;
    if (!wallet || !amount) return res.status(400).json({ error: "wallet and amount required" });

    const user = new PublicKey(wallet);
    const lamports = BigInt(Math.floor(parseFloat(String(amount)) * 1e9));

    if (lamports < 1000000n) return res.status(400).json({ error: "min 0.001 SOL" });

    const ix = SystemProgram.transfer({
      fromPubkey: user,
      toPubkey: CREATOR,
      lamports: Number(lamports),
    });

    const tx = new Transaction().add(ix);
    tx.feePayer = user;
    tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;

    const encoded = tx.serialize({ requireAllSignatures: false }).toString("base64");
    const validUntil = Math.floor(Date.now() / 1000) + 60;

    return res.status(200).json({
      type: "action",
      version: "1",
      title: "Tip the Creator (SOL)",
      icon: "https://yourcdn.com/icons/tip.svg",
      description: "Direct onchain tip. Thank you!",
      transaction: { network: "mainnet-beta", encoded, validUntil },
      links: { success: "https://yourapp.com/tip/thanks?tx={signature}" }
    });
  } catch (e) {
    console.error(e);
    return res.status(500).json({ error: "internal_error" });
  }
}

C) “Mint an NFT” Action (Candy Machine or Custom Program)

For mints, Actions shine: you can throttle per-wallet mints server-side, inject a merkle proof or signature for allowlists, and cancel when supply is exhausted, all without users ever leaving a social post or article.

// pages/api/actions/mint.ts (illustrative)
import { Connection, PublicKey, Transaction } from "@solana/web3.js";
// import your mint program client (e.g., Candy Machine SDK)

const RPC = process.env.SOLANA_RPC!;
const connection = new Connection(RPC, "confirmed");

export default async function handler(req, res) {
  try {
    const { wallet } = req.method === "POST" ? req.body : req.query;
    if (!wallet) return res.status(400).json({ error: "wallet required" });

    const user = new PublicKey(wallet);

    // 1) Check allowlist / supply / per-wallet mint caps
    const ok = await checkEligibility(user);
    if (!ok) return res.status(403).json({ error: "not eligible or cap reached" });

    // 2) Build mint transaction with your program client
    const tx = await buildMintTx({ payer: user }); // returns Transaction with instructions
    tx.feePayer = user;
    tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;

    const encoded = tx.serialize({ requireAllSignatures: false }).toString("base64");
    const validUntil = Math.floor(Date.now() / 1000) + 60;

    return res.status(200).json({
      type: "action",
      version: "1",
      title: "Mint Your NFT",
      icon: "https://yourcdn.com/icons/mint.svg",
      description: "Supply limited. One per wallet.",
      transaction: { network: "mainnet-beta", encoded, validUntil },
      links: {
        success: "https://yourapp.com/mint/success?tx={signature}",
        fail: "https://yourapp.com/mint/fail"
      }
    });
  } catch (e) {
    console.error(e);
    return res.status(500).json({ error: "internal_error" });
  }
}

How to Embed on Websites, Blogs, and X

You can surface Actions anywhere a link fits. For websites and blogs, create styled buttons that resolve to your Action URL and let integrated wallets intercept. For X, post the Blink URL with a clear CTA. Many wallets and Action-aware clients render a clickable card inside the post so users transact without leaving the feed.

Website Button (Vanilla)

<a
  href="https://yourapp.com/api/actions/swap-sol-usdc?amount=0.3"
  rel="nofollow"
  style="display:inline-block; padding:12px 16px; background:#2fc9b2; color:#fff; border-radius:10px; text-decoration:none; font-weight:800;"
>Swap 0.3 SOL → USDC</a>

Enhance with device detection: if a mobile wallet is installed, open its deep link; otherwise, fallback to a universal wallet selector that can consume the Action endpoint.

X (Twitter) Post Copy

Swap SOL → USDC in one click ⚡
Action-enabled link below (wallets will simulate + confirm):

https://yourapp.com/api/actions/swap-sol-usdc?amount=0.3&utm_source=x&utm_campaign=blink-swap

#Solana #Blinks #OnchainUX

QR Codes (Events & IRL)

Generate a QR pointing to your Action URL. At conferences, this is perfect for instant tip jars, POAP-style claims, or limited mints. Rotate the QR if you notice abuse.

Analytics & Growth Loops: Measure and Improve

Actions and Blinks reduce friction, but you still need data. The flow splits across your server, the wallet, and the chain. Your goal is a privacy-respecting pipeline that answers: which surfaces drive signed transactions, what’s the drop-off between click → simulation → signature, and how do fee spikes affect completion?

1) blink_impression (optional): generated by your site if you render a card
2) action_request: every hit to /api/actions/* (log UTM, IP hash, user-agent, wallet param if present)
3) action_response: returned a tx payload (log type, quote details, blockhash age)
4) wallet_simulation: cannot observe directly; infer via time-to-signature patterns
5) tx_submitted: wallet calls back /success?tx=... (record signature)
6) onchain_confirmation: watch signature; record slot, compute slippage, realized fees

• Attribution: Use UTM tags in your Blink URLs and propagate them into success/fail callbacks. Avoid storing full IPs; hash with a rotating salt if you need repeat-click metrics.
• Completion rates: Track response → signature conversion; bucket by fee levels and time of day. If completion collapses at high fees, surface UI nudges (“try again when fees drop”).
• AB tests: Compare “preset amounts” vs “custom amount” Blinks; test short vs long descriptions; try different icons and verbs (“Mint Now” vs “Claim”).
• Growth loop: After success, show a “Share this Blink” prompt with a prefilled X post—this compounds distribution.

Security Caveats & Hardening (Read Before You Ship)

Moving the transaction builder server-side is powerful and dangerous if you skip guardrails. Here are the major risks and how to mitigate them.

Production-Ready Checklist (Copy/Paste into Your Runbook)

1. Domain & TLS: Serve Actions from your primary HTTPS domain; configure HSTS; pin your canonical URL in all Blinks.
2. Schema Validation: Enforce JSON schema for inputs; reject unknown query params immediately.
3. Blockhash Freshness: Target < 30s; expire responses; include validUntil in payload.
4. Simulation: Simulate server-side for complex Actions; wallets will simulate again, double safety.
5. Slippage Discipline: Hard cap slippage; fail fast if quotes are stale; instruct users to retry.
6. Caps & Rate Limits: Per-wallet caps (on chain + server), IP throttles, and campaign-level limits.
7. Observability: Log action_request/response; export metrics (p95 time-to-signature, fail codes); set alerts.
8. Fallback UX: Provide “Open in dApp” link if the client cannot consume the Action.
9. Content Security: Where possible, sign Action metadata or include a short fingerprint so wallets can detect tampering.
10. Docs & Transparency: Publicly document your Action endpoints and safety policies; it builds trust.

Go Deeper with TokenToolHub

• Blockchain Technology Guides
• Blockchain Intermediate Guides
• AI Learning Hub
• AI Crypto Tools
• Prompt Libraries
• Web3 Trends & News

Frequently Asked Questions

Do Actions replace my dApp?

No. Actions are the fast lane for common flows (tip, claim, mint, swap). Keep your full dApp for complex journeys (portfolio views, settings, multi-step flows). In practice, Actions boost top-of-funnel conversion and discovery; the dApp handles power-user depth.

How do wallets know what to show?

Wallets and compatible clients fetch your Action endpoint and parse the returned JSON metadata and transaction payload. They render a descriptive summary, run simulation, and then prompt the user to sign. Good wallets surface domain names and safety warnings to prevent phishing.

Can I include dynamic pricing or allowlists?

Yes. Compute quotes server-side at request time and insert merkle proofs or signatures for allowlisted mints. Always revalidate when the wallet calls back with a signature; if the response is stale, instruct the user to retry.

What happens if fees spike mid-flow?

Wallet simulation should catch insufficient fees or changing compute budgets. Your Action can also set a short validity window and conservative slippage so transactions fail safely instead of executing at a bad price. Teach users that “Retry” is normal under volatile fees.

How do I prevent abuse during promotions?

Use per-wallet server caps, allowlists, device/IP throttles, and signed coupons/tokens that the wallet must present to mint/claim. Consider progressive disclosure (email capture → Action link) to slow bots, and monitor velocity with alerts.

Glossary

• Action: An HTTPS endpoint that returns a tailored Solana transaction payload with display metadata for wallets.
• Blink (Blockchain Link): A shareable URL clients render as a “do it now” card/button that calls an Action.
• Preflight/Simulation: A wallet step that simulates your transaction before signing to catch errors and high slippage.
• ATA: Associated Token Account; the standard SPL token holding account for a wallet.
• Slippage: Allowed price movement between quote and execution; expressed in basis points (bps).
• Blockhash: A recent block’s hash; transactions must include a fresh one to be valid (prevents replay).