Farcaster Frames v2

A simple approach

cast

A URL is considered a valid frame if:

it includes an embed in its headers

manifest file at a well known location at the root of the domain.

Frames will follow semantic versioning and frames must declare the version that they support. Apps will choose to render frames based on the versions they can support.

A frame URL must have a FrameEmbed in a serialized form in the fc:frame meta tag on the headers. When this URL is rendered in a cast, the image is displayed in a 1.9:1 ratio with a button underneath. Clicking the button will open an app frame to the provided target url and use the splash page to animate the transition.

Frame manifest:

type FarcasterManifest = {
  accountAssociation: {
    header: string; // base64url encoded JFS header
    payload: string;  // base64url encoded payload containing a single property `domain`
    signature: string; // base64url encoded signature
  };
  frame: FrameConfig;
  triggers?: TriggerConfig[];
};

The account association links the domain to a Farcaster FID. The signature must be a signed JSON Farcaster Signature from the FID's custody address with the following payload:

{ domain: string }

The domain must match the domain the manifest is being served from.

Frame config

type FrameConfig = {
  version: string; 
  name: string;
  homeUrl?: string
  iconUrl: string;
  splashImageUrl?: string;
  splashBackgroundColor?: string;
  webhookUrl?: string
};

Frame Invocation

Frames may be invoked in the following ways:

Method Description Context

global Called when the app is invoked from the app launcher or other unspecified context, only when homeUrl is set. Loads the app’s homeUrl. None

embed Called when the frame is invoked from an embed in a feed or direct cast. Loads the url specified in the embed metadata Cast hash, embed URL, embed type (feed or direct cast), see below

notification Called when a user clicks on a frame notification. Loads the targetUrl specified in the notification payload. Notification ID, see below

Triggers

Triggers will allow a user to launch into your Frame from different places in a Farcaster application. These will eventually replace "cast actions" and "composer actions." See "Feature: Triggers" in the Appendix for details.

type TriggerConfig = {
  type: 'cast_action',
  id: string,
  url: string,
  name?: string
} | {
  type: 'composer_action',
  id: string,
  url: string,
  name?: string
}

Attribute Description Example

type The type of trigger, castaction or composeracton. Required. "cast-action"

id Unique ID. Required. Reported to the frame. "do-yoink"

url Handler URL. Required. "https://yoink.party/trigger-handler"

name Name override. Optional, defaults to FrameConfig.name. "View Leaderboard"

Frame manifest caching

Farcaster clients may cache the frame manifest when scraping embeds, but should provide a mechanism for refreshing the manifest file.

Frame UI Specifications

Header A header is rendered above the frame and includes the name and author which must be specified in the manifest. The header is rendered whenever the app frame is launched.

Splash Screen A splash screen is shown as soon as the app is launched and the icon and background must be specified in the frame manifest or embed meta tags. The frame can hide the splash screen once loading is complete.

Size & Orientation A frame should be rendered in a vertical modal. Mobile frame sizes will be dictated by device dimensions while web frame sizes will be set to 424x695px.

Client SDK API

type LaunchContext =
 | CastEmbedLaunchContext
 | NotificationLaunchContext

> Farcaster.context.location
{
  type: "cast_embed",
  cast: {
    fid: 3621,
    hash: "0xa2fbef8c8e4d00d8f84ff45f9763b8bae2c5c544",
    text: "New Yoink just dropped:",
    embeds: ["https://yoink.party/frames"]
  }
}

type Cast = {
  fid: number;
  hash: string;
  text: string;
  embeds: string[];
  mentions: Mention[];
};

type CastEmbedLaunchContext = {
  type: 'cast_embed';
  cast: Cast;
};

Notification

type NotificationLaunchContext = {
  type: 'notification';
  notification: {
    title: string;
    body: string;
    id: string;
  };
};

context user

type User = {
  fid: number;
  username?: string;
  displayName?: string;
  pfp?: string;
  bio?: string;
  location?: {
    placeId: string;
    description: string;
  },
  custodyAddress: string;
  verifiedAddresses: {
    ethereum: string[];
    solana: string[];
  }
  connectedAccounts: {
    platform: string;
    username: string;
  }[];
};