# Installation

Add MoonPay Wallets authentication and embedded wallets to a native iOS or Android app with `@moon-x/react-native-sdk`.

The React Native SDK is **headless**: it provides hooks, session state, native passkey ceremonies, and wallet operations, while your app owns every screen. There is no drop-in modal or pre-built UI. If you are building for web browsers, use the [React SDK](/get-started/frontend-sdks/react/installation) instead.

## Requirements

* **React Native 0.78 or later** with the Hermes engine
* **React 18 or 19**
* **iOS 16 or later** and **Android 9 or later** (native passkeys require these OS versions)
* Expo (with prebuild / dev client) and bare React Native are both supported

## Install the SDK

:::code-group

```bash [npm]
npm install @moon-x/react-native-sdk@latest
```

```bash [pnpm]
pnpm install @moon-x/react-native-sdk@latest
```

```bash [yarn]
yarn add @moon-x/react-native-sdk@latest
```

:::

## Install peer dependencies

The SDK keeps native modules and crypto libraries as peer dependencies so your app controls their versions:

:::code-group

```bash [npm]
npm install react-native-webview react-native-passkeys @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill buffer bs58 viem
```

```bash [pnpm]
pnpm install react-native-webview react-native-passkeys @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill buffer bs58 viem
```

```bash [yarn]
yarn add react-native-webview react-native-passkeys @react-native-async-storage/async-storage react-native-get-random-values react-native-url-polyfill buffer bs58 viem
```

:::

| Peer dependency | Used for |
|---|---|
| `react-native-webview` | Hosts the SDK's secure context for key operations |
| `react-native-passkeys` | Native passkey ceremonies (iOS ASAuthorization, Android Credential Manager) |
| `@react-native-async-storage/async-storage` | Session persistence between launches |
| `react-native-get-random-values` | Secure randomness polyfill |
| `react-native-url-polyfill` | WHATWG URL polyfill |
| `buffer` | `Buffer` polyfill for encoding |
| `bs58` | Solana base58 encoding |
| `viem` | EVM types and utilities |

### OAuth login (optional)

Google and Apple login use the system browser and a deep link back into your app. If you enable OAuth, also install:

:::code-group

```bash [npm]
npm install expo-web-browser expo-linking
```

```bash [pnpm]
pnpm install expo-web-browser expo-linking
```

```bash [yarn]
yarn add expo-web-browser expo-linking
```

:::

### Solana support (optional)

If your app builds Solana transactions, install the Solana web3 library your app will use to construct them, for example `@solana/web3.js`.

### Tron support (optional)

If your app builds Tron transactions, install TronWeb; your app constructs transactions with its `TransactionBuilder` and the SDK signs them:

:::code-group

```bash [npm]
npm install tronweb
```

```bash [pnpm]
pnpm install tronweb
```

```bash [yarn]
yarn add tronweb
```

:::

## Add the polyfills

Import the polyfills at the very top of your app's entry file (`index.js`), before any other import:

```js [index.js]
import 'react-native-get-random-values';
import 'react-native-url-polyfill/auto';
import { Buffer } from 'buffer';

if (!global.Buffer) {
  global.Buffer = Buffer;
}
```

<Info>
  Hermes on React Native 0.71+ provides `atob`, `btoa`, and `TextEncoder` natively, so no additional encoding polyfills are needed.
</Info>

## Expo configuration

The SDK ships an Expo config plugin that writes the native passkey and OAuth configuration during `expo prebuild`:

```json [app.json]
{
  "expo": {
    "scheme": "myapp",
    "ios": {
      "bundleIdentifier": "com.example.myapp"
    },
    "android": {
      "package": "com.example.myapp"
    },
    "plugins": [
      [
        "@moon-x/react-native-sdk",
        {
          "passkeyDomains": ["signin.example.com"],
          "oauthRedirectScheme": "myapp"
        }
      ]
    ]
  }
}
```

Plugin options:

* `passkeyDomains`: domains for the iOS Associated Domains entitlement and Android asset statements. Must match the Relying Party ID configured in the MoonPay Wallets Dashboard.
* `oauthRedirectScheme`: the deep link scheme for OAuth callbacks. This adds the Android intent filter only; iOS gets its URL scheme from the top-level Expo `scheme` field, so set both to the same value. Only needed when using Google or Apple login.
* `passkeyDeveloperMode`: appends `?mode=developer` to the iOS entitlement for local development. Never enable in production builds.

Run `npx expo prebuild` after changing plugin options.

<Warning>
  The plugin configures your app binary, but passkeys also require association files hosted on your domain and Android signing fingerprints registered in the MoonPay Wallets Dashboard. Follow the [React Native Passkeys guide](/wallets/mobile-passkeys) for the complete platform setup; it is the canonical reference for iOS Associated Domains, Android Digital Asset Links, and signing fingerprints.
</Warning>

## Bare React Native

Without Expo prebuild, apply the same configuration by hand:

* Add the Associated Domains entitlement (iOS) and `asset_statements` metadata (Android) as described in the [React Native Passkeys guide](/wallets/mobile-passkeys).
* For OAuth, register your deep link scheme in `Info.plist` (iOS) and add an intent filter for it in `AndroidManifest.xml` (Android).

## Verify installation

```tsx
import { MoonXProvider } from '@moon-x/react-native-sdk';
```

If the import resolves, the SDK is installed. Next, [set up the provider](/get-started/frontend-sdks/react-native/setup).

## Next steps

* [Configure the MoonPay Wallets provider](/get-started/frontend-sdks/react-native/setup)
* [Build your first login and wallet flow](/get-started/frontend-sdks/react-native/quick-start)
* [Complete the passkey platform setup](/wallets/mobile-passkeys)