zh-web-sdk
v3.12.2
Published
ZeroHash Web SDK
Downloads
27,731
Readme
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-sdkor
yarn add zh-web-sdkQuick 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://sdk-cdn.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://sdk-cdn.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://sdk-cdn.cert.zerohash.com",
env: "cert"
});Default URLs per environment:
- Production:
https://sdk-cdn.zerohash.com - Certification/Sandbox:
https://sdk-cdn.cert.zerohash.com
zeroHashAppsURL is optional. The SDK resolves the apps URL and environment from whichever options you pass:
- Neither
envnorzeroHashAppsURL: defaults toprod(useshttps://sdk-cdn.zerohash.com) envonly: derives the apps URL from the environmentzeroHashAppsURLonly: infers the environment from the URL hostname (hosts outside the recognized Zero Hash list resolve to'prod')- Both: uses
zeroHashAppsURLfor the apps iframe and letsenvdrive the environment
Pass env explicitly when integrating from a partner-hosted domain, so the environment is not misinferred from your own hostname.
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_DEPOSITS | Deposit crypto from external wallets |
| 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; // Optional: Base URL for ZeroHash apps (derived from env when omitted)
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
destroyOnClose?: boolean; // Optional: Remove injected DOM on close (defaults to false)
// Optional: Set JWTs during initialization
cryptoBuyJWT?: string;
cryptoSellJWT?: string;
cryptoDepositsJWT?: 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
});Travel Rule
AppIdentifier.TRAVEL_RULE accepts three additional, Travel Rule-only params on openModal (ignored for every other app identifier):
sdk.openModal({
appIdentifier: AppIdentifier.TRAVEL_RULE,
jwt: "<JWT_TOKEN_HERE>",
depositId?: string, // Deposit the flow should collect info for
walletAddress?: string, // Wallet address the flow should collect info for
intentionAction?: 'deposit' | 'withdrawal', // Which side of the flow is being opened
});Onboarding
AppIdentifier.ONBOARDING accepts an optional, Onboarding-only onboardingFlow param on openModal (ignored for every other app identifier). It selects which onboarding experience is rendered:
| Value | Enum | Experience |
|---|---|---|
| 'full_with_tax' | OnboardingFlow.FULL_WITH_TAX | Full onboarding, including the brokerage tax certification. Default when omitted. |
| 'full_without_tax' | OnboardingFlow.FULL_WITHOUT_TAX | Full onboarding, without the tax certification. |
| 'tax_only' | OnboardingFlow.TAX_ONLY | Tax certification only, for participants that are already onboarded. |
import { AppIdentifier, OnboardingFlow } from 'zh-web-sdk';
sdk.openModal({
appIdentifier: AppIdentifier.ONBOARDING,
jwt: "<JWT_TOKEN_HERE>",
onboardingFlow: OnboardingFlow.FULL_WITHOUT_TAX, // Optional: defaults to OnboardingFlow.FULL_WITH_TAX
});closeModal(appIdentifier)
Closes the modal for the specified app.
sdk.closeModal(AppIdentifier.FUND);By default the SDK keeps the injected DOM mounted after close (just hidden) so
re-opening is instant. To have the SDK remove everything it injected on every
close — leaving no leftover zerohash elements on your page — initialize with
destroyOnClose: true:
const sdk = new ZeroHashSDK({
zeroHashAppsURL: "https://web-sdk.zerohash.com/",
destroyOnClose: true, // unmount + remove injected nodes on every close
});With destroyOnClose on, closing via any path (the in-flow close button, a
backdrop click, an onClose, or a programmatic closeModal) unmounts the React
tree and removes the injected node; the next openModal re-injects a fresh one.
Only nodes the SDK created are torn down — if you passed your own
rootQuerySelector, that element is left untouched (it keeps the default
hide-and-reuse behavior).
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://sdk-cdn.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
