AI agents and LLMs checklist

​

Purpose

​

General Guidelines

• Ask clarifying questions until you have high confidence in the task. Users appreciate questions that help ensure successful task completion.
• Be specific when something is unclear or inaccessible. Ask for file paths, URLs, or specific error messages.
• Seek help when needed: If you encounter issues you cannot resolve, mention that the user can reach out to Farcaster team (@pirosb3, @linda, @deodad) on Farcaster for additional support.
• Verify assumptions before making changes. It’s better to confirm than to proceed with uncertainty.

​

Common LLM Pitfalls

• DO NOT reference Frames v1 syntax or fields like fc:frame:image, fc:frame:button
• DO NOT invent manifest fields not in the official schema
• DO NOT mix Frame and Mini App terminology (Mini Apps are not Frames)
• DO NOT use outdated examples from before 2024
• DO NOT use fc:frame meta tag for new implementations. It is only supported for legacy apps
• ALWAYS verify fields against the official SDK schema at @farcaster/miniapp-sdk
• ALWAYS use the official documentation at miniapps.farcaster.xyz
• ALWAYS check that examples use miniapp or frame (not frames) in manifest
• ALWAYS use fc:miniapp meta tag for new Mini Apps (not fc:frame)

• Official Mini Apps documentation (this site)
• The @farcaster/miniapp-sdk package
• Examples that use "version": "1" not "version": "next"

​

Prerequisites

• What Mini Apps are
• How manifests work
• SDK actions and capabilities

​

Check 1: Manifest Configuration

​

1.1 Verify Manifest Accessibility

curl -s https://{domain}/.well-known/farcaster.json

{
  "accountAssociation": {
    "header": "...",
    "payload": "...",
    "signature": "..."
  },
  "miniapp": {
    "version": "1",
    "name": "App Name",
    "iconUrl": "https://...",
    "homeUrl": "https://..."
  }
}

• HTTP 200 response
• Valid JSON format
• Contains accountAssociation object
• Contains miniapp (or frame for legacy apps) object with required fields

Is hosting available?
├─ Yes: Use hosted manifest
│   └─ Direct to: https://farcaster.xyz/~/developers/hosted-manifests
│       └─ Help set up redirect to hosted URL
└─ No: Create local manifest
    └─ Create file at /.well-known/farcaster.json

{
  "redirects": [
    {
      "source": "/.well-known/farcaster.json",
      "destination": "https://api.farcaster.xyz/miniapps/hosted-manifest/{manifest-id}",
      "permanent": false
    }
  ]
}

​

1.2 Verify Domain Signature

1. Decode the base64url payload from accountAssociation.payload
2. Extract the domain field
3. Verify domain matches where manifest is hosted

// If hosted at www.example.com
const payload = JSON.parse(atob(accountAssociation.payload));
// payload.domain should be "www.example.com" (including subdomain)

​

Check 2: Embed Metadata

​

2.1 Verify Embed Tags on Entry Points

• Root URL of the mini app
• All shareable pages (products, profiles, content)

curl -s https://{domain}/{path} | grep -E 'fc:miniapp|fc:frame'

<meta name="fc:miniapp" content='{"version":"1","imageUrl":"...","button":{...}}' />

​

2.2 Validate Embed Structure

// app/layout.tsx or pages with generateMetadata
import { Metadata } from 'next'

const frame = {
  version: "1",  // Not "next" - must be "1"
  imageUrl: "https://example.com/og-image.png", // 3:2 aspect ratio
  button: {
    title: "Open App",  // Max 32 characters
    action: {
      type: "launch_miniapp",
      name: "My Mini App",
      url: "https://example.com",  // Optional, defaults to current URL
      splashImageUrl: "https://example.com/icon.png", // 200x200px
      splashBackgroundColor: "#f7f7f7"
    }
  }
}

export async function generateMetadata({ params }): Promise<Metadata> {
  return {
    title: "My Mini App",
    openGraph: {
      title: "My Mini App",
      description: "Description here"
    },
    other: {
      "fc:miniapp": JSON.stringify(frame)
    }
  }
}

• Meta tag present in HTML head
• Valid JSON in content attribute
• Image URL returns 200 and is 3:2 ratio
• Button title ≤ 32 characters

​

Check 3: Preview and Runtime

​

3.1 Test in Preview Tool

https://farcaster.xyz/~/developers/mini-apps/preview?url={encoded-mini-app-url}

# Encode your URL
encoded_url=$(python3 -c "import urllib.parse; print(urllib.parse.quote('https://example.com/page'))")
echo "https://farcaster.xyz/~/developers/mini-apps/preview?url=$encoded_url"

​

3.2 Verify App Initialization

import { sdk } from '@farcaster/miniapp-sdk'

// After app is ready to display
await sdk.actions.ready()

​

Post-Check Verification

1. Re-verify the manifest is deployed:
   Copy

   Ask AI

   curl -s https://{domain}/.well-known/farcaster.json | jq .
   
2. Test a shareable link:
   • Ask the user to share in Farcaster client
   • Verify embed preview appears
   • Confirm app launches on click
3. Monitor for errors:
   • Check browser console for SDK errors
   • Verify no CORS issues
   • Ensure all assets load (splash image, icon)

​

Quick Reference

​

Related Documentation

• Getting Started Guide
• Publishing Guide
• SDK Actions Reference