Farcaster Frames

A Farcaster Frame is fundamentally an extension of the Open Graph Protocol. Developers embed a special set of <meta> tags within the HTML of a webpage. When a Farcaster client (like Warpcast) encounters a URL, it parses these tags to render the Frame directly in the user's feed, turning a link into an interactive application.

• Core Tags: fc:frame, fc:frame:image, fc:frame:button:*
• Client Detection: The client reads the tags and renders the UI without requiring the user to leave the app.

The most powerful feature of Frames is their ability to request and receive on-chain transactions. When a user clicks a button, the Frame can specify a transaction payload to be signed.

• User Flow: The client (e.g., wallet) presents the transaction for signing.
• Post-URL: After signing, the transaction data is POSTed back to a server endpoint specified by the Frame, allowing the server to verify and execute logic based on the on-chain action.
• Use Cases: Minting NFTs, voting, making payments, bridging assets.

Frames are stateful applications. They can guide users through multi-step flows without requiring a separate website. State is managed by passing data between the client and the Frame's server.

• State Passing: The server can return a new Frame image, button set, and state string with each interaction.
• Dynamic Updates: This allows for complex flows like quizzes, multi-stage mints, or games, all within the social feed post.
• Stateless Option: Simple Frames can also be completely static with no server backend.

Frames natively integrate with Farcaster's decentralized identity system. They can request and verify signatures from a user's Farcaster account (via FID) or their connected Ethereum wallet.

• Signed Message Verification: The POST request from the client includes verifiable signatures (messageBytes, signature).
• Identity Proofs: This allows the Frame developer to trustlessly authenticate the user and their Farcaster social graph, enabling gated experiences or social actions.

Frames adhere to a strict, versioned Frame Specification that ensures compatibility across all Farcaster clients. Clients validate the Frame's metadata before rendering.

• Specification Versions: (e.g., fc:frame:version). New versions add features while maintaining backward compatibility.
• Client Validation: Invalid tags or structures cause the Frame to fail gracefully, often falling back to a standard link preview.
• Interoperability: This open standard allows any client to implement Frame support, preventing platform lock-in.

Create real-time, on-chain polls where votes are recorded as transactions, providing verifiable and tamper-proof results.

• Governance Snapshot: Gauge community sentiment for a DAO proposal directly on social media.
• Live Feedback: Run a poll on product features or content direction.
• Key Feature: Results are updated live within the Frame as votes are cast, leveraging the Farcaster protocol for state.

Frames can embed decentralized exchange (DEX) interfaces or payment widgets, allowing users to swap tokens or make payments.

• Token Swap: A Frame can integrate with a DEX aggregator to offer the best swap rates for a given pair.
• Direct Payment: Pay for a subscription, donation, or physical good using crypto from the social post.
• Example: A creator's Frame lets supporters swap ETH for their community token in one click.

Use Frames to gate access to exclusive content, websites, or communities based on on-chain credentials or token ownership.

• Token-Gated Links: Unlock a private Discord, newsletter, or article by proving NFT ownership.
• Membership Check: Verify a user holds a specific token to display exclusive content within the Frame itself.
• Mechanism: The Frame validates the user's connected wallet against a smart contract holding requirement.

Deploy lightweight, interactive games or quests that can reward players with tokens or status directly through the social interface.

• Simple Games: Tic-tac-toe, puzzles, or trivia where moves or answers are recorded on-chain.
• On-Chain Quests: Complete a series of actions (e.g., visit a site, mint an NFT) for a reward, with progress tracked via the Frame.
• Engagement Driver: These use cases leverage Frames' ability to maintain state across user interactions.

Brands and protocols use Frames to create interactive advertisements where engagement (like a click) can directly lead to an on-chain action or conversion.

• Try & Buy: An ad for a new NFT project lets users preview traits and mint immediately.
• Lead Generation: Collect wallet addresses from interested users who interact with the ad.
• Analytics: All interactions are measurable on-chain, providing clear conversion metrics.

A Frame is a standardized HTML meta tag specification that defines an interactive card. Key components include:

• Open Graph Protocol Tags: Define the initial image, buttons, and text.
• Frame Transaction Payloads: Handle user interactions (button clicks) via signed messages.
• Post-Redirect URLs: Specify the server endpoint that processes interactions and returns the next Frame state. This architecture allows any Farcaster client (like Warpcast) to parse and render the interactive experience.

Building a Frame involves creating a simple web server that responds to two primary requests:

1. Initial GET Request: Returns the HTML with the required Open Graph meta tags to display the Frame.
2. POST Request: Processes the user's button press, which includes a signed message. The server validates this signature, executes logic (like minting an NFT or casting a vote), and returns the HTML for the next Frame state. Frames are stateless; all necessary data must be passed via transaction payloads or stored on-chain.

Frames enable seamless on-chain transactions directly from a feed. Common patterns include:

• Minting NFTs: Users can mint a collectible with one click.
• Token Swaps & Bridges: Initiate DeFi transactions via integrated protocols.
• Voting & Governance: Cast votes in DAO proposals.
• Cross-Chain Actions: Use transaction payloads to specify target chains (e.g., Base, OP Mainnet). The user's Farcaster wallet (like Privy or Rainbow) signs the transaction, maintaining security and custody.

Real-world Frames demonstrate the protocol's versatility:

• Mint & Claim: Free NFT mints (e.g., OpenEdition), token airdrops, or loyalty badges.
• Games & Quizzes: Interactive polls, trivia, and turn-based games with on-chain rewards.
• Commerce: Direct purchase of physical or digital goods.
• Cross-App Actions: "Remix" a song in a music app or book an event ticket. These turn static social posts into actionable endpoints for applications.

Interoperability is governed by the Farcaster Frames specification, which defines:

• Required Meta Tags: fc:frame, fc:frame:image, fc:frame:button:*.
• Post Target: The fc:frame:post_url for submitting interactions.
• Transaction Payloads: Structure for Mint, Transaction, and Link action types.
• Frame Validation: How clients verify payload signatures and image aspect ratios. Adherence ensures Frames work across all compliant clients.

Frames solve key Web3 UX hurdles by being native to the social layer:

• No Pop-ups or Redirects: Actions occur in-feed, eliminating disruptive wallet connection flows.
• Lower Friction: One-click interactions using the user's already-connected social identity.
• Discoverability: Frames are shared via casts, enabling viral distribution.
• Composability: Frames can chain together, creating multi-step experiences (e.g., mint, then bridge, then stake). This shifts development from building standalone dApps to creating social-native features.

A core security challenge is ensuring the Frame's metadata (image, buttons, post URLs) originates from and is validated by the Frame's origin server. Malicious actors could spoof this data if clients don't verify the cryptographic signature provided in the fc:frame:signature tag. This signature, created by the Frame's server, allows clients to confirm the authenticity of the Frame's state and prevent UI manipulation attacks.

Frames can request users to sign transactions or messages, creating significant trust assumptions. Key risks include:

• Blind Signing: Users may sign complex transactions without understanding the full implications.
• Phishing: Malicious Frames can mimic trusted interfaces to steal assets.
• Permission Scope: Unlike traditional dApps, Frames have a constrained UI, making it harder to display detailed transaction data. Users must verify the transaction origin and payload within their wallet interface before approving.

The Frame's backend server is a critical attack surface. The post_url endpoint must be secured against:

• Cross-Site Request Forgery (CSRF): Validate the trusted_data or untrustedData payload to ensure the request originated from a valid Frame interaction.
• Open Redirects: Redirects based on user-supplied URLs in the payload can be exploited. Servers must validate or sanitize all redirect targets.
• Denial-of-Wallet (DoW): Spamming transaction prompts can degrade user experience and drain wallet resources.

Frames run within a social media client's sandboxed environment (e.g., a Warpcast client). Considerations include:

• Data Leakage: Frames can potentially access the user's Farcaster FID, connected addresses, and other client-provided data. They must handle this PII responsibly.
• Cross-Frame Communication: The spec restricts direct communication between Frames to prevent malicious coordination.
• Client Enforcement: The security model relies heavily on the host client correctly implementing the Frame specification, validating signatures, and isolating Frame content.

Unlike web2 iFrames, Frames leverage blockchain-based identity. Emerging trust models include:

• Developer Attestation: Verifying the Frame was created by a specific Farcaster account or Ethereum address with a known reputation.
• Client Allowlists: Some clients may maintain allowlists of trusted Frame domains based on community feedback or audits.
• On-Chain Activity: A Frame's interaction history (e.g., transaction success rate) could become a public reputation signal. Users should assess the creator's on-chain footprint before engaging.