Farcaster — how to connect

Before you start

• A Neynar account with an API key that has write/cast access (the free plan may not include cast-publish access — a paid plan is generally required to post via the API)
• A registered Neynar "managed signer" whose signer_uuid has been approved — create the signer, then approve it by scanning the signer_approval_url QR code (or opening the deep link) in your Farcaster client (Warpcast); Neynar sponsors the on-chain signer registration by default so there's no gas cost
• An existing Farcaster account (an fid) that the signer gets approved for — the signer is useless until it is linked to and approved by that account
• Both the Neynar API key and the approved signer_uuid ready to paste into this integration's connect form (this is a credentials-paste flow, not OAuth)

Step by step

1. 1
   Create a Neynar account

   Sign up at the Neynar developer portal (dev.neynar.com) with your email or Farcaster login to reach your dashboard.

   Open
2. 2
   Create an API key

   In the dashboard's API keys section, generate a key (the free tier is enough to post) and copy it — this is the value the app calls the Neynar API key.

   Open
3. 3
   Create a managed signer

   Call Neynar's create-signer + register-signed-key endpoints (or their SDK's createSigner/registerSignedKey helper) with your API key to generate a new signer and its signer_approval_url.

   Open
4. 4
   Approve the signer in Warpcast

   Open the signer_approval_url — scan its QR code on desktop or tap the link on mobile — and approve the signer request inside Warpcast or your Farcaster client.

   Open
5. 5
   Confirm approval and copy the signer UUID

   Look up the signer until its status flips from pending_approval to approved, then copy that signer's signer_uuid.

   Open
6. 6
   Paste both values into the app

   Enter the Neynar API key and the approved signer UUID in the connect form; the app rejects the signer if its status isn't exactly "approved" or it has no linked fid.

Paste when you connect

• Neynar API keysecret

  dev.neynar.com → dashboard → API keys. Posting needs a plan with write/cast access (free tier may not include it).

• Approved signer UUIDsecret

  A Neynar managed signer's signer_uuid — create it via the API, approve it in Warpcast (scan the approval QR), then paste the UUID once its status is "approved".

Troubleshooting

Connecting fails immediately with something like "Signer is 'pending_approval', not 'approved'"

The signer was created but never approved in a Farcaster client. Open the signer_approval_url (or its QR code) from Neynar and approve it in Warpcast — status only flips to approved after that confirmation, and you can't publish until it does.

Casts fail to publish even though the signer shows approved, with a 401/403 from Neynar

The API key is invalid, revoked, or on a plan tier that doesn't include write/cast access. Confirm the key in the Neynar dashboard and that your plan includes the cast-publish endpoint — read-only/free-tier keys can fail here even though signer lookup succeeds.

Publish fails with a 400 even though the cast text is under the visible character counter

Farcaster's real limit is 320 bytes, not 320 characters — multi-byte characters (emoji, non-Latin text) can blow the byte cap while looking short. Neynar rejects the request server-side; trim non-ASCII content or shorten the cast.

Signer that worked before suddenly returns 'revoked' or the connected account stops publishing

Signers can be revoked if the user resets/removes app permissions in Warpcast, or if the underlying fid's key rotates. Re-run signer creation and go through the QR/deep-link approval flow again to get a fresh signer_uuid, then update the stored credentials.