Farcaster Miniapp Sdk

Farcaster MiniApp SDK

Comprehensive documentation for building Mini Apps on Farcaster using the @farcaster/miniapp-sdk. Covers context, actions, haptics, navigation, capability detection, and client events.

When to Apply

Reference this documentation when:

• Building a new Farcaster Mini App
• Accessing user/client/location context via sdk.context
• Implementing SDK actions (composeCast, viewProfile, openUrl, etc.)
• Adding haptic feedback to your mini app
• Handling back navigation
• Detecting platform capabilities and supported chains
• Listening to client events (miniappAdded, notificationsEnabled, etc.)
• Integrating wallet/token operations (swapToken, sendToken, viewToken)

SDK Categories

Quick Reference

Context (sdk.context)

Access session information when your app opens:

• user - FID, username, displayName, pfpUrl, location
• client - platformType ('web'|'mobile'), clientFid, added, safeAreaInsets, notificationDetails
• location - Launch context: cast_embed, cast_share, notification, launcher, channel, open_miniapp
• features - haptics, cameraAndMicrophoneAccess

Actions (sdk.actions.*)

Haptics (sdk.haptics.*)

// Impact feedback: 'light' | 'medium' | 'heavy' | 'soft' | 'rigid'
await sdk.haptics.impactOccurred('medium')

// Notification feedback: 'success' | 'warning' | 'error'
await sdk.haptics.notificationOccurred('success')

// Selection feedback
await sdk.haptics.selectionChanged()

Back Navigation (sdk.back.*)

// Auto-integrate with browser navigation
await sdk.back.enableWebNavigation()

// Manual control
sdk.back.onback = () => { /* custom handler */ }
await sdk.back.show()
await sdk.back.hide()

Capability Detection

// Check supported features
const capabilities = await sdk.getCapabilities()
const supportsCompose = capabilities.includes('actions.composeCast')

// Check supported chains (CAIP-2 identifiers)
const chains = await sdk.getChains()

// Detect if running in mini app context
const isMiniApp = await sdk.isInMiniApp()

Client Events

sdk.on('miniappAdded', () => { /* user added app */ })
sdk.on('miniappRemoved', () => { /* user removed app */ })
sdk.on('notificationsEnabled', () => { /* notifications on */ })
sdk.on('notificationsDisabled', () => { /* notifications off */ })

// Cleanup
sdk.removeListener('miniappAdded', handler)
sdk.removeAllListeners()

Quick Auth (Authentication for API Routes)

Quick Auth provides authenticated sessions for Farcaster users. Use it to protect API endpoints that access user-specific data.

When to Use Quick Auth

Rule: If the user should only access THEIR data, use Quick Auth.

Frontend: Making Authenticated Requests

Use sdk.quickAuth.fetch for authenticated API calls:

import { sdk } from "@farcaster/miniapp-sdk";

// Authenticated fetch - automatically adds Bearer token
const response = await sdk.quickAuth.fetch("/api/todos");
const todos = await response.json();

// For mutations
await sdk.quickAuth.fetch("/api/todos", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "New todo" }),
});

Or get the token directly:

const { token } = await sdk.quickAuth.getToken();
// Use token in custom fetch calls

Backend: Validating Tokens

Install the Quick Auth library:

yarn add @farcaster/quick-auth

Create an auth utility packages/nextjs/utils/auth.ts:

import { createClient, Errors } from '@farcaster/quick-auth';

const client = createClient();

export async function getAuthenticatedFid(request: Request): Promise<number | null> {
  const authorization = request.headers.get('Authorization');
  if (!authorization?.startsWith('Bearer ')) {
    return null;
  }

  try {
    const token = authorization.split(' ')[1];
    const payload = await client.verifyJwt({
      token,
      domain: process.env.NEXT_PUBLIC_URL || 'localhost:3000',
    });
    return payload.sub; // FID of authenticated user
  } catch (e) {
    if (e instanceof Errors.InvalidTokenError) {
      console.info('Invalid token:', e.message);
    }
    return null;
  }
}

export async function requireAuth(request: Request): Promise<number> {
  const fid = await getAuthenticatedFid(request);
  if (!fid) {
    throw new Error('Unauthorized');
  }
  return fid;
}

Protected API Route Example

import { sql } from '~~/utils/db';
import { requireAuth } from '~~/utils/auth';
import { NextResponse } from 'next/server';

// GET /api/todos - Get MY todos only
export async function GET(request: Request) {
  try {
    const fid = await requireAuth(request);
    
    // Only return todos owned by this user
    const todos = await sql`
      SELECT * FROM todos 
      WHERE owner_fid = ${fid}
      ORDER BY created_at DESC
    `;
    
    return NextResponse.json(todos);
  } catch {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
}

// DELETE /api/todos/[id] - Delete MY todo only
export async function DELETE(request: Request) {
  try {
    const fid = await requireAuth(request);
    const { id } = await request.json();
    
    // Only delete if user owns this todo
    const result = await sql`
      DELETE FROM todos 
      WHERE id = ${id} AND owner_fid = ${fid}
      RETURNING id
    `;
    
    if (result.length === 0) {
      return NextResponse.json({ error: 'Not found or not authorized' }, { status: 404 });
    }
    
    return NextResponse.json({ success: true });
  } catch {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
}

Performance Optimization

Add preconnect hint in your app:

import { preconnect } from 'react-dom';

function AppRoot() {
  preconnect("https://auth.farcaster.xyz");
}

Or in HTML:

<link rel="preconnect" href="https://auth.farcaster.xyz" />

Important Patterns

Safe Area Insets

Handle mobile navigation elements:

<div style={{
  marginTop: context.client.safeAreaInsets?.top,
  marginBottom: context.client.safeAreaInsets?.bottom,
  marginLeft: context.client.safeAreaInsets?.left,
  marginRight: context.client.safeAreaInsets?.right,
}}>
  {/* app content */}
</div>

Location Context Types

• cast_embed - Launched from a cast where app is embedded
• cast_share - User shared a cast to your app
• notification - Launched from app notification
• launcher - Launched from client app directly
• channel - Launched from a channel context
• open_miniapp - Launched from another mini app (includes referrerDomain)

Token Identifiers (CAIP-19)

// Format: eip155:{chainId}/erc20:{contractAddress}
const baseUsdc = "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

// Native token
const opEth = "eip155:10/native"

How to Use

Read individual rule files for detailed explanations and code examples:

rules/context.md
rules/actions-compose-cast.md
rules/haptics.md
rules/back-navigation.md
rules/capabilities.md
rules/client-events.md

All Rule Files

Each rule file contains:

• Brief explanation of the feature
• TypeScript usage examples
• Parameters and return types
• Best practices and notes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.