Getting Started with Expo

Build a native iOS/Android app with StarkNet wallets using Expo and the @chipi-stack/chipi-expo package. Users create wallets with Face ID or fingerprint. No extensions, no seed phrases. The Expo package provides the same React hooks as the web packages, optimized for mobile. All transactions are gasless.

Create an Expo project and install the Chipi SDK:

bashnpx create-expo-app@latest my-app --template tabs
cd my-app
npx expo install @chipi-stack/chipi-expo@latest

Use npx expo install instead of npm install. It resolves compatible native module versions automatically.

Chipi ties each wallet to an authenticated user. Install your auth provider:

• - Clerk (recommended): npx expo install @clerk/clerk-expo. Mobile-optimized auth
• - Firebase: npx expo install @react-native-firebase/auth. Google's auth platform
• - Supabase: npx expo install @supabase/supabase-js. Open-source auth

Each authenticated user gets their own self-custody wallet linked to their auth session.

Wrap your app with ChipiProvider in App.tsx (or your root layout):

tsx// App.tsx
import { ClerkProvider } from "@clerk/clerk-expo";
import { ChipiProvider } from "@chipi-stack/chipi-expo";

export default function App() {
  return (
    <ClerkProvider publishableKey={process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!}>
      <ChipiProvider>
        <RootNavigator />
      </ChipiProvider>
    </ClerkProvider>
  );
}

Use the MCP tool get_component_code("chipi-providers") for the exact wrapper matching your auth setup.

Create a .env file in the project root:

bash# Chipi API key. From dashboard.chipipay.com
EXPO_PUBLIC_CHIPI_API_KEY=pk_prod_YOUR_KEY

# Clerk auth (or your provider)
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_YOUR_CLERK_KEY

Expo uses the EXPO_PUBLIC_ prefix for client-accessible variables. Secret keys (sk_prod_) should live on your backend server, not in the mobile app.

Use the CreateWalletDialog component for the wallet creation flow. Get the full code via the MCP:

get_component_code("create-wallet-dialog")

Defaults:

• - walletType: "CHIPI". Chipi's own account contract with session key support
• - usePasskey: true. Biometric authentication (Face ID, Touch ID, fingerprint)

On mobile, the passkey prompt uses the device's native biometric UI. Users see a familiar Face ID or fingerprint dialog. No custom UI needed.

Wire the wallet screen with useChipiWallet:

tsximport { useChipiWallet } from "@chipi-stack/chipi-expo";

function WalletScreen() {
  const { wallet, hasWallet, formattedBalance } = useChipiWallet({
    externalUserId: user.id,
    getBearerToken: async () => process.env.EXPO_PUBLIC_CHIPI_API_KEY!,
  });

  if (!hasWallet) return <CreateWalletDialog />;
  return (
    <View>
      <WalletSummary wallet={wallet} />
      <SendUsdcDialog wallet={wallet} />
    </View>
  );
}

The hooks API is identical to the web packages. Only the import path changes. Update imports to use @chipi-stack/chipi-expo.

• - Biometric prompts: Face ID / fingerprint dialogs are system-level. They appear over your app and cannot be styled. Users are familiar with this pattern
• - Keyboard handling: When entering transfer amounts or addresses, use KeyboardAvoidingView to prevent the keyboard from covering inputs
• - Deep linking: For external wallet payments, configure deep links to return users to your app after checkout
• - Offline behavior: Wallet creation and transfers require network. Show appropriate loading states

Start with:

bashnpx expo start

Test on a physical device for the full biometric experience. Simulators support passkeys but the UX differs.