Skip to main content
Opens another Mini App from within your Mini App.

​
Usage

import { sdk } from '@farcaster/miniapp-sdk'
 
// Open a Mini App using an embed URL
await sdk.actions.openMiniApp({
  url: 'https://www.bountycaster.xyz/bounty/0x983ad3e340fbfef785e0705ff87c0e63c22bebc4'
})
 
// Open a Mini App using a launch URL
await sdk.actions.openMiniApp({
  url: 'https://farcaster.xyz/miniapps/WoLihpyQDh7w/farville'
})

​
Parameters

​
domain

  • Type: string
The domain of the Mini App to open.

​
path (optional)

  • Type: string
An optional path to append to the Mini App’s home URL. ##Options 
type OpenMiniAppOptions = {
  url: string
}
  • url: The URL of the Mini App to open. This can be either:
    • A Mini App embed URL (e.g., https://example.com/specific-page)
    • A Mini App launch URL (e.g., https://farcaster.xyz/miniapps/[id]/[name])

​
Return Value

Promise<void> The promise resolves when navigation is successful. If navigation fails, the promise will be rejected with an error.

​
Error Handling

Always await the openMiniApp call and handle potential errors: 
import { sdk } from '@farcaster/miniapp-sdk'
 
try {
  await sdk.actions.openMiniApp({
    url: 'https://example.com/miniapp'
  })
  // Navigation successful - your app will close
} catch (error) {
  console.error('Failed to open Mini App:', error)
  // Handle the error - your app remains open
}

​
Referrer Information

When a Mini App is opened using openMiniApp, the target app receives a special location context with referrer information: 
// In the target Mini App:
if (sdk.context.location?.type === 'open_miniapp') {
 console.log('Referred by:', sdk.context.location.referrerDomain)
 // e.g., "Referred by: yourminiapp.com"
}

​
Use Cases

​
Hub or Portfolio Apps

Create a central hub that showcases multiple Mini Apps: 
const miniApps = [
  { name: 'Farville', url: 'https://farcaster.xyz/miniapps/WoLihpyQDh7w/farville' },
  { name: 'Bountycaster', url: 'https://www.bountycaster.xyz' },
  { name: 'Yoink', url: 'https://yoink.party/framesV2/' }
]
 
function MiniAppHub() {
  const handleOpenApp = async (url: string) => {
    try {
      await sdk.actions.openMiniApp({ url })
    } catch (error) {
      console.error('Failed to open app:', error)
    }
  }
 
  return (
    <div>
      {miniApps.map(app => (
        <button key={app.name} onClick={() => handleOpenApp(app.url)}>
          Open {app.name}
        </button>
      ))}
    </div>
  )
}

​
Referral Systems

Implement referral tracking between Mini Apps: 
// In the source Mini App
const referralUrl = 'https://partner-app.com/campaign?ref=myapp'
await sdk.actions.openMiniApp({ url: referralUrl })
 
// In the target Mini App
if (sdk.context.location?.type === 'open_miniapp') {
  // Track the referral
  analytics.track('referral_received', {
    referrer: sdk.context.location.referrerDomain,
    campaign: new URL(window.location.href).searchParams.get('ref')
  })
}

​
Notes

  • This will prompt the user to open the new app
  • The current Mini App will be closed when the new app is opened
  • There is no way to navigate back to the original app
  • The opened Mini App will receive a location.type of 'open_miniapp' with a referrerDomain indicating where the user came from