SDK Quick Starts

This quick start guide will get you up and running with any of the Portal SDKs.

Adding Portal to Your App

Portal offers SDKs for Web, iOS, Android, and React Native. To install the chosen Portal SDK in your app, simply add the Portal package to your project.

Web

yarn add @portal-hq/web

iOS

Using Swift Package Manager (SPM)

1. In Xcode, right-click on your project in the Project Navigator

2. Select "Add Packages..."

3. In the search field, enter either:

   • Package name: PortalSwift

   • Repository URL: https://github.com/portal-hq/PortalSwift

4. Select your desired version

5. Click "Add Package"

Using CocoaPods

1. Add the following line to your Podfile:

pod 'PortalSwift', :git => 'https://github.com/portal-hq/PortalSwift.git'

1. In Terminal, navigate to your project directory and run:

pod install

1. After installation:

   • Close your .xcodeproj file

   • Open the newly generated .xcworkspace file

   • ⚠️ Important: Always use the .xcworkspace file for development when using CocoaPods

Android

Update the dependencies in your app level build.gradle to include the portal-android dependency

implementation "io.portalhq.android:portal-android:X.X.X"

React Native

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 modules allow you to initialize Portal in your app.

yarn add @portal-hq/core @portal-hq/keychain @portal-hq/gdrive-storage

Authentication

The Portal SDK is initialized with a Client API Key or Client Session Token. You can get a test Client API Key from the Portal Admin Dashboard in the Settings -> Test Client API Keys section. Simply click the New + button.

A modal will then be presented, allowing you to copy your test Client API Key. You can repeat this process as many times as you need to.

Initializing Portal

To initialize Portal in your application, create a new instance of the Portal class included in the package dependency you added. You can provide your new test Client API Key as the apiKey argument during initialization. rpcConfig is a map of CAIP-2 Chain IDs to their respective RPC URLs.

Portal offers custom approval flows during the signing process, but for now, we can auto-approve all signatures with the autoApprove argument.

Web

import Portal from '@portal-hq/web'

const portal = new Portal({
    apiKey: 'YOUR_TEST_CLIENT_API_KEY',
    autoApprove: true,
    rpcConfig: {
      'eip155:11155111': 'YOUR-INFURA-OR-ALCHEMY-URL'
    },
})

iOS

import PortalSwift

let portal = Portal("YOUR_TEST_CLIENT_API_KEY", autoApprove: true)

Android

import io.portalhq.android.Portal

val portal = Portal("YOUR_TEST_CLIENT_API_KEY", autoApprove = true)

React Native

import Portal from '@portal-hq/core'

const portal = new Portal({
    apiKey: 'YOUR_TEST_CLIENT_API_KEY',
    autoApprove: true,
    gatewayConfig: {
      ['eip155:1']: 'https://api.portalhq.io/rpc/v1/eip155/1',
      ['eip155:11155111']: 'https://api.portalhq.io/rpc/v1/eip155/11155111',
      ['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp']: 'https://api.portalhq.io/rpc/v1/solana/5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
      ['solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1']: 'https://api.portalhq.io/rpc/v1/solana/EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
    },
})

Creating a Wallet

To create a new wallet you can use the createWallet() function. This function also offers an optional callback that can be provided to receive status updates during the MPC operation.

This function will create two wallets in the background, an EIP-155 wallet and a Solana wallet.

Web

const eip155Address = await portal.createWallet()

console.log(`My Portal E1P155 address: ${eip155Address}`)
console.log(`My Portal Solana address: ${await portal.getSolanaAddress()}`)

iOS

let addresses = try await portal.createWallet()

print("My Portal EVM address: \(addresses.ethereum)")
print("My Portal Solana address: \(addresses.solana)")

Android

val addresses = portal.createWallet()

println("My Portal EVM wallet: ${addresses.ethereumAddress}")
println("My Portal Solana wallet: ${addresses.solanaAddress}")

React Native

const addresses = await portal.createWallet()

console.log(`My Portal EVM address: ${addresses.eip155}`)
console.log(`My Portal Solana address: ${addresses.solana}`)

Submitting a Transaction

The Portal library has a Provider built-in, so signing transactions and making RPC calls is built into the library out-of-the-box. All of these actions can be handled by the request(chainId, method, params) function. The chainId will need to be a CAIP-2 compliant Chain ID.

For more info on Chain ID formatting, see this doc.

The return value of the request() function is largely dependent on the RPC method provided. In the case of signing a transaction, we can use the eth_sendTransaction RPC method for EVM (EIP-155) or the sol_signAndSendTransaction RPC method for Solana. This method will return a transaction hash.

Submitting an EVM Transaction

Web

const chainId = 'eip155:11155111' // Use Sepolia testnet

// Get your local EVM address
const address = await portal.getEip155Address()

// Build the transaction
const transaction = {
    to: '0xRecipientAddress',
    value: BigNumber.from('1').toHexString(),
    gasPrice: '0x6000',
    from: address,
}

// Sign the transaction
const txHash = await portal.request({
    method: 'eth_sendTransaction',
    params: [transaction], // RPC params are always expected to be an array
    chainId
})

console.log(`✅ Transaction hash: ${txHash}`)

iOS

let chainId = "eip155:11155111" // Use Sepolia testnet

// Get your local Ethereum address
guard let address = await portal.getAddress(chainId) else {
    // Handle a missing address here
    return
}

// Build the transaction
let transaction = [
    "from": address,
    "to": "0xRecipientAddress",
    "value": "0x10", // Native token amount to send (WEI for eip155:11155111).
]

// Sign the transaction
let response = try await portal.request(
    chainId,
    withMethod: .eth_sendTransaction,
    andParams: [transaction] // RPC params are always expected to be an array
)

// Obtain the transaction hash.
guard let txHash = response.result as? String else {
    // Handle a bad response here
    return
}

print("✅ Transaction hash: \(txHash)")

Android

val chainId = "eip155:11155111" // Use Sepolia testnet

// Get your local Ethereum address
val address = portal.getAddress(chainId)

// Build the transaction
val transaction = EthTransactionParam(
    from = address,
    to = "0xRecipientAddress",
    gas = "0x6000",
    gasPrice = null,
    maxFeePerGas = null,
    maxPriorityFeePerGas = null,
    value = "0x${BigInteger("1").toString(16)}",
    data = "",
)

// Sign the transaction
val response = portal.request(
    chainId, 
    PortalRequestMethod.eth_sendTransaction, 
    listOf(transaction), // RPC params are always expected to be a list
)

println("✅ Transaction hash: ${response.result}")

React Native

const SEPOLIA_USDC_TOKEN_ADDRESS = '0x419Fe9f14Ff3aA22e46ff1d03a73EdF3b70A62ED';

// Build the transaction using API endpoint: https://docs.portalhq.io/reference/client-api/v3-endpoints#build-a-transaction-to-send-an-asset
const response = await fetch(
  'https://api.portalhq.io/api/v3/clients/me/chains/sepolia/assets/send/build-transaction',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${portal.apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '1', // Sends 1 USDC
      to: '0xDestinationAddress',
      token: SEPOLIA_USDC_TOKEN_ADDRESS, // USDC
    }),
  },
);
const { transaction } = await response.json();

// Send transaction using Portal
const txHash = await portal.provider.request({
  method: 'eth_sendTransaction',
  params: [transaction],
  chainId: 'eip155:11155111', // Sepolia
});

console.log(`✅ Transaction hash: ${txHash}`)

Submitting a Solana Transaction

Web

const chainId = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1'; // Use Solana Devnet
const solanaDevnetUsdcMintAddress = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';

// Build the transaction with Portal
const { transaction } = await portal.buildTransaction(
  chainId,
  'RecipientAddress',
  solanaDevnetUsdcMintAddress,
  '1' // Sends 1 USDC
)

// Send transaction using Portal
const txHash = await portal.request({
  method: 'sol_signAndSendTransaction',
  params: [transaction],
  chainId,
});

console.log(`✅ Transaction hash: ${txHash}`)

iOS

let chainId = "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z" // Use Solana Devnet
let solanaDevnetUsdcMintAddress = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"

let transactionParam = BuildTransactionParam(
    to: "DestinationAddress",
    token: solanaDevnetUsdcMintAddress,
    amount: "1" // Sends 1 USDC
)

// Build the transaction using Portal
let transactionResponse = await portal.buildSolanaTransaction(chainId: chainId, params: transactionParam)

// Sign the transaction
let response = try await portal.request(
    chainId,
    withMethod: .sol_signAndSendTransaction,
    andParams: [transactionResponse.transaction] // RPC params are always expected to be an array
)

// Obtain the transaction hash.
guard let txHash = response.result as? String else {
    // Handle a bad response here
    return
}

print("✅ Transaction hash: \(txHash)")

Android

val chainId = "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z" // Use Solana Devnet

val transactionParam = BuildTransactionParam(
    to = "DestinationAddress",
    token = "SOL",
    amount = "1" // Sends 1 SOL
)

// Build the transaction using Portal
val buildSolanaTransactionResponse = portal.api.buildSolanaTransaction(chainId = chainId, params = transactionParam)
val solanaTransaction = buildSolanaTransactionResponse.getOrThrow()

// Sign the transaction
val txHash = portal.request(
  chainId,
  PortalRequestMethod.sol_signAndSendTransaction,
  listOf(solanaTransaction.transaction)
).result as String


print("✅ Transaction hash: \(txHash)")

React Native

const SOLANA_USDC_DEVNET_MINT_ADDRESS = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
const SOLANA_DEVNET_NAMESPACE = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';

// Build the transaction using API endpoint: https://docs.portalhq.io/reference/client-api/v3-endpoints#build-a-transaction-to-send-an-asset
const response = await fetch(
  'https://api.portalhq.io/api/v3/clients/me/chains/solana-devnet/assets/send/build-transaction',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${portal.apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '1', // Sends 1 USDC
      to: 'DestinationAddress',
      token: SOLANA_USDC_DEVNET_MINT_ADDRESS, // USDC
    }),
  },
);
const { transaction } = await response.json();

// Send transaction using Portal
const txHash = await portal.provider.request({
  method: 'sol_signAndSendTransaction',
  params: [transaction],
  chainId: SOLANA_DEVNET_NAMESPACE,
});

console.log(`✅ Transaction hash: ${txHash}`)