Frame interactions
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
POST frame/action
APIThis 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
- optional value, defaults to
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
andredirect
: these actions should be handled on the client either as awindow.replace
or as a link to a new tabmint
andtx
: 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 aswagmi
orviem
. 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!
Updated 5 days ago