We’re so excited that mini apps are supported in Base App! The purpose of this guide is to go over how to build or update your mini app so it works as well as possible in Base App.

​
Using MiniKit

For reference, MiniKit is easiest way to build mini apps on Base, allowing developers to easily build mini apps without needing to know the details of the SDK implementation. It integrates seamlessly with OnchainKit components and provides Base App-specific hooks.

Quick Start with MiniKit

If you use MiniKit and/or follow the MiniKit quickstart guide, your mini app will work out of the box in Base App!

Debugging Guide

If you’re already using MiniKit and experiencing issues, you can refer to our debugging guide

​
Authentication

As a general rule of thumb, we recommend that you save authentication that requires an interaction for interactions that require it(eg. buying something, viewing personalized pages etc)
Below we will quickly cover the different methods of authentication offered for mini apps and how well each of them work in Base App:
Base App natively supports Sign In with Farcaster(SIWF) in-app, so you can sign users in and get their social identity all without leaving Base App.We also support Quick Auth, which uses Sign In with Farcaster to issue developers a JWT that can be used to persist the user’s session in the mini app.This is the expected flow for end-users to Sign In with Farcaster in your mini app:
  • Create Account Users: Users who created a net-new Farcaster account during Base App onboarding
    • When signing into a mini app, the user will be prompted to see a “Login request” tray showing the SIWF message and can sign it right their with their passkey
  • Connect Account Users: Users who connected an existing Farcaster account during Base App onboarding
    • When signing into a mini app for the first time, the user will be prompted to deeplink to Farcaster(one-time only) and register their wallet as an auth address, which will then enable seamless in-app sign in — just like the above create account flow
The official mini apps SDK offers a set of actions (which MiniKit offers as well) so that users of your mini app can be led to do things back in clients like Base App (e.g. compose a cast, view a profile, etc).
Always use official SDK functions instead of Farcaster-specific deeplinks in your mini app.
While some developers have used Farcaster-specific deeplinks in the openUrl function as a workaround, this approach can create problems. Farcaster-specific deeplinks might not match Base App-specific deeplinks, potentially leaving users dead-ended and unable to take further action in your mini app. Using the official SDK functions ensures your users have the best viewing experience possible across all supported clients, including Base App.

​
Wallet Interactions

Wallet interactions are a core part of the miniapp experience. We want to ensure both that building wallet interactions on top of the Base App is smooth for developers and that users can choose/have funds sent to their Base App when interacting with mini apps. As a mini app host, we expose an EIP-1193 Ethereum Provider that can be accessed in two primary ways:

​
Metadata

Farcaster has recently extended the metadata spec for mini apps, which allows developers to add screenshot links, categories, and more to their manifest (farcaster.json) file. Making use of these new metadata fields is highly recommended for increasing the chance that your mini app could be featured throughout Base App. Below is a table of the new metadata fields introduced, what they mean/could potentially be used for, and an example of what a manifest file could look like with these new fields (all taken from the official spec)
Note: We highly recommend that you set this metadata as it will give your mini app a better shot at being featured throughout Base App.

​
Example Manifest

{
  "accountAssociation": {
    "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0",
    "payload": "eyJkb21haW4iOiJyZXdhcmRzLndhcnBjYXN0LmNvbSJ9",
    "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj"
  },
  "frame": {
    "version": "1",
    "name": "Example Mini App",
    "iconUrl": "https://example.com/app.png",
    "splashImageUrl": "https://example.com/logo.png",
    "splashBackgroundColor": "#000000",
    "homeUrl": "https://example.com",
    "webhookUrl": "https://example.com/api/webhook",
    "subtitle": "Example Mini App subtitle",
    "description": "Example Mini App subtitle",
    "screenshotUrls": [
      "https://example.com/screenshot1.png",
      "https://example.com/screenshot2.png",
      "https://example.com/screenshot3.png"
    ],
    "primaryCategory": "social",
    "tags": [
      "example",
      "mini app",
      "Base App"
    ],
    "heroImageUrl": "https://example.com/og.png",
    "tagline": "Example Mini App tagline",
    "ogTitle": "Example Mini App",
    "ogDescription": "Example Mini App description",
    "ogImageUrl": "https://example.com/og.png"
  }
}

​
Notifications

You will soon be able to send notifications from your Mini App that will appear in Base App. These notifications help re-engage users when something important happens, like a new drop, an update, or a reminder to complete an action. There are two ways to integrate:

​
Mini Apps Compatibility in Base App

Base App is working towards full compatibility with the Farcaster Mini App SDK. While we continue to enhance support during the beta phase, there are currently some features that are not yet supported.

​
AI-Powered Compatibility Checking

We provide a validate.txt file that can be used with AI tools to automatically check your codebase for Base App compatibility issues. Similar to llms.txt files, you can provide this validation file to language models to scan your Mini App code and receive a detailed compatibility report highlighting any unsupported features or patterns.
This AI validation is experimental and should only be used in a read-only capacity for analysis and reporting purposes.

​
Currently Unsupported Features

The following Mini App SDK features are not currently supported in Base App:

​
Environment Detection

  • sdk.isInMiniApp()

​
Haptic Feedback

  • All haptic related SDK methods
    • sdk.haptics.impactOccurred()
    • sdk.haptics.notificationOccurred()
    • sdk.haptics.selectionChanged()

​
Token Actions

  • sdk.actions.swapToken()
  • sdk.actions.sendToken()

​
Wallet Interactions

  • sdk.actions.getEthereumProvider()
  • Direct HTML links to third-party websites (<a href=, <Link href=)
    • Note: You can instead use sdk.actions.openUrl() to safely open a third-party website in our in-app browser
  • Warpcast/Farcaster composer intent URLs (warpcast.com/~/compose, farcaster.com/~/compose)
    • Note: You can instead use sdk.actions.composeCast() to compose a cast directly in Base App

​
Context Features

  • Share extensions
  • sdk.context.location

​
Supported Chains

  • Base
  • Mainnet
  • Optimism
  • Arbitrum
  • Polygon
  • Zora
  • BNB
  • Avalanche C-Chain

​
Development Notes

  • Use sdk.actions.openUrl() for external navigation instead of direct HTML links
  • Use sdk.actions.composeCast() instead of Warpcast composer URLs
  • Implement visual feedback alternatives for haptic feedback
  • Avoid relying on location context for core functionality
  • To conditionally render functionality based on the user’s client, check context.client.clientFid (Base App returns 309857)
We are actively working to expand compatibility and expect to support additional features in future releases.