> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Follow this guide to integrate Portal in your React Native app.

Portal provides MPC **wallets** and dApp **connections** for organizations and their users.\
\
To integrate Portal, an organization adds a **client library** to their mobile app and a few **server API endpoints**.

## Basic setup

The basic Portal setup consists of three packages:

* `@portal-hq/core` - The core Portal library
* `@portal-hq/keychain` - An adapter for storing MPC signing shares on-device
* `@portal-hq/gdrive-storage` - An adapter for storing MPC backup shares off-device

These pieces allow you to initialize `Portal` in your app.

### Authentication

Follow this guide to gather all of the credentials you need to [Authenticate to Portal](../../../resources/authentication-and-api-keys).

## Installation <a href="#installation" id="installation" />

<Tabs>
  <Tab title="yarn">
    ```bash theme={null}
    yarn add @portal-hq/core @portal-hq/keychain @portal-hq/gdrive-storage
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install --save @portal-hq/core @portal-hq/keychain @portal-hq/gdrive-storage
    ```
  </Tab>
</Tabs>

#### Dependency linking

Because these packages have native module dependencies there is some additional linking required to make it work with your React Native project.

Explicitly install the native module packages in your project.

<Tabs>
  <Tab title="yarn">
    ```bash theme={null}
    yarn add react-native-keychain
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install --save react-native-keychain react-native-rsa-native
    ```
  </Tab>
</Tabs>

#### MPC

The core Portal library relies on a native module to support MPC behaviors. In order to enable this functionality, you must properly link Portal's MPC client to your React Native project.

<Tabs>
  <Tab title="Android">
    ```java theme={null}
    dependencies {
      ...

      runtimeOnly files("../../node_modules/@portal-hq/core/android/libs/mpc.aar")

      ...
    }
    ```
  </Tab>

  <Tab title="iOS">
    ```
    cd ios && pod install && cd ..
    ```
  </Tab>
</Tabs>

*To learn more about how to use Portal MPC, see:* [*@portal-hq/core*](../reference/core#mpc)

### Initializing Portal

When `gatewayConfig` is omitted, the SDK automatically routes RPC traffic through Portal's managed gateway for 10 built-in chains. No third-party RPC provider setup is required to get started.

```typescript theme={null}
import { useEffect, useState } from 'react'

// Portal imports
import { BackupMethods, Portal, PortalContextProvider } from '@portal-hq/core'
import Keychain from '@portal-hq/keychain'
import GoogleDriveStorage from '@portal-hq/gdrive-storage'
import { PasswordStorage } from '@portal-hq/utils/src/definitions'

const MyAppComponent = () => {
  // Store the Portal instance in the state
  const [portal, setPortal] = useState<Portal>(null)

  useEffect(() => {
    if (!portal) {
      // Initialize backup storage providers.
      const gDriveStorage = new GoogleDriveStorage({
        androidClientId: 'YOUR_ANDROID_CLIENT_ID',
        iosClientId: 'YOUR_IOS_CLIENT_ID',
      })
      const passwordStorage = new PasswordStorage()

      // Create a Portal instance — Portal gateway handles RPC for 10 built-in chains automatically.
      setPortal(
        new Portal({
          autoApprove: true, // If you want to auto-approve transactions
          apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
          backup: {
            [BackupMethods.GoogleDrive]: gDriveStorage,
            [BackupMethods.Password] : passwordStorage
          },
          // Optional: Override the default gateway for specific chains, or add chains beyond the built-in 10
          // gatewayConfig: { 'eip155:1': 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY' },
          // Optional: Enable logging for debugging and monitoring
          // logLevel: 'debug', // 'none' (default), 'error', 'warn', 'info', or 'debug'
        }),
      )
    }
  }, [portal])

  return (
    {/* Expose your Portal instance to your app */}
    <PortalContextProvider value={portal as Portal}>
      {/**
        * Now all children rendered in this scope
        * will have access to the `Portal` instance
        * via the `usePortal` hook
        */}
    </PortalContextProvider>
  )
}

export default MyAppComponent
```

<Note>
  The 10 built-in chains covered by the default gateway config are: Ethereum Mainnet (`eip155:1`), Ethereum Sepolia (`eip155:11155111`), Polygon Mainnet (`eip155:137`), Polygon Amoy (`eip155:80002`), Base Mainnet (`eip155:8453`), Base Sepolia (`eip155:84532`), Monad Mainnet (`eip155:143`), Monad Testnet (`eip155:10143`), Solana Mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`), and Solana Devnet (`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`). Polygon Mumbai (`eip155:80001`) has been removed — use Polygon Amoy (`eip155:80002`) instead.
</Note>

#### Custom RPC configuration

If your app needs chains beyond the 10 built-in ones, or you prefer to use your own RPC provider, pass a `gatewayConfig` object. When provided, it is used exactly as supplied — the SDK does **not** merge defaults into a custom config.

```typescript theme={null}
import { buildDefaultGatewayConfig } from '@portal-hq/utils'

// Option 1: fully custom config (replaces defaults entirely)
new Portal({
  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
  backup: { /* ... */ },
  gatewayConfig: {
    'eip155:1': 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
    'eip155:137': 'https://polygon-mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
  },
})

// Option 2: start from the defaults and add additional chains
new Portal({
  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
  backup: { /* ... */ },
  gatewayConfig: {
    ...buildDefaultGatewayConfig('api.portalhq.io'),
    'eip155:42161': 'https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY', // Arbitrum
  },
})
```

<Note>
  Requests to Portal's managed gateway automatically include your `apiKey` as a Bearer token — no extra setup required. Custom RPC URLs (e.g. Infura, Alchemy) are called without it, since third-party providers require their own credentials.
</Note>

<Note>
  **Optional Logging Configuration**

  You can enable logging for debugging and monitoring by setting the `logLevel` parameter. For advanced logging configuration, including custom loggers and external service integration, see [Logging Configuration](./logging).

  ```typescript theme={null}
  new Portal({
    apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
    logLevel: __DEV__ ? 'debug' : 'error', // Debug in dev, errors in production
    backup: { /* ... */ },
  })
  ```
</Note>

*For more information on how to use the Portal class, see:* [*@portal-hq/core*](../reference/core)

## Next Steps

Now that you've initialized your Portal instance, you can [generate a wallet](./create-a-wallet)!

<Note>
  If you are using [Client Session Tokens (CSTs)](../../../resources/authentication-and-api-keys), this hint is for you.

  When your user's CST expires, all Portal SDKs will throw an error on the next MPC Operation the user makes (e.g. creating a wallet, backing up a wallet, recovering a wallet, or signing). That error will include a code **`SESSION_EXPIRED`** in the SDK methods, which you can use as an indicator to refresh your CST.
</Note>