Authentication & Setup

Learn how to configure HSM/MPC authentication for secure wallet operations with MSA API.

The MSA API requires two types of authentication:

API Key: Required for all API requests to identify your account and access contract addresses
HSM/MPC Credentials: Required for signing operations (Fireblocks client ID, version ID, or asset ID)

This guide explains how to obtain your API key and configure HSM/MPC authentication for secure wallet operations.

Obtaining Your API Key

Before you can use the MSA API, you need to obtain an API key. This key is used to:

Authenticate your requests to the MSA API
Access contract addresses for supported networks
Use the remote bundler service
Identify your account for rate limiting and usage tracking

Request Your API Key

To get your API key, you have two options:

Schedule a Meeting: Book a 30-minute call with our team
Send an Email: Contact us to request access

Once approved, you'll receive your API key via email. Store it securely and never commit it to version control.

Using Your API Key

The API key is sent in the X-API-Key header for all API requests:

// REST API Request
fetch('https://api.msa.omnes.tech/getbundleraddress', {
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  }
});

When using the SmartWallet SDK, pass the API key during initialization:

import { SmartWallet, PKSigner } from '@omnes/smartwallet-ts-sdk';

const signer = await PKSigner.create(privateKey);
const smartWallet = await SmartWallet.create(
  signer.signMessage,
  signer.signMessage,
  signer.getEVMAddress(),
  rpcURL,
  'your-api-key-here', // API Key here
  null,
  false
);

Environment Variables

Store your API key securely using environment variables:

# .env file
API_KEY=your-api-key-here
PRIVATE_KEY=0x...
RPC_URL=https://rpc-amoy.polygon.technology/

// In your code
const apiKey = process.env.API_KEY!;
const rpcURL = process.env.RPC_URL!;
const privateKey = process.env.PRIVATE_KEY!;

Signing Providers

MSA API currently supports:

Fireblocks HSM: Hardware Security Module integration
Fireblocks MPC: Multi-Party Computation signing
Private Key Signing: Direct private key signing (for testing)
Google Cloud KMS: GCP HSM signing
More providers coming soon

Fireblocks Integration

Prerequisites

Fireblocks Account: Active Fireblocks workspace
API Credentials: Client ID and Version ID (HSM) or Asset ID (MPC)
Network Configuration: Proper RPC endpoints and contract addresses

HSM Configuration

For Fireblocks HSM, you'll need:

interface HSMConfig {
  clientId: string;     // Your Fireblocks client ID
  versionId: string;    // HSM version identifier
}

MPC Configuration

For Fireblocks MPC, you'll need:

interface MPCConfig {
  clientId: string;     // Your Fireblocks client ID
  assetId: string;      // Asset identifier (e.g., "ETH", "MATIC")
}

API Settings Structure

Every MSA API request requires a settings object with authentication and network configuration:

interface Settings {
  // Network Configuration
  rpc: string;                    // Blockchain RPC endpoint
  factory: string;                // Wallet factory contract address
  validator: string;              // Validator contract address
  entryPoint: string;             // EIP-4337 entry point address
  beaconAdminAddress: string;     // Beacon admin contract address
  
  // Optional Contracts
  paymaster?: string;             // Paymaster contract (optional)
  aggregator?: string;            // Signature aggregator (optional)
  beaconAdminCreationCode?: string; // Beacon creation bytecode
  
  // Gas Configuration
  percentUserOpGasOvershoot?: number;     // UserOp gas buffer (default: 50%)
  percentTxGasOvershoot?: number;         // Transaction gas buffer (default: 50%)
  percentTxGasPriceOvershoot?: number;    // Gas price buffer (default: 20%)
  
  // HSM/MPC Authentication
  signer: {
    clientId: string;             // Fireblocks client ID
    versionId?: string;           // For HSM (required if no assetId)
    assetId?: string;             // For MPC (required if no versionId)
  };
  
  // Optional Features
  useABI?: Array<any>;            // Custom ABI for response decoding
}

Network Configurations

Polygon Amoy Testnet

{
  "rpc": "https://rpc-amoy.polygon.technology/",
  "factory": "0xb09Fd1134553a43A3E02182a6B04F4dEBa7476F4",
  "validator": "0x9bD18Da66990F80d598dE02d5143dC9A4422eC3a",
  "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
  "beaconAdminAddress": "0x99Ee7725D6a8f691d8B375e0aD33d1Aff2236618",
  "beaconAdminCreationCode": "0x60a060405260405161059d38038061059d83398101604081905261002291610354565b..."
}

Polygon Mainnet

{
  "rpc": "https://polygon-rpc.com/",
  "factory": "0x...",
  "validator": "0x...",
  "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
  "beaconAdminAddress": "0x..."
}

Base Sepolia Testnet

{
  "rpc": "https://sepolia.base.org/",
  "factory": "0x...",
  "validator": "0x...",
  "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
  "beaconAdminAddress": "0x..."
}

Example Authentication Setup

SmartWallet SDK

import { GCPSigner, SmartWallet } from '@omnes/smartwallet-ts-sdk';

// HSM Configuration (GCP)
const hsmSigner = await GCPSigner.create(
    googleCredentials, 
    googleProjectId,
    kmsLocationId, 
    kmsKeyRingId, 
    clientId, 
    versionId
);

const smartWallet = await SmartWallet.create(
    hsmSigner.signMessage,
    hsmSigner.signMessage,
    hsmSigner.getEVMAddress(),
    rpcURL,
    apiKey
);

// For MPC, use the appropriate signer from the SmartWallet SDK
// The SDK handles authentication through the API key

cURL Example

curl -X POST "https://api.msa.omnes.tech/create" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [{
      "walletCustody": 1,
      "salt": "user@example.com"
    }],
    "settings": {
      "rpc": "https://rpc-amoy.polygon.technology/",
      "factory": "0xb09Fd1134553a43A3E02182a6B04F4dEBa7476F4",
      "validator": "0x9bD18Da66990F80d598dE02d5143dC9A4422eC3a",
      "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
      "beaconAdminAddress": "0x99Ee7725D6a8f691d8B375e0aD33d1Aff2236618",
      "beaconAdminCreationCode": "0x60a060405260405161059d...",
      "signer": {
        "clientId": "e94aecb1-5daf-47f3-948f-2a639a56baa6",
        "versionId": "1"
      }
    }
  }'

Python Example

import requests

# Configuration
config = {
    "base_url": "https://api.msa.omnes.tech",
    "settings": {
        "rpc": "https://rpc-amoy.polygon.technology/",
        "factory": "0xb09Fd1134553a43A3E02182a6B04F4dEBa7476F4",
        "validator": "0x9bD18Da66990F80d598dE02d5143dC9A4422eC3a",
        "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
        "beaconAdminAddress": "0x99Ee7725D6a8f691d8B375e0aD33d1Aff2236618",
        "signer": {
            "clientId": "e94aecb1-5daf-47f3-948f-2a639a56baa6",
            "versionId": "1"
        }
    }
}

# Create wallet request
response = requests.post(
    f"{config['base_url']}/create",
    json={
        "accounts": [{
            "walletCustody": 1,
            "salt": "user@example.com"
        }],
        "settings": config["settings"]
    }
)

Gas Configuration

UserOperation Gas Overshoot

Adds a buffer to gas estimation for UserOperations to prevent failures:

{
  percentUserOpGasOvershoot: 60  // 60% buffer (recommended)
}

Transaction Gas Overshoot

Adds a buffer to transaction gas estimation:

{
  percentTxGasOvershoot: 20  // 20% buffer (recommended)
}

Gas Price Overshoot

Adds a buffer to gas price to ensure transaction inclusion:

{
  percentTxGasPriceOvershoot: 20  // 20% buffer (recommended)
}

Security Best Practices

1. Environment Variables

Never hardcode credentials in your application:

# .env file
MSA_CLIENT_ID=e94aecb1-5daf-47f3-948f-2a639a56baa6
MSA_VERSION_ID=1
MSA_RPC_URL=https://rpc-amoy.polygon.technology/

// Using SmartWallet SDK
import { PKSigner, SmartWallet } from '@omnes/smartwallet-ts-sdk';

const signer = await PKSigner.create(privateKey as `0x${string}`);
const smartWallet = await SmartWallet.create(
    signer.signMessage,
    signer.signMessage,
    signer.getEVMAddress(),
    process.env.MSA_RPC_URL!,
    apiKey
);

2. Network Validation

Always validate network configurations:

const SUPPORTED_NETWORKS = {
  80002: { // Polygon Amoy
    rpc: 'https://rpc-amoy.polygon.technology/',
    factory: '0xb09Fd1134553a43A3E02182a6B04F4dEBa7476F4',
    // ... other addresses
  },
  137: { // Polygon Mainnet
    rpc: 'https://polygon-rpc.com/',
    factory: '0x...',
    // ... other addresses
  }
};

function getNetworkConfig(chainId: number) {
  const config = SUPPORTED_NETWORKS[chainId];
  if (!config) {
    throw new Error(`Unsupported network: ${chainId}`);
  }
  return config;
}

3. Request Timeout

Set appropriate timeouts for API requests:

// Using SmartWallet SDK
import { PKSigner, SmartWallet } from '@omnes/smartwallet-ts-sdk';

const signer = await PKSigner.create(privateKey as `0x${string}`);
const smartWallet = await SmartWallet.create(
    signer.signMessage,
    signer.signMessage,
    signer.getEVMAddress(),
    rpcURL,
    apiKey
);

Error Handling

Common Authentication Errors

Error	Description	Solution
`Invalid client ID`	Fireblocks client ID is incorrect	Verify your Fireblocks credentials
`Version not found`	HSM version doesn't exist	Check your version ID
`Asset not supported`	MPC asset not available	Use supported asset ID
`Network connection failed`	RPC endpoint unreachable	Verify RPC URL and network status

Example Error Handling

try {
  const result = await client.createWallet({
    walletCustody: 1,
    salt: "user@example.com"
  });
  console.log('Wallet created:', result);
} catch (error) {
  if (error.code === 'INVALID_CLIENT_ID') {
    console.error('Please check your Fireblocks credentials');
  } else if (error.code === 'NETWORK_ERROR') {
    console.error('Network connection failed, please try again');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Testing Your Setup

Verify your authentication setup with a simple wallet prediction:

// Test prediction (doesn't require signing)
const prediction = await client.predictWallet({
  walletCustody: 1,
  salt: "test@example.com"
});

console.log('Predicted wallet address:', prediction.walletAddress);

Next Steps

Once your authentication is configured:

Create Your First Wallet - Deploy a test wallet
Explore Custody Types - Learn about different security models
Start Building - Integrate with your application

✅ Pro Tip: Start with testnet environments and ECDSA_VALIDATOR custody type for initial testing before moving to production with advanced custody features.

Authentication & Setup

On this page