Hashinals WalletConnect SDK

This SDK provides a simple interface for interacting with the Hedera Hashgraph using WalletConnect. It allows developers to easily integrate Hedera functionality into their applications, whether they're using inscribed HTML files or modern JavaScript frameworks.

Features

• Initialize and connect to WalletConnect
• Submit messages to Hedera topics
• Transfer HBAR between accounts
• Execute smart contracts
• Create topics and tokens
• Mint NFTs
• Fetch account balance and information
• Retrieve messages from a topic
• Transfer tokens between accounts
• Create accounts
• Associate tokens with accounts
• Dissociate tokens from accounts
• Update account properties
• Approve token allowances
• Get transaction details by transaction ID or timestamp from the mirror node
• Get account NFTs with optional filtering by token ID
• Validate NFT ownership by serial number and token ID
• Make read-only calls to smart contracts on the mirror node

Installation

For inscribed HTML files (UMD)

No installation needed. Reference the script directly in your HTML:

<script data-src="hcs://1/0.0.7473819" data-script-id="wallet-connect"></script>

For NPM projects (ESM)

Install the package:

npm install @hashgraphonline/hashinal-wc @hashgraph/sdk @hashgraph/proto @hashgraph/hedera-wallet-connect @walletconnect/modal @walletconnect/qrcode-modal @walletconnect/utils @walletconnect/types @walletconnect/modal-core fetch-retry

Usage

UMD (inscribed HTML)

Access the SDK through the global window object:

const sdk = window.HashinalsWalletConnectSDK;

ESM (modern JavaScript/TypeScript projects)

Import and use the SDK:

import { HashinalsWalletConnectSDK } from '@hashgraphonline/hashinal-wc';
const sdk = HashinalsWalletConnectSDK.getInstance();

SDK Reference

init(projectId: string, metadata: SignClientTypes.Metadata, network?: LedgerId)

Initializes the SDK with the given project ID, metadata, and optional network selection.

UMD Example:

const projectId = 'your_project_id';
const metadata = {
  name: 'My Hashinals App',
  description: 'A Hashinals application using WalletConnect',
  url: 'https://myapp.com',
  icons: ['https://myapp.com/icon.png'],
};
await window.HashinalsWalletConnectSDK.init(projectId, metadata);

ESM Example:

import { HashinalsWalletConnectSDK } from '@hashgraphonline/hashinal-wc';
import { LedgerId } from '@hashgraph/sdk';

const sdk = HashinalsWalletConnectSDK.getInstance();
await sdk.init(projectId, metadata, LedgerId.TESTNET);

connect()

Opens the WalletConnect modal for users to connect their wallet.

UMD Example:

const session = await window.HashinalsWalletConnectSDK.connect();

ESM Example:

const session = await sdk.connect();

disconnect()

Disconnects from all connected wallets.

UMD Example:

await window.HashinalsWalletConnectSDK.disconnect();

ESM Example:

await sdk.disconnect();

submitMessageToTopic(topicId: string, message: string, submitKey?: PrivateKey)

Submits a message to a specified Hedera topic.

UMD Example:

const topicId = '0.0.1234567';
const message = 'Hello, Hedera!';
const receipt = await window.HashinalsWalletConnectSDK.submitMessageToTopic(
  topicId,
  message
);

ESM Example:

import { PrivateKey } from '@hashgraph/sdk';

const submitKey = PrivateKey.fromString(
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6'
);
const receipt = await sdk.submitMessageToTopic(topicId, message, submitKey);

transferHbar(fromAccountId: string, toAccountId: string, amount: number)

Transfers HBAR from one account to another.

UMD Example:

const fromAccountId = '0.0.1234567';
const toAccountId = '0.0.7654321';
const amount = 10; // in HBAR
const receipt = await window.HashinalsWalletConnectSDK.transferHbar(
  fromAccountId,
  toAccountId,
  amount
);

ESM Example:

const receipt = await sdk.transferHbar(fromAccountId, toAccountId, amount);

executeSmartContract(contractId: string, functionName: string, parameters: ContractFunctionParameters, gas: number = 100000)

Executes a function on a smart contract.

UMD Example:

const contractId = '0.0.1234567';
const functionName = 'myFunction';
const parameters =
  new window.HashgraphSDK.ContractFunctionParameters().addString('Hello');
const receipt = await window.HashinalsWalletConnectSDK.executeSmartContract(
  contractId,
  functionName,
  parameters
);

ESM Example:

import { ContractFunctionParameters } from '@hashgraph/sdk';

const parameters = new ContractFunctionParameters().addString('Hello');
const receipt = await sdk.executeSmartContract(
  contractId,
  functionName,
  parameters,
  150000
);

getMessages(topicId: string, lastTimestamp?: number, disableTimestampFilter: boolean = false)

Retrieves messages from a specific Hedera topic.

UMD Example:

const topicId = '0.0.1234567';
const result = await window.HashinalsWalletConnectSDK.getMessages(topicId);
console.log(result.messages);

ESM Example:

const result = await sdk.getMessages(topicId, 1625097600000, true);
console.log(result.messages);

transferToken(tokenId: string, fromAccountId: string, toAccountId: string, amount: number)

Transfers tokens between accounts.

UMD Example:

const tokenId = '0.0.1234567';
const fromAccountId = '0.0.7654321';
const toAccountId = '0.0.8765432';
const amount = 100;
const receipt = await window.HashinalsWalletConnectSDK.transferToken(
  tokenId,
  fromAccountId,
  toAccountId,
  amount
);

ESM Example:

const receipt = await sdk.transferToken(
  tokenId,
  fromAccountId,
  toAccountId,
  amount
);

createAccount(initialBalance: number)

Creates a new account on the Hedera network.

UMD Example:

const initialBalance = 50; // in HBAR
const receipt = await window.HashinalsWalletConnectSDK.createAccount(
  initialBalance
);

ESM Example:

const receipt = await sdk.createAccount(initialBalance);

associateTokenToAccount(accountId: string, tokenId: string)

Associates a token with an account.

UMD Example:

const accountId = '0.0.1234567';
const tokenId = '0.0.7654321';
const receipt = await window.HashinalsWalletConnectSDK.associateTokenToAccount(
  accountId,
  tokenId
);

ESM Example:

const receipt = await sdk.associateTokenToAccount(accountId, tokenId);

dissociateTokenFromAccount(accountId: string, tokenId: string)

Removes a token association from an account.

UMD Example:

const accountId = '0.0.1234567';
const tokenId = '0.0.7654321';
const receipt =
  await window.HashinalsWalletConnectSDK.dissociateTokenFromAccount(
    accountId,
    tokenId
  );

ESM Example:

const receipt = await sdk.dissociateTokenFromAccount(accountId, tokenId);

updateAccount(accountId: string, maxAutomaticTokenAssociations: number)

Updates an account's properties.

UMD Example:

const accountId = '0.0.1234567';
const maxAutomaticTokenAssociations = 10;
const receipt = await window.HashinalsWalletConnectSDK.updateAccount(
  accountId,
  maxAutomaticTokenAssociations
);

ESM Example:

const receipt = await sdk.updateAccount(
  accountId,
  maxAutomaticTokenAssociations
);

getAccountInfo()

Fetches the account ID and network of the connected wallet.

UMD Example:

const accountInfo = await window.HashinalsWalletConnectSDK.getAccountInfo();
console.log('Account ID:', accountInfo.accountId);
console.log('Network:', accountInfo.network);

ESM Example:

const accountInfo = await sdk.getAccountInfo();
console.log('Account ID:', accountInfo.accountId);
console.log('Network:', accountInfo.network);

getAccountBalance()

Retrieves the HBAR balance of the connected account.

UMD Example:

const balance = await window.HashinalsWalletConnectSDK.getAccountBalance();
console.log('Account balance:', balance);

ESM Example:

const balance = await sdk.getAccountBalance();
console.log('Account balance:', balance);

createTopic(memo?: string, adminKey?: string, submitKey?: string)

Creates a new topic on the Hedera network.

UMD Example:

const memo = 'My new topic';
const adminKey =
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6';
const submitKey =
  '302e020100300506032b6570042204203e7b42b1d113a323daf39a35a86824a570fc92192502f5e4b4d5830dac9af0f1';
const topicId = await window.HashinalsWalletConnectSDK.createTopic(
  memo,
  adminKey,
  submitKey
);
console.log('New topic created:', topicId);

ESM Example:

import { PrivateKey } from '@hashgraph/sdk';

const memo = 'My new topic';
const adminKey = PrivateKey.fromString(
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6'
);
const submitKey = PrivateKey.fromString(
  '302e020100300506032b6570042204203e7b42b1d113a323daf39a35a86824a570fc92192502f5e4b4d5830dac9af0f1'
);
const topicId = await sdk.createTopic(memo, adminKey, submitKey);
console.log('New topic created:', topicId);

createToken(name: string, symbol: string, initialSupply: number, decimals: number, treasuryAccountId: string, adminKey: string, supplyKey: string)

Creates a new token on the Hedera network.

UMD Example:

const name = 'My Token';
const symbol = 'MTK';
const initialSupply = 1000000;
const decimals = 2;
const treasuryAccountId = '0.0.1234567';
const adminKey =
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6';
const supplyKey =
  '302e020100300506032b6570042204203e7b42b1d113a323daf39a35a86824a570fc92192502f5e4b4d5830dac9af0f1';
const tokenId = await window.HashinalsWalletConnectSDK.createToken(
  name,
  symbol,
  initialSupply,
  decimals,
  treasuryAccountId,
  adminKey,
  supplyKey
);
console.log('New token created:', tokenId);

ESM Example:

import { PrivateKey } from '@hashgraph/sdk';

const name = 'My Token';
const symbol = 'MTK';
const initialSupply = 1000000;
const decimals = 2;
const treasuryAccountId = '0.0.1234567';
const adminKey = PrivateKey.fromString(
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6'
);
const supplyKey = PrivateKey.fromString(
  '302e020100300506032b6570042204203e7b42b1d113a323daf39a35a86824a570fc92192502f5e4b4d5830dac9af0f1'
);
const tokenId = await sdk.createToken(
  name,
  symbol,
  initialSupply,
  decimals,
  treasuryAccountId,
  adminKey,
  supplyKey
);
console.log('New token created:', tokenId);

mintNFT(tokenId: string, metadata: string, supplyKey: PrivateKey)

Mints a new NFT for an existing token.

UMD Example:

const tokenId = '0.0.1234567';
const metadata = 'ipfs://QmXxx...';
const supplyKey =
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6';
const receipt = await window.HashinalsWalletConnectSDK.mintNFT(
  tokenId,
  metadata,
  supplyKey
);
console.log('NFT minted:', receipt);

ESM Example:

import { PrivateKey } from '@hashgraph/sdk';

const tokenId = '0.0.1234567';
const metadata = 'ipfs://QmXxx...';
const supplyKey = PrivateKey.fromString(
  '302e020100300506032b657004220420f4361ec73dc43e568f1620a7b7ecb7330790b8a1c7620f1ce353aa1de4f0eaa6'
);
const receipt = await sdk.mintNFT(tokenId, metadata, supplyKey);
console.log('NFT minted:', receipt);

getAccountTokens(accountId: string)

Retrieves all tokens associated with an account.

UMD Example:

const accountId = '0.0.1234567';
const tokens = await window.HashinalsWalletConnectSDK.getAccountTokens(
  accountId
);
console.log('Account tokens:', tokens);

ESM Example:

const accountId = '0.0.1234567';
const tokens = await sdk.getAccountTokens(accountId);
console.log('Account tokens:', tokens);

getTransaction(transactionId: string)

Retrieves transaction details by transaction ID from the mirror node.

UMD Example:

const transactionId = "[email protected]";
const transaction = await window.HashinalsWalletConnectSDK.getTransaction(transactionId);
console.log(transaction);

ESM Example:

const transaction = await sdk.getTransaction(transactionId);

getTransactionByTimestamp(timestamp: string)

Retrieves transaction details by consensus timestamp from the mirror node.

UMD Example:

const timestamp = "1234567890.000000000";
const transaction = await window.HashinalsWalletConnectSDK.getTransactionByTimestamp(timestamp);
console.log(transaction);

ESM Example:

const transaction = await sdk.getTransactionByTimestamp(timestamp);

getAccountNFTs(accountId: string, tokenId?: string)

Retrieves all NFTs owned by an account, with optional filtering by token ID.

UMD Example:

const accountId = "0.0.123456";
const nfts = await window.HashinalsWalletConnectSDK.getAccountNFTs(accountId);
console.log(nfts);

// With token filter
const tokenId = "0.0.789012";
const filteredNfts = await window.HashinalsWalletConnectSDK.getAccountNFTs(accountId, tokenId);

ESM Example:

const nfts = await sdk.getAccountNFTs(accountId);
const filteredNfts = await sdk.getAccountNFTs(accountId, tokenId);

validateNFTOwnership(serialNumber: string, accountId: string, tokenId: string)

Validates if an account owns a specific NFT by serial number and token ID.

UMD Example:

const serialNumber = "1";
const accountId = "0.0.123456";
const tokenId = "0.0.789012";
const nft = await window.HashinalsWalletConnectSDK.validateNFTOwnership(serialNumber, accountId, tokenId);
console.log(nft ? "Account owns this NFT" : "Account does not own this NFT");

ESM Example:

const nft = await sdk.validateNFTOwnership(serialNumber, accountId, tokenId);

readSmartContract(data: string, fromAccount: AccountId, contractId: ContractId, estimate?: boolean, value?: number)

Makes a read-only call to a smart contract on the mirror node.

UMD Example:

const data = "0x..."; // Contract call data
const fromAccount = window.HashgraphSDK.AccountId.fromString("0.0.123456");
const contractId = window.HashgraphSDK.ContractId.fromString("0.0.789012");
const result = await window.HashinalsWalletConnectSDK.readSmartContract(data, fromAccount, contractId);
console.log(result);

ESM Example:

import { AccountId, ContractId } from '@hashgraph/sdk';

const fromAccount = AccountId.fromString("0.0.123456");
const contractId = ContractId.fromString("0.0.789012");
const result = await sdk.readSmartContract(data, fromAccount, contractId);

Versions and Topic IDs

Version 1.0.58 and onward correlate with the NPM Package version.

Version	Topic ID	Type
v0.0.1	0.0.6790163	UMD
v1.0.4	0.0.6843009	UMD
v1.0.58	0.0.7001143	UMD
v1.0.62	0.0.7111719	UMD
v1.0.64	0.0.7153927	UMD
v1.0.71	0.0.7337015	UMD
v1.0.79	0.0.7473819	UMD
v1.0.82	0.0.7522981	UMD
v1.0.86	0.0.7770334	UMD
v1.0.88	0.0.7797532	UMD
v1.0.89	0.0.7812387	UMD

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.