How to handle frame interactions with the Neynar API

In this guide, we'll go over how to use our POST frame/action API to handle frame interactions on your backend. If you're looking for a guide on handling frame interactions on the client side with our @neynar/react SDK, click here.

Note: Before beginning, ensure that your backend has your Neynar API Key securely managed so you have safe access set up to call our API.

Calling the POST frame/action API

This API route takes three inputs:

• signer_uuid: the Neynar Signer UUID for the user who is taking the frame action, which would be retrieved through using Sign In with Neynar
  • required value
• cast_hash: the hash of the cast from which the frame action is taking place
  • optional value, defaults to 0xfe90f9de682273e05b201629ad2338bdcd89b6be
• action: the object of the frame being interacted with, including the interacted with button/action, which can normally be retrieved from the Neynar APIs
  • required value

Here's an example of what your POST request might look like:

curl --request POST \
  --url https://api.neynar.com/v2/farcaster/frame/action \
  --header 'accept: application/json' \
  --header 'api_key:  "'"neynarAPIKey"'"\
  --header 'content-type: application/json' \
  --data '{
    "signer_uuid": "'"$signerValue"'",
    "castHash": "'"$castHash"'",
    "action": {
      "button": "'"$button"'",
      "frames_url": "'"$localFrame.frames_url"'",
      "post_url": "'"${postUrl:-$localFrame.frames_url}"'",
      "input": {
        "text": "'"$inputValue"'"
      }
    }
  }'

Handling client-side interactions

There are a few frame actions that take place fully on the client-side and do not/cannot be sent to the POST frame/action API. Those actions are:

• post and redirect: these actions should be handled on the client either as a window.replace or as a link to a new tab
• mintand tx: the mint/transaction data itself should also be handled on the client, as the data from the frame object should have enough information to use in a package such as wagmi or viem. Here's an example from our wownar-react-sdk repo.

Conclusion

This guide went over how to handle frame interactions on your backend with the Neynar POST frame/action API. Make sure to share what you built with us on Farcaster by tagging @neynar, and if you have any questions, reach out to us on Warpcast or Telegram!