Skip to main content

Farcaster Frames

The app exposes HTML frame responses and PNG image routes so a Farcaster cast can open into a wallet-specific ClankerCats browser.

Entry points​

GET /api/frame
GET /api/frame/<wallet>
POST /api/frame/<wallet>?idx=<n>&count=<total>

Behavior:

  • GET /api/frame returns the landing frame with an input box for a wallet address.
  • GET /api/frame/<wallet> validates the address, reads OwnerUpegsCount, and returns the first cat view for that wallet.
  • POST /api/frame/<wallet> handles button clicks and moves backward or forward through the wallet's cats.
  • Invalid or missing wallet paths fall back to the landing frame.

Image routes used by the frame​

EndpointOutput
GET /api/frame-landing-image1200x630 PNG for the landing state
GET /api/cat-image?wallet=<address>&idx=<n>1200x630 PNG for the selected cat
GET /api/no-cats1200x630 PNG for empty-state wallets

Notes:

  • cat-image reads the wallet's cats from OwnerUpegsPage(owner, 0, 100) and clamps idx into bounds.
  • cat-image returns 400 for invalid wallets and 404 if the wallet has no cats.
  • Frame and image routes are rate-limited to 60 requests per minute per IP.

Button behavior​

The wallet frame builds its button row dynamically:

  • Prev only appears when the current index is greater than zero.
  • The center button shows the current position as 🐱 current/total.
  • Next only appears when there are more cats ahead.
  • Buy CCAT is always a link button to the app's Uniswap URL.

Base URL requirement​

The frame route builds absolute image and post URLs from NEXT_PUBLIC_URL.

Current fallback behavior in code:

  • If NEXT_PUBLIC_URL is set, frame metadata uses that value.
  • If it is unset, the route falls back to https://clankercats.xyz.

If the production public site is https://clankercats.com, set NEXT_PUBLIC_URL explicitly so shared frames point at the intended domain.