Skip to main content

Installation Guide

This guide will help you set up Hashinal Wallet Connect SDK for your specific use case. Choose the installation method that matches your application type.

Installation Methods​

The SDK provides two distribution formats to support different application architectures:

Option 1: Inscribed HTML Files (UMD)​

Overview​

For inscribed HTML Hashinals, the SDK is loaded directly from Hedera Consensus Service using the HCS-3 recursion standard. This approach requires no traditional installation and ensures your application always uses an immutable, on-chain version of the SDK.

Setup Steps​

1. Create Your Hashinal​

First, create your inscribed HTML file following the HCS-3 Recursion Standard.

2. Include the SDK​

Add the following script tag to your HTML file:

<!DOCTYPE html>
<html>
<head>
    <title>My Hashinal</title>
</head>
<body>
    <!-- Load Hashinal Wallet Connect SDK from HCS -->
    <script data-src="hcs://1/0.0.8084872" data-script-id="wallet-connect"></script>
    
    <!-- Your application code -->
    <script>
        // SDK is available as window.HashinalsWalletConnectSDK
        async function initializeApp() {
            const sdk = window.HashinalsWalletConnectSDK;
            // Your code here
        }
    </script>
</body>
</html>

Version Selection​

VersionTopic IDStatusFeatures
v1.0.920.0.8084872🟢 LatestAll features including NFT validation
v1.0.890.0.7812387StableCore features + smart contracts
v1.0.820.0.7522981LegacyBasic wallet operations

📍 Note: Always check the Topics page for the latest version.

Benefits​

  • ✅ No Installation: Load directly from Hedera
  • ✅ Immutable: Code cannot be changed once inscribed
  • ✅ Automatic: No dependency management needed
  • ✅ Decentralized: Hosted on Hedera, not traditional servers

Option 2: Modern JavaScript Applications (ESM)​

Prerequisites​

Before installing the SDK for modern JavaScript applications, ensure you have:

1. Node.js Environment​

RequirementVersionInstallation
Node.js≥ 20.0Download or use NVM
NPM≥ 8.0Included with Node.js
Yarn (optional)≥ 1.22npm install --global yarn
# Check your versions
node --version  # Should be >= 20.0.0
npm --version   # Should be >= 8.0.0

# Using NVM (recommended)
nvm install 20
nvm use 20
nvm alias default 20

2. WalletConnect Project ID​

You'll need a WalletConnect Cloud Project ID to enable wallet connections:

Steps to get your Project ID:

  1. 🌐 Visit WalletConnect Cloud
  2. 🔐 Sign in or create a new account
  3. ➕ Click "Create New Project"
  4. 🏷️ Name your project (e.g., "My Hedera App")
  5. 📋 Copy the Project ID from the dashboard

3. Framework Compatibility​

The SDK is compatible with:

FrameworkVersionGuide
React≥ 17.0React Guide
Next.js≥ 12.0Next.js Guide
Vue≥ 3.0Coming Soon
Vite≥ 4.0Vite Guide
Vanilla JSES6+See examples below

Installation Commands​

Choose your package manager and install the SDK with all required dependencies:

Using NPM​

# Install all required packages
npm install @hashgraphonline/hashinal-wc \
  @hashgraph/sdk \
  @hashgraph/proto \
  @hashgraph/hedera-wallet-connect \
  @walletconnect/modal \
  @walletconnect/qrcode-modal \
  @walletconnect/utils \
  @walletconnect/modal-core

Using Yarn​

# Install all required packages
yarn add @hashgraphonline/hashinal-wc \
  @hashgraph/sdk \
  @hashgraph/proto \
  @hashgraph/hedera-wallet-connect \
  @walletconnect/modal \
  @walletconnect/qrcode-modal \
  @walletconnect/utils \
  @walletconnect/modal-core

Using PNPM​

# Install all required packages
pnpm add @hashgraphonline/hashinal-wc \
  @hashgraph/sdk \
  @hashgraph/proto \
  @hashgraph/hedera-wallet-connect \
  @walletconnect/modal \
  @walletconnect/qrcode-modal \
  @walletconnect/utils \
  @walletconnect/modal-core

Package Dependencies Explained​

PackagePurposeRequired
@hashgraphonline/hashinal-wcMain SDK package✅ Yes
@hashgraph/sdkHedera SDK for core functionality✅ Yes
@hashgraph/protoProtocol buffers for Hedera✅ Yes
@hashgraph/hedera-wallet-connectHedera WalletConnect integration✅ Yes
@walletconnect/modalConnection modal UI✅ Yes
@walletconnect/qrcode-modalQR code display✅ Yes
@walletconnect/utilsUtility functions✅ Yes
@walletconnect/modal-coreCore modal functionality✅ Yes

Basic Setup Example​

Once installed, here's a minimal setup:

// 1. Import the SDK
import { HashinalsWalletConnectSDK } from '@hashgraphonline/hashinal-wc';
import { LedgerId } from '@hashgraph/sdk';

// 2. Get SDK instance (singleton)
const sdk = HashinalsWalletConnectSDK.getInstance();

// 3. Initialize with your configuration
async function initializeSDK() {
  try {
    await sdk.init(
      'YOUR_WALLETCONNECT_PROJECT_ID', // From WalletConnect Cloud
      {
        name: 'My Hedera App',
        description: 'A modern Hedera application',
        url: 'https://myapp.com',
        icons: ['https://myapp.com/icon.png']
      },
      LedgerId.MAINNET // or TESTNET for development
    );
    
    console.log('SDK initialized successfully');
  } catch (error) {
    console.error('Failed to initialize SDK:', error);
  }
}

// 4. Connect wallet
async function connectWallet() {
  try {
    const session = await sdk.connect();
    console.log('Wallet connected:', session);
    
    // Get account info
    const accountInfo = await sdk.getAccountInfo();
    console.log('Connected account:', accountInfo.accountId);
  } catch (error) {
    console.error('Failed to connect wallet:', error);
  }
}

Troubleshooting​

Common Issues and Solutions​

IssueSolution
Module not found errorsEnsure all peer dependencies are installed
TypeScript errorsInstall @types/node if using TypeScript
Connection timeoutCheck network connectivity and WalletConnect project status
Invalid Project IDVerify your WalletConnect Cloud project ID is correct
Wallet not connectingEnsure wallet supports WalletConnect v2

Environment Variables​

For security, store your Project ID in environment variables:

# .env file
VITE_WALLETCONNECT_PROJECT_ID=your_project_id_here
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id_here
REACT_APP_WALLETCONNECT_PROJECT_ID=your_project_id_here

Next Steps​

Now that you have the SDK installed, explore:

Additional Resources​