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 MethodsDirect link to Installation Methods

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

Option 1: Inscribed HTML Files (UMD)Direct link to Option 1: Inscribed HTML Files (UMD)

OverviewDirect link to 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 StepsDirect link to Setup Steps

1. Create Your HashinalDirect link to 1. Create Your Hashinal

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

2. Include the SDKDirect link to 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 SelectionDirect link to Version Selection

Version	Topic ID	Status	Features
v1.0.92	`0.0.8084872`	🟢 Latest	All features including NFT validation
v1.0.89	`0.0.7812387`	Stable	Core features + smart contracts
v1.0.82	`0.0.7522981`	Legacy	Basic wallet operations

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

BenefitsDirect link to 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)Direct link to Option 2: Modern JavaScript Applications (ESM)

PrerequisitesDirect link to Prerequisites

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

1. Node.js EnvironmentDirect link to 1. Node.js Environment

Requirement	Version	Installation
Node.js	≥ 20.0	Download or use NVM
NPM	≥ 8.0	Included with Node.js
Yarn (optional)	≥ 1.22	`npm 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 IDDirect link to 2. WalletConnect Project ID

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

Steps to get your Project ID:

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

3. Framework CompatibilityDirect link to 3. Framework Compatibility

The SDK is compatible with:

Framework	Version	Guide
React	≥ 17.0	React Guide
Next.js	≥ 12.0	Next.js Guide
Vue	≥ 3.0	Coming Soon
Vite	≥ 4.0	Vite Guide
Vanilla JS	ES6+	See examples below

Installation CommandsDirect link to Installation Commands

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

Using NPMDirect link to 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 YarnDirect link to 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 PNPMDirect link to 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 ExplainedDirect link to Package Dependencies Explained

Package	Purpose	Required
`@hashgraphonline/hashinal-wc`	Main SDK package	✅ Yes
`@hashgraph/sdk`	Hedera SDK for core functionality	✅ Yes
`@hashgraph/proto`	Protocol buffers for Hedera	✅ Yes
`@hashgraph/hedera-wallet-connect`	Hedera WalletConnect integration	✅ Yes
`@walletconnect/modal`	Connection modal UI	✅ Yes
`@walletconnect/qrcode-modal`	QR code display	✅ Yes
`@walletconnect/utils`	Utility functions	✅ Yes
`@walletconnect/modal-core`	Core modal functionality	✅ Yes

Basic Setup ExampleDirect link to 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);
  }
}

TroubleshootingDirect link to Troubleshooting

Common Issues and SolutionsDirect link to Common Issues and Solutions

Issue	Solution
Module not found errors	Ensure all peer dependencies are installed
TypeScript errors	Install `@types/node` if using TypeScript
Connection timeout	Check network connectivity and WalletConnect project status
Invalid Project ID	Verify your WalletConnect Cloud project ID is correct
Wallet not connecting	Ensure wallet supports WalletConnect v2

Environment VariablesDirect link to 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 StepsDirect link to Next Steps

Now that you have the SDK installed, explore:

📖 API Reference - Complete method documentation
⚛️ React Integration - React-specific patterns
🌐 Next.js Integration - Server-side considerations
⚡ Vite Integration - Vite configuration
🎨 Hashinals Guide - Building inscribed applications

Installation MethodsDirect link to Installation Methods​

Option 1: Inscribed HTML Files (UMD)Direct link to Option 1: Inscribed HTML Files (UMD)​

OverviewDirect link to Overview​

Setup StepsDirect link to Setup Steps​

1. Create Your HashinalDirect link to 1. Create Your Hashinal​

2. Include the SDKDirect link to 2. Include the SDK​

Version SelectionDirect link to Version Selection​

BenefitsDirect link to Benefits​

Option 2: Modern JavaScript Applications (ESM)Direct link to Option 2: Modern JavaScript Applications (ESM)​

PrerequisitesDirect link to Prerequisites​

1. Node.js EnvironmentDirect link to 1. Node.js Environment​

2. WalletConnect Project IDDirect link to 2. WalletConnect Project ID​

3. Framework CompatibilityDirect link to 3. Framework Compatibility​

Installation CommandsDirect link to Installation Commands​

Using NPMDirect link to Using NPM​

Using YarnDirect link to Using Yarn​

Using PNPMDirect link to Using PNPM​

Package Dependencies ExplainedDirect link to Package Dependencies Explained​

Basic Setup ExampleDirect link to Basic Setup Example​

TroubleshootingDirect link to Troubleshooting​

Common Issues and SolutionsDirect link to Common Issues and Solutions​

Environment VariablesDirect link to Environment Variables​

Next StepsDirect link to Next Steps​

Additional ResourcesDirect link to Additional Resources​