Neynar Documentation

Publishing Mini Apps

Publishing Mini Apps involves providing information like who developed the app, how it should be displayed, and what its capabilities are. Since Farcaster is a decentralized network with multiple clients, publishing is done by hosting a manifest file at /.well-known/farcaster.json on the domain your app is hosted on rather than submitting information directly to a single entity.

Published Mini Apps can be discovered in App Stores.

Steps

1. Choose a domain
   A Mini App is associated with a single domain (i.e. rewards.warpcast.com). This domain serves as the identifier for your app and can’t be changed later, so you should choose a stable domain. There’s no limit on the number of apps you can create. You can create a separate domain specifically for development purposes if needed.

   A domain does not include the scheme (e.g. https) or path. It can optionally include a subdomain.

   • ✅ rewards.warpcast.com
   • ❌ https://rewards.warpcast.com

The www. prefix is treated as a subdomain like any other. www.example.com and example.com are considered different apps with separate notification tokens and user data. Pick one and use it consistently everywhere — in your manifest, accountAssociation, and target_url when sending notifications.

2. Host a manifest file
   Host a manifest file on your chosen domain at /.well-known/farcaster.json.

For now we’ll create an empty file:

touch public/.well-known/farcaster.json

Benefits of hosted manifests:

• No need to manage manifest files in your codebase
• Update manifest details without redeploying
• Automatic validation and error checking
• Easy domain migration support

To create a hosted manifest, visit: https://farcaster.xyz/~/developers/mini-apps/manifest

Setting up hosted manifests Instead of serving a /.well-known/farcaster.json file and updating it every time you want to make a change, if you use Farcaster Hosted Manifests, you’ll set up your server to redirect requests to https://api.farcaster.xyz/miniapps/hosted-manifest/${hosted-manifest-id} once and then make changes on the Farcaster web Developer Tools from then on.

To get your hosted manifest ID:

1. Go to https://farcaster.xyz/~/developers/mini-apps/manifest
2. Enter your domain and app details
3. You’ll receive a hosted manifest ID
4. Set up the redirect as shown below

Redirects in Next.js

// next.config.js
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async redirects() {
    return [
      {
        source: '/.well-known/farcaster.json',
        destination: 'https://api.farcaster.xyz/miniapps/hosted-manifest/1234567890',
        permanent: false,
      },
    ]
  },
}

export default nextConfig

Redirects in Express

const express = require('express')
const app = express()

app.get('/.well-known/farcaster.json', (req, res) => {
  res.redirect(307, 'https://api.farcaster.xyz/miniapps/hosted-manifest/1234567890')
})

Redirects in Hono

import { Hono } from 'hono'
const app = new Hono()

app.get('/.well-known/farcaster.json', (c) => {
  return c.redirect('https://api.farcaster.xyz/miniapps/hosted-manifest/1234567890', 307)
})

Redirects in Remix

// app/routes/.well-known/farcaster.json.tsx
import { redirect } from '@remix-run/node'

export const loader = () => {
  return redirect('https://api.farcaster.xyz/miniapps/hosted-manifest/1234567890', 307)
}

export default () => null

3. Define your application configuration
   A Mini App has metadata that is used by Farcaster clients to host your app. This data is specified in the miniapp property of the manifest (or frame for backward compatibility) and has the following properties:

Manifest properties

Here’s an example farcaster.json file:

{
  "miniapp": {
    "version": "1",
    "name": "Yoink!",
    "iconUrl": "https://yoink.party/logo.png",
    "homeUrl": "https://yoink.party/framesV2/",
    "imageUrl": "https://yoink.party/framesV2/opengraph-image",
    "buttonTitle": "🚩 Start",
    "splashImageUrl": "https://yoink.party/logo.png",
    "splashBackgroundColor": "#f5f0ec",
    "requiredChains": ["eip155:8453"],
    "requiredCapabilities": [
      "actions.signIn",
      "wallet.getEthereumProvider",
      "actions.swapToken"
    ]
  }
}

4. Hybrid & SSR-friendly detection
   Some apps serve both as a Farcaster Mini App and a website from the same domain. When you want to fetch specific resources during server-side rendering (SSR) or conditionally lazy-load the SDK on the client, add a lightweight flag that only Mini-App launch URLs include.

Two suggested patterns

Treat these markers as a best-effort hint, not proof. Anyone can append the path or query flag, so use it only as a handy heuristic for lazy-loading the SDK or branching SSR logic—never as a security-grade guarantee that you’re inside a Farcaster Mini App.

5. Verifying ownership
   A Mini App is owned by a single Farcaster account. This lets users know who they are interacting with and developers get credit for their work.

Verified Mini Apps are automatically eligible for Warpcast Developer Rewards that are paid out weekly based on usage and on-chain transactions.

Verification is done by placing a cryptographically signed message in the accountAssociation property of your farcaster.json. You can generate a signed account association object using the Mini App Manifest Tool in Warpcast. Take the output from that tool and update your farcaster.json file.

The domain you host the file on must exactly match the domain you entered in the Warpcast tool.

Here’s an example farcaster.json file for the domain yoink.party with the account association:

{
  "accountAssociation": {
    "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0",
    "payload": "eyJkb21haW4iOiJyZXdhcmRzLndhcnBjYXN0LmNvbSJ9",
    "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj"
  },
  "miniapp": {
    "version": "1",
    "name": "Rewards",
    "iconUrl": "https://rewards.warpcast.com/app.png",
    "splashImageUrl": "https://rewards.warpcast.com/logo.png",
    "splashBackgroundColor": "#000000",
    "homeUrl": "https://rewards.warpcast.com",
    "webhookUrl": "https://client.farcaster.xyz/v1/creator-rewards-notifs-webhook",
    "subtitle": "Top Warpcast creators",
    "description": "Climb the leaderboard and earn rewards by being active on Warpcast.",
    "screenshotUrls": [
      "https://rewards.warpcast.com/screenshot1.png",
      "https://rewards.warpcast.com/screenshot2.png",
      "https://rewards.warpcast.com/screenshot3.png"
    ],
    "primaryCategory": "social",
    "tags": [
      "rewards",
      "leaderboard",
      "warpcast",
      "earn"
    ],
    "heroImageUrl": "https://rewards.warpcast.com/og.png",
    "tagline": "Top Warpcast creators",
    "ogTitle": "Rewards",
    "ogDescription": "Climb the leaderboard and earn rewards by being active on Warpcast.",
    "ogImageUrl": "https://rewards.warpcast.com/og.png"
  }
}