Skip to content
Github

XMTP Support

Cross-protocol frames are supported by frames.js via familiar APIs. This guide will showcase how to write a simple stateless frame, which returns the identity of the user that interacted with the frame in Farcaster or an XMTP chat.

Setup

First, you need to install frames.js and @xmtp/frames-validator. You can do this by running the following command:

npm install frames.js @xmtp/frames-validator

Writing a Frame

To write a frame using Next.js, we need to create a page which renders the frame and a route which handles frame action requests.

API Route

We start by creating a new API route which will handle POST requests to our frame. In your Next.js project, create a new directory /frames and inside it, create a route.ts file which contains the following code:

export { POST } from "frames.js/next/server";

This will handle POST requests to our frame and redirect them to page we are about to create, which will handle the rendering logic.

Page

In your Next.js project, create a new page.tsx at the root of the project and write the following code:

First import the necessary functions and components from frames.js:

import {
  FrameButton,
  FrameContainer,
  FrameImage,
  NextServerPageProps,
  getFrameMessage,
  getPreviousFrame,
} from "frames.js/next/server";

FrameButton, FrameContainer, and FrameImage are components that are used to construct Frame metadata tags in HTML. NextServerPageProps is a type that you can use to define the props of your page. getFrameMessage and getPreviousFrame are functions that you can use to get the message and the previous frame of your page to determine the next state to return.

Next, import the XMTP validation methods from frames.js

import {
  FrameButton,
  FrameContainer,
  FrameImage,
  NextServerPageProps,
  getFrameMessage,
  getPreviousFrame,
} from "frames.js/next/server";
import { getXmtpFrameMessage, isXmtpFrameActionPayload } from "frames.js/xmtp";

Then define the client protocols that your frame will support. In our case we will support XMTP and Farcaster.

import {
  FrameButton,
  FrameContainer,
  FrameImage,
  NextServerPageProps,
  getFrameMessage,
  getPreviousFrame,
} from "frames.js/next/server";
import { getXmtpFrameMessage, isXmtpFrameActionPayload } from "frames.js/xmtp";
 
const acceptedProtocols: ClientProtocolId[] = [ 
  {
    id: "xmtp", 
    version: "vNext", 
  }, 
  { 
    id: "farcaster", 
    version: "vNext", 
  }, 
];

Now define the render method for your frame. This will take place in a server component, so all the logic will be executed on the server and a plain HTML response containing our frame will be sent to the client.

// ...
 
export default async function Home({
  params,
  searchParams,
}: NextServerPageProps) {
  const previousFrame = getPreviousFrame(searchParams);
 
  // do some logic to determine the next frame
 
  // return the frame
 
  return <FrameContainer
    pathname="/"
    postUrl="/frames"
    state={{}}
    previousFrame={previousFrame}
    accepts={acceptedProtocols}
  >
    <FrameImage>Hello world</FrameImage>
    <FrameButton>Next</FrameButton>
  </FrameContainer>;
}

Here we use previousFrame to extract the frame action payload and state from the previous frame which are stored in URL params. We then use these to determine the next frame to return, passing the new state and accepted protocols to the FrameContainer component. The props of the FrameContainer component determine the routing and functionality of the frame. pathname is the path of the rendering method of the frame, postUrl is the path of the API route that handles frame action requests, state is the state of the frame, previousFrame is the previous frame, and accepts is an array of client protocols that this frame supports.

Validating a Frame Action

Before returning a frame or doing any processing, you may want to validate the frame and extract the context from which the frame was interacted with e.g. the user that clicked the button in a farcaster in an XMTP chat. This is where the getFrameMessage, getXmtpFrameMessage, and isXmtpFrameActionPayload functions come in.

const previousFrame = getPreviousFrame(searchParams);
 
// do some logic to determine the next frame
 
let fid: number | undefined;
let walletAddress: string | undefined;
 
if ( 
  previousFrame.postBody &&
  isXmtpFrameActionPayload(previousFrame.postBody) 
) { 
  const frameMessage = await getXmtpFrameMessage(previousFrame.postBody); 
  // do something with XMTP frame message
} else { 
  const frameMessage = await getFrameMessage(previousFrame.postBody); 
  // do something with Farcaster frame message
} 
 
// ...

Here we use previousFrame.postBody to extract the frame action payload from the previous frame. We then use isXmtpFrameActionPayload to determine if the frame action payload is an XMTP frame action payload. If it is, we use getXmtpFrameMessage to extract the XMTP frame message from the frame action payload. If it isn't, we use getFrameMessage to extract the Farcaster frame message from the frame action payload.

Now we can use data from the different message contexts to populate our fid and walletAddress variables.

// ...
 
let fid: number | undefined;
let walletAddress: string | undefined;
 
if (
  previousFrame.postBody &&
  isXmtpFrameActionPayload(previousFrame.postBody)
) {
  const frameMessage = await getXmtpFrameMessage(previousFrame.postBody);
  walletAddress = frameMessage?.verifiedWalletAddress; 
} else {
  const frameMessage = await getFrameMessage(previousFrame.postBody);
  if (frameMessage && frameMessage?.isValid) {

    fid = frameMessage?.requesterFid; 
    walletAddress =
      frameMessage?.requesterCustodyAddress.length > 0
        ? frameMessage?.requesterCustodyAddress 
        : frameMessage.requesterCustodyAddress; 
  } 
}
 
// ...

Here we use the frameMessage to extract the verifiedWalletAddress and requesterFid from the XMTP and Farcaster frame messages respectively. We then use these to populate our walletAddress and fid variables. You can use this information to execute some action like a database query or an onchain transaction.

Returning a Frame

Now that we have our fid and walletAddress variables populated, we can use them to determine the next frame to return.

// ...
 
return (
  <FrameContainer
    pathname="/"
    postUrl="/frames"
    state={{}}
    previousFrame={previousFrame}
    accepts={acceptedProtocols}
  >
    <FrameImage>
      <div tw="flex flex-col">
        <div tw="flex">
          This frame gets the interactor&apos;s wallet address or FID depending
          on the client protocol.
        </div>
        {fid && <div tw="flex">FID: {fid}</div>}
        {walletAddress && <div tw="flex">Wallet Address: {walletAddress}</div>}
      </div>
    </FrameImage>
    <FrameButton>Check</FrameButton>
  </FrameContainer>
);

Above, we conditionally render the fid and walletAddress variables in the frame.