If you’re looking for a guide on handling frame interactions on the client side with our @neynar/react SDK, click here.

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!