> ## 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 web app.

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

## Basic setup

The basic Portal setup consists of a single packages:

* `@portal-hq/web` - The core Portal library

This allows you to initialize `Portal` in your app. We recommend only initializing one Portal instance per user.

### 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/web
    ```
  </Tab>

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

### Update TSConfig

The Web SDK uses the [TSConfig `lib` configuration](https://www.typescriptlang.org/tsconfig#lib) to properly type interaction with the DOM. Update your TSConfig file to include this:

```
// tsconfig.json
{
  "compilerOptions": {
    "lib": ["es2022", "dom"],
    ...
  },
  ...
}
```

### Initializing Portal

When `rpcConfig` is omitted, the SDK automatically generates gateway URLs for 13 built-in chains. The gateway host defaults to `web.portalhq.io`, and derives from `host` (or `gatewayHost`) when you set a custom subdomain. No third-party RPC provider setup is required.

```typescript theme={null}
import Portal from '@portal-hq/web'

// Minimal setup — Portal gateway handles RPC for 13 built-in chains automatically.
export const portal = new Portal({
    apiKey: 'YOUR-CLIENT-API-KEY',
    host: 'YOUR-CUSTOM-SUBDOMAIN', // Set this once you've defined your custom subdomain
    // logLevel: 'debug', // optional: 'none' (default), 'error', 'warn', 'info', or 'debug'
    // logger: console,    // optional: custom ILogger
})
```

If your app needs chains beyond the 13 built-in ones (e.g. Tron, AVAX Fuji), use `buildDefaultRpcConfig` to start from the default set and extend it:

```typescript theme={null}
import Portal, { buildDefaultRpcConfig } from '@portal-hq/web'

export const portal = new Portal({
    apiKey: 'YOUR-CLIENT-API-KEY',
    host: 'YOUR-CUSTOM-SUBDOMAIN',
    rpcConfig: {
      ...buildDefaultRpcConfig('YOUR-CUSTOM-SUBDOMAIN'),
      'tron:mainnet': 'https://YOUR-CUSTOM-SUBDOMAIN/rpc/v1/tron/mainnet',
    },
})
```

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

<Warning>
  We recommend only initializing one Portal instance per user. Do **not** modify **`portal.apiKey`** directly.
</Warning>

You can enable logging for debugging and monitoring by setting the `logLevel` parameter. For full logging configuration, including custom loggers and runtime level changes, see [Logging Configuration](./logging).

<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>

### Custom Subdomain

In order to support usage on Safari or other browsers with third-party cookie restrictions, you need to configure a custom subdomain for the Portal Web API.

Follow the instructions in our [configure-a-custom-subdomain.md](./configure-a-custom-subdomain) guide to complete setup for the Web SDK!

### Web SDK Architecture

The Web SDK leverages our [Enclave MPC API](../../../apis/enclave-mpc/guide/getting-started) for efficient MPC operation performance. Utilizing confidential computing using [AWS Nitro Enclaves](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html), the Enclave MPC API provides the same MPC client-server distribution of responsibilities with the speed and efficiency of server side compute.