ZeroHash Web SDK

The ZeroHash Web SDK enables platforms to integrate ZeroHash financial services on web and mobile applications. Access various UI flows including Fund, Onboarding, Crypto Buy, Crypto Sell, Crypto Withdrawals, Fiat Deposits, and Fiat Withdrawals through a single SDK instance.

Installation

npm install zh-web-sdk

or

yarn add zh-web-sdk

Quick Start

React Example

import React, { useMemo } from 'react';
import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

const App = () => {
  // Create SDK instance once - not on every render
  const sdk = useMemo(() => new ZeroHashSDK({
    zeroHashAppsURL: "https://web-sdk.zerohash.com",
    env: "prod",
    theme: "light"
  }), []);

  const handleOpenFund = () => {
    sdk.openModal({
      appIdentifier: AppIdentifier.FUND,
      jwt: "<JWT_TOKEN_HERE>"
    });
  };

  return (
    <button onClick={handleOpenFund}>
      Fund Account
    </button>
  );
};

export default App;

Vanilla JavaScript Example

import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

// Initialize SDK once
const sdk = new ZeroHashSDK({
  zeroHashAppsURL: "https://web-sdk.zerohash.com",
  env: "prod",
  theme: "light"
});

// Open a modal
sdk.openModal({
  appIdentifier: AppIdentifier.FUND,
  jwt: "<JWT_TOKEN_HERE>"
});

// Close when done
sdk.closeModal(AppIdentifier.FUND);

Environments

Pass env to select the deployment the SDK should target. Accepted values are 'cert' and 'prod'. When set, env is the source of truth for environment resolution and overrides hostname-based inference from zeroHashAppsURL.

const sdk = new ZeroHashSDK({
  zeroHashAppsURL: "https://web-sdk.cert.zerohash.com",
  env: "cert"
});

Default URLs per environment:

• Production: https://web-sdk.zerohash.com
• Certification/Sandbox: https://web-sdk.cert.zerohash.com

If env is omitted, the SDK falls back to inferring the environment from the hostname of zeroHashAppsURL. Hosts outside the recognized Zero Hash list resolve to 'prod' — pass env explicitly when integrating from a partner-hosted domain.

env is init-only: it is read once when you construct ZeroHashSDK and cannot be changed afterwards. Region (EU) routing is derived from the JWT, not from env.

Available App Identifiers

The SDK supports the following application flows:

| AppIdentifier | Description | |--------------|-------------| | FUND | Fund account operations | | ONBOARDING | User onboarding and KYC | | CRYPTO_BUY | Purchase cryptocurrency | | CRYPTO_SELL | Sell cryptocurrency | | CRYPTO_WITHDRAWALS | Withdraw crypto to external wallets | | FIAT_DEPOSITS | Deposit fiat currency | | FIAT_WITHDRAWALS | Withdraw fiat currency | | PROFILE | User profile management | | CRYPTO_ACCOUNT_LINK | Link cryptocurrency accounts | | CRYPTO_ACCOUNT_LINK_PAYOUTS | Link crypto accounts for payouts | | FIAT_ACCOUNT_LINK | Link bank accounts | | PAYOUTS | Payout operations | | PAY | Payment operations |

API Reference

Constructor

new ZeroHashSDK(config: IInitializeParameters)

Configuration Options:

{
  zeroHashAppsURL: string;           // Required: Base URL for ZeroHash apps
  env?: 'cert' | 'prod';             // Optional: Explicit environment selection
  theme?: 'light' | 'dark' | 'auto'; // Optional: Appearance for next-gen flows (defaults to 'light')
  rootQuerySelector?: string;        // Optional: Custom DOM element selector

  // Optional: Set JWTs during initialization
  cryptoBuyJWT?: string;
  cryptoSellJWT?: string;
  cryptoWithdrawalsJWT?: string;
  fiatDepositsJWT?: string;
  fiatWithdrawalsJWT?: string;
  userOnboardingJWT?: string;
  fundJWT?: string;
  profileJWT?: string;
  cryptoAccountLinkJWT?: string;
  cryptoAccountLinkPayoutsJWT?: string;
  fiatAccountLinkJWT?: string;
  payoutsJWT?: string;
  payJWT?: string;
}

Methods

openModal(params)

Opens a modal for the specified app.

sdk.openModal({
  appIdentifier: AppIdentifier.FUND,
  jwt?: string,           // Optional: Set or update JWT
  filters?: Filters,      // Optional: Filter options
  navigate?: Page         // Optional: Navigation parameters
});

closeModal(appIdentifier)

Closes the modal for the specified app.

sdk.closeModal(AppIdentifier.FUND);

setJWT(params)

Set or update the JWT for a specific app.

sdk.setJWT({
  jwt: "<JWT_TOKEN>",
  appIdentifier: AppIdentifier.FUND
});

isModalOpen(appIdentifier)

Check if a modal is currently open.

const isOpen = sdk.isModalOpen(AppIdentifier.FUND);

setFilters(params)

Set filters for a specific app.

sdk.setFilters({
  appIdentifier: AppIdentifier.FUND,
  filters: {
    getAssets: {
      stablecoin: true
    }
  }
});

setTheme(params)

Update the theme forwarded to the next-generation @zerohash-sdk/*-react flows and Connect Auth (Fund). Has no effect on the legacy iframe.

sdk.setTheme({ theme: "dark" }); // 'light' | 'dark' | 'auto'

JWT Authentication

⚠️ Security Note: JWTs should be obtained from your backend server using the ZeroHash API with your API key. Never expose your API key or perform JWT exchanges on the client side.

Ways to provide JWTs

You only need to provide the JWT once. If it was set during initialization or via setJWT, calling openModal without a jwt uses the token already set for that app. Passing jwt to openModal sets or updates it. Either way the SDK reads the same token to decide whether to render the next-generation UI, so no change to how you call openModal is needed.

1. During initialization:

const sdk = new ZeroHashSDK({
  zeroHashAppsURL: "https://web-sdk.zerohash.com",
  env: "prod",
  fundJWT: jwt
});

2. When opening a modal:

sdk.openModal({
  appIdentifier: AppIdentifier.FUND,
  jwt: jwt
});

3. Update JWT later:

sdk.setJWT({
  jwt: newJwt,
  appIdentifier: AppIdentifier.FUND
});

TypeScript Support

The SDK is written in TypeScript and includes type definitions. Import types as needed:

import ZeroHashSDK, {
  AppIdentifier,
  IInitializeParameters,
  IOpenModalParameters,
  Filters
} from 'zh-web-sdk';

Documentation & Support

• Full Documentation: ZeroHash SDK Documentation
• Changelog: ZeroHash Documentation Changelog
• Mobile Usage: See the SDK Overview for mobile implementation details

License

MIT