Neynar Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

While Mini Apps are designed to be associated with a stable domain, there are times when you may need to migrate your app to a new domain. This could be due to rebranding, domain expiration, or other business reasons. The canonicalDomain field enables a smooth transition by allowing you to specify the new domain in your old manifest, ensuring clients can discover and redirect to your app’s new location.

How domain migration works

When a Mini App is accessed through its old domain, Farcaster clients check the manifest for a canonicalDomain field. If present, clients will:

1. Recognize that the app has moved to a new domain
2. Update their references to point to the new domain
3. Redirect users to the app at its new location

This ensures continuity for your users and preserves your app’s presence in app stores and user installations.

What happens to existing notification tokens

When Farcaster picks up the updated manifest with canonicalDomain, it automatically migrates all existing notification tokens from the old domain to the canonical domain. This means:

• Users who enabled notifications on your old domain do not need to re-enable them
• Notifications sent with a targetUrl on the new domain will be delivered to all existing subscribers
• If you use the same Neynar app (and therefore the same webhookUrl) on both domains, no additional Neynar configuration is needed — notifications will work seamlessly from the new domain once Farcaster processes the manifest update

Do not create a new Neynar app or change your webhookUrl during migration.
If you use a different webhookUrl on the new domain, new notification tokens will be stored in a separate Neynar app from the migrated ones, breaking notifications for existing users. Always reuse the same Neynar app and webhookUrl across both domains.

The automatic token migration happens on Farcaster’s side when it processes your updated manifest. No database changes or API calls on your end are required.

Migration steps

1. Prepare your new domain
   Set up your Mini App on the new domain with a complete manifest file at /.well-known/farcaster.json. This should include all your app configuration and an account association from the same FID to maintain ownership verification.

{
  "accountAssociation": {
    "header": "...",
    "payload": "...",
    "signature": "..."
  },
  "miniapp": {
    "version": "1",
    "name": "Your App Name",
    "iconUrl": "https://new-domain.com/icon.png",
    "homeUrl": "https://new-domain.com"
    // ... other configuration
  }
}

2. Update the old domain manifest
   Add the canonicalDomain field to your manifest on the old domain, pointing to your new domain:

{
  "accountAssociation": {
    "header": "...",
    "payload": "...",
    "signature": "..."
  },
  "miniapp": {
    "version": "1",
    "name": "Your App Name",
    "iconUrl": "https://old-domain.com/icon.png",
    "homeUrl": "https://old-domain.com",
    "canonicalDomain": "new-domain.com"
    // ... other configuration
  }
}

The canonicalDomain value must be a valid domain name without protocol, port, or path:

• ✅ app.new-domain.com
• ✅ new-domain.com
• ❌ https://new-domain.com
• ❌ new-domain.com:3000
• ❌ new-domain.com/app

3. Add canonicalDomain to the new manifest
   Include the canonicalDomain field in your new domain’s manifest as well, pointing to itself. This ensures consistency and makes it clear which domain is canonical:

{
  "accountAssociation": {
    "header": "...",
    "payload": "...",
    "signature": "..."
  },
  "miniapp": {
    "version": "1",
    "name": "Your App Name",
    "iconUrl": "https://new-domain.com/icon.png",
    "homeUrl": "https://new-domain.com",
    "canonicalDomain": "new-domain.com"
    // ... other configuration
  }
}

Both manifests must be live simultaneously. Farcaster verifies the canonicalDomain by fetching the manifest from the target domain — if the new domain’s manifest is not accessible, the migration will not be processed.

4. Maintain both domains during transition
   Keep both domains active during the migration period to ensure a smooth transition:

• Continue serving your app from the old domain with redirects to the new domain
• Keep the manifest file accessible on both domains
• Monitor traffic to understand when most users have migrated

5. Implement redirects (recommended)
   While the canonicalDomain field helps Farcaster clients understand the migration, you should also implement HTTP redirects from your old domain to the new one for users accessing your app directly after the manifest changes have been retrieved by the clients:

// Example redirect in Express
app.get('*', (req, res) => {
  const newUrl = `https://new-domain.com${req.originalUrl}`;
  res.redirect(301, newUrl);
});

Best practices

Plan ahead

• Choose a stable domain from the start to minimize the need for migrations
• If you anticipate a rebrand, consider using a neutral domain that can outlast brand changes

Communicate the change

• Notify your users about the domain change through in-app messages or casts
• Update any documentation or links that reference your old domain

Test thoroughly

• Verify that your manifest is correctly served on both domains
• Test the migration flow in different Farcaster clients
• Ensure all app functionality works correctly on the new domain

Monitor the transition

• Track traffic on both domains to understand migration progress
• Keep the old domain active until traffic drops to negligible levels
• Consider setting up analytics to track successful redirects

Troubleshooting

Clients not recognizing the new domain

Ensure that:

• The canonicalDomain value is correctly formatted (no protocol, port, or path)
• Your manifest is accessible at /.well-known/farcaster.json on both domains
• The manifest JSON is valid and properly formatted

Users still accessing the old domain

This is normal during transition. Some clients may cache manifest data, and users may have bookmarked the old URL. Continue to serve redirects from the old domain.

www. prefix issues

The www. prefix is treated as a subdomain. www.example.com and example.com are different domains and will be treated as separate apps. If your app is on example.com, do not use www.example.com as either a canonicalDomain value or in your targetUrl when sending notifications — this will cause domain mismatch errors and token invalidation.

Account association issues

Make sure you use the same account to produce the association on both domains to maintain ownership verification. Do not reuse the account association data from one manifest to the other.