Overview

All notable changes to the zerohash Web SDK will be documented in this file.

This project adheres to Semantic Versioning.

[3.12.1]

Removed

• The npm package no longer includes the dist/index.js.map source map. It also no longer includes the declaration files for tests, mocks and test utilities (dist/__tests__/, dist/__mocks__/, dist/utils/test-utils.d.ts). The runtime bundle and the public types do not change. You do not need to change your integration.

[3.12.0]

Added

• openModal accepts a new optional onboardingFlow parameter for the Onboarding flow. Use the new exported OnboardingFlow enum to set it:

  • full_with_tax: full onboarding with the tax certification. This is the default when you omit the parameter.
  • full_without_tax: full onboarding without the tax certification.
  • tax_only: the tax certification only, for participants who are already onboarded.

  Other app identifiers ignore this parameter. See User Onboarding.

[3.11.1]

Fixed

• Constructing more than one ZeroHashSDK on a page (for example, when the component that creates it remounts between opens) no longer stacks a hidden copy of the widget for every instance. Previously each later open rendered one copy per instance ever created, all loading in the background with the same JWT, which duplicated backend calls and sessions. All instances now share a single widget per app. No integration changes are needed to pick up the fix.

[3.11.0]

Added

• openModal now forwards a new intentionAction ('deposit' | 'withdrawal') param to the Travel Rule flow, alongside the existing depositId and walletAddress, so Travel Rule can be opened in withdrawal mode.

Changed

• Bumped @zerohash-sdk/travel-rule-react to ^0.6.0, which forwards intentionAction to the Travel Rule widget.

[3.9.1]

Changed

• The SDK modal no longer closes when the user clicks the backdrop (the dimmed area outside the widget). It now closes only via the in-flow close button (X), preventing a session from being accidentally discarded by a click outside the modal.

[3.9.0]

Added

• Exported typed message unions CryptoWithdrawalsMessage and CryptoDepositsMessage (plus the payload types CryptoWithdrawalsCompletedData, CryptoDepositsCompletedData, CryptoWithdrawalsEvent, CryptoDepositsEvent, CryptoDepositData, and WidgetErrorPayload). Integrators listening for widget postMessage events on the host window can now narrow on message.type with full payload typing. Payload shapes are derived from the underlying @zerohash-sdk/*-react packages, so they stay in sync with the version this SDK ships.

[3.8.0]

Added

• New Crypto Deposits flow, letting integrators deposit crypto from external wallets through the SDK. Open with sdk.openModal({ appIdentifier: 'crypto-deposits', jwt }), or preload the JWT via the new cryptoDepositsJWT constructor option. Emits the standard CRYPTO_DEPOSITS_APP_LOADED, CRYPTO_DEPOSITS_CLOSE_BUTTON_CLICKED, CRYPTO_DEPOSITS_COMPLETED, and CRYPTO_DEPOSITS_FAILED events.

[3.7.0]

Changed

• zeroHashAppsURL is now optional. The SDK resolves the apps URL and environment from whichever of env / zeroHashAppsURL you provide: with neither it defaults to prod; with env alone it derives the matching URL; with zeroHashAppsURL alone it infers the environment from the URL (unchanged). Existing integrations that pass zeroHashAppsURL are unaffected.

[3.6.1]

Added

• New destroyOnClose constructor option. When true, closing a modal (via the in-flow close button, a backdrop click, onClose, or a programmatic closeModal) unmounts its React tree and removes the DOM node the SDK injected, so no leftover zerohash elements stay on the host page. Defaults to false (previous "hide and reuse" behavior). Only SDK-created nodes are removed — a partner-provided rootQuerySelector element is left in place.

[3.5.1] - 2026-08-17

Changed

• Documented the env initialization option: omit it to target production ('prod'), and note that it is init-only — read once when the SDK is constructed and cannot be changed afterwards.

[3.4.3]

Fixed

• The modal now renders the new @zerohash-sdk/* UI whenever the JWT enables it, even when the token was set through the constructor or an earlier setJWT instead of passed straight to openModal. Those integrations previously fell back to the legacy iframe. No integration changes are needed to pick up the fix.

[3.4.0]

Added

• New walletAddress option on sdk.openModal, used by the Travel Rule flow to identify which wallet address the flow should collect travel-rule information for. Ignored by every other app identifier. Works the same way as the existing depositId option.

Changed

• Bumped @zerohash-sdk/travel-rule-react to ^0.2.2, the first version exposing the walletAddress prop this option forwards.

[3.2.0] - 2026-07-13

Added

• New Travel Rule flow, letting integrators collect travel-rule information for a deposit through the SDK. Open with sdk.openModal({ appIdentifier: 'travel-rule', jwt, depositId }), or preload the JWT via the new travelRuleJWT constructor option. Emits the standard TRAVEL_RULE_APP_LOADED, TRAVEL_RULE_CLOSE_BUTTON_CLICKED, TRAVEL_RULE_COMPLETED, and TRAVEL_RULE_FAILED events.
• New depositId option on sdk.openModal, used by the Travel Rule flow to identify which deposit the flow should collect travel-rule information for. Ignored by every other app identifier.

[3.1.2] - 2026-06-19

Fixed

• Crypto Buy now honours filters set via sdk.setFilters or sdk.openModal when rendering through the next-generation path. Filters were previously applied on the existing iframe path but silently ignored on the next-generation path. No API changes, existing filters configurations resume working as documented.

[3.1.0] - 2026-06-17

Added

• Trusted additional CDN origins used by next-generation widgets. The previously trusted origins remain valid during the migration, no integrator action required.

Changed

• Updated bundled @zerohash-sdk/*-react and @connect-xyz/auth-react packages to their latest versions.

[3.0.1] - 2026-06-12

Changed

• Updated bundled @zerohash-sdk/*-react and @connect-xyz/auth-react packages. Includes improved error handling and clearer messaging when an embedded widget fails to load its scripts.

[3.0.0] - 2026-05-21

Major version bump signalling the rollout of a next-generation rendering path for zerohash widgets. The public SDK API is unchanged for cert and prod consumers, the only public-type change is a narrowing of env (see Changed).

Added

• Next-generation rendering for Crypto Buy/Sell, Onboarding, Fiat Deposits/Withdrawals, Crypto Withdrawals, Fund, Pay, Payouts, Profile, and Account Link flows. Improved performance and UX. Rollout is gradual and controlled server-side, no integration changes required, and flows not yet migrated continue to render via the existing iframe.
• theme option on the SDK constructor ('light' | 'dark' | 'auto', defaults to 'light') and a matching sdk.setTheme({ theme }) method. Applies to the next-generation flows; the existing iframe and Fund Connect Auth surfaces are unchanged.
• env option on the SDK constructor ('cert' | 'prod') for explicit environment selection. When set, it takes precedence over the SDK's hostname-based inference. This is now the recommended way to target a specific deployment.
• The SDK version is now attached to embedded widget logs to make support investigations faster.

Changed

• Breaking (TypeScript surface only): narrowed the public Environment type from 'dev' | 'cert' | 'prod' to 'cert' | 'prod'. The 'dev' value was never intended for integrator use. Consumers on cert or prod do not need to make any changes.

Fixed

• Environment auto-detection now recognises the full set of zerohash hostnames used by integrators. Previously, some cert setups silently fell back to loading production assets. If you've ever been unsure which environment the SDK was targeting, we recommend passing the new env option explicitly.
• Removed a brief wrong-theme flash when opening a next-generation flow in dark or auto mode. The modal also now becomes visible as soon as the inner widget reports it has loaded, instead of waiting on a multi-second fallback. Light mode and the existing iframe flow are unchanged.
• Fixed Fund's Connect Auth flow targeting the production Connect API when the host page was running against a non-production deployment. The Connect environment is now resolved from the same source as the next-generation widgets, explicit env first, otherwise hostname-based inference.

Security

• Tightened the Fund Connect Auth issuer check to use a strict hostname allowlist instead of a permissive substring match.

[2.16.1] - 2026-02-23

Added

• Bump connect-xyz version to 0.46.0 to fix a problem for Auth into Fund users where the UI was taking too long to be displayed

[2.16.0] - 2026-02-22

Added

• Add dynamic styles for "Auth into Fund" integration
• This allows customizing Modal appearance without requiring customers to bump their SDK version

[2.15.0] - 2026-02-18

Added

• Add dynamic styles for "iframe" SDKs via postMessage
• This allows customizing Modal appearance without requiring customers to bump their SDK version

[2.14.0] - 2026-01-16

Added

• Allow existing Fund customers to integrate with Auth seamlessly
  • Existing Fund customers shall now be able to use Auth integrations aside from Manual deposit.
    Auth does not rely on an iframe, has dark and light mode, improved UI, and improved performance.

[2.13.0] - 2026-01-02

Changed

• Changes SDK wrapper positioning to fixed to prevent it being scrolled out of view by the parent application

[2.12.6] - 2025-10-27

Security

• Addressed security vulnerabilities identified by automated dependency scanning
• Updated multiple dependencies to their latest secure versions

[2.12.5] - 2025-10-22

Changed

• Restored original fiat-account-link terminology for existing integrations

[2.12.4] - 2025-10-21

Fixed

• Improved border styling consistency between mobile and desktop views

[2.12.3] - 2025-10-01

Changed

• Updated Fiat Account Link terminology to better reflect the feature's purpose

[2.12.2] - 2025-09-30

Added

• New fiat account linking feature for connecting bank accounts

[2.12.1] - 2025-09-11

Fixed

• Refined corner styling and border radius for improved visual consistency

[2.12.0] - 2025-07-07

Added

• Introduced support for new "PAY" application name

[2.11.2] - 2025-07-02

Changed

• Improved integration with World App's MiniKit for better mobile experience

[2.11.1] - 2025-07-02

Changed

• Enhanced World App message handling with improved error recovery