Skip to main content
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.

​
Installation 

yarn add @portal-hq/web

​
Update TSConfig

The Web SDK uses the TSConfig lib configuration 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. 
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: 
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',
    },
})
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.
We recommend only initializing one Portal instance per user. Do not modify portal.apiKey directly.
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.
If you are using Client Session Tokens (CSTs), 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.

​
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 guide to complete setup for the Web SDK!

​
Web SDK Architecture

The Web SDK leverages our Enclave MPC API for efficient MPC operation performance. Utilizing confidential computing using AWS Nitro Enclaves, the Enclave MPC API provides the same MPC client-server distribution of responsibilities with the speed and efficiency of server side compute.