From f3c6e6e73696aad7ce469128f56e7152e7f6891e Mon Sep 17 00:00:00 2001 From: sohey Date: Tue, 14 Apr 2026 14:41:06 +0200 Subject: [PATCH] removed files --- docs/.mintignore | 9 +- docs/apps/core-concepts/authentication.mdx | 157 ---- docs/apps/core-concepts/base-account.mdx | 215 ------ docs/apps/core-concepts/context.mdx | 400 ---------- .../core-concepts/embeds-and-previews.mdx | 146 ---- docs/apps/core-concepts/manifest.mdx | 214 ------ docs/apps/core-concepts/navigation.mdx | 216 ------ docs/apps/core-concepts/notifications.mdx | 387 ---------- .../featured-guidelines/design-guidelines.mdx | 84 --- .../notification-guidelines.mdx | 57 -- docs/apps/featured-guidelines/overview.mdx | 69 -- .../product-guidelines.mdx | 71 -- .../technical-guidelines.mdx | 79 -- docs/apps/growth/build-viral-apps.mdx | 297 -------- docs/apps/growth/optimize-onboarding.mdx | 116 --- docs/apps/introduction/overview.mdx | 188 ----- docs/apps/quality-and-publishing/overview.mdx | 9 - .../quality-and-publishing/quality-bar.mdx | 9 - .../submission-guidelines.mdx | 9 - docs/apps/quickstart/build-checklist.mdx | 70 -- .../quickstart/building-for-the-base-app.mdx | 57 -- docs/apps/quickstart/create-new-app.mdx | 152 ---- .../apps/quickstart/migrate-existing-apps.mdx | 241 ------ docs/apps/quickstart/template.mdx | 6 - .../apps/technical-guides/accept-payments.mdx | 110 --- .../technical-guides/building-chat-agents.mdx | 710 ------------------ .../technical-guides/neynar-notifications.mdx | 263 ------- .../sharing-and-social-graph.mdx | 61 -- docs/apps/technical-guides/sign-manifest.mdx | 104 --- .../base-app-compatibility.mdx | 62 -- docs/apps/troubleshooting/common-issues.mdx | 243 ------ docs/apps/troubleshooting/error-handling.mdx | 9 - .../apps/troubleshooting/how-search-works.mdx | 81 -- docs/apps/troubleshooting/testing.mdx | 78 -- 34 files changed, 1 insertion(+), 4978 deletions(-) delete mode 100644 docs/apps/core-concepts/authentication.mdx delete mode 100644 docs/apps/core-concepts/base-account.mdx delete mode 100644 docs/apps/core-concepts/context.mdx delete mode 100644 docs/apps/core-concepts/embeds-and-previews.mdx delete mode 100644 docs/apps/core-concepts/manifest.mdx delete mode 100644 docs/apps/core-concepts/navigation.mdx delete mode 100644 docs/apps/core-concepts/notifications.mdx delete mode 100644 docs/apps/featured-guidelines/design-guidelines.mdx delete mode 100644 docs/apps/featured-guidelines/notification-guidelines.mdx delete mode 100644 docs/apps/featured-guidelines/overview.mdx delete mode 100644 docs/apps/featured-guidelines/product-guidelines.mdx delete mode 100644 docs/apps/featured-guidelines/technical-guidelines.mdx delete mode 100644 docs/apps/growth/build-viral-apps.mdx delete mode 100644 docs/apps/growth/optimize-onboarding.mdx delete mode 100644 docs/apps/introduction/overview.mdx delete mode 100644 docs/apps/quality-and-publishing/overview.mdx delete mode 100644 docs/apps/quality-and-publishing/quality-bar.mdx delete mode 100644 docs/apps/quality-and-publishing/submission-guidelines.mdx delete mode 100644 docs/apps/quickstart/build-checklist.mdx delete mode 100644 docs/apps/quickstart/building-for-the-base-app.mdx delete mode 100644 docs/apps/quickstart/create-new-app.mdx delete mode 100644 docs/apps/quickstart/migrate-existing-apps.mdx delete mode 100644 docs/apps/quickstart/template.mdx delete mode 100644 docs/apps/technical-guides/accept-payments.mdx delete mode 100644 docs/apps/technical-guides/building-chat-agents.mdx delete mode 100644 docs/apps/technical-guides/neynar-notifications.mdx delete mode 100644 docs/apps/technical-guides/sharing-and-social-graph.mdx delete mode 100644 docs/apps/technical-guides/sign-manifest.mdx delete mode 100644 docs/apps/troubleshooting/base-app-compatibility.mdx delete mode 100644 docs/apps/troubleshooting/common-issues.mdx delete mode 100644 docs/apps/troubleshooting/error-handling.mdx delete mode 100644 docs/apps/troubleshooting/how-search-works.mdx delete mode 100644 docs/apps/troubleshooting/testing.mdx diff --git a/docs/.mintignore b/docs/.mintignore index 665b1c221..d7328fd5d 100644 --- a/docs/.mintignore +++ b/docs/.mintignore @@ -1,11 +1,4 @@ # Exclude specific files writing.md -# Hidden apps sections (redirected to migrate-to-standard-web-app) -/apps/core-concepts/* -/apps/resources/* -/apps/featured-guidelines/* -/apps/troubleshooting/* -/apps/introduction/* -/apps/growth/build-viral-apps -/apps/growth/optimize-onboarding + diff --git a/docs/apps/core-concepts/authentication.mdx b/docs/apps/core-concepts/authentication.mdx deleted file mode 100644 index f0414a9d3..000000000 --- a/docs/apps/core-concepts/authentication.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -hidden: true -title: Authentication -description: Quick Auth provides instant authentication by leveraging Farcaster's identity system - no passwords, email verification, or complex OAuth flows required. ---- - -When Quick Auth is called: - -* The user authenticates with a signature -* The SDK returns a JWT that your backend verifies to confirm the user's identity -* The backend returns trusted data that can be used for sensitive actions - - -This differs from the [Context API](/mini-apps/core-concepts/context), which provides instant access to user information without authentication but cannot be trusted for sensitive operations. - - - -## Implementation - -### Step 1: Frontend Authentication - -This code authenticates the user with Quick Auth, stores the JWT in memory, and uses it to verify the user's identity with your backend. - - ```jsx App.tsx -import { useState } from "react"; -import { sdk } from "@farcaster/miniapp-sdk"; - -export function App() { - const [token, setToken] = useState(null); - const [userData, setUserData] = useState<{ fid: number} | null>(null); - - async function signIn() { - try { - const { token } = await sdk.quickAuth.getToken(); - setToken(token); - - // Use the token to authenticate the user and fetch authenticated user data - const response = await sdk.quickAuth.fetch(`${BACKEND_ORIGIN}/auth`, { - headers: { "Authorization": `Bearer ${token}` } - }); - - const data = await response.json(); - setUserData(data); - } catch (error) { - console.error("Authentication failed:", error); - } - } - - function signOut() { - setToken(null); - setUserData(null); - } - - if (!token) { - return ; - } - - return ( -
-

Authenticated as FID: {userData?.fid}

- -
- ); -} -``` - -### Step 2: Backend Verification - -Install the Quick Auth client: - -```bash -npm install @farcaster/quick-auth -``` - -**Quick Auth Client** is the SDK that initiates the authentication flow in your application. - -**Quick Auth Server** is Farcaster's service that handles signature verification and issues JWTs. - -When a user authenticates, the Quick Auth Server verifies their signature and issues a JWT. Your backend verifies this JWT using the `@farcaster/quick-auth` package. - -```jsx route.tsx -// app/api/auth/route.ts -import { createClient, Errors } from '@farcaster/quick-auth'; -import { NextRequest, NextResponse } from 'next/server'; - -const domain = 'your-domain.com'; // Must match your mini app's deployment domain -const client = createClient(); - -// This endpoint returns the authenticated user's FID -export async function GET(request: NextRequest) { - const authorization = request.headers.get('Authorization'); - if (!authorization?.startsWith('Bearer ')) { - return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }); - } - - const token = authorization.split(' ')[1]; - - try { - const payload = await client.verifyJwt({ token, domain }); - - return NextResponse.json({ - fid: payload.sub, - }); - } catch (e) { - if (e instanceof Errors.InvalidTokenError) { - return NextResponse.json({ error: 'Invalid token' }, { status: 401 }); - } - throw e; - } -} -``` - -## Schema - -### JWT Payload - - -```json -{ - "iat": 1747764819, - "iss": "https://auth.farcaster.xyz", - "exp": 1747768419, - "sub": 6841, - "aud": "your-domain.com" -} -``` -Payload fields: - - - -Issued at timestamp - - - -Quick Auth Server that issued the JWT - - - -Expiration timestamp (1 hour from issuance) - - - -User's Farcaster ID (FID) - - - -Your mini app's domain - - - - - - - Understand how context is used in mini apps. - - - diff --git a/docs/apps/core-concepts/base-account.mdx b/docs/apps/core-concepts/base-account.mdx deleted file mode 100644 index 000d659dd..000000000 --- a/docs/apps/core-concepts/base-account.mdx +++ /dev/null @@ -1,215 +0,0 @@ ---- -hidden: true -title: "Base Account" -description: "Deliver a frictionless user experience with one universal account and built-in identity that works across every Mini App in the Base App." ---- - -## What is Base Account? - -Base Account is a Smart Wallet-backed account that provides: - -- **Universal sign-on** – one passkey works across every Base-enabled app -- **One-tap USDC payments** – low-friction payments built into the account layer -- **Gasless transactions** – apps can sponsor user transaction fees -- **Batch transactions** – combine multiple operations into a single confirmation - - -Mini Apps launched within the Base App are automatically connected to the user's Base Account, eliminating wallet connection flows and enabling instant onchain interactions. - - - -Base Account relies on the [Blockaid](https://blockaid.io/) platform to flag apps as unsafe. -If your app is being flagged as unsafe or if you are concerned -about your app being flagged as unsafe, -you can follow the steps detailed in the [Common Issues & Debugging](/mini-apps/troubleshooting/common-issues#7-your-app-is-being-flagged-as-unsafe%3F) guide. - - - ---- - -## Implementation - - - -Configure Wagmi with the Farcaster Mini App connector and Base Account connector to enable Base Account features in your Mini App: - -```typescript wagmi.ts expandable highlight={16-22} -"use client"; - -import { createConfig, http, WagmiProvider } from "wagmi"; -import { base, optimism } from "wagmi/chains"; -import { baseAccount } from "wagmi/connectors"; -import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; -import { farcasterMiniApp } from "@farcaster/miniapp-wagmi-connector"; -import { METADATA } from "../lib/utils"; - -export const config = createConfig({ - chains: [base, optimism], - transports: { - [base.id]: http(), - [optimism.id]: http(), - }, - connectors: [ - farcasterMiniApp(), - baseAccount({ - appName: METADATA.name, - appLogoUrl: METADATA.iconImageUrl, - }) - ], -}); - -const queryClient = new QueryClient(); - -export default function Provider({ children }: { children: React.ReactNode }) { - return ( - - {children} - - ); -} -``` - - -The `farcasterMiniApp()` connector automatically connects to the user's Base Account when the Mini App launches within the Base App. - - - - -Use Wagmi's [`sendCalls`](https://wagmi.sh/core/api/actions/sendCalls) to send batched transactions. First, check if the wallet supports paymaster capabilities using [`getCapabilities`](https://wagmi.sh/core/api/actions/getCapabilities), then conditionally include paymaster settings in your transaction: - -```typescript components/BatchTransaction.tsx highlight={9,10,11,12,34} -import { parseEther } from 'viem'; -import { sendCalls, getCapabilities } from '@wagmi/core'; -import { config } from '../providers/Provider'; - -async function sendBatchTransaction() { - // Get the connected account - const [account] = await config.getClient().getAddresses(); - - // Check if paymaster capability is supported - const capabilities = await getCapabilities(config, { - account, - }); - - const baseCapabilities = capabilities[8453]; // Base mainnet chain ID - const supportsPaymaster = baseCapabilities?.paymasterService?.supported; - - // Prepare transaction calls - const calls = [ - { - to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', - value: parseEther('0.01'), - }, - { - to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC', - value: parseEther('0.01'), - }, - ]; - - // Send calls with optional paymaster capability - const id = await sendCalls(config, { - account, - calls, - chainId: 8453, - capabilities: supportsPaymaster - ? { - paymasterService: { - url: 'https://api.developer.coinbase.com/rpc/v1/base/YOUR_KEY', - }, - } - : undefined, - }); - - console.log('Transaction batch ID:', id); -} -``` - - -You can get your paymaster API key from [Coinbase Developer Platform](https://docs.cdp.coinbase.com/paymaster/introduction/welcome) to sponsor gas fees for your users. - - - - - Learn about atomic batching and how to use it with Base Account - - - - Set up paymasters and manage gas sponsorship - - - - - -Getting the provider allows you to use the Base Account SDK to interact with the user's Base Account. -Follow the [Base Account guides](/base-account/overview/what-is-base-account) to use these features. - -Once you have the provider, you can call Base Account RPC methods. See the [full RPC methods reference](/base-account/reference/core/provider-rpc-methods/request-overview) for complete details. - -The next section lists the methods and capabilities that are not supported in Mini Apps yet. - - ---- - -## Verify social accounts with Base Verify - -[Base Verify](/base-account/guides/verify-social-accounts) lets your Mini App users prove ownership of verified accounts (X, Coinbase, Instagram, TikTok) without sharing credentials. You receive a deterministic token for Sybil resistance — one verified account produces the same token regardless of which wallet the user connects with. - -**How it works:** - -1. Check if the wallet has a verification → API returns yes/no -2. If no → redirect to the Base Verify Mini App for OAuth -3. User verifies → returns to your app -4. Check again → now verified, you receive a token - -**Quick example — check if a user has a verified X account:** - -```typescript Title "Base Verify check" highlight={1-4,7-8} -const resources = [ - 'urn:verify:provider:x', - 'urn:verify:provider:x:verified:eq:true', - 'urn:verify:action:claim_airdrop' -] - -// Generate SIWE message with these resources, sign it, -// then send to your backend to call the Base Verify API -``` - - - Complete walkthrough covering all providers, traits, API reference, security, and implementation details. - - ---- - -## Unsupported Methods and Capabilities - -The following methods and capabilities are not yet supported in Mini Apps but will be added soon: - -| Feature | Method/Capability | -|---------|------------------| -| Sign in with Base | `wallet_connect` | -| Sub accounts | `wallet_getSubAccounts`, `wallet_addSubAccount` | -| Profiles | `datacallback` | - -All other standard Ethereum and Base Account RPC methods work as expected. - - -The above list is not exhaustive and may be updated in the future. - - ---- - -## Additional Resources - - - - Full overview of Base Account - - - - Complete reference for the Base Account SDK - - - - Get support from the Base team and community - - diff --git a/docs/apps/core-concepts/context.mdx b/docs/apps/core-concepts/context.mdx deleted file mode 100644 index d1096e7cf..000000000 --- a/docs/apps/core-concepts/context.mdx +++ /dev/null @@ -1,400 +0,0 @@ ---- -hidden: true -title: "Mini App Context" -description: "Improve user experience by instantly displaying user profile data and customizing user flows based on where your mini app was opened" -sidebarTitle: "Context" ---- - -When your app is opened as a mini app, `sdk.context` provides 4 data objects: - -- `user`: User profile data -- `location`: Where the mini app was opened -- `client`: Host platform (e.g. the Base app or another Farcaster client) and device data -- `features`: Availability and state of features in the current client - - - -```ts MiniAppContextTypes.ts -export type MiniAppPlatformType = 'web' | 'mobile'; - -export type MiniAppContext = { - user: { - fid: number; - username?: string; - displayName?: string; - pfpUrl?: string; - }; - location?: MiniAppLocationContext; - client: { - platformType?: MiniAppPlatformType; - clientFid: number; - added: boolean; - safeAreaInsets?: SafeAreaInsets; - notificationDetails?: MiniAppNotificationDetails; - }; - features?: { - haptics: boolean; - cameraAndMicrophoneAccess?: boolean; - }; -}; -``` - - -## Implementation - -1. Install and import `@farcaster/miniapp-sdk` -2. Check if opened as a mini app using `sdk.isInMiniApp();` -3. If in a mini app, load the context object using `sdk.context` - - -In the example below we detect if the app was opened as a mini app, and if so, we return the user's username, fid, display name, and profile image. - -```typescript app/profile/page.tsx -"use client"; -import { sdk } from "@farcaster/miniapp-sdk"; -import { useEffect, useState } from "react"; - -export default function Profile() { - const [user, setUser] = useState(null); - const [isInMiniApp, setIsInMiniApp] = useState(false); - - useEffect(() => { - const loadUserData = async () => { - try { - // Check if we're in a Mini App - const miniAppStatus = await sdk.isInMiniApp(); - setIsInMiniApp(miniAppStatus); - - if (miniAppStatus) { - // Get context and extract user info - const context = await sdk.context; - setUser(context.user); - } - } catch (error) { - console.error("Error loading user data:", error); - } - }; - - loadUserData(); - }, []); - - // Show message if not in Mini App - if (!isInMiniApp) { - return ( -
-

Please open this app in a Farcaster or Base client to see your profile.

-
- ); - } - - // Show user information - if (user) { - return ( -
-

Welcome, {user.displayName || user.username}!

-

FID: {user.fid}

-

Username: @{user.username}

- {user.pfpUrl && ( - Profile - )} -
- ); - } - - return
Loading user profile...
; -} -``` - -## Schema - - -### User Object - -Contains the user's profile information. This data shouldn't be used for authentication or sensitive actions because its passed by the application. - - - -Unique Farcaster identifier for the user. - - - -Handle without @ symbol. - - - -User's chosen display name. - - - -Profile picture URL. - - - -User's biography text. - - - -User's location information. - - - -Google Places ID. - - - -Human-readable location description. - - - - - -```json user.json -{ - "fid": 6841, - "username": "deodad", - "displayName": "Tony D'Addeo", - "pfpUrl": "https://i.imgur.com/dMoIan7.jpg", - "bio": "Building @warpcast and @farcaster", - "location": { - "placeId": "ChIJLwPMoJm1RIYRetVp1EtGm10", - "description": "Austin, TX, USA" - } -} -``` -### Location Object - -Contains information about the context from which the Mini App was launched. This helps you understand how users discovered and accessed your app. - -**Location Types:** -- **`cast_embed`**: Launched from a cast where your app is embedded -- **`cast_share`**: Launched when a user shared a cast to your app -- **`notification`**: Launched from a notification triggered by your app -- **`launcher`**: Launched directly from the client app catalog -- **`channel`**: Launched from within a specific Farcaster channel -- **`open_miniapp`**: Launched from another Mini App - -#### CastEmbedLocationContext - - - -Indicates the Mini App was launched from a cast where it is an embed. - - - -The embed URL. - - - -Cast information containing the embed. - - - -```json cast_embed.json -{ - "type": "cast_embed", - "embed": "https://myapp.example.com", - "cast": { - "author": { - "fid": 3621, - "username": "alice", - "displayName": "Alice", - "pfpUrl": "https://example.com/alice.jpg" - }, - "hash": "0xa2fbef8c8e4d00d8f84ff45f9763b8bae2c5c544", - "timestamp": 1749160866000, - "text": "Check out this awesome mini app!", - "embeds": ["https://myapp.example.com"], - "channelKey": "farcaster" - } -} -``` - -#### CastShareLocationContext - - - -Indicates the Mini App was launched when a user shared a cast to your app. - - - -The cast that was shared to your app. - - - -#### NotificationLocationContext - - - -Indicates the Mini App was launched from a notification. - - - -Notification details. - -Unique notification identifier. - - -Notification title. - - -Notification body text. - - - - - - -```json notification.json -{ - "type": "notification", - "notification": { - "notificationId": "f7e9ebaf-92f0-43b9-a410-ad8c24f3333b", - "title": "Yoinked!", - "body": "horsefacts captured the flag from you." - } -} -``` - -#### LauncherLocationContext - - - -Indicates the Mini App was launched directly by the client app outside of a context. - - - -#### ChannelLocationContext - - - -Indicates the Mini App was launched from within a specific Farcaster channel. - - - -Channel details. - - - -Channel key identifier. - - - -Channel name. - - - -Channel profile image URL. - - - - -#### OpenMiniAppLocationContext - - - -Indicates the Mini App was launched from another Mini App. - - - -The domain of the Mini App that opened the current app. - - - -### Client Object - -Contains details about the Farcaster client running your Mini App. This data should be considered untrusted. - - -#### ClientContext - - - -Platform where the app is running. - - - -Self-reported FID of the client (e.g., 9152 for Farcaster). - - - -Whether the user has added your Mini App to their client. - - - -Screen insets to avoid navigation elements that obscure the view. - - -Top safe area inset in pixels. - - -Bottom safe area inset in pixels. - - -Left safe area inset in pixels. - - -Right safe area inset in pixels. - - - - - -Notification configuration if enabled. - - -Endpoint for sending notifications. - - -Authentication token for notifications. - - - - - -```json client.json -{ - "platformType": "mobile", - "clientFid": 9152, - "added": true, - "safeAreaInsets": { - "top": 0, - "bottom": 20, - "left": 0, - "right": 0 - }, - "notificationDetails": { - "url": "https://api.farcaster.xyz/v1/frame-notifications", - "token": "a05059ef2415c67b08ecceb539201cbc6" - } -} -``` - - -### Features Object - -Indicates which platform features are available and their current state in the client. - - - -Whether haptic feedback is supported on the current platform. - - - -Whether camera and microphone permissions have been granted and stored for this mini app. - - - -```json features.json -{ - "haptics": true, - "cameraAndMicrophoneAccess": true -} -``` - -For more detailed capability detection, use the `sdk.getCapabilities()` method which returns specific SDK methods supported by the host. diff --git a/docs/apps/core-concepts/embeds-and-previews.mdx b/docs/apps/core-concepts/embeds-and-previews.mdx deleted file mode 100644 index 2f7e82482..000000000 --- a/docs/apps/core-concepts/embeds-and-previews.mdx +++ /dev/null @@ -1,146 +0,0 @@ ---- -hidden: true -title: Embeds & Previews -description: Mini apps use metadata to create embeds when users share links. The embed shows a preview image and launch button. ---- - - - - Mini app feed - - -## Implementation -Add this meta tag to the `` section of any page you want to make shareable: - - - ```html html metadata - - - - My Mini App - - - - - - - ``` - - ```jsx next.js metadata - // app/layout.tsx or app/page.tsx (Next.js App Router) - import type { Metadata } from "next"; - -export async function generateMetadata(): Promise { - return { - title: miniapp.name, - description: miniapp.description, - other: { - "fc:miniapp": JSON.stringify({ - version: miniapp.version, - imageUrl: miniapp.heroImageUrl, - button: { - title: `Join the ${miniapp.name}`, - action: { - name: `Launch ${miniapp.name}`, - url: `${miniapp.homeUrl}` - }, - }, - }), - }, - }; -} - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - {children} - - ); - } - ``` - -The `homeUrl` used in the `manifest` *must* have embed metadata defined, in order for the mini app to render correctly in the Base app. - - - -## Schema - - - -Version of the embed. Use `"next"` — this is the current recommended version for Mini Apps. (`"1"` is a legacy value and should not be used.) - - - -Image URL for the embed. Must be 3:2 aspect ratio, maximum 10MB, maximum 1024 characters. - - - -Button configuration object. - - - -### Button Configuration - -Defines the launch button that appears on the embed. - - - -Button text. Maximum 32 characters. - - - -Action configuration object. Maximum 1024 characters. - - - -### Action Configuration - -Specifies what happens when the embed button is clicked. - - - -Action type. Must be `"launch_miniapp"`. - - - -App URL to open. Defaults to the full URL of the page including query parameters. Maximum 1024 characters. - - - -Application name. Maximum 32 characters. Defaults to manifest name. - - - -Splash screen image URL. Must be 3:2 aspect ratio, between 600x400px and 3000x2000px, less than 10MB, maximum 1024 characters. Defaults to manifest splash image. - - - -Splash screen background color. Must be hex color code. Defaults to manifest splash background color. - - - - -## Related Concepts - - - - Learn how your manifest powers search indexing and category placement in the Base app discovery features. - - - - Learn how to maximize sharing, social engagement, and viral growth for your Mini App using Base's social graph features. - - diff --git a/docs/apps/core-concepts/manifest.mdx b/docs/apps/core-concepts/manifest.mdx deleted file mode 100644 index 227824633..000000000 --- a/docs/apps/core-concepts/manifest.mdx +++ /dev/null @@ -1,214 +0,0 @@ ---- -hidden: true -title: "Manifest" -description: "Define how your mini app appears and behaves within the Base app, enabling search, discovery, and rich embed features in the Base app." ---- - - - -```json farcaster.json -{ - "accountAssociation": { - "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0", - "payload": "eyJkb21haW4iOiJhcHAuZXhhbXBsZS5jb20ifQ", - "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj" - }, - "miniapp": { - "version": "1", - "name": "Crypto Portfolio Tracker", - "homeUrl": "https://ex.co", - "iconUrl": "https://ex.co/i.png", - "splashImageUrl": "https://ex.co/l.png", - "splashBackgroundColor": "#000000", - "subtitle": "Easy to manage", - "description": "Track and manage your cryptocurrency portfolio.", - "screenshotUrls": [ - "https://ex.co/s1.png", - "https://ex.co/s2.png", - "https://ex.co/s3.png" - ], - "primaryCategory": "finance", - "tags": ["finance"], - "heroImageUrl": "https://ex.co/og.png", - "tagline": "Save instantly", - "ogTitle": "Example Mini App", - "ogDescription": "Easy to manage portfolio.", - "ogImageUrl": "https://ex.co/og.png", - "noindex": true - } -} -``` - - - -Set `"noindex": true` for development or staging environments to prevent search indexing. - - - -## Implementation - -1. Create the manifest file in your project at `/public/.well-known/farcaster.json`. It needs to be accessible at `https://your-domain.com/.well-known/farcaster.json` -2. Update the [required](#accountassociation) and [optional](#display-information) fields in the `miniapp` object -3. Ensure all changes are live so that the Manifest file is available at your app's url -4. Navigate to the Base Build [Account association tool](https://www.base.dev/preview?tab=account) -5. Paste your domain in the App URL field (ex: sample-url.vercel.app) and click "Submit" -6. Click on the "Verify" button that appears and sign the manifest with your wallet to generate the `accountAssociation` fields -7. Copy the generated `accountAssociation` fields (header, payload, and signature) and paste them into your manifest file, replacing the empty values in the `accountAssociation` object - - -Changes to the manifest take effect when you redeploy your Mini App and repost it. The platform re-indexes the updated configuration and applies changes to search, discovery, and embed rendering. - - - -Use the [Mini App Assets Generator](https://www.miniappassets.com/) to generate properly formatted icons, splash screens, and images that meet the requirements for both Base App and Farcaster mini apps. - - - - - -## Schema - -### accountAssociation - -Proves domain ownership for your Mini App. - - -Encoded header for the association payload. - - - -Encoded payload containing your domain. - - - -Signature over the payload. - - - - -#### Identity & Launch - -Defines your Mini App's core identity and the URL users land on when they open it. - - - -Manifest version. Must be `"1"`. - - - -Mini App name. Max 32 chars. - - - -Default launch URL. HTTPS URL, max 1024 chars. - - - -Icon image URL. HTTPS URL, PNG 1024×1024; transparent background discouraged. - - - -#### Loading Experience - -Controls the splash screen visuals and colors shown while your Mini App loads. - - - -Loading image. HTTPS URL, recommended 200×200px. - - - -Loading background color. Hex code (e.g., `#000000`). - - - -#### Discovery & Search - -Determines how your Mini App is indexed, categorized, and surfaced across Base App discovery features. - - - -Controls where your app appears in category browsing. One of: `games`, `social`, `finance`, `utility`, `productivity`, `health-fitness`, `news-media`, `music`, `shopping`, `education`, `developer-tools`, `entertainment`, `art-creativity`. - - - -Search/filter tags. Up to 5; ≤ 20 chars each; lowercase; no spaces/emojis/special chars. - - - -Exclude from search results. `true` = exclude, default = include. - - - -#### Display Information - -Provides the descriptive text, screenshots, and promotional images shown on your Mini App's profile. - - - -Short description under name. Max 30 chars; avoid emojis/special chars. - - - -Promo text for app page. Max 170 chars; avoid emojis/special chars. - - - -Marketing tagline. Max 30 chars. - - - -Large promo image. 1200×630px (1.91:1), PNG/JPG. - - - -Visual previews. Max 3; portrait 1284×2778px recommended. - - - -#### Notifications - -Notification endpoint. - - -POST events endpoint. HTTPS URL, max 1024 chars. Required if using notifications. - - - -Only add webhookUrl if you are using notifications or save functionality. This must be a valid URL. - - -#### Embeds & Social Sharing - -Configures how your Mini App appears when shared in feeds or on social platforms. - - - -Open Graph title. Max 30 chars. - - - -Open Graph description. Max 100 chars. - - - -Open Graph image. 1200×630px (1.91:1), PNG/JPG. - - - - - -## Related Concepts - - - - Understand how your manifest creates rich embeds when your Mini App is shared in feeds and social platforms. - - - See how your mini app is displayed in the Base app in our Figma file. - - diff --git a/docs/apps/core-concepts/navigation.mdx b/docs/apps/core-concepts/navigation.mdx deleted file mode 100644 index 3cb98d1bc..000000000 --- a/docs/apps/core-concepts/navigation.mdx +++ /dev/null @@ -1,216 +0,0 @@ ---- -hidden: true -title: Navigation -description: Gracefully navigate users from your mini app through the Base app and to external links. ---- - -## Overview - -Use the functions provided by the `@farcaster/miniapp-sdk` to navigate users from your mini app throughout the Base app and to external links with a native user experience. - - - - -```md -# Mini App Navigation Pattern Migration - -## Context -I'm building a Farcaster Mini App on Base. Mini Apps must use official SDK functions for all navigation and external interactions to ensure cross-client compatibility. - -## Your Task -Review this file and refactor any incorrect navigation patterns to use the correct SDK actions. - -## Incorrect Patterns to Fix - -### Don't Use: -- Direct HTML links: ``, `` -- Window navigation: `window.open()` -- Static URLs or deeplinks to Farcaster -- Client-specific URLs (like Warpcast URLs) -- Composer intent URLs: `https://farcaster.com/~/compose?text=...` -- Direct cast URLs for viewing - -## Correct SDK Actions - -### For Farcaster SDK (`@farcaster/miniapp-sdk`) -1. **External Links:** Use `sdk.actions.openUrl(url)` -2. **Create Posts:** Use `sdk.actions.composeCast({ text, embeds })` -3. **View Casts:** Use `sdk.actions.viewCast(castUrl)` - -## Migration Examples - -// BEFORE (Incorrect) -Visit Site - - -// AFTER (Correct) -import { sdk } from '@farcaster/miniapp-sdk'; - - -// BEFORE (Incorrect) -window.open('https://farcaster.com/~/compose?text=Check this out!') - -// AFTER (Correct) -sdk.actions.composeCast({ - text: 'Check this out!', - embeds: [window.location.href] -}) - -``` - - - - - - -## External Navigation - -### Opening External URLs - -Use `sdk.actions.openUrl()` to safely open external websites in the client's in-app browser: - -```typescript App.tsx highlight={5} -import { sdk } from '@farcaster/miniapp-sdk'; - -// Correct: Use SDK action -const openExternalSite = () => { - sdk.actions.openUrl('https://example.com'); -}; - -// Incorrect: Direct HTML link -// Visit Site -``` - -### Composing Casts - -Use `sdk.actions.composeCast()` instead of composer intent URLs: - -```typescript App.tsx highlight={5-8} -import { sdk } from '@farcaster/miniapp-sdk'; - -// Correct: Use SDK action -const shareContent = () => { - sdk.actions.composeCast({ - text: 'Check out this Mini App!', - embeds: ['https://yourminiapp.com'] - }); -}; - -// Incorrect: Composer intent URLs -// window.open('https://farcaster.com/~/compose?text=...') -``` - -### Viewing Casts - -Use `sdk.actions.viewCast()` instead of cast intent URLs: - -```typescript App.tsx -import { sdk } from '@farcaster/miniapp-sdk'; - -// Correct: Use SDK action -const viewCast = () => { - sdk.actions.viewCast('https://base.app/post/0xffdec7c879aad726b5400d22ec8a89aaff6e0737'); -}; -``` - -### Conditional Navigation - -If your mini app can be opened in the browser, implement conditional navigation to handle cases where mini app-specific functions (e.g., Compose Cast) are unavailable. - -```javascript ConditionalNavigation.tsx highlight={4, 8-13} -import { sdk } from 'farcaster/miniapp-sdk'; - -const ConditionalNavigation = () => { - const context = sdk.context; - - const handleNavigation = () => { - // Adapt behavior based on client capabilities - if (context.client.clientFid) { - sdk.actions.openUrl('https://app-specific-url.com'); - } else { - // Fallback for other clients - window.open('https://fallback-url.com', '_blank'); - } - }; - - return ( - - ); -}; -``` - -## Deeplinks - -Provide your users with direct access to Mini Apps, group messages, and DMs using our deeplinking schema. - -### Mini Apps - -Launch your mini app directly from external sources like websites, QR codes, or other applications. - -```HTML index.html - - Launch Mini App - -``` - -### Group Messages - -Navigate users directly to a specific group chat conversation. - - - Users can only access group conversations they have been added to as members. - - -Getting the `conversationID`: - -```typescript agent.ts highlight={3,6,9} -agent.on('text', async (ctx) => { - // Get conversation ID - const conversationId = ctx.conversation.id; - - // Create deeplink to THIS conversation (not just the agent) - const groupDeeplink = `cbwallet://messaging/${conversationId}`; - - if (ctx.isGroup()) { - await ctx.sendText(`Share this group: ${groupDeeplink}`); - } -}); -``` - -Use the `conversationID` as a button: - -```typescript DeeplinkButton.tsx - -``` - -### Direct Messages (Users or Agents) - -Start a private conversation with a specific user or agent. - -```typescript DeeplinkDM.tsx - -``` - -## Schema - -### Group Message Parameters - - - The unique identifier for an XMTP group conversation. - - -### Direct Message Parameters - - - The 0x address of the user or agent you want to chat with (in hex format, e.g., `0xabc...1234`). - diff --git a/docs/apps/core-concepts/notifications.mdx b/docs/apps/core-concepts/notifications.mdx deleted file mode 100644 index 3eab314bc..000000000 --- a/docs/apps/core-concepts/notifications.mdx +++ /dev/null @@ -1,387 +0,0 @@ ---- -hidden: true -title: Notifications -description: Regularly re-engage users by sending in-app notifications through the Base app ---- - - -If you are looking for a no code solution for notification we recommend using neynars notification service. See the [Neynar Notifications Guide](/mini-apps/technical-guides/neynar-notifications) for implementation details. - - - -## Overview - -When a user enables notifications for your Mini App, the Base app generates a unique notification `token` and `url` which is sent to your server via webhook. - -This `token` grants your app permission to send in-app notifications to that specific user. - -To send a notification, make a `POST` request to the `url` with the user's notification `token` and your content. - -You will receive webhook events when users enable or disable notifications for your app. When disabled, the notification token becomes invalid and should no longer be used. - -## Client App Behavior - -Different client apps handle webhook responses differently: - -**Farcaster app**: Activates notification tokens immediately without waiting for a webhook success response. - -**Base app**: Waits for a successful webhook response before activating tokens. - - -If your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app. - - - - -![notification-image-iphone](/images/minikit/notifications-sample.png) - -Notification tokens are unique to each client app. This means a user can have separate notification preferences for your Mini App across different clients (e.g., Farcaster, the Base app). Removing your Mini App in one client does not affect its status in other clients. - - - -## Implementation - - - Install the `@farcaster/miniapp-node` package in your project: - ```bash - npm install @farcaster/miniapp-node - ``` - Get a free API key from [neynar](https://dev.neynar.com/) and set `NEYNAR_API_KEY` in your environment variables. - - - - Create a webhook server to handle webhook events. - - - Use `parseWebhookEvent` with `verifyAppKeyWithNeynar` to verify the client signature and authenticate events signed by the app key. - - - The `data` object returned by `parseWebhookEvent` contains three key fields: - - **`fid`**: The user's FID - - **`appFid`**: The client's FID (the Base app is 309857) - - **`event`**: The event payload with type and notification details - - Always use both `fid` and `appFid` together to identify a unique user-client combination. - - - - ```ts app/api/webhook/route.ts expandable highlight={20-50} - - import { - parseWebhookEvent, - verifyAppKeyWithNeynar, - } from "@farcaster/miniapp-node"; - - export async function POST(request: NextRequest) { - const requestJson = await request.json(); - - // Parse and verify the webhook event - let data; - try { - data = await parseWebhookEvent(requestJson, verifyAppKeyWithNeynar); - // Events are signed by the app key of a user with a JSON Farcaster Signature. - } catch (e: unknown) { - // Handle verification errors (invalid data, invalid app key, etc.) - // Return appropriate error responses with status codes 400, 401, or 500 - } - - - // Extract webhook data - - const fid = data.fid; - const appFid = data.appFid; // The FID of the client app that the user added the Mini App to - const event = data.event; - - // Handle different event types - - try { - switch (event.event) { - case "miniapp_added": - if (event.notificationDetails) { - setUserNotificationDetails(fid, appFid, event.notificationDetails); - sendMiniAppNotification(fid, appFid, "Welcome to Base Mini Apps", "Mini app is now added to your client"); - fid, - appFid, - title: "Welcome to Base Mini Apps", - body: "Mini app is now added to your client", - }); - } - break; - - case "miniapp_removed": - // Delete notification details - await deleteUserNotificationDetails(fid, appFid); - break; - - case "notifications_enabled": - // Save new notification details and send confirmation - setUserNotificationDetails(fid, appFid, event.notificationDetails); - sendMiniAppNotification({ - fid, - appFid, - title: "Ding ding ding", - body: "Notifications are now enabled", - }); - break; - - case "notifications_disabled": - // Delete notification details - await deleteUserNotificationDetails(fid, appFid); - break; - } - } catch (error) { - console.error("Error processing webhook:", error); - } - - return response; - - ``` - - - Add the Webhook URL to your manifest file - - ```json app/.well-known/farcaster.json highlight={16} - { - "accountAssociation": { - "header": "eyJmaWQiOjU0NDgsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHg2MWQwMEFENzYwNjhGOEQ0NzQwYzM1OEM4QzAzYUFFYjUxMGI1OTBEIn0", - "payload": "eyJkb21haW4iOiJleGFtcGxlLmNvbSJ9", - "signature": "MHg3NmRkOWVlMjE4OGEyMjliNzExZjUzOTkxYTc1NmEzMGZjNTA3NmE5OTU5OWJmOWFmYjYyMzAyZWQxMWQ2MWFmNTExYzlhYWVjNjQ3OWMzODcyMTI5MzA2YmJhYjdhMTE0MmRhMjA4MmNjNTM5MTJiY2MyMDRhMWFjZTY2NjE5OTFj" - }, - "miniapp": { - "version": "1", - "name": "Example App", - "iconUrl": "https://example.com/icon.png", - "homeUrl": "https://example.com", - "imageUrl": "https://example.com/image.png", - "buttonTitle": "Check this out", - "splashImageUrl": "https://example.com/splash.png", - "splashBackgroundColor": "#eeccff", - "webhookUrl": "https://example.com/api/webhook" - } - } - - ``` - - - Use the `addMiniApp()` hook to prompt users to add your Mini App - - - **Important: Webhook Response Timing** - Webhooks must respond within 10 seconds to avoid timeouts from the Base app. If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. - - - ```tsx page.tsx highlight={11, 25-27} - "use client"; - - import { sdk } from "@farcaster/miniapp-sdk"; - import { useCallback, useState } from "react"; - - export default function AddMiniApp() { - const [result, setResult] = useState(""); - - const handleAddMiniApp = useCallback(async () => { - try { - const response = await sdk.actions.addMiniApp(); - - if (response.notificationDetails) { - setResult("Mini App added with notifications enabled!"); - } else { - setResult("Mini App added without notifications"); - } - } catch (error) { - setResult(`Error: ${error}`); - } - }, []); - - return ( -
- - {result &&

{result}

} -
- ); - } - ``` - - - - The `token` and `url` need to be securely saved to a database so they can be looked up when you want to send a notification to a particular user. - - ```json miniapp_added_payload.json highlight={4-5} - { - "event": "notifications_enabled", - "notificationDetails": { - "url": "https://api.farcaster.xyz/v1/frame-notifications", - "token": "a05059ef2415c67b08ecceb539201cbc6" - } - } - ``` - - - - - Send notifications by sending a `POST` request to the `url` associated with the user's `token` - - ```ts sendNotification.ts highlight={15-28} - export async function sendMiniAppNotification({ - fid, - appFid, - title, - body, - }: { - fid: number; - appFid: number; - title: string; - body: string; - }): Promise { - const notificationDetails = await getUserNotificationDetails(fid, appFid); - if (!notificationDetails) { - return { state: "no_token" }; - } - - const response = await fetch(notificationDetails.url, { - method: "POST", - headers: { - "Content-Type": "application/json", - }, - body: JSON.stringify({ - notificationId: crypto.randomUUID(), - title, - body, - targetUrl: appUrl, - tokens: [notificationDetails.token], - } satisfies SendNotificationRequest), - }); - - const responseJson = await response.json(); - - if (response.status === 200) { - const responseBody = sendNotificationResponseSchema.safeParse(responseJson); - if (responseBody.success === false) { - // Malformed response - return { state: "error", error: responseBody.error.errors }; - } - - if (responseBody.data.result.rateLimitedTokens.length) { - // Rate limited - return { state: "rate_limit" }; - } - - return { state: "success" }; - } else { - // Error response - return { state: "error", error: responseJson }; - } - } - ``` - - - -## Schema - -### Send Notification Request Schema - - - -Identifier that is combined with the FID to form an idempotency key. When the user opens the Mini App from the notification this ID will be included in the context object. **Maximum length of 128 characters.** - - - -Title of the notification. **Max length 32 characters.** - - - -Body of the notification. **Max length 128 characters.** - - - -URL to open when the user clicks the notification. **Max length 1024 characters.** -Must be on the same domain as the Mini App. - - - - -Array of notification tokens to send to. **Max 100 tokens.** - - - -### Send Notification Response Schema - - - -Tokens for which the notification succeeded. - - - -Tokens which are no longer valid and should never be used again. This could happen if the user disabled notifications but for some reason the Mini App server has no record of it. - - - -Tokens for which the rate limit was exceeded. The Mini App server can try later. - - - - - -## Events - -Mini App events use the following object structure: - -* **`type`**: notification event type -* **`notificationDetails.url`**: URL that the app should call to send a notification. -* **`notificationDetails.token`**: A secret token generated by the Base app and shared with the Notification Server. A token is unique for each (Farcaster Client, Mini App, user Fid) tuple. - -If users are not seeing the option to enable notifications when they call `addMiniApp()`, verify that your manifest file contains a valid `webhookUrl`. - -### `miniapp_added` - -Sent when the user adds the Mini App to their Farcaster client (whether or not it was triggered by an `addMiniApp()` prompt). - - - -```json miniapp_added_payload.json -{ - "event": "miniapp_added", - "notificationDetails": { - "url": "https://api.farcaster.xyz/v1/frame-notifications", - "token": "a05059ef2415c67b08ecceb539201cbc6" - } -} -``` - -### `miniapp_removed` - -Sent when a user removes the Mini App, which means that any notification tokens for that FID and client app (based on signer requester) should be considered invalid: - - -```json miniapp_removed_payload -{ - "event": "miniapp_removed" -} -``` - -### `notifications_enabled` - -Sent when a user enables notifications (e.g. after disabling them). The payload includes a new `token` and `url`: - -```json notifications_enabled_payload -{ - "event": "notifications_enabled", - "notificationDetails": { - "url": "https://api.farcaster.xyz/v1/frame-notifications", - "token": "a05059ef2415c67b08ecceb539201cbc6" - } -} -``` - -### `notifications_disabled` - -Sent when a user disables notifications from, e.g., a settings panel in the client app. Any notification tokens for that FID and client app (based on signer requester) should be considered invalid: - -```json notifications_disabled_json -{ - "event": "notifications_disabled" -} -``` - diff --git a/docs/apps/featured-guidelines/design-guidelines.mdx b/docs/apps/featured-guidelines/design-guidelines.mdx deleted file mode 100644 index 0ef900446..000000000 --- a/docs/apps/featured-guidelines/design-guidelines.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -hidden: true -title: "Design Guidelines" -description: "Build a mini app that is intuitive and delightful to use." ---- - -### Display - - - -Your [manifest configuration](/mini-apps/core-concepts/manifest) controls how your app appears across these surfaces. [See full specification](/images/miniapps/miniapp-design-spec.png). - - -### Layout - -* Keep core actions visible near the top or middle of the screen — not hidden behind scrolls. -* Limit the number of buttons. Make it obvious what users should do first. -* Use clear primary calls to action (e.g., “Create”, “Start Game”, “Deposit”). -* Design for **small viewports** and **portrait orientation.** -* **Optimize for thumb reach and one-handed use.** - -### Navigation - -* Most mini apps should include a **bottom navigation bar**. - -Bottom navigation bar example - -* A side menu can also be an intuitive place to put settings and user profile information. - Side navigation menu example - -* Always include **labels under icons** so users understand each tab. -* Test on multiple device sizes to ensure buttons are not cut off. - - -### Colors - -Use color to communicate clearly, express your brand, and create cohesive mini app experiences. - -### **Color Palette** - -* **Primary:** Brand color for CTAs and key interactions. -* **Secondary:** Complements primary; use for accents or secondary actions. -* **Neutral:** For text, backgrounds, and structure with strong contrast. - -### **Themes** - -* Support **light and dark modes**: -* Maintain contrast and brand consistency. -* Respect system preference but allow manual toggle. -* Use smooth transitions between themes. -* **💡Tip:** Use **semantic color tokens** (e.g., `--color-primary`, `--color-background`) with **light/dark theme overrides** for maintainability and flexibility. - - -### Typography - -* Ensure the fonts you use are easy to read. Our team recommends **Inter.** -* **Ensure sufficient contrast between text and background colors** to make reading easy under various lighting conditions. -* **Stick to regular, bold, and italic as needed.** Decorative or script fonts should be reserved for accents, not body text. - -### Spacing - -* Groups related elements together. -* Consistent spacing: Creates visual rhythm and predictability with consistent spacing. -* Give content room to breathe with white space. -* Avoid cramped layouts. -* Base Unit: Start with a base spacing unit (typically **4px** or **8px**) and maintain consistency throughout: - * 4px base: More granular control, better for mobile. - * 8px base: Easier mental math, good for desktop. - - -### Touch Interactions - -* Ensure all touch targets are at least **44px**. -* Support common gestures (tap, swipe, pinch) where appropriate. -* Don’t rely on **hover states** — they don’t exist on touch screens. - diff --git a/docs/apps/featured-guidelines/notification-guidelines.mdx b/docs/apps/featured-guidelines/notification-guidelines.mdx deleted file mode 100644 index ea7f9a57b..000000000 --- a/docs/apps/featured-guidelines/notification-guidelines.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -hidden: true -title: "Notification Guidelines" -description: "Well designed notifications re-engage users, driving retention, and highlight key moments" ---- - -Notifications will allow you to re-engage users who have saved your Mini App, driving retention and bringing users back at key moments like new content releases, achievements, or time-sensitive events. - -Focus on sending updates that are relevant, well-timed, and valuable. It’s important to balance how many notifications you send — too many can cause users to turn them off entirely. - -# Anatomy - -* Title - * Short, clear statement of feature or what’s happening - * Max length 32 characters -* Body - * Supporting detail or call-to-action - * Max length 128 characters -* targetURL - * URL to open when the user clicks the notification - * Max length 1024 characters.Must be on the same domain as the Mini App. - - -# Best practices - -1. **Keep notifications short and clear** - Each notification should be easy to scan. Use the title to state the key details, and keep the body text brief and focused on value. Users should know at a glance what is happening and why it matters. - -2. **Control frequency** - Send notifications sparingly. Stay well below the enforced limit (1 every 30 seconds, maximum 100 per day) to avoid users from turning off notifications from your mini app. Focus on moments that truly benefit the user, and avoid sending multiple alerts close together. - -3. **Deliver at the right time** - Timing shapes how notifications feel. Send them when they’re most relevant, such as after an event or during active hours. Avoid off-hours or interrupting while users are already in your mini app. Well-timed notifications feel helpful, not disruptive. - -4. **Measure and refine** - Analytics reveal whether your notifications are working. High click-through rates show value, rising disabled rates mean you’re overwhelming users. Use these signals to adjust content, timing, or cadence so notifications remain useful. - -# Types of notifications - -Different mini apps use notifications in different ways. Choose the type that best fits your app’s purpose, and always keep the message relevant. - -* **Reminders** encourage users to return regularly - * “Your crops are ready to harvest\! -* **Events driven updates** highlight something new or time sensitive. - * “BTC is up 5% today\! Check your portfolio” -* **Feature announcements** showcase new functionality or opportunities - * Example: “New quest unlocked\! More Coins are waiting for you\!” -* **Alerts/warnings** share urgent or critical information - * Example: “Your balance is low. Top up to keep trading” - - -Not every message deserves to be a notification, here are some to avoid: - -* **Avoid overly generic nudges**. Messages with no clear value feel spammy, always explain why it matter to the user - * Example: “Open the app today\!” -* **Avoid unnecessary confirmations**. Notifications should only confirm meaningful or irreversible events like payments or shipments - * Example: “You liked a post” \ No newline at end of file diff --git a/docs/apps/featured-guidelines/overview.mdx b/docs/apps/featured-guidelines/overview.mdx deleted file mode 100644 index d80bc7610..000000000 --- a/docs/apps/featured-guidelines/overview.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -hidden: true -title: "Featured Checklist" -description: "Build high quality mini apps to get more distribution." ---- - -Your app must meet all product, design, and technical guidelines outlined below. Meeting these guidelines is a prerequisite for featured placement, but __does not guarantee placement__. Base holds a very high bar for featured placement. - - - - To submit your app for featured placement, first verify your mini app in the [Base Build dashboard](https://base.dev/), then fill out the [submission form](https://docs.google.com/forms/d/e/1FAIpQLSeZiB3fmMS7oxBKrWsoaew2LFxGpktnAtPAmJaNZv5TOCXIZg/viewform). - - - - - - * In-app authentication stays within the Base app with no external redirects - * Wallet connection happens automatically - * No email or phone verification inside the app - - - - * Explain the purpose of the app and how to get started, with clear onboarding instructions either on the home page or as a a pop-up window. - * App only requests essential personal information, with clear context - * Display user's avatar and username **(no 0x addresses)** - - - - * App is client-agnostic, with no hard-coded Farcaster text or links, or other client-specific behavior - * Transactions are sponsored - - - - * Call to actions are visible and centered on page - * App has a bottom navigation bar or side menu to easily access core flow - * All buttons are accessible and not cut off - * Navigation bar items have clear, understandable labels - - - - * App loads within **3 seconds** - - * In-app actions complete within **1 second** - - * Loading indicators are shown during actions - - - - * App supports **light and dark modes** consistently - * App has minimum **44px touch targets** - - - - * App description is clear, concise, and user-focused - * App icon is **1024×1024 px**, PNG, **no transparency**, readable at small sizes - * App cover photo is **high quality**, does not contain Base logo or team photos, and is 1200×630px (1.91:1) dimensions, PNG/JPG. - * Include 3 screenshots that highlight key app functionality. Use portrait orientation with 1284x2778 dimensions. - * Subtitle should be descriptive and specific, and use sentence case capitalization with no punctuation at the end. - - - -## Next Steps - - - - - - - diff --git a/docs/apps/featured-guidelines/product-guidelines.mdx b/docs/apps/featured-guidelines/product-guidelines.mdx deleted file mode 100644 index 3c2350edd..000000000 --- a/docs/apps/featured-guidelines/product-guidelines.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -hidden: true -title: "Product Guidelines" ---- - -## Load Time - -* Apps should load within **3 seconds**, and in-app actions should complete within **1 second**. -* Always show a **loading indicator** when an action is in progress. - -## Onboarding Flow - -* When a user opens your mini app for the first time, they should see a brief, informative screen explaining what the mini app does and how to get started. Keep this limited to 3 screens, and use succinct language and images. - -
- Bolero onboarding flow -
Example onboarding flow
-
- -## User Information & Privacy - -* Only ask for personal information when absolutely necessary. Give users context and explain the value of using the app **before** asking for private information. -* Always explain why the information is needed. Respect user privacy and data minimization principles. - -## User Profile - -* Show the user’s profile somewhere on the screen, and include their avatar and username used on the Base app -* **Avoid showing 0x addresses in your mini app.** - -## App Description - -* Your mini app should have a clear, simple value proposition that makes sense to anyone. -* Describe what your app does and why it matters in one sentence. -* **Keep your messaging human, concise, and benefit-focused.** - -***Examples**:* “Earn and borrow on your terms”, “Create and share art that lives onchain” - -## App Cover Photo - -**Do’s ✅** - -* Your app’s visuals should make users want to click in and explore. -* Include a high-quality cover image that feels trustworthy and engaging. -* Ensure no typos or visual clutter in the image. - -**Don’ts ❌** - -* Include the Base logo in your cover photo. -* Include photos of your team - -
- Bolero onboarding flow -
Example cover photo
-
- -## App Icon - -* **Design clear, recognizable icons:** Use bold, simple shapes and high contrast; avoid fine details so icons remain clear at **16×16px**. -* **Follow icon specs** - * Size: **1024×1024px** - * Format: **PNG (no alpha transparency)** - * Defined via `iconUrl` in `farcaster.json` - diff --git a/docs/apps/featured-guidelines/technical-guidelines.mdx b/docs/apps/featured-guidelines/technical-guidelines.mdx deleted file mode 100644 index 80cbf94ef..000000000 --- a/docs/apps/featured-guidelines/technical-guidelines.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -hidden: true -title: "Technical Guidelines" -description: "Ensure your mini app is built for the Base app" ---- - -## Complete Metadata - -Metadata includes your manifest and embed metadata. Complete, valid metadata is required for indexing, category placement, and high‑quality embeds. - -**Acceptance Criteria** -- Manifest is publicly accessible at `/.well-known/farcaster.json` -- Required fields are present and valid (`accountAssociation`, `frame`, `primaryCategory`, `tags`) -- Images meet size/format constraints; text fields respect length limits - -**How to Implement** -- Follow the [Manifest guide](/mini-apps/core-concepts/manifest) -- Implement [embed metadata](/mini-apps/core-concepts/embeds-and-previews#implementation) - - - Validate your manifest using our preview tools at base.dev/preview. - - -## In-app Authentication - -Users must remain in the Base app throughout the authentication flow. Eliminate flows that bounce users out of the Base app. - -**Acceptance Criteria** -- No external redirects -- No email / phone verification -- Users can explore before sign‑in when possible - -**How to Implement** -- Follow the [Authentication guide](/mini-apps/core-concepts/authentication) -- Prefer in‑app SIWF/Quick Auth or wallet auth; - -## Client-Agnostic - -There must be no client‑specific behaviors or wording that degrade the experience in the Base app. You must also ensure that you don't redirect the user to another client for functionality supported in the Base app. - -**Acceptance criteria** -- Do not hardcode client‑specific URLs (e.g., Farcaster‑only links) -- Use neutral language in UI (e.g. use "Share to Feed" instead of "Share to Farcaster") -- Eliminate buttons that deeplink to other clients for features supported in the Base app - -**How to Implement** -- Update all links according to the [Links](/mini-apps/technical-guides/links) guide -- Review the [Base App Compatability](/mini-apps/troubleshooting/base-app-compatibility) guide for functionality not supported in the Base app. All other functionality must keep users in the Base app. - -## Sponsor Transactions - -Sponsor transaction fees to remove friction and reduce drop‑off for new users. For mini apps on Base, we recommend using the [Base Paymaster](/base-account/improve-ux/sponsor-gas/paymasters). - -**Acceptance criteria** -- Transactions are sponsored via a paymaster - -**How to Implement** -- Recommended: [Base Paymaster](/base-account/improve-ux/sponsor-gas/paymasters) - - - Claim free gas credits on base.dev. - - - -## Batch Transactions (EIP-5792) - -Batch sequential actions where applicable to minimize signatures and reduce friction. Use EIP‑5792 capabilities to send multiple calls in one request. - -**Acceptance criteria** -- Where applicable, combine sequential actions into a single batch (e.g. approve + swap) - -**How to Implement** -- See [Batch Transactions](/base-account/improve-ux/batch-transactions) -- Provider APIs: [`wallet_sendCalls`](/base-account/reference/core/provider-rpc-methods/wallet_sendCalls), [`wallet_getCapabilities`](/base-account/reference/core/provider-rpc-methods/wallet_getCapabilities) - - - - - diff --git a/docs/apps/growth/build-viral-apps.mdx b/docs/apps/growth/build-viral-apps.mdx deleted file mode 100644 index ada2b4b3f..000000000 --- a/docs/apps/growth/build-viral-apps.mdx +++ /dev/null @@ -1,297 +0,0 @@ ---- -hidden: true -title: Ideating Viral Apps -description: Designing mini apps that people actually come back to ---- - -**Designing mini apps that people actually come back to.** - -Most apps can launch. But few become part of someone's daily rhythm. -That's usually not a product problem. It's a people problem. - -Social mini apps live or die based on how they make people feel: seen, connected, curious or like they belong. That's not something you tack on — it's something you build in from the start. - -If you're designing for feed-based platforms (like Farcaster, Threads, or anything with posts, reactions, and reply chains), this guide will help you: - - - - - - - -## How to Use This Guide - -Welcome to your blueprint for designing social mini‑apps that people love to revisit. This guide is organized into distinct, actionable sections—each building on the last—to help you move from idea validation to deploying social features with purpose. - - - -Before writing a single line of code or sketching UI, use our four diagnostic questions to see if your concept naturally supports social behavior. Drop your one‑line idea into the supplied prompt to get clear insights on post frequency, social lift, content momentum, and emotional payoff. - - - - Analyze the responses. Identify which one or two social dimensions resonate - most with your concept—whether it's habit formation, community spark, content - growth, or emotional reward. The guide shows you how to validate and - prioritize those dimensions before moving forward. - - - - See a worked example that demonstrates how to translate test results into a - prototype feature. This mini case study will illustrate rapid iteration, - metric considerations, and how to decide when you're ready to scale social - elements. - - - -Dive into the heart of the guide—three social patterns designed to deepen engagement: - -- **Identity Playgrounds:** Customization and self‑expression -- **Co‑Creation Loops:** Collaboration and building on each other's posts -- **Long‑Term Rituals:** Scheduled, shared activities that foster habit and community - -Each pattern includes explanations, real‑world examples, and copy‑and‑paste prompts to spark your own brainstorming. - - - - -Finish with a set of reflective questions and practical advice on measuring success. Use the closing prompts to refine your roadmap, plan experiments, and define key metrics for daily, weekly, and monthly engagement. - - - - -**Tips for Getting the Most Out of This Guide:** - -- **Iterate Quickly:** Treat prompts and patterns as hypotheses. Prototype fast, gather data, and refine. -- **Stay Human‑Centered:** At every stage, ask: "How will this make someone feel?" -- **Measure What Matters:** Define metrics for each dimension early—then use them to validate your choices. -- **Keep It Simple:** You don't need every pattern at once. Start with the one or two dimensions that align strongest with your concept. - - - -## Pressure-test your idea - -Before you get into features or UI, take a step back. Ask whether your idea wants to be social — or if you're forcing it. These prompts are designed to give you structured, clear feedback if you drop them into a LLM or use them in your own reflection. - -``` -Here's a one-line description of my app: [insert idea]. - -Evaluate it across these questions: - -1. Why would someone post here more than once? -2. Would the experience be better with another person involved? -3. What kind of content might naturally fill the feed over time? -4. What emotional reward might someone feel when they open it? - -Please be direct. If the idea lacks natural social behavior, suggest ways it could evolve. -``` - -## Social Patterns - -### 1. Identity Playgrounds - -**The idea:** Give people ways to explore, express, or shape their identity within the app. - -**Why it works:** People don't just use feeds to consume — they use them to perform. Customization invites play, self-expression, and experimentation. - -**Where it shows up:** Discord roles, Reddit flair, Tumblr themes. - -**Use it for:** Differentiation, emotional investment, repeat posting. - -``` -Given my app idea: [insert idea], explore 2 ways users might express or explore identity. - -For each, include: -– What the user customizes or signals -– How that shows up in the feed -– Why that might matter over time -``` - -### 2. Co-Creation Loops - -**The idea:** Design behaviors that are better when shared — where users build on each other's contributions. - -**Why it works:** The strongest feeds don't just display content; they build momentum. If one person's post sparks another, you get a chain reaction. - -**Where it shows up:** Remix threads, collab playlists, group journaling. - -**Use it for:** Participation loops, content momentum, chain reactions. - -``` -How could users in [insert app idea] create something together or build on each other's actions? -Return 3 co-creation flows that include: -– What kicks it off -– How others join in -– What the feed looks like after a few days -``` - -### 3. Long-Term Rituals - -**The idea:** Introduce regular, shared behaviors that become a rhythm. - -**Why it works:** Rituals create predictability, belonging, and anticipation. They give users a reason to come back on a schedule. - -**Where it shows up:** Wordle scores, Monday memes, Friday drops, yearly Spotify Wrapped. - -**Use it for:** Habit loops, appointment-based engagement, social cohesion. - -``` -Design 2 recurring rituals for [insert app idea]. - -For each, include: -– Frequency (daily, weekly, monthly) -– What users post -– What emotion or payoff they get -– How it could spread through the feed -``` - -## Interpreting your feedback - -After you get back raw answers to the four pressure‑test questions, look for the one or two dimensions that most naturally fit your idea. Nail those first, then decide if you need to shore up any others. - - - -Scan your AI responses for signs of strength in these four key areas: - - - -**Look for:** "Daily check‑ins create habit" or "Natural reason to post weekly" - - - - **Look for:** "Comments spark friendly competition" or "Better with others - involved" - - - - **Look for:** "Automated reminders nudge new posts" or "Community‑driven - growth" - - - -**Look for:** "Badges tap into achievement" or "Pride in sharing progress" - - - - -Focus on the dimensions where the AI feedback was most enthusiastic and specific. Vague responses usually indicate weak social potential. - - - - -For each dimension that scored well, confirm the feedback includes clear, actionable examples: - - - -**Strong signal:** At least 1 post per week feels natural to users - -**Examples to look for:** - -- "Users would naturally share daily progress" -- "Weekly challenges create posting rhythm" -- "Status updates become habitual" - -**Red flag:** Forced or infrequent posting suggestions - - - - -**Strong signal:** Others are meaningfully involved, not just passive viewers - -**Examples to look for:** - -- "Friends can collaborate on projects" -- "Comments turn into conversations" -- "Peer reactions drive engagement" - -**Red flag:** Social features feel like an afterthought - - - - -**Strong signal:** Community‑driven growth that builds over time - -**Examples to look for:** - -- "Posts inspire similar content from others" -- "Popular topics emerge naturally" -- "User‑generated content feeds itself" - -**Red flag:** Content relies entirely on individual creators - - - - -**Strong signal:** Opening the app delivers a felt reward - -**Examples to look for:** - -- "Users feel proud sharing progress" -- "Achievements create satisfaction" -- "Community recognition feels meaningful" - -**Red flag:** Emotional benefits are unclear or generic - - - - - - -Now that you've identified your strongest dimensions, here's how to proceed: - - - -**You're ready to build!** - -If your top 1–2 dimensions check out, skip straight to building social features around them. You don't need to perfect all four dimensions before starting. - - -Focus your energy on the social angles that truly resonate with your concept first. - - - - -**Iterate before building** - -If your dimensions are weak, spend time strengthening them before moving to development: - -- **Add a relational hook** (how do others get involved?) -- **Include a habit prompt** (what brings people back?) -- **Create emotional stakes** (why should users care?) - - -Don't force social features onto an inherently solo experience. Consider if your idea needs to evolve. - - - - -**Example Decision Flow:** - -You see strong **"Social lift"** ("Friends' reactions spark threads") and decent **"Emotional payoff"** ("Likes feel rewarding"). - -✅ **Decision:** Prototype a co‑posting feature focusing on these strengths - -⏳ **Later:** Explore "Content momentum" and "Repeat‑posting" patterns once core social features are solid - - -This focused approach prevents feature bloat and ensures you build social mechanics that actually work for your specific concept. - - - - -## Closing note - -The mini apps that thrive aren't the most complex — they're the ones that understand how people connect. - - -**Remember:** - -- Social features only work when they reflect real human behavior -- A feed isn't just content — it's a shared ritual -- True engagement comes from meaning over mechanics - - - -As you build, ask: _Why would someone want to come back? Why would they share this with a friend?_ Those answers matter more than any feature list. - -The best apps don't just fill feeds. They create places people want to return to. -So — what will your app make people feel? diff --git a/docs/apps/growth/optimize-onboarding.mdx b/docs/apps/growth/optimize-onboarding.mdx deleted file mode 100644 index 0abb796da..000000000 --- a/docs/apps/growth/optimize-onboarding.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -hidden: true -title: Optimize Onboarding -description: Reduce friction with wallet‑optional flows and clear value moments ---- - -Optimize your onboarding flow to increase user engagement and retention. This guide outlines the best practices that will keep your users in-app and engaged. - -### Overview - -Deliver value instantly and avoid blocking actions. - -- Make the first interaction instant and non-blocking -- Authenticate only when required for security purposes and defer prompts until necessary -- Prefer the built-in Base Account; only offer connect/switch for alternate wallets, never gating -- Use progressive disclosure tied to intent (buy, post, personalize) -- Keep users in-app with [SDK actions for links](/mini-apps/features/links); avoid fragile static urls - -### Recommended onboarding flow - - - -- Show immediate value (demo content, sample state, or read-only mode) -- Personalize instantly with [`context`](/mini-apps/core-concepts/context) of the user's profile to instantly personalize -- Display one clear CTA that leads to a meaningful action (e.g. "Post a message", "Buy a token", "Follow a user") - - - -- Trigger Sign In with Farcaster (SIWF) / Quick Auth only when needed per [Authentication](/mini-apps/features/Authentication) -- For onchain actions, use the Base Account automatically. Eliminate explicit wallet connect flows -- Alternate wallets: offer a non-blocking connect/switch option without gating exploration - - - -- After success, prompt social actions via [SDK actions](/mini-apps/features/links) and [Sharing & Social Graph](/mini-apps/features/sharing-and-social-graph) -- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/troubleshooting/how-search-works) - - - -### UX patterns that work - - -- Progressive prompts: ask only when needed (buy, post, personalize) -- Clear copy: explain why you’re asking ("Sign in to save your score") - - -- One-time deep link (Connect Account users): if SIWF requires a one-time Farcaster link to register auth address, message it as a quick, one-time setup and return the user seamlessly -- Friendly fallbacks: if auth is skipped or fails, allow continued browsing in read-only mode - -### Authentication and wallet guidance - -#### Authentication - -- Only when your backend needs a verified user -- Use SIWF/Quick Auth to issue a session (JWT) when required - - -Do not treat Mini App context as primary auth (it can be spoofed) - - -Read more in [Authentication](/mini-apps/features/Authentication). - -#### Wallets -- Base App provides an in-app Base Account. This should be the default wallet used by your app to streamline interactions. -- Do not show a connect button on first load -- If you support other wallets, show connect/switch as optional and non-blocking - -### Do not use raw deeplinks - - -- Always use official SDK actions for cross-client compatibility (e.g., compose cast, view profile) -- This prevents dead ends and ensures consistent behavior across hosts - - -Learn how to implement them with [SDK actions](/mini-apps/features/links). - -### Measure activation and iterate - - -- Define activation as the first successful protected action (e.g., first post, first onchain action) -- Track funnel: first render → intent click → auth/wallet prompt → success → share/save - - -- Break down Create Account vs Connect Account behavior to spot friction -- See: Base Build Analytics (coming soon) - -### Implementation checklist - - -- Landing screen is usable without auth or wallet prompts -- Trigger SIWF/Quick Auth only when backend needs it - - -- Use MiniKit context for analytics only; avoid using it as primary auth -- Use Base Account seamlessly for onchain actions; no upfront connect flow -- If supporting alternate wallets, provide optional, non-blocking connect/switch -- Use SDK actions for social flows (compose/view) instead of deeplinks -- Provide a post-success share step and clear next action -- Test both Create Account and Connect Account paths - -### Further reading - - - - - - - - - - - - - - - diff --git a/docs/apps/introduction/overview.mdx b/docs/apps/introduction/overview.mdx deleted file mode 100644 index 87cbfc10e..000000000 --- a/docs/apps/introduction/overview.mdx +++ /dev/null @@ -1,188 +0,0 @@ ---- -hidden: true -title: "Why Mini Apps" -description: "Discover how Mini Apps eliminate friction and leverage social distribution to create instantly engaging, viral experiences that traditional apps can't match." ---- - -The next evolution of digital experiences extends beyond app stores into social feeds and direct messages. Mini Apps are lightweight, social-native apps that launch instantly when you tap them: no downloads, no friction, just immediate engagement. While the Base App provides the discoverability through social distribution and featured listings, Mini Apps deliver the frictionless experience that makes instant trial and viral sharing possible. - - -Existing web applications can be converted into Mini Apps. Learn how to [integrate your existing app](/mini-apps/quickstart/existing-apps/install) with our helpful guide. - - - - **Framework Compatibility Note** -Mini apps built with either the [Farcaster SDK](https://miniapps.farcaster.xyz/) or MiniKit both work seamlessly in the Base app. Choose the framework that best fits your development preferences - - -## Beyond the App Store Model - -Traditional apps face costly user acquisition because they're buried among millions of competitors in app stores, require separate iOS and Android development with ongoing maintenance across platforms, and create commitment friction through installation requirements. Mini Apps eliminate these barriers entirely by running as lightweight web applications that work instantly across all devices, deploy with zero installation friction, and spread organically through social feeds where users naturally discover content—turning every interaction into potential viral distribution that no app store algorithm can match. - - - - - Limited to app store discovery - - Require downloads and installations - - Expensive user acquisition campaigns - - Users start with empty social graphs - - - - - Distributed through social feeds - - Launch instantly with one tap - - Viral distribution through social sharing - - Built-in friend networks and social context - - - -## What Makes Mini Apps Different - -### For Users: Frictionless Discovery and Engagement - -Mini Apps eliminate the gap between discovery and engagement. Instead of downloading apps you might never use again, you can instantly try interactive experiences shared by friends. With leaderboards, challenges, and multiplayer features, these apps transform from individual experiences into social activities you do with your friends—competing, collaborating, and sharing achievements together. - -### For Builders: Built-in Social Infrastructure - -As a developer, you build on top of existing social infrastructure instead of recreating it from scratch. - -**What you get out of the box:** -- User identity and authentication -- Social connections and friend graphs -- Viral distribution mechanisms -- Immediate access to engaged communities - - - - -## The Builder's Advantage - -Mini Apps solve three major product development challenges: - - -Image of social feed with Mini Apps - - - - - **Traditional Apps:** Builders pay for ads and fight algorithms for visibility - - **Mini Apps Solution:** User activity appears organically in their social feed (followers, friends, connections), naturally inviting others through social proof via sharing. - - - - -Image of social feed with Mini Apps - - - - - **Traditional Apps:** Expensive campaigns with low conversion rates. - - **Mini Apps Solution:** Every interaction becomes viral distribution. Users broadcast engagement to their entire network, creating compound growth loops that traditional apps can't achieve. - - - - -Image of social feed with Mini Apps - - - - **Traditional Apps:** Users start alone and build social graphs slowly. - - **Mini Apps Solution:** Launch directly into existing friend groups, see live activity from friends, and join conversations already in progress. - - - - - -## The Network Effect Advantage - - -Image of builder flywheel - - -As more people interact with these apps, they create valuable user activity and market opportunities that attract talented builders to Base, who see the engaged audience and build even better, more innovative experiences to capture that demand.This self-reinforcing cycle means every successful app strengthens the entire network, creating exponential growth that benefits every builder on Base. - - - -## What You Can Build - -The most successful Mini Apps solve everyday problems with built-in social mechanics: - - - - - Multiplayer games with real-time competition - - Trivia nights with friend groups - - Interactive stories and collaborative experiences - - - - - Group buying for better discounts - - Product recommendations from trusted friends - - Collaborative wish lists and gift planning - - - - - - Event planning with built-in RSVP tracking - - Group dining decisions with real-time voting - - Expense splitting with transparent calculations - - Travel planning with collaborative itineraries - - - - - Collaborative art and design projects - - Study groups with progress tracking - - Skill-sharing marketplaces - - Book clubs and discussion forums - - - - -**The winning pattern:** Take activities people already do individually or struggle to coordinate with others, then make them social, transparent, and immediate. - - -## From Idea to Live Application - -The development path is streamlined and permissionless: - - - - Use [MiniKit](/mini-apps/quickstart/new-apps/install) or the [Farcaster SDK](https://miniapps.farcaster.xyz/docs/getting-started) to create your application. - - - - Deploy your Mini App without waiting for approval processes or store reviews. - - - - Post your Mini App to Base App and it gets automatically indexed for discovery. No special permissions or approval processes required to show up in the Base App. - - Your app becomes instantly discoverable in: - - Base App search results - - The broader Farcaster ecosystem - - User social feeds through organic sharing - - - - - Monitor actual usage patterns and iterate based on real user feedback rather than building in isolation. - - - -## Start Building Today - -Mini Apps represent a fundamental shift toward social-native digital experiences. The advantage goes to builders who understand that in a social-first world, distribution and engagement are built into the platform itself. - - - - Get started with MiniKit and build your first Mini App in minutes. - - - - Already have a web app? Turn it into a Mini App with our integration guide. - - - - diff --git a/docs/apps/quality-and-publishing/overview.mdx b/docs/apps/quality-and-publishing/overview.mdx deleted file mode 100644 index 5fa9af359..000000000 --- a/docs/apps/quality-and-publishing/overview.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -hidden: true -title: Overview -description: How to meet the bar and submit your Mini App for featuring ---- - -TODO: Write end‑to‑end guidance for becoming Featured: prerequisites, examples, review process, and timelines. Link to Quality Bar and Submission Guidelines. - - diff --git a/docs/apps/quality-and-publishing/quality-bar.mdx b/docs/apps/quality-and-publishing/quality-bar.mdx deleted file mode 100644 index 6e230ab1b..000000000 --- a/docs/apps/quality-and-publishing/quality-bar.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -hidden: true -title: Quality Bar -description: The standards your Mini App should meet before being featured ---- - -TODO: Draft the full Quality Bar article with performance, stability, UX, and instrumentation requirements. Link concrete acceptance criteria and example checks. - - diff --git a/docs/apps/quality-and-publishing/submission-guidelines.mdx b/docs/apps/quality-and-publishing/submission-guidelines.mdx deleted file mode 100644 index 5c4a2e54e..000000000 --- a/docs/apps/quality-and-publishing/submission-guidelines.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -hidden: true -title: Submission Guidelines -description: Assets and information required to submit your Mini App for featuring ---- - -TODO: Define required assets (icons, hero, screenshots), URLs, manifest checks, and contact path for submission. - - diff --git a/docs/apps/quickstart/build-checklist.mdx b/docs/apps/quickstart/build-checklist.mdx deleted file mode 100644 index 79d677939..000000000 --- a/docs/apps/quickstart/build-checklist.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -hidden: true -title: Build Checklist -description: Key steps to build a successful mini app ---- - - - -## Register for Base Build - -Base Build unlocks Builder Rewards, boosts your chances of being featured, provides growth insights, and gives you a Preview tool to test and debug your app. - - - - -## Authentication - -Authenticate when it unlocks value, not before. Fast, optional sign‑in keeps momentum and lets users act the moment onchain interactions are needed. - - - -## Manifest - -Your manifest powers saving, discovery, and rich embeds. A strong manifest includes complete fields, valid assets, and `noindex: true` during testing. - - - -## Embeds & Previews - -Distribution starts in the feed: compelling previews with a clear image and launch button turn impressions into launches. - - - -## Search & Discovery - -Be found across surfaces: set a primary category, share once to trigger indexing, and keep assets valid to appear in search and categories. - - - -## Sharing & Social Graph - -Design for social lift: native share flows and social navigation turn single‑player moments into threads and returns. - - - -## Notifications - -Re‑engage saved users with relevant, rate‑limited notifications at the right moments. - - - -## UX Best Practices - -Build for compact, touch‑first contexts: respect safe areas, keep interfaces concise, and emphasize clear primary actions. - - - - -## Build for Growth - -Follow best practices to improve user engagement and retention. - - - - - - - - - diff --git a/docs/apps/quickstart/building-for-the-base-app.mdx b/docs/apps/quickstart/building-for-the-base-app.mdx deleted file mode 100644 index 6ec3c7cf0..000000000 --- a/docs/apps/quickstart/building-for-the-base-app.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -hidden: true -title: "Building for The Base App" -description: "People use apps to have fun, learn, earn, or connect. Your mini app should focus on **one core need** and do it exceptionally well." ---- - -The best apps are **simple, focused, and easy to understand.** - - - - -* What’s the **one thing** my app does really well? - -* Why would someone **use it every day**? - -* Why and when would someone **share it with a friend**? - - - - -Base users are social, onchain-native, and interested in **creating, earning, trading, and connecting**. - - - - - -* Help people **earn** (e.g. rewards, yield, creator income) - -* Help people **create** (e.g. minting, designing, storytelling) - -* Help people **have fun** (games, collectibles, quizzes, social experiences with onchain elements) - -* Are **simple,** **easy and satisfying** to use - -* Have **low friction onboarding** — avoid: - - * Collecting personal info (address, phone number, etc.) - - * Requiring upfront deposits or complex setup steps - - - - - -We’re especially excited about mini apps that make group chats more fun, functional, or rewarding — from games with onchain buy-ins, to tools like dinner-bill splitting with USDC. - - - -### Featured Guidelines -When building mini apps for the Base app, follow the [Featured Guidelines](/mini-apps/featured-guidelines/overview): - - - - - - - \ No newline at end of file diff --git a/docs/apps/quickstart/create-new-app.mdx b/docs/apps/quickstart/create-new-app.mdx deleted file mode 100644 index 6d6043fb1..000000000 --- a/docs/apps/quickstart/create-new-app.mdx +++ /dev/null @@ -1,152 +0,0 @@ ---- -hidden: true -title: Create a Mini App -description: Quickly create a mini app, sign a manifest, and publish to the Base app. ---- - - - -**Prerequisites** - -* Base app account -* [Vercel](https://vercel.com/) account for hosting the application - - - - - - - -Click the button below and follow the prompts to deploy the quickstart template to Vercel. - - Rapidly deploy the quickstart template to Vercel to get started. - - - -Clone the repo created by Vercel to make local edits. - -Replace `` with your github username. -```bash Terminal -git clone https://github.com//new-mini-app-quickstart -cd new-mini-app-quickstart -npm install -``` - - -The `minikit.config.ts` file is responsible for configuring your manifest located at `app/.well-known/farcaster.json` and creating embed metadata. - - You can customize the manifest by updating the `miniapp` object. - -For details on each field, see the [field reference](/mini-apps/features/manifest#field-reference). -```ts minikit.config.ts -export const minikitConfig = { - accountAssociation: { // this will be added in step 5 - "header": "", - "payload": "", - "signature": "" - }, - miniapp: { - version: "1", - name: "Cubey", - subtitle: "Your AI Ad Companion", - description: "Ads", - screenshotUrls: [`${ROOT_URL}/screenshot-portrait.png`], - iconUrl: `${ROOT_URL}/blue-icon.png`, - splashImageUrl: `${ROOT_URL}/blue-hero.png`, - splashBackgroundColor: "#000000", - homeUrl: ROOT_URL, - webhookUrl: `${ROOT_URL}/api/webhook`, - primaryCategory: "social", - tags: ["marketing", "ads", "quickstart", "waitlist"], - heroImageUrl: `${ROOT_URL}/blue-hero.png`, - tagline: "", - ogTitle: "", - ogDescription: "", - ogImageUrl: `${ROOT_URL}/blue-hero.png`, - }, -} as const; -``` - - - - - -Now that you have a public domain for your application, you are ready to associate your mini app with your Farcaster account. - - - 1. Ensure all changes are live by pushing changes to the `main` branch. - Ensure that Vercel's **Deployment Protection** is off by going to the Vercel dashboard for your project and navigating to Settings -> Deployment Protection and toggling "Vercel Authentication" to off and click save. - - 2. Navigate to the Base Build [Account association tool](https://www.base.dev/preview?tab=account). - 3. Paste your domain in the `App URL` field (ex: sample-url.vercel.app) and click "Submit" - - Sign manifest - - 4. Click on the "Verify" button that appears and follow the instructions to generate the `accountAssociation` fields. - 5. Copy the `accountAssociation` object - - - - -Update your `minikit.config.ts` file to include the `accountAssociation` object you copied in the previous step. - -```ts minikit.config.ts -export const minikitConfig = { - accountAssociation: { - "header": "eyJmaBBiOjE3MzE4LCJ0eXBlIjoiY3VzdG9keSIsImtleSI6IjB4NzYwQjA0NDc5NjM4MTExNzNmRjg3YDPBYzA5OEJBQ0YxNzNCYkU0OCJ9", - "payload": "eyJkb21haW4iOiJ4BWl0bGlzdC1xcy52ZXJjZWwuYXBwIn7", - "signature": "MHhmNGQzN2M2OTk4NDIwZDNjZWVjYTNiODllYzJkMjAwOTkyMDEwOGVhNTFlYWI3NjAyN2QyMmM1MDVhNzIyMWY2NTRiYmRlZmQ0NGQwOWNiY2M2NmI2B7VmNGZiMmZiOGYzNDVjODVmNmQ3ZTVjNzI3OWNmMGY4ZTA2ODYzM2FjZjFi" - }, - miniapp: { - ... - }, - } -``` - - -Push all changes to the `main` branch. Vercel will automatically deploy the changes to your production environment. - - - - Go to [base.dev/preview](https://base.dev/preview) to validate your app. - 1. Add your app URL to view the embeds and click the launch button to verify the app launches as expected. - 2. Use the "Account association" tab to verify the association credentials were created correctly. - 3. Use the "Metadata" tab to see the metadata added from the manifest and identify any missing fields. - - - - - - - To publish your app, create a post in the Base app with your app's URL. - - -Posting an app to Base app - - - -## Next Steps -Explore the templates and resources available to help you build your mini app. - - - - \ No newline at end of file diff --git a/docs/apps/quickstart/migrate-existing-apps.mdx b/docs/apps/quickstart/migrate-existing-apps.mdx deleted file mode 100644 index e2b3d2c1b..000000000 --- a/docs/apps/quickstart/migrate-existing-apps.mdx +++ /dev/null @@ -1,241 +0,0 @@ ---- -hidden: true -title: Migrate an Existing App -description: Quickly migrate your existing app to a mini app, preview it in Base Build, and publish to the Base app. ---- - - - - -**Prerequisites** -* You have an existing web app -* You have a Base app account - - - - - -```bash npm -npm install @farcaster/miniapp-sdk -``` - -```bash pnpm -pnpm add @farcaster/miniapp-sdk -``` - -```bash yarn -yarn add @farcaster/miniapp-sdk -``` - - - - -Once your app has loaded, call `sdk.actions.ready()` to hide the loading splash screen and display your app. - - - ```javascript app.js - import { sdk } from '@farcaster/miniapp-sdk'; - - // Once app is ready to be displayed - await sdk.actions.ready(); - ``` - - - In React apps, call `ready()` inside a `useEffect` hook to prevent it from running on every re-render. Call `ready()` as soon as possible and avoid jitter and content reflows. - ```typescript app.tsx - import { sdk } from '@farcaster/miniapp-sdk'; - import { useEffect } from 'react'; - - function App() { - useEffect(() => { - sdk.actions.ready(); - }, []); - - return(...your app content goes here...) - } - - export default App; - - ``` - - - - - -Create a file available at `https://www.your-domain.com/.well-known/farcaster.json`. - - - - Create the manifest file in your project at `/public/.well-known/farcaster.json`. - - - Create a Next.js route to host your manifest file - ```typescript app/.well-known/farcaster.json/route.ts - function withValidProperties(properties: Record) { - return Object.fromEntries( - Object.entries(properties).filter(([_, value]) => (Array.isArray(value) ? value.length > 0 : !!value)) - ); - } - - export async function GET() { - const URL = process.env.NEXT_PUBLIC_URL as string; - return Response.json(paste_manifest_json_object_here); // see the next step for the manifest_json_object - } - ``` - - - - - - -Copy the example manifest below and add it to the file created in the previous step. Update each field in the `miniapp`. - -For details on each field, see the [field reference](/mini-apps/features/manifest#field-reference) - -### Example Manifest -```json /.well-known/farcaster.json -{ - "accountAssociation": { // these will be added in step 5 - "header": "", - "payload": "", - "signature": "" - }, - "miniapp": { - "version": "1", - "name": "Example Mini App", - "homeUrl": "https://ex.co", - "iconUrl": "https://ex.co/i.png", - "splashImageUrl": "https://ex.co/l.png", - "splashBackgroundColor": "#000000", - "webhookUrl": "https://ex.co/api/webhook", - "subtitle": "Fast, fun, social", - "description": "A fast, fun way to challenge friends in real time.", - "screenshotUrls": [ - "https://ex.co/s1.png", - "https://ex.co/s2.png", - "https://ex.co/s3.png" - ], - "primaryCategory": "social", - "tags": ["example", "miniapp", "baseapp"], - "heroImageUrl": "https://ex.co/og.png", - "tagline": "Play instantly", - "ogTitle": "Example Mini App", - "ogDescription": "Challenge friends in real time.", - "ogImageUrl": "https://ex.co/og.png", - "noindex": true - } -} -``` - - - -The `accountAssociation` fields in the manifest are used to verify ownership of your app. You can generate these fields on Base Build. - - - 1. Ensure all changes are live so that the Manifest file is available at your app's url. - 2. Navigate to the Base Build [Account association tool](https://www.base.dev/preview?tab=account). - 3. Paste your domain in the `App URL` field (ex: sample-url.vercel.app) and click "Submit" - 4. Click on the "Verify" button that appears and follow the instructions to generate the `accountAssociation` fields. - 5. Copy the `accountAssociation` fields and paste them into the manifest file you added in the previous step. - ```json /.well-known/farcaster.json - { - "accountAssociation": { - "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0", - "payload": "eyJkb21haW4iOiJhcHAuZXhhbXBsZS5jb20ifQ", - "signature": "MHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwNDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAyMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwYzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMTIwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxNzAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDEyNDdhNDhlZGJmMTMwZDU0MmIzMWQzZTg1ZDUyOTAwMmEwNDNkMjM5NjZiNWVjNTNmYjhlNzUzZmIyYzc1MWFmNTI4MWFiYTgxY2I5ZDE3NDAyY2YxMzQxOGI2MTcwYzFiODY3OTExZDkxN2UxMzU3MmVkMWIwYzNkYzEyM2Q1ODAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMjVmMTk4MDg2YjJkYjE3MjU2NzMxYmM0NTY2NzNiOTZiY2VmMjNmNTFkMWZiYWNkZDdjNDM3OWVmNjU0NjU1NzJmMWQwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwOGE3YjIyNzQ3OTcwNjUyMjNhMjI3NzY1NjI2MTc1NzQ2ODZlMmU2NzY1NzQyMjJjMjI2MzY4NjE2YzZjNjU2ZTY3NjUyMjNhMjI2NDJkMzQ0YjMzMzMzNjUyNDY3MDc0MzE0NTYxNjQ2Yjc1NTE0ODU3NDg2ZDc5Mzc1Mzc1Njk2YjQ0MzI0ZjM1NGE2MzRhNjM2YjVhNGM3NDUzMzczODIyMmMyMjZmNzI2OTY3Njk2ZTIyM2EyMjY4NzQ3NDcwNzMzYTJmMmY2YjY1Nzk3MzJlNjM2ZjY5NmU2MjYxNzM2NTJlNjM2ZjZkMjIyYzIyNjM3MjZmNzM3MzRmNzI2OTY3Njk2ZTIyM2E2NjYxNmM3MzY1N2QwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA" - }, - "miniapp": {...} // these fields remain the same - } - ``` - - Note: Because you are signing with your Base Account, the `signature` field will be significantly longer than if you were to sign directly with your Farcaster custody wallet. - - - - - - Update your index.html file to include the `fc:miniapp` metadata. This is used to generate the rich embeds when your app is shared and is required for your app to display. - - - - Add directly to your index.html file. - ```html index.html - - ``` - - - Use the `generateMetadata` function to add the `fc:miniapp` metadata. - ```typescript app/layout.tsx - export async function generateMetadata(): Promise { - return { - other: { - 'fc:miniapp': JSON.stringify({ - version: 'next', - imageUrl: 'https://your-app.com/embed-image', - button: { - title: `Launch Your App Name`, - action: { - type: 'launch_miniapp', - name: 'Your App Name', - url: 'https://your-app.com', - splashImageUrl: 'https://your-app.com/splash-image', - splashBackgroundColor: '#000000', - }, - }, - }), - }, - }; - } - ``` - - - - - Ensure all changes are live. - - - - Use the Base Build [Preview tool](https://www.base.dev/preview) to validate your app. - 1. Add your app URL to view the embeds and click the launch button to verify the app launches as expected. - 2. Use the "Account association" tab to verify the association credentials were created correctly. - 3. Use the "Metadata" to see the metadata added from the manifest and identify any missing fields. - - - - - To publish your app, create a post in the Base app with your app's URL. - - - Posting an app to Base app - - - diff --git a/docs/apps/quickstart/template.mdx b/docs/apps/quickstart/template.mdx deleted file mode 100644 index 6ba49ed01..000000000 --- a/docs/apps/quickstart/template.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -hidden: true -title: "Mini App Templates" -url: "https://github.com/base/demos/tree/master/mini-apps/templates/farcaster-sdk/mini-app-full-demo" - ---- \ No newline at end of file diff --git a/docs/apps/technical-guides/accept-payments.mdx b/docs/apps/technical-guides/accept-payments.mdx deleted file mode 100644 index 41848c8cd..000000000 --- a/docs/apps/technical-guides/accept-payments.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -hidden: true -title: "Accept Payments" -description: "Enable one-tap USDC payments with Base Pay." ---- - -Accept one-tap USDC payments with the Base Pay helper function. No additional setup required: - - - - - -```bash npm -npm install @base-org/account -``` -```bash pnpm -pnpm add @base-org/account -``` -```bash yarn -yarn add @base-org/account -``` -```bash bun -bun add @base-org/account -``` - - - - - - -```typescript title="PaymentComponent.tsx" highlight={5-10} -import { pay, getPaymentStatus } from '@base-org/account'; - -async function handlePayment() { - try { - const payment = await pay({ - amount: '5.00', // USD amount - to: '0xRecipient', // your recipient address - testnet: true // set false for mainnet - }); - - console.log(`Payment sent! ID: ${payment.id}`); - - // Check payment status - const { status } = await getPaymentStatus({ - id: payment.id, - testnet: true - }); - - if (status === 'completed') { - console.log('Payment confirmed!'); - } - } catch (error) { - console.error('Payment failed:', error.message); - } -} -``` - - -**Collecting user info at checkout** - -With Base Pay, you can request email, phone, or shipping address by passing a `payerInfo` object. See the [Accept Payments Guide](/base-account/guides/accept-payments#collect-user-information-optional) for details. - -However, this is ***not supported*** in Mini Apps yet. - - - -If you intend on using Base Pay, make sure to follow the [Brand Guidelines](/base-account/reference/ui-elements/brand-guidelines) or use the [`BasePayButton`](/base-account/reference/ui-elements/base-pay-button) component whenever possible to ensure consistency across all applications. - - - - - -Use the pre-built component for a native look-and-feel: - -```tsx title="PaymentComponent.tsx" -import { BasePayButton } from '@base-org/account-ui/react'; -import { pay } from '@base-org/account'; - -export function Checkout() { - const handlePayment = async () => { - try { - const payment = await pay({ amount: '5.00', to: '0xRecipient' }); - console.log(`Payment sent! Transaction ID: ${payment.id}`); - } catch (error) { - console.error(`Payment failed: ${error.message}`); - } - }; - - return ( - - ); -} -``` - - - - - - - - Complete reference for the Base Pay helper function - - - Pre-built UI component reference - - \ No newline at end of file diff --git a/docs/apps/technical-guides/building-chat-agents.mdx b/docs/apps/technical-guides/building-chat-agents.mdx deleted file mode 100644 index 9cf4981ae..000000000 --- a/docs/apps/technical-guides/building-chat-agents.mdx +++ /dev/null @@ -1,710 +0,0 @@ ---- -hidden: true -title: "Building Chat Agents" -description: "Build conversational chat agents for Base App using XMTP messaging protocol" ---- - -import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx" - -This guide covers how to build messaging agents for Base App using XMTP, a decentralized messaging protocol. Discover a fast, easy way to build and get distribution in Base App. - -## Why agents? - -Messaging is the largest use-case in the world, but it's more than just conversations—it's a secure, programmable channel for financial and social innovation. When combined with the onchain capabilities of Base App, builders have a new surface area to build 10X better messaging experiences not currently possible on legacy platforms like WhatsApp or Messenger. - -Real Examples: - -- **Smart Payment Assistant:** Text "split dinner $200 4 ways" and everyone gets paid instantly with sub-cent fees, no app switching or Venmo delays. -- **AI Trading Companion:** Message "buy 100 dollars of ETH when it hits $3,000" and your agent executes trades 24/7 while you sleep. -- **Travel Planning Agent:** "Book flight LAX to NYC under $300" and get instant booking with crypto payments, all in your group chat. - -Base App & XMTP are combining AI, crypto, and mini apps with secure messaging to unlock use-cases never before possible. Secure group chats & DMs are the new surface area for developers. - -## Getting started - -Build powerful chat agents that integrate seamlessly with Base App using the XMTP messaging protocol. - - -For more detailed information, visit [XMTP documentation](https://docs.xmtp.org/agents/get-started/build-an-agent) - - -### Installation - - - -```bash npm -npm install @xmtp/agent-sdk -``` - -```bash pnpm -pnpm add @xmtp/agent-sdk -``` - -```bash yarn -yarn add @xmtp/agent-sdk -``` - - - -### Usage - -This example shows how to create an agent that sends a message when it receives a text message. - -```ts agent.ts -import { Agent } from '@xmtp/agent-sdk'; - -// 2. Spin up the agent -const agent = await Agent.createFromEnv({ - env: 'production', // base app works only on production -}); - -// 3. Respond to text messages -agent.on('text', async (ctx) => { - await ctx.sendText('Hello from my Base App Agent! 👋'); -}); - -// 4. Log when we're ready -agent.on('start', () => { - console.log(`Waiting for messages...`); - console.log(`Address: ${agent.address}`); -}); - -await agent.start(); -``` - -### Set environment variables - -To run an example XMTP agent, you must create a `.env` file with the following variables: - -```bash .env -XMTP_WALLET_KEY= # the private key of the wallet -XMTP_DB_ENCRYPTION_KEY= # encryption key for the local database -XMTP_ENV=production # local, dev, production -``` - -### Get a basename for your agent - -Give your agent a human-readable name: - -**1. Import agent wallet to Base App extension:** - -- Install Base App browser extension -- Import using your agent's private key - -**2. Purchase a basename:** - -- Visit https://base.org/names -- Connect your agent's wallet -- Search and purchase your desired basename (e.g., myagent.base.eth) -- Set as primary name - -**3. Verify setup:** - -- Your agent can now be reached via the basename instead of the long address -- Users can message myagent.base.eth instead of 0x123... - -## Quick actions - -While Base App supports all standard XMTP content types for rich messaging capabilities, this section focuses specifically on **Base-developed content types** that enhance agent interactions within Base App. - -These Base-specific content types (Quick Actions and Intent) provide unique functionality that may not be supported by other XMTP clients. For standard XMTP content types like reactions, attachments, and transactions, see the [XMTP documentation](https://docs.xmtp.org/agents/content-types/content-types). - -### Base App content types - -There are content types developed by the Base App team for agents in Base App. Other XMTP clients may not support these content types. - -**Quick Actions (coinbase.com/actions:1.0)** - -Purpose: Present interactive buttons in a message - -Structure: - -```typescript ActionsContent -type ActionsContent = { - id: string; - description: string; - actions: Action[]; - expiresAt?: string; -}; - -type Action = { - id: string; - label: string; - imageUrl?: string; - style?: 'primary' | 'secondary' | 'danger'; - expiresAt?: string; -}; -``` - -Validation Rules: - -- `id`, `description` are required -- `actions` must be 1–10 items with unique IDs -- Style must be one of: `primary`, `secondary`, `danger` - -Fallback: - -```text Fallback format -[Description] - -[1] [Action Label 1] -[2] [Action Label 2] -... -Reply with the number to select -``` - -Example: Payment Options - -```json Payment options -{ - "id": "payment_alice_123", - "description": "Choose amount to send to Alice", - "actions": [ - { "id": "send_10", "label": "Send $10", "style": "primary" }, - { "id": "send_20", "label": "Send $20", "style": "primary" }, - { "id": "custom_amount", "label": "Custom Amount", "style": "secondary" } - ], - "expiresAt": "2024-12-31T23:59:59Z" -} -``` - - - Manifest Embed Example - - -**Intent (coinbase.com/intent:1.0)** - -Purpose: User expresses choice from Quick Actions - -Structure: - -```typescript IntentContent -type IntentContent = { - id: string; - actionId: string; - metadata?: Record; -}; -``` - -Validation Rules: - -- `id`, `actionId` required -- Must match corresponding Actions -- `metadata` is optional, `<10KB` - -Fallback: - -```text Fallback format -User selected action: [actionId] -``` - -Example: Intent Message - -```json Intent message -{ - id: 'payment_alice_123', - actionId: 'send_10', - metadata: { - timestamp: Date.now(), - actionLabel: 'Send $10' - } -} -``` - - - Analytics dashboard with charts - - - -## Transaction trays - -If you would like to display agent information such as favicon and branded title, utilize the metadata property of wallet send calls data. - -**Example: Display agent information** - -```ts Wallet send calls data -// example of wallet send calls data shape -{ - version: "1.0", - from: request.from as `0x${string}`, - chainId: this.networkConfig.chainId, - calls: [ - { - ... - metadata: { - description: "Transfer token", - ...other fields, - hostname: "tba.chat", - faviconUrl: "https://tba.chat/favicon", - title: "Your favorite Agent" - } - } - ] -} -``` - - - Transaction tray - - -You can send "GM" to **tbachat.base.eth** to get more details about message content types we support and get the firsthand experience on by interacting with our agent - - - -## Deeplinks - -Deeplinks enable seamless navigation within Base App, allowing agents to create more engaging and intuitive user experiences. The most common use case is directing users to start a private conversation with an agent from a group chat context. - -### Direct message deeplinks - -#### Use case - -Your miniapp has an agent and you want to encourage people to chat with the agent directly. Or, your agent exists in a group chat context and wants users to interact with it privately. You could add a button like "Chat with me" and use this deeplink. - -#### Syntax - -```text Deeplink syntax -cbwallet://messaging/address -``` - -#### Parameters - -- **address** — The 0x address of the user you want to chat with (in hex format, e.g., `0xabc...1234`) - -### Implementation examples - -**Basic Button Implementation:** - -```typescript Basic button - -``` - -**React Component with Error Handling:** - -```typescript DeeplinkButton.tsx expandable -import { useState } from 'react'; - -interface DeeplinkButtonProps { - agentAddress: string; - label?: string; - className?: string; -} - -export function DeeplinkButton({ - agentAddress, - label = "Direct Message", - className = "btn-primary" -}: DeeplinkButtonProps) { - const [isLoading, setIsLoading] = useState(false); - - const handleDeeplink = async () => { - setIsLoading(true); - try { - const deeplink = `cbwallet://messaging/${agentAddress}`; - - // Check if running in supported environment - if (typeof window !== 'undefined') { - window.location.href = deeplink; - } else { - // Fallback for server-side rendering - console.warn('Deeplink not supported in this environment'); - } - } catch (error) { - console.error('Failed to open deeplink:', error); - } finally { - setIsLoading(false); - } - }; - - return ( - - ); -} -``` - -## Payment agents (x402) - -x402 is an open payment protocol developed by Coinbase that enables instant, automatic stablecoin payments directly over HTTP. It empowers AI agents to autonomously pay for services without subscriptions or API keys. - -### Key benefits - -- **Autonomous economic transactions** - Agents can transact without human intervention -- **Pay-as-you-go monetization** - Only pay for the services you actually use -- **Minimal setup** - Often requires just one middleware line -- **Instant settlement** - Payments are verified on-chain in real-time - -### Basic integration - -Here's how your agent handles payment-gated requests: - -```typescript x402-agent.ts expandable -import { Agent } from '@xmtp/agent-sdk'; -import { PaymentFacilitator } from '@coinbase/x402-sdk'; - -// Create agent -const agent = await Agent.createFromEnv({ - env: 'production', -}); - -// Initialize payment facilitator -const facilitator = new PaymentFacilitator({ - privateKey: process.env.XMTP_WALLET_KEY!, - network: process.env.NETWORK || 'base' -}); - -// Handle text messages with premium features -agent.on('text', async (ctx) => { - const message = ctx.message.content; - - // Check if user is requesting premium feature - if (message.includes('floor price')) { - const response = await fetch("/premium-api/nft-floor-price"); - - // Check if payment is required - if (response.status === 402) { - const paymentDetails = await response.json(); - - // Notify user about payment requirement - await ctx.sendText(`💰 Payment required: ${paymentDetails.amount} USDC. Processing...`); - - // Execute payment - const payment = await facilitator.createPayment({ - amount: paymentDetails.amount, - recipient: paymentDetails.recipient, - reference: paymentDetails.reference, - currency: 'USDC' - }); - - // Retry request with payment - const retryResponse = await fetch("/premium-api/nft-floor-price", { - headers: { "X-PAYMENT": payment.payload } - }); - - if (retryResponse.ok) { - const data = await retryResponse.json(); - await ctx.sendText(`📊 NFT floor price: ${data.floorPrice} ETH`); - } - } - } -}); - -await agent.start(); -``` - -### UX considerations - - -Always inform users about payment requirements before executing transactions. Transparency builds trust with your agent. - - -- **Clear pricing** - Display exact costs upfront -- **Payment confirmation** - Confirm successful payments -- **Graceful failures** - Handle payment errors elegantly -- **Value communication** - Explain what users get for their payment - - -Never expose private keys in your code. Always use environment variables and secure key management practices. - - -For complete x402 documentation, implementation examples, and SDK reference, see the [CDP x402 documentation](https://docs.cdp.coinbase.com/x402/welcome). - -## Mini app integration - -Mini Apps can live inside conversations, letting friends play, trade, plan, and coordinate together without ever leaving the chat. - -This means that you can have virality spread through natural conversation ("try this right here") along with sharing in larger settings. When combined with intelligent agents, you create powerful experiences that spread through natural conversation. - -This integration unlocks unique distribution and engagement patterns: - -- **Natural virality:** "Try this right here" moments spread organically through conversation -- **Contextual engagement:** Agents can introduce Mini Apps at the perfect moment -- **Group coordination:** Agents orchestrate multiplayer experiences and keep everyone engaged -- **Persistent presence:** Agents maintain engagement between Mini App sessions - -**Real Examples:** - -- **Group Gaming:** Agent coordinates a multiplayer quiz, announces winners, and keeps score across sessions -- **Event Planning:** Agent shares planning Mini App when someone mentions meeting up, handles RSVPs and updates -- **Trading Competitions:** Agent creates trading challenges, shares leaderboards, and celebrates wins -- **Social Polls:** Agent launches polls when decisions need to be made, tallies results, and announces outcomes - -### Share Mini Apps in App - -Every Mini App has a shareable URL that agents can send directly in chat. When dropped into a conversation, the link automatically unfurls into a rich preview card that others can tap to launch instantly. - -**Share Flow:** -1. **Agent triggers share** — Based on conversation context or user request -2. **Link generates preview** — Platform fetches Mini App metadata and creates rich embed -3. **Users engage** — Tap preview to launch Mini App directly in conversation -4. **Agent coordinates** — Continues engagement, shares updates, mentions participants - -**Basic Mini App Sharing:** - -```typescript Basic sharing -agent.on("text", async (ctx) => { - const description = "🎯 Ready for a quick quiz challenge?"; - const appUrl = "https://your-miniapp.com/quiz"; - await ctx.sendText(`${description}\n\n${appUrl}`); -} -``` - -**Advanced Integration with Context:** - -```typescript Context-aware sharing -// Agent detects conversation context and shares relevant Mini App -async function handleMessage(message, conversation) { - const text = message.content.toLowerCase(); - - if (text.includes("game") || text.includes("play")) { - await shareMiniApp( - conversation, - "https://your-miniapp.com/games", - "🎮 Let's play! Choose your game:" - ); - } else if (text.includes("vote") || text.includes("decide")) { - await shareMiniApp( - conversation, - "https://your-miniapp.com/poll", - "🗳️ Let's settle this with a poll:" - ); - } -} -``` - -### User engagement and mentions - -Agents on XMTP only have access to the 0x addresses. If you're building a group chat experience with Mini Apps, you'll want to use human-readable mentions like display names (like @jesse) for a more social, intuitive experience. - -This API from Neynar will give your agent access to this data: - -**Getting Display Names:** - -```typescript neynar.ts -import { NeynarAPIClient } from "@neynar/nodejs-sdk"; - -const neynar = new NeynarAPIClient("YOUR_API_KEY"); - -async function getDisplayName(address) { - try { - const users = await neynar.lookupUserByVerification(address); - return users.result.users[0]?.display_name || address.slice(0, 8); - } catch (error) { - return address.slice(0, 8); // Fallback to truncated address - } -} - -// Usage in agent messages -async function announceWinner(conversation, winnerAddress, gameType) { - const displayName = await getDisplayName(winnerAddress); - await conversation.send(`🏆 @${displayName} wins the ${gameType}! Amazing job!`); -} -``` - -### Agent spotlight: Squabble - -[Squabble](https://github.com/builders-garden/squabble) uses Mini Apps in a social, fun way, with the agent coordinating the multiplayer experience. - -The agent sends a Mini App to the group, and broadcasts to the group updates as people join and compete in the game. They mention the usernames of the people who have joined the game and won the game. The game happens inside the Mini App, which provides a more interactive, visual experience. - -**Key Features:** -- **Rich mentions** — Agent uses display names (@username) instead of wallet addresses -- **Real-time updates** — Broadcasts join notifications and game progress to maintain group engagement -- **Social celebration** — Announces winners and achievements to drive continued participation -- **Contextual triggers** — Responds to gaming-related conversation with relevant Mini App shares - -### Best practices for agent behavior - - - -- **Smart triggers** — Share Mini Apps when conversation context suggests engagement opportunity -- **Avoid spam** — Don't share the same Mini App repeatedly in short timeframes -- **Read the room** — Gauge group interest before introducing games or activities -- **Natural integration** — Make Mini App shares feel like helpful suggestions, not advertisements - - - -- **Direct messages** — Automatically share relevant Mini Apps based on user requests -- **Group messages** — Only share Mini Apps when mentioned (@agentname) or when replying to agent messages -- **React to acknowledge** — Use emoji reactions (👀, ⌛) to show message received while processing -- **Coordinate experience** — In groups, act as facilitator for multiplayer Mini App experiences - - - -- **Use display names** — Always resolve addresses to human-readable names for mentions -- **Celebrate achievements** — Announce wins, completions, and milestones to drive engagement -- **Maintain context** — Remember ongoing games/activities and provide relevant updates -- **Enable discovery** — Suggest related Mini Apps based on user interests and behavior - - - - -## Best practices - -As you start building, review these guidelines to understand what makes an agent successful in the Base app. We recommend trying out existing agents in the app first to get a feel for the quality bar, what works well, and areas for improvement. - -### Build a high quality foundation - -Your agent should provide a seamless, professional experience that users will want to engage with repeatedly. Here are the core requirements: - -#### Responding to messages - -**Multi-Channel Support** -- Respond to both DMs and group chats appropriately -- Maintain consistent functionality across different conversation types - -**Immediate Feedback** -- React to messages with a simple reaction (👀, 👍, ⌛, etc.) to show acknowledgment -- This gives users confidence their message was received while processing - -**Fast Response Times** -- Provide responses quickly (< 5 seconds) -- Users expect near-instant communication in messaging apps - -#### Group chat etiquette - -In group chats, agents should only respond when: - -1. **Mentioned directly** with "@" + agent name (e.g., @bankr) -2. **Replied to directly** when a user replies to the agent's message using the reply content type - -This prevents spam and ensures agents participate naturally in group conversations. - -#### Communication style - -**Sound Human** -- Use conversational, fun, and clear language -- Keep responses polished but not robotic -- Match the energy and tone of the conversation - -**Privacy Conscious** -- Only ask for personal information when absolutely necessary -- Always explain why the information is needed -- Respect user privacy and data minimization principles - -### Craft compelling onboarding - -Your agent's first impression is critical. The onboarding message should immediately communicate value and give users a clear path forward. - -#### Great onboarding message structure - -1. **Introduce the agent** - Quick, friendly greeting with the agent's name -2. **Explain capabilities** - Clear, specific examples of what it can do -3. **Use quick select buttons** - Make it easy for users to select an action to take with the agent - -**Example: High-Quality Onboarding** - -```text Good onboarding -hey, i'm bankr. i can help you trade, transfer, and manage your crypto. here's the rundown: - -• trade anything: buy, sell, swap tokens on base, polygon, and mainnet. try "buy 0.1 eth of degen." -• send it: transfer crypto to anyone on x, farcaster, or a wallet address. -• get alpha: token recs, market data, charts. -• automate: set up recurring buys/sells. e.g. "buy $10 of $bnkr every week." - -what do you want to do first? -``` - -**Why this works:** -- Friendly, conversational tone -- Specific feature examples with concrete commands -- Clear value propositions -- Ends with a direct call-to-action - -**Example: Poor Onboarding** - -```text Bad onboarding -Gm! What can I help you with? -``` - -**Why this fails:** -- Generic greeting with no context -- No explanation of capabilities -- Puts burden on user to figure out what to do -- No clear value proposition - -### Showcase unique value - -#### Solve real problems - -Your agent should: -- **Address a unique pain point** or bring a delightful twist to an existing space -- **Help users accomplish tasks** more easily than existing solutions -- **Provide clear benefits** that users can understand immediately - -#### Enable user success - -Focus on helping users: -- **Earn** - Generate income, rewards, or value -- **Connect** - Build relationships or communities -- **Have fun** - Provide entertainment or engaging experiences -- **Complete tasks** - Streamline workflows or processes - -#### Design for engagement - -**Build Natural Growth Loops** -- Include features that encourage sharing, re-engagement, and habit forming -- Make it beneficial for users to invite others -- Create ongoing value that brings users back - -**Plan the User Journey** -1. **Define the ideal user experience first** -2. **Craft agent messages around that journey** -3. **Guide users through progressive value discovery** - -#### Continuous engagement strategy - -As users complete actions with your agent: - -- **Show clear next steps** - Always give users something else to try -- **Highlight ongoing value** - Explain how continued use benefits them -- **Create habit loops** - Design features that encourage regular interaction -- **Prevent one-and-done usage** - Build features that require return visits - -#### Examples of engagement features - -- **Progressive features** - Unlock new capabilities as users engage more -- **Personalization** - Learn user preferences and customize experiences -- **Social elements** - Enable sharing achievements or inviting friends -- **Recurring value** - Automated tasks, alerts, or regular check-ins -- **Gamification** - Points, levels, or achievement systems - -## Resources - - - - Complete XMTP protocol documentation for messaging integration - - - - Complete x402 protocol specification and implementation guide - - - - Reference implementation for Base App chat agents - - - - Multiplayer game agent with Mini App integration - - diff --git a/docs/apps/technical-guides/neynar-notifications.mdx b/docs/apps/technical-guides/neynar-notifications.mdx deleted file mode 100644 index 13a773dc6..000000000 --- a/docs/apps/technical-guides/neynar-notifications.mdx +++ /dev/null @@ -1,263 +0,0 @@ ---- -hidden: true -title: Send Notifications (Neynar) -description: Learn how to engage users through in-app notifications using Neynar ---- - - -## Overview - - -If your app doesn't have a backend, if you're already using Neynar, or if you would rather use a hosted solution instead of [implementing notification logic](/mini-apps/core-concepts/notifications) in your backend, we recommend using Neynar for notifications. [**Neynar**](https://neynar.com/) is an infrastructure platform for building mini apps on Base. - -Neynar's solution allows you to: - -- Manage notification infrastructure (tokens, permissions, batching) in a single UI -- Send via API or Neynar developer portal UI—no code required -- Track notification performance with built-in analytics -- Target specific user cohorts with advanced segmentation - - -## Prerequisites -- A Base App account -- A mini app with the [Farcaster SDK](https://miniapps.farcaster.xyz/docs/getting-started#manual-setup) implemented -- Neynar developer account -- sign up for free [here](https://neynar.com) - - -## Enable Notifications - - - -The Neynar mini app events webhook URL is on the Neynar app page. - -Navigate to [dev.neynar.com/app](https://dev.neynar.com/app) and then click on the app. - -Copy the url under **Mini app Notifications**. - - -![neynar webhook url](/images/miniapps/neynar-notification-webhook.png) - - - - - -Paste the url you copied from the **Mini app Notifications** field in the step above into the `webhookUrl` field in the `miniapp` object inside your manifest. - -Here's an example manifest with the updated `webhookUrl` field: -```json highlight={14} -{ - "accountAssociation": { - "header": "eyJmaWQiOjE5MSwidHlwZSI6ImN1c3RvZHkiLCJrZXkiOiIweDNhNmRkNTY5ZEU4NEM5MTgyOEZjNDJEQ0UyMGY1QjgyN0UwRUY1QzUifQ", - "payload": "eyJkb21haW4iOiIxYmNlLTczLTcwLTE2OC0yMDUubmdyb2stZnJlZS5hcHAifQ", - "signature": "MHg1ZDU1MzFiZWQwNGZjYTc5NjllNDIzNmY1OTY0ZGU1NDMwNjE1YTdkOTE3OWNhZjE1YjQ5M2MxYWQyNWUzMTIyM2NkMmViNWQyMjFhZjkxYTYzM2NkNWU3NDczNmQzYmE4NjI4MmFiMTU4Y2JhNGY0ZWRkOTQ3ODlkNmM2OTJlNDFi" - }, - "miniapp": { - "version": "4.2.0", - "name": "Your Mini App Name", - "iconUrl": "https://your-miniapp-domain.com/icon.png", - "splashImageUrl": "https://your-miniapp-domain.com/splash.png", - "splashBackgroundColor": "#f7f7f7", - "homeUrl": "https://your-miniapp-domain.com", - "webhookUrl": "https://api.neynar.com/f/app/3c274018-6402-4a47-96bbg-1fea72afc408/event" - } -} -``` - - -Caching: The Base App might have your mini app manifest cached. To make sure all changes have taken effect, repost your application to the Base App. - - - -Test your Mini App in [Base Build](https://base.dev/preview) using the Preview tool. Once signed in, paste your app's URL in the `App URL` field and click the `Submit` button. - - - - - -## Prompt Users to Add Your App -To send notifications to users, they must first add your app. - - - - -```shell terminal -npm install @neynar/react -``` - - - - - -Use the `addMiniApp()` hook to prompt users to add your Mini App. - -Neynar will manage all [notification events](/mini-apps/core-concepts/notifications#events) which tell your app when a user has enabled or disabled notifications for your mini app. - -To confirm that the mini app was added and notifications were enabled, check `result.added` is true and `result.notificationDetails` is a valid object. - -```javascript app/page.tsx -import { useMiniApp } from '@neynar/react'; - -export default function HomePage() { - const { isSDKLoaded, addMiniApp } = useMiniApp(); - - const handleAddMiniApp = async () => { - if (!isSDKLoaded) return; - - const result = await addMiniApp(); - if (result.added && result.notificationDetails) { - // Mini app was added and notifications were enabled - console.log('Notification token:', result.notificationDetails.token); - } - }; - - return ( - - ); -} -``` - - - - -## Send Notifications to Users - -Neynar makes it easy to send notifications to all users who have enabled notifications or to a subset based on filter criteria you define. - -### Option 1: API - -You can programmatically send notifications using the Neynar API. This gives you full control over targeting and filtering users. - - - - -Install the [@neynar/nodejs-sdk](https://github.com/neynarxyz/nodejs-sdk) package: - -```shell -npm install @neynar/nodejs-sdk -``` - - - - -Create a reusable function to send notifications with targeting and filtering capabilities: - -```javascript lib/sendNotification.js -import { NeynarAPIClient } from "@neynar/nodejs-sdk"; - -const client = new NeynarAPIClient(process.env.NEYNAR_API_KEY); - -/** - * Send a notification to mini app users - * @param {number[]} targetFids - Array of FIDs to target (empty array = all users with notifications enabled) - * @param {Object} filters - Optional filters to narrow down recipients - * @param {Object} notification - Notification content and target URL - */ -export async function sendNotification(targetFids, filters, notification) { - try { - const response = await client.publishFrameNotifications({ - targetFids, - filters, - notification, - }); - - return { - success: true, - data: response, - }; - } catch (error) { - console.error("Failed to send notification:", error); - return { - success: false, - error: error.message, - }; - } -} -``` - - - - -Use the function to broadcast notifications with advanced filtering criteria: - -```javascript sendNotificationsAdvanced.ts -import { sendNotification } from './lib/sendNotification'; - -// Define target FIDs (empty array targets all users with notifications enabled) -const targetFids = []; - -// Define filters to narrow down recipients -const filters = { - exclude_fids: [420, 69], // Exclude specific FIDs - following_fid: 3, // Only send to users following this FID - minimum_user_score: 0.5, // Only send to users with score >= this value - near_location: { // Only send to users near a specific location - latitude: 34.052235, - longitude: -118.243683, - radius: 50000, // Distance in meters (optional, defaults to 50km) - } -}; - -// Define notification content -const notification = { - title: "🪐", - body: "It's time to savor farcaster", - target_url: "https://your-miniapp-domain.com/notification-destination", -}; - -// Send the notification -const result = await sendNotification(targetFids, filters, notification); - -if (result.success) { - console.log("Notification sent successfully:", result.data); -} else { - console.error("Failed to send notification:", result.error); -} -``` - - -The `target_fids` parameter is the starting point for all filtering. Pass an empty array to target all users with notifications enabled, or specify FIDs to target specific users. - - - - -### Option 2: Neynar UI - -The [Neynar dev portal](https://dev.neynar.com) offers the same functionality as the API for broadcasting notifications. Navigate to your app and click the "Mini App" tab. Once your mini app is configured with your Neynar webhook URL and users have enabled notifications for your mini app, you'll see a "Broadcast Notification" section with an expandable filters section. - - - - -https://dev.neynar.com/home - - - - -![select app in neynar dev portal](/images/miniapps/neynar-select-app.png) - - - - - -![select app in neynar dev portal](/images/miniapps/neynar-mini-app-tab.png) - - - - - -![select app in neynar dev portal](/images/miniapps/neynar-send-notification.png) - -The `target_fids` parameter is the starting point for all filtering. Pass an empty array for `target_fids` to start with the set of all FIDs with notifications enabled for your app, or manually define `target_fids` to list specific FIDs. - - - - -Once you have filled in the notification details and applied any filtering, broadcast your notification by clicking the broadcast button at the bottom of the page. - - - - - - -Additional documentation on the API and its body parameters can be found at [publish-miniapp-notifications](https://docs.neynar.com/reference/publish-frame-notifications). diff --git a/docs/apps/technical-guides/sharing-and-social-graph.mdx b/docs/apps/technical-guides/sharing-and-social-graph.mdx deleted file mode 100644 index 57f612ed2..000000000 --- a/docs/apps/technical-guides/sharing-and-social-graph.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -hidden: true -title: Sharing & Social Graph -description: Enable native share flows and social navigation ---- - -## Adding Share Functionality - -Prompt users to share during key accomplishment moments using MiniKit’s compose hook. - -```ts ComposeCastButton.tsx -import { useComposeCast } from '@coinbase/onchainkit/minikit'; - -export default function ComposeCastButton() { - const { composeCast } = useComposeCast(); - - const handleCompose = () => { - composeCast({ text: 'Just minted an awesome NFT!' }); - }; - - const handleComposeWithEmbed = () => { - composeCast({ - text: 'Check out this amazing Mini App!', - embeds: ['https://your-mini-app-url.com'], - }); - }; - - return ( -
- - -
- ); -} -``` - - -Strategic sharing moments include: post‑achievement, post‑mint, after beating a challenge, or reaching milestones. - - -## View Casts and Profiles - -Link users into casts and profiles directly from your app via MiniKit hooks. - - - - - - -## Best Practices - -- Encourage meaningful, contextual shares -- Avoid spammy prompts; tie sharing to value -- Make shared previews visually consistent with your UI - -Further reading: - -- [Embeds & Previews](/mini-apps/core-concepts/embeds-and-previews) - - - diff --git a/docs/apps/technical-guides/sign-manifest.mdx b/docs/apps/technical-guides/sign-manifest.mdx deleted file mode 100644 index 7a44ccbd5..000000000 --- a/docs/apps/technical-guides/sign-manifest.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -hidden: true -title: Sign Your Manifest -description: Learn what a Mini App manifest is, why signing it matters, and how to generate and add an account association to your app. ---- - -Every Mini App needs a **manifest** (`farcaster.json`) file to be recognized by Farcaster clients. It declares your app’s details and domain, and when signed, produces an **Account Association** that proves your Farcaster account owns and can publish the app. Without it, your app won’t work as a Mini App. - -### Prerequisites - - - A deployed App, accessible via HTTPS - - A Base app account - -## Location -Your manifest file must be publicly accessible at: -`https://your-domain.com/.well-known/farcaster.json` - - - Want to learn more about manifests? 👉 Check out our [Manifest guide](/mini-apps/features/manifest). - - -## Sign Your Manifest - -There are two supported ways to sign and generate your manifest: - - - - - ## Option 1: Base Build Preview Tool - - 1. Visit **[Base.dev](https://base.dev)** and sign in with your Base account. - 2. Open **Preview → Account Association**. - 3. Enter your Mini App domain in the App URL field. - 4. Click **Submit**. You should see a notification that you should verify your app ownership. Click **Verify → Sign**. - 5. Follow the on-screen instructions to sign the message in your wallet. - 6. Click **Copy** to copy the generated `accountAssociation` object. - 7. Paste it into your project’s `farcaster.json` under `accountAssociation`. - 8. Redeploy your application to production. - - You should now see three green check marks indicating successful signing. - - Main dashboard interface - - - - - - ## Option 2: Farcaster Manifest Tool - - 1. Go to **[farcaster.xyz](https://farcaster.xyz)** and log in. - 2. Navigate to **Developers → Manifest Tool**. - 3. Enter your domain (exclude `https://` and trailing slashes). - 4. Click **Refresh** to fetch your app. - 5. Select **Generate Account Association**. - 6. Copy the generated object. - 7. Paste it into your project’s `farcaster.json` under `accountAssociation`. - 8. Redeploy your application to production. - - You should now see green check marks indicating successful signing. - - Main dashboard interface - - - -## Example Manifest - - -Here’s a simplified example of what a `farcaster.json` could look like from the [Base Camp Mini App](https://basecamp25.app/.well-known/farcaster.json): - -```json -{ - "accountAssociation": { - "header": "", - "payload": "", - "signature": "" - }, - "miniapp": { - "version": "1", - "name": "Basecamp 2025", // App name - "description": "Access and manage your experience @ Basecamp", - "iconUrl": "https://basecamp25.app/icon.png", // App icon - "homeUrl": "https://basecamp25.app", // Landing page - "canonicalDomain": "basecamp25.app", // Must match your domain - "requiredChains": ["eip155:8453"], // Chains your app supports - "tags": ["basecamp", "miniapp"], // Optional tags - "requiredCapabilities": [ // Capabilities your app needs - "actions.ready", - "actions.signIn" - ] - } -} -``` - - diff --git a/docs/apps/troubleshooting/base-app-compatibility.mdx b/docs/apps/troubleshooting/base-app-compatibility.mdx deleted file mode 100644 index e432fc9e8..000000000 --- a/docs/apps/troubleshooting/base-app-compatibility.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -hidden: true -title: Base App Compatibility -description: Build Mini Apps with features that work seamlessly across the Base App and Farcaster. ---- - -Base App is working towards full compatibility with the Farcaster Mini App SDK. During beta, some features are not yet supported. - -## Currently Unsupported -- [`signManifest` (experimental)](https://miniapps.farcaster.xyz/docs/sdk/actions/sign-manifest) - -## Base app Mini App SDK Supported Features -- [Quick Auth](https://miniapps.farcaster.xyz/docs/sdk/actions/quick-auth) -- [addMiniApp](https://miniapps.farcaster.xyz/docs/sdk/actions/add-miniapp) -- [close](https://miniapps.farcaster.xyz/docs/sdk/actions/close) -- [composeCast](https://miniapps.farcaster.xyz/docs/sdk/actions/compose-cast) -- [ready](https://miniapps.farcaster.xyz/docs/sdk/actions/ready) -- [openUrl](https://miniapps.farcaster.xyz/docs/sdk/actions/open-url) -- [openMiniApp](https://miniapps.farcaster.xyz/docs/sdk/actions/open-miniapp) -- [signIn](https://miniapps.farcaster.xyz/docs/sdk/actions/sign-in) -- [viewProfile](https://miniapps.farcaster.xyz/docs/sdk/actions/view-profile) -- [viewCast](https://miniapps.farcaster.xyz/docs/sdk/actions/view-cast) -- [swapToken](https://miniapps.farcaster.xyz/docs/sdk/actions/swap-token) -- [sendToken](https://miniapps.farcaster.xyz/docs/sdk/actions/send-token) -- [viewToken](https://miniapps.farcaster.xyz/docs/sdk/actions/view-token) -- [requestCameraAndMicrophoneAccess](https://miniapps.farcaster.xyz/docs/sdk/actions/request-camera-and-microphone-access) -- [Haptics](https://miniapps.farcaster.xyz/docs/sdk/haptics) - -## Base App Client Detection -To detect if the app is running in the Base App, you can use the `clientFid` property of the `context` object. - -```tsx App.tsx -import { sdk } from '@farcaster/miniapp-sdk'; - -function MyComponent() { - const isBaseApp = sdk.context.client.clientFid === 309857; - - if (isBaseApp) { - // Use Base App-specific features - console.log('Running in Base App'); - } - - return
{/* Your component */}
; -} -``` - -## Supported Chains - -- Base -- Mainnet -- Optimism -- Arbitrum -- Polygon -- Zora -- BNB -- Avalanche C‑Chain - - -We are actively expanding compatibility and will update this page as support increases. - - - diff --git a/docs/apps/troubleshooting/common-issues.mdx b/docs/apps/troubleshooting/common-issues.mdx deleted file mode 100644 index 826fc341d..000000000 --- a/docs/apps/troubleshooting/common-issues.mdx +++ /dev/null @@ -1,243 +0,0 @@ ---- -hidden: true -title: Common Issues & Debugging -description: Frequent issues encountered during Mini App development and their solutions ---- - -## Prerequisites & Setup Verification - -Ensure your Mini App has the foundational requirements in place. - -### Required Files and Structure - -```text -your-domain.com/ -├── .well-known/ -│ └── farcaster.json # Required manifest file -├── your-app/ -│ ├── index.html # Your app entry point -│ └── ... # Your app files -``` - -### Environment Setup Checklist - -- Domain is accessible via HTTPS -- Manifest file exists at `/.well-known/farcaster.json` -- All image URLs are publicly accessible - -# Debugging -Use Base Build's built-in Preview Tool for foundational debugging. - - -Start debugging your app using the [Preview tool](https://base.dev/preview) - - -The **Preview tool** will help you: - -- Validate your app's manifest and metadata -- Test how your app will appear in the Base app -- Verify ownership and account association - -The Preview tool provides clear visual cues: -- ✅ Green check marks when things are set up correctly -- ❌ Red indicators when something needs your attention - -### Components of the Preview Tool - -The Preview tool has three main components: - -- **Console**: Preview your app and review logs to make informed decisions about performance. -- **Account Association**: Confirm your app is linked to the correct account, signatures are valid, and the domain matches what’s specified in the manifest. -- **Metadata**: Ensure your Mini App renders exactly as expected by verifying required fields like name, icon, tags, and splash image. - - -### Basic Validation Steps - -1. Test manifest accessibility: visit `https://yourdomain.com/.well-known/farcaster.json` -2. Validate JSON syntax with JSONLint -3. Ensure your app loads without console errors - -## Quick Diagnostic Workflow - -The best way to validate your app works is by using Base Build's built-in [Preview tool](https://base.dev/preview) - -- Not appearing in search? → App Discovery & Indexing Issues -- Not rendering as an embed? → Embed Rendering Issues -- Wallet connection problems? → Wallet Connection Problems -- Need mobile testing tools? → Mobile Testing & Debugging -- Changes not appearing? → Manifest Configuration Problems -- App closes on gestures? → Gesture Conflicts and App Dismissal Issues - -## Detailed Problem Solutions - -### 1. App Discovery & Indexing Issues - -Problem: Your Mini App doesn't appear in search results or app catalogs. - -Root cause: Missing or incomplete manifest configuration. - -Solution: Ensure your manifest includes all required fields (see Manifest feature guide). - -Critical requirements: - -- `primaryCategory` is required for searchability and category pages -- `accountAssociation` is required for verification - -App Indexing Requirements: - -1. Complete your manifest setup -2. Share your Mini App URL in a post -3. Indexing can take up to 10 minutes -4. Verify appearance in app catalogs - -Caching Issues — Changes Not Appearing: - -Farcaster clients may cache manifest data for up to 24 hours. Re‑share to trigger a refresh and allow ~10 minutes. - -### 2. Manifest Configuration Problems - -Image Display Issues: - -1. Test image accessibility in incognito -2. Verify image format (PNG, JPG, WebP supported) -3. Check dimensions -4. Ensure HTTPS URLs only - -### 3. Embed Rendering Issues - -Problem: Your Mini App URL doesn't render as a rich embed when shared. - -Root cause: Incorrect or missing `fc:miniapp` metadata. - -Solution: Use `name="fc:miniapp"` meta tag in `` and validate using the Embed Tool. - -### 4. Wallet Connection Problems - -Always use the user's connected wallet for optimal experience. You can do this using Wagmi hooks. Below is an example: - -```tsx App.tsx -import { useAccount } from 'wagmi'; - -function MyComponent() { - const { address, isConnected } = useAccount(); - - const walletConnected = isConnected; - - const userAddress = address; // Cryptographically verified - - return ( -
- {walletConnected && ( -

Wallet: {userAddress}

- )} - {/* Use wallet data for secure operations */} -
- ); -} -``` - - - -### 5. Gesture Conflicts and App Dismissal Issues - -Disable native gestures when calling ready if you use swipe/drag interactions: - -```ts App.tsx -await sdk.actions.ready({ disableNativeGestures: true }); -``` - -### 6. Mobile Testing & Debugging - -**Eruda Mobile Console Setup:** - -Add Eruda for mobile console debugging during development: - -```tsx App.tsx -import { useEffect } from 'react'; - -export default function App() { - useEffect(() => { - // Only load Eruda in development and not on localhost - if (typeof window !== 'undefined' && - process.env.NODE_ENV === 'development' && - !window.location.hostname.includes('localhost')) { - import('eruda').then((eruda) => eruda.default.init()); - } - }, []); - - return ( -
- {/* Your app content */} -
- ); -} -``` - -**Mobile Testing Workflow:** - -1. Deploy to production or use ngrok for local testing -2. Share the mini app in a Farcaster DM to yourself -3. Open in mobile client (Base App, Farcaster) -4. Use Eruda console for debugging on mobile -5. Test across multiple clients for compatibility - -**Testing Checklist:** - -- [ ] App loads correctly on mobile devices -- [ ] Touch interactions work properly -- [ ] Viewport is correctly sized -- [ ] Images load and display correctly -- [ ] Console shows no critical errors - -### 7. Your app is being flagged as unsafe? - -Base Account relies on the [Blockaid](https://blockaid.io/) platform to flag apps as unsafe. -If your app is being flagged as unsafe or if you are concerned about your app being flagged as unsafe, you can follow the steps below to resolve the issue: - -1. Navigate to [Blockaid Reporting Portal](https://report.blockaid.io/). -2. Submit a "mistake" or "developer" report. -3. Follow the instructions provided by Blockaid to resolve the issue. -4. If you are unable to resolve the issue, you can contact the Base core team on [Discord](https://discord.com/invite/buildonbase) for support. - - -## Advanced Troubleshooting - -**CBW Validator Tool:** - -Use the Coinbase Wallet validator for Base App compatibility analysis. This AI-powered tool can identify unsupported patterns and suggest improvements. - -**Complete Manifest Example:** - -```json farcaster.json -{ - "accountAssociation": { - "header": "your-farcaster-header", - "payload": "your-farcaster-payload", - "signature": "your-farcaster-signature" - }, - "frame": { - "name": "Your Mini App", - "iconUrl": "https://yourapp.com/icon.png", - "homeUrl": "https://yourapp.com", - "imageUrl": "https://yourapp.com/og.png", - "buttonTitle": "Launch App", - "description": "Your app description under 130 characters", - "primaryCategory": "social", - "tags": ["tag1", "tag2"] - } -} -``` - -## Success Verification - -Basic functionality and discovery/sharing checklists: confirm load, images, wallet, manifest endpoint, embed rendering, and search presence. - -## Getting Additional Help - -- [Base Build Preview Tool](https://base.dev/preview) -- JSONLint -- [Eruda](https://github.com/liriliri/eruda) -- Base Discord — #minikit channel - - - diff --git a/docs/apps/troubleshooting/error-handling.mdx b/docs/apps/troubleshooting/error-handling.mdx deleted file mode 100644 index 78a37725a..000000000 --- a/docs/apps/troubleshooting/error-handling.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -hidden: true -title: Error Handling -description: Patterns for surfacing and resolving common runtime errors in Mini Apps ---- - -TODO: Provide guidance on handling errors from hooks, network issues, and manifest/metadata failures. - - diff --git a/docs/apps/troubleshooting/how-search-works.mdx b/docs/apps/troubleshooting/how-search-works.mdx deleted file mode 100644 index 9078a4cc1..000000000 --- a/docs/apps/troubleshooting/how-search-works.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -hidden: true -title: How Search works -description: If your Mini App isn't appearing in the Base app, this guide explains how indexing and search work so you can identify and fix the issue. ---- -Indexing is how The Base app adds your Mini App to its catalog, making it discoverable through search and browsing. -Unlike traditional app stores with manual submission, you control when indexing happens. Share your Mini App URL to the social feed, and indexing starts automatically—no review process required. - -## How indexing works - -Understanding the indexing process helps you diagnose why your Mini App may not be appearing. - - -Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. - - - - - Share your URL to the feed. - - - The Base app fetches and validates your manifest file. - - Invalid or unreachable manifests will fail indexing. - - - - Your Mini App is recorded and becomes searchable within 10 minutes. - - - - -## How search works -The Base App's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. - - -search bar in the Base app - - - -When making changes to your manifest, you will need to share your URL to reindex. - - -## Discovery surfaces - -### Category browsing -Your app appears in the category specified by `primaryCategory` in your manifest. Users browse categories to discover apps by interest. - - -app categories - - - -**Category rankings**: Rankings use 7-day engagement metrics such as shares. - - -### Saved apps -When users save your Mini App, it appears in their personal saved options for quick access. Prompt users to save at key moments. - - -saved apps - - -### Direct messages - -When users share your Mini App URL in a direct message, it displays as an interactive embed. Recipients can preview and open your app directly from the conversation, with `context.location` set to `messaging` so you can customize the experience for shared discovery. - -## Related - - - - Configure name and metadata for indexing. - - - Add required embed metadata. - - - Complete debugging guide. - - - diff --git a/docs/apps/troubleshooting/testing.mdx b/docs/apps/troubleshooting/testing.mdx deleted file mode 100644 index 0c1dfd4d4..000000000 --- a/docs/apps/troubleshooting/testing.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -hidden: true -title: Test Your App -description: Confidently test your app before going live in the Base app ---- - -Testing your mini app before launch ensures it functions correctly, displays properly, and provides the user experience you intended. You can test your app using a few different methods, each suited for different stages of development and testing needs. The only requirement is to have your mini app publicly accessible URL via `https://`. - -## Base Build Preview Tool - -Preview and debug your mini app to ensure it displays correctly in the Base App using the [Preview Tool.](https://www.base.dev/preview) - - -Your browser's console won't show Base-specific logs. Base.dev console provides logs specific to how your mini app works within the Base app, including user context and Base app-specific functionality. - - -### Best for - - * Validating correctness of manifest files and required fields -* Using an interactive console for viewing logs -* Signing your app's manifest - -### Not ideal for testing -* Full look and feel on your app in Base app -* Chat and Base app specific functionality -* User context functionality - -### Steps - -1. Navigate to [Base.dev/preview](https://www.base.dev/preview) -2. Log in using your Base app account -3. Paste your app's url in the field -4. Click `Submit` - -## Base app - -Preview how your app would function directly using the Base App. - -### Best for - -* Keeping your app private from the feed -* Preview in-app functionality (UX) -* Chat-based applications -* Apps that require user and Base app context - -### Not ideal for testing - -* Logs -* Validating correctness of manifest file - -### Steps - -1. Enable Developer Mode: **Open Base App > Privacy & Security > toggle Developer Mode** -2. Open preview: **Settings > Developer > Preview** -3. Enter the URL of your mini app -4. Click `Preview` - -## In-feed and DMs - -Preview your app by posting the URL directly in the Base app feed or by sending a DM to another user. - -### Best for - -* Requesting feedback from the public -* Apps that require user and Base app context -* Testing edge cases - -### Not ideal for - -* Viewing logs -* Validating correctness of manifest file - -### Steps - -1. Open [Base app](https://join.base.app/) -2. Share your mini app URL by: - - Posting it in the Base app feed, or - - Sending it in a DM to someone or a group chat