Farmark

Farmark is a Farcaster mini app and backend for saving casts, browsing a personal library, and unlocking Pro features with an NFT on Base.

Product Features

Free Features

• Save casts from Farcaster into a personal library.
• Save casts natively from the Farcaster share sheet after adding Farmark to Apps.
• Browse bookmarks on the web UI.
• Search and filter saved casts.
• Use the Farcaster mini app and frame-based entry flow.

Pro Features

• NFT-based Pro access on Base Mainnet.
• Pro membership is minted from the live ProAccessNFT contract.
• AI summary tools for saved content.
• Advanced analytics dashboard.
• Export bookmarks in JSON or CSV.
• Pro mint page and on-chain verification flow.

What Runs in Production

• index.js is the only backend entrypoint.
• public/ contains the static pages served by Express.
• db.js, neynar.js, ai.js, nft.js, pro-middleware.js, cache.js, alerts.js, and fid-mapper.js support the running app.
• pro-access-nft-contract/ is only for contract deployment and maintenance.
• miniapp/ is a separate Expo app and is not part of the Vercel backend deploy.

Required Environment Variables

Copy from .env.example and fill the real values.

# Database
POSTGRES_URL=postgres://...

# Farcaster / Admin
NEYNAR_API_KEY=...
ADMIN_KEY=...

# AI providers (fill at least one)
GROQ_API_KEY=...
DEEPSEEK_API_KEY=
GEMINI_API_KEY=

# Pro / NFT (optional)
PRO_NFT_CONTRACT_ADDRESS=0x08944d1bdA93dA6157784ca40A7F45DAe832Dc5b
BASE_MAINNET_RPC_URL=https://mainnet.base.org

# Local / debug
DEBUG=false
PORT=3000

Important: POSTGRES_URL must be a real Neon/Vercel Postgres connection string. The app now accepts either direct or pooled Neon URLs locally, but pooled is still the better choice for deployment.

Local Run

npm install
npm run dev

Useful local checks:

curl http://127.0.0.1:3000/health
curl -I http://127.0.0.1:3000/pro
curl -I http://127.0.0.1:3000/pro-wagmi

If the database is missing or misconfigured, the server still starts in fallback mode, but DB-backed features will not work.

Vercel Deploy

1. Create or link the Vercel project.
2. Add the required environment variables in Vercel.
3. Set POSTGRES_URL to the pooled Neon connection string.
4. Deploy with:

npx vercel --prod

The app serves Farcaster metadata from:

/.well-known/farcaster.json

If you want to preserve the existing Farcaster association, redeploy on the same domain: farmark.vercel.app.

Native Save Flow in Farcaster

Farmark now uses a Farcaster Mini App share extension for native cast saving.

User Flow

1. Open Farmark and tap Add to Apps.
2. Close and reopen the Farcaster app so the share sheet refreshes.
3. Open any cast, tap Share, and select Farmark.
4. Farmark opens the share handler and saves the cast automatically.

What Changed

• The home screen now includes an Add to Apps button that calls sdk.actions.addMiniApp().
• The first app launch shows a one-time onboarding popup explaining the save flow.
• After a successful add, the app shows a toast reminding the user to close and reopen Farcaster.
• The share save screen now shows Open Library and Close actions after saving.

Technical Implementation

• /.well-known/farcaster.json includes frame.castShareUrl pointing to /share.
• index.js serves the /share route.
• public/share.html reads the cast share context from the Farcaster Mini App SDK.
• When the share context is present, the app sends the cast hash, cast text, author info, and viewer FID to /api/add-bookmark.
• This avoids external browser redirects and does not rely on legacy Cast Action install URLs.

Important Notes

• The native save entry appears only after the app has been added through Add to Apps.
• Users usually need to fully close and reopen Farcaster once after adding the app.
• Manual saving is still available at /save-cast for direct testing and fallback use.

Main Routes

• / - main mini app page
• /library - saved casts
• /analytics - analytics dashboard
• /share - Farcaster share extension handler for native save flow
• /save-cast - manual save page
• /pro - current Pro landing page
• /pro-wagmi - alternate NFT mint page
• /.well-known/farcaster.json - Farcaster manifest
• /health - health check

Smart Contract

• Contract: ProAccessNFT
• Network: Base Mainnet
• Address: 0x08944d1bdA93dA6157784ca40A7F45DAe832Dc5b
• Current mint price: 0.0005 ETH

License

MIT. See LICENSE.