API Reference

Complete reference for ProphetXProvider props, all hooks, events, and exported types across React, React Native, and JavaScript SDKs.

The Flutter SDK (prophetx_sdk) mirrors the React Native surface — same provider, same options, same event payloads. Differences are called out per-section: hooks become ChangeNotifier flow controllers on ProphetX.of(context), callbacks fire on Dart Function types, and the event bus is a Dart Stream.

triangle-exclamation

useOnboarding/openOnboarding is not available. It used to combine terms + KYC + a first deposit, but the route is permanently gated off with an error screen today (the underlying Verified Inc API integration was never approved for that integration type). Use 1-Click Signup (useOneClickSignup) for new users instead, and Document verification (useKyc/useIdUpload) for re-verifying an existing user — see those sections below. onGeofenceBlocked is accepted by every flow, but it never fires on 1-Click Signup, which runs before a user exists. Its two arguments are currently always 'unknown'.

ProphetXProvider

Props

Environment

Pass a preset name or a custom config object:

NameEmbed URLAPI Base URL
"production"https://embed.prophetx.cohttps://isv-api.prophetx.co
"staging"https://isv-embed-fe-embed.vercel.apphttps://isv-api.staging.prophetx.dev
"sandbox"https://isv-embed-fe-embed-sandbox.vercel.apphttps://isv-api.sandbox.prophetx.dev

Custom config:

type EnvironmentConfig = {
  embedUrl: string;
  apiBaseUrl: string;
};

AuthConfig

Optional. When provided, the SDK manages authentication internally — you don't need to pass token yourself.

⚠️

The auth module logs in with POST {apiBaseUrl}/api/v1/auth/login, which isv-api doesn't serve. It can't log a user in against the ProphetX API today, so pass a backend-minted token instead (see Embedded UI).

FieldTypeRequiredDescription
apiBaseUrlstringYesAPI base URL for authentication requests.
refreshBufferSecondsnumberNoAuto-refresh the token this many seconds before expiry. Default: 30.
onAuthStateChanged(state: AuthState) => voidNoCalled whenever auth state changes.
getCredentials() => LoginCredentials | Promise<LoginCredentials>NoReturns credentials on demand for auto-refresh. Avoids storing plaintext credentials in memory.
storageStorageAdapterNoCustom storage adapter. Defaults to browser localStorage.
httpHttpAdapterNoCustom HTTP adapter. Defaults to fetch.
randomRandomAdapterNoCustom random number adapter.

Without getCredentials, the SDK can't log in again on its own: when the token expires, the auth state moves to expired and stays there until you call login().

On Flutter, AuthConfig also takes source (the __source header, default 'web') and devtools, and getCredentials must return a Future<LoginCredentials>.

DevToolsConfig

FieldTypeRequiredDescription
enabledbooleanNoEnable or disable devtools.
logLevel"none" | "error" | "warn" | "info" | "debug"NoLog level threshold.
redactPIIbooleanNoWhen true, masks tokens, passwords, and emails in log output.
onEvent(entry: DevToolsLogEntry) => voidNoCustom log sink — receives every log entry.

Deposit flow

Opens the deposit flow. The SDK renders a modal that handles the full deposit UI. React/React Native expose this via the useDeposit hook; the Flutter SDK exposes a DepositFlow controller on ProphetX.of(context).deposit.

Controller surface

SurfaceFieldTypeDescription
React / React Nativeopen(options?: OpenDepositOptions) => voidOpens the deposit modal.
React / React Nativeclose() => voidCloses the deposit modal programmatically.
React / React NativeisOpenbooleanWhether the deposit modal is currently open.
Flutteropen([OpenDepositOptions?]) => voidOpens the deposit modal.
Flutterclose() => voidCloses the deposit modal programmatically.
FlutterisOpenboolWhether the deposit modal is currently open. Notifies via ChangeNotifier.

OpenDepositOptions

OptionTypeDescription
onSuccess(transactionId: string, amount?: number) => voidFires when the deposit is accepted. The modal stays open on the success screen. Store transactionId on your backend.
onError(code: string, message: string) => voidFires on an error. message is for logs. See Error Codes.
onCancel() => voidFires when the modal closes — the user dismissed it, or tapped Close on the success or error screen.
onReady() => voidFires when the first screen has rendered (after payment methods load).
onGeofenceBlocked(stateCode: string, reason: string) => voidFires when the user's location blocks the flow as it opens. Both arguments are currently 'unknown'.
initialAmountnumberPre-fills the amount field. The user can still change it. Values that aren't a finite positive number are ignored.
successButtonLabelstringText for the success screen's button, in place of "Make Another Deposit". Trimmed, at most 40 characters, shown exactly as given (not translated). Setting it also makes the button close the modal instead of starting another deposit.
onSuccessAction() => voidFires when the user presses the success screen's button; then the modal closes. onCancel doesn't fire for that path.
appLinkstringReact Native and Flutter only. Your app's bare URL scheme, e.g. "myapp://". Needed on devices for Online Bank accounts whose bank login uses OAuth, and for Apple Pay and Google Pay: without it, the user is stuck on "Almost there!" after the bank login. Your app must handle the incoming link without navigating. The web SDKs ignore it.

The JavaScript SDK's OpenOptions also accepts token, theme, locale, and onSessionExpired per call, because it has no provider. It doesn't take appLink.

Withdraw flow

Opens the withdrawal flow. Follows the same pattern as the deposit flow above. React/React Native expose useWithdraw; Flutter exposes ProphetX.of(context).withdraw.

Controller surface

SurfaceFieldTypeDescription
React / React Nativeopen(options?: OpenWithdrawOptions) => voidOpens the withdraw modal.
React / React Nativeclose() => voidCloses the withdraw modal programmatically.
React / React NativeisOpenbooleanWhether the withdraw modal is currently open.
Flutteropen([OpenWithdrawOptions?]) => voidOpens the withdraw modal.
Flutterclose() => voidCloses the withdraw modal programmatically.
FlutterisOpenboolWhether the withdraw modal is currently open. Notifies via ChangeNotifier.

OpenWithdrawOptions

OptionTypeDescription
onSuccess(transactionId: string, amount?: number) => voidFires when the withdrawal is accepted. The modal stays open on the success screen. Store transactionId on your backend.
onError(code: string, message: string) => voidFires on an error. message is for logs. See Error Codes.
onCancel() => voidFires when the modal closes — the user dismissed it, or tapped Close on the success or error screen.
onReady() => voidFires when the first screen has rendered (after payment methods load).
onGeofenceBlocked(stateCode: string, reason: string) => voidFires when the user's location blocks the flow as it opens. Both arguments are currently 'unknown'.
initialAmountnumberPre-fills the amount field. The user can still change it. Values that aren't a finite positive number are ignored.
successButtonLabelstringText for the success screen's button, in place of "Make Another Withdrawal". Trimmed, at most 40 characters, shown exactly as given (not translated). Setting it also makes the button close the modal instead of starting another withdrawal.
onSuccessAction() => voidFires when the user presses the success screen's button; then the modal closes. onCancel doesn't fire for that path.
appLinkstringReact Native and Flutter only. Your app's bare URL scheme, e.g. "myapp://". Needed on devices for Online Bank accounts whose bank login uses OAuth: without it, the user is stuck on "Almost there!" after the bank login. Your app must handle the incoming link without navigating. The web SDKs ignore it.

1-Click Signup flow

triangle-exclamation

Replaces the old "Onboarding flow." useOnboarding/openOnboarding opened a combined terms + KYC + first-deposit experience that is not available in the current embed — the route is permanently gated off with an error screen, because the underlying Verified Inc API integration was never approved for that integration type. 1-Click Signup, documented below, is the real, live path for creating a new user from a phone number. It has a different contract: no token (it runs before a user exists), a backend-minted sessionKey instead, and onOneClick* callbacks rather than onKyc*. If you need terms acceptance too, open the Terms flow separately after redeeming the identity.

Creates a ProphetX user from a phone number in about ten seconds, with no signup form of your own. The user confirms their phone by one-time code inside Verified Inc's own hosted modal, reviews the identity Verified already holds for them, and shares it. Your backend redeems that identity and the user exists — KYC has not run yet at that point; it starts once your backend redeems the identity. React/React Native expose useOneClickSignup; Flutter exposes ProphetX.of(context).oneClickSignup.

This is the one flow with no embed token at all — it carries a single-use sessionKey (minted by your backend via POST /private/v1/one-click/sessions) instead.

Controller surface

SurfaceFieldTypeDescription
React / React Nativeopen(options: OpenOneClickSignupOptions) => voidOpens the modal. Unlike other flows, options are required — there's no opening this one without a sessionKey.
React / React Nativeclose() => voidCloses the modal programmatically.
React / React NativeisOpenbooleanWhether the modal is currently open.
Flutteropen(OpenOneClickSignupOptions) => voidOpens the modal. Options are required here too.
Flutterclose() => voidCloses the modal programmatically.
FlutterisOpenboolWhether the modal is currently open. Notifies via ChangeNotifier.

OpenOneClickSignupOptions

OptionTypeDescription
sessionKeystring (required)Single-use key from POST /private/v1/one-click/sessions. Consumed by one modal open — a spent or lapsed key must be re-minted.
environment'sandbox' | 'production' (required)Must match the environment the key was minted for. Passed straight to Verified's own SDK.
onOneClickSuccess(identityUuid: string) => voidAlways present — unlike document verification's KYC success, 1-Click always yields an identity.
onOneClickDeclined() => voidThe user chose not to share. Not an error — fall back to manual signup.
onOneClickFailed(reason: string, retryable?: boolean) => voidTerminal. retryable is true only when a fresh session key would help: INVALID_SESSION_KEY, SESSION_TIMEOUT, or SHARE_CREDENTIALS_ERROR. Everything else (no credentials found, risk score, exhausted attempts) can't be fixed by reopening.
onCancel() => voidFires when the modal closes, including from Close on the embed's outcome screens — so it can follow an outcome callback.
onError(code: string, message: string) => voidFires on any error. See Error Codes.
onReady() => voidFires when the flow has mounted.

There is no token or redirectUrl on this flow. onGeofenceBlocked is accepted but never fires here: 1-Click runs before a user exists, so there is no location check. On React Native and Flutter the outcome can arrive twice with the same values; act on the first one.

Terms flow

circle-info

There is no useTerms/openTerms hook. Terms acceptance is a standalone route, /tandc, that you show with the SDK's low-level component or a plain iframe. The embed itself doesn't block deposits or withdrawals on terms acceptance, and the SDK never reports a terms error: check the user's terms gate on your backend and show this route first when it isn't complete.

Messages this route sends

MessageWhenPayload
PROPHETX_READYOnce the terms document has loaded, or failed to load—
PROPHETX_SUCCESSThe user accepted. Also sent immediately, with no screen, when they had already accepted the current version{ transactionId: "tandc", amount: 0 }
PROPHETX_CANCELThe user tapped Close on the success page (the terms screen itself has no back or cancel control), or you sent PROPHETX_BACK—
PROPHETX_ERRORSession or origin problems only: SESSION_EXPIRED, SESSION_INVALID, ORIGIN_UNAUTHORIZED, UNCAUGHT_ERROR{ code, message }
PROPHETX_GEOFENCE_BLOCKEDLocation check fails{ stateCode, reason } (both "unknown")
PROPHETX_RESIZEContent height changes (document list length drives this){ height }

A failure to load or accept the terms doesn't send PROPHETX_ERROR: the embed shows its own error page with Try again. If the terms were republished while the user was reading (the accept call returns 409), the embed asks them to review the new version instead of showing an error.

What users see

  1. Document list. The documents come from GET /embed/v1/terms verbatim, with document types PRIVACY_POLICY, TERMS_OF_USE, MARKET_PARTICIPANT_AGREEMENT, RISK_DISCLOSURE_STATEMENT, RULEBOOK, each with a checkbox and a link to the full document. An "Accept all" checkbox toggles all documents at once. Continue stays disabled until every document is checked — there's no partial acceptance.
  2. Continue. Submits acceptance in a single request. The screen goes back to the same loading state as the initial fetch — a submit and a fetch look identical.
  3. Terminal state. Success shows a result page and sends PROPHETX_SUCCESS; failure shows an in-embed error page with Try Again (which restarts from the terms fetch, wiping any checked boxes).

Don't log or reconcile transactionId as a payment reference — it's the literal string "tandc", and amount: 0 doesn't mean a zero-value transaction; no money moves in this flow at all.

Document verification flow

triangle-exclamation

This is not a phone/OTP flow. A previous version of this page described useKyc as opening a phone-entry → SMS-OTP → PII-confirmation experience. That's Verified Inc's UI, and it's what 1-Click Signup uses (see above) — useKyc never opened it. useKyc opens a document-photo-upload flow reviewed by IDComply, described below.

For a user who already exists and whose automated KYC check came back FAILURE, this opens a government-ID photo upload reviewed by IDComply. React/React Native expose useKyc (a historical alias, kept for backward compatibility) and useIdUpload (the current preferred name) — both open the exact same flow. Flutter exposes ProphetX.of(context).idUpload.

This flow is narrow by design: it only reaches the document step for a user whose automated check actually came back FAILURE. Anyone already verified, still under review, or out of attempts sees the matching terminal screen within a second or two instead — that's expected behavior, not a bug. Gate any "Verify ID" entry point on the user's KYC status rather than showing it unconditionally.

Controller surface

SurfaceFieldTypeDescription
React / React Nativeopen(options?: OpenIdUploadOptions) => voidOpens the modal.
React / React Nativeclose() => voidCloses the modal programmatically.
React / React NativeisOpenbooleanWhether the modal is currently open.
Flutteropen([OpenIdUploadOptions?]) => voidOpens the modal.
Flutterclose() => voidCloses the modal programmatically.
FlutterisOpenboolWhether the modal is currently open. Notifies via ChangeNotifier.

OpenIdUploadOptions vs. OpenKycOptions

In React, React Native and Flutter these two option types are identical except for one field, redirectUrl — present on OpenIdUploadOptions, absent on OpenKycOptions. That's the one functional reason to prefer useIdUpload over the legacy useKyc alias: on native, a user who finishes in the device browser without a redirectUrl lands on the vendor's own web page instead of back in your app. On web there's no functional difference. (In the JavaScript SDK, openKyc and openIdUpload both take KycOpenOptions, which includes redirectUrl.)

OptionTypeDescription
redirectUrlstring — useIdUpload only, not on useKycAbsolute URL IDComply returns the user to when they finish. Defaults to an in-embed "you can close this" page. Only same-origin URLs and custom app schemes are used; any other URL is replaced by the default. Native apps must set this to a deep link (e.g. myapp://kyc/return) — otherwise the OS browser can't hand control back to your app.
onSuccess(transactionId: string, amount?: number) => voidNot emitted by this flow (no transaction) — present only for parity with the shared callbacks union.
onKycSuccess(identityUuid?: string) => voidFires when the document is verified, or immediately if the user was already verified. No identityUuid — the IDPV API returns none. You already have the user's UUID from POST /users.
onKycFailed(reason: string, retryable?: boolean) => voidFires when the user can't verify through this flow (compliance outcome or attempts exhausted). Always final: retryable is always false, because a photo the user can retake stays inside the modal and fires nothing. reason is for logging only.
onKycPending() => voidFires when the document was submitted but review hasn't resolved yet.
onError(code: string, message: string) => voidFires on any error. See Error Codes.
onCancel() => voidFires when the user closes the modal.
onReady() => voidFires when the flow has mounted.
onGeofenceBlocked(stateCode: string, reason: string) => voidSee the geofence note at the top of this page.

What users see

Once you call open():

  1. The embed reads the user's KYC status first. If they're not eligible (already verified, still under review, compliance-failed, or attempts exhausted), it stops here and shows the matching terminal screen — no attempt is consumed. All four ineligible cases answer the same 409 kyc_not_retryable from the API; the embed disambiguates by checking status first, so you just receive the resolved outcome.
  2. If eligible, it mints an IDComply session and opens the hosted form in a second browser tab — IDComply sets X-Frame-Options/frame-ancestors, so it cannot be shown in an iframe. There is no in-modal fallback.
  3. The modal shows a "Finish Verifying Your Identity" waiting screen and polls while the user is in the other tab. Document capture takes minutes, so this wait is deliberately generous.
  4. When the session finishes, the verdict resolves and the modal lands on a terminal screen, then fires the corresponding callback. Unlike 1-Click Signup, there's no further async step after this — by the time your callback fires, the decision is final.

Wallet

Fetches and returns the user's current wallet balance. Requires ProphetXProvider with an environment configured. React/React Native expose useWallet; Flutter exposes ProphetX.of(context).wallet (a ChangeNotifier).

Return value (React / React Native)

FieldTypeDescription
balanceWalletBalance | nullCurrent balance, or null if not yet fetched.
loadingbooleanWhether a fetch is in progress.
errorProphetXApiError | nullLast error, or null.
refetch() => Promise<void>Call to re-fetch the balance. Not automatic — call it on mount and after deposits/withdrawals.

WalletBalance

FieldTypeDescription
totalBalancenumberThe user's available balance.
currencystringCurrency code (e.g. "USD").

JavaScript SDK

The vanilla SDK exposes a wallet property on the SDK instance:

MethodTypeDescription
sdk.wallet.getBalance()() => Promise<WalletBalance>Returns the user's balance. sdk.wallet is null unless both auth and an environment are configured; since the auth module can't log in today, fetch the balance from your backend.

Flutter

ProphetX.of(context).wallet is a WalletClient that extends ChangeNotifier. Pair it with ListenableBuilder to react to balance / loading / error transitions.

FieldTypeDescription
balanceWalletBalance?Current balance, or null if not yet fetched.
loadingboolWhether a fetch is in progress.
errorObject?Last error, or null.
refetchFuture<WalletBalance?> Function()Re-fetches the balance. Call on mount and after deposits/withdrawals.

Auth

⚠️

isv-api doesn't serve the /api/v1/auth/login endpoint this module calls, so login() can't succeed against the ProphetX API today. Use a backend-minted token instead. This section documents the module as the SDKs expose it.

Manages user authentication. Requires ProphetXProvider with the auth prop configured. React/React Native expose useAuth; Flutter exposes ProphetX.of(context).auth (an AuthManager that extends ChangeNotifier).

Return value (React / React Native)

FieldTypeDescription
stateAuthStateCurrent authentication state. See AuthState.
login(credentials: LoginCredentials) => Promise<LoginResult>Authenticate with email and password.
logout() => voidClear the token and reset state.
tokenstring | nullCurrent JWT, or null if unauthenticated.
isAuthenticatedbooleanConvenience boolean — true when state.status === "authenticated".

AuthState

StatusFieldsDescription
"unauthenticated"—No active session.
"authenticating"—Login in progress.
"authenticated"token: string, expiresAt: numberActive session with a valid JWT.
"expired"lastToken: stringSession expired. Contains the last token for reference.
"error"error: ProphetXAuthErrorAuthentication failed.

LoginCredentials

FieldTypeRequiredDescription
emailstringYesUser's email address.
passwordstringYesUser's password.
deviceIdstringNoOptional device identifier.

LoginResult

FieldTypeDescription
tokenstringSigned JWT.
expiresAtnumberUnix timestamp in seconds (the JWT exp claim) when the token expires. Multiply by 1000 for a JavaScript Date.

ProphetXAuthError

FieldTypeDescription
type"AUTH_ERROR"Always "AUTH_ERROR".
code"INVALID_CREDENTIALS" | "NETWORK_ERROR" | "SERVER_ERROR" | "TIMEOUT"Error category.
messagestringHuman-readable error message.
statusnumber | undefinedHTTP status code, if applicable.

JavaScript SDK

The vanilla SDK exposes an auth property on the SDK instance:

MethodTypeDescription
sdk.auth.login(credentials)(LoginCredentials) => Promise<LoginResult>Authenticate.
sdk.auth.logout()() => voidClear the session.
sdk.auth.getToken()() => string | nullGet the current JWT.
sdk.auth.getState()() => AuthStateGet the current auth state.
sdk.auth.onStateChange(cb)(cb: (state: AuthState) => void) => () => voidSubscribe to state changes. Returns an unsubscribe function.
sdk.auth.handleSessionExpired()() => Promise<string | null>Re-authenticates using the getCredentials callback from AuthConfig.
sdk.auth.destroy()() => voidTear down the auth manager and clear timers.

sdk.auth is null if AuthConfig was not passed to createProphetX.

Flutter

ProphetX.of(context).auth is an AuthManager that extends ChangeNotifier. state is a sealed hierarchy (Unauthenticated, Authenticating, Authenticated, Expired, AuthError) — match on it with Dart 3 pattern syntax.

MemberTypeDescription
loginFuture<LoginResult> Function(LoginCredentials)Authenticate with email + password. Throws ProphetXAuthError.
logoutvoid Function()Clear the session.
tokenString?Current JWT, or null when not in the Authenticated state.
isAuthenticatedbooltrue when state is Authenticated.
stateAuthStateSealed hierarchy. See enum below.
handleSessionExpiredFuture<String?> Function()Re-authenticates using the getCredentials callback from AuthConfig. Used internally as the default onSessionExpired.

AuthState subtypes: Unauthenticated, Authenticating, Authenticated(token, expiresAt), Expired(lastToken), AuthError(error). expiresAt is Unix seconds (the JWT exp claim), the same as in the JavaScript SDKs.

ProphetXAuthError.code is the Dart enum AuthErrorCode { invalidCredentials, networkError, serverError, timeout }.

Events

Subscribes to all SDK events globally. Useful for analytics, logging, or cross-cutting concerns that apply regardless of which flow is open. React/React Native expose useEvents; Flutter exposes a broadcast Stream on ProphetX.of(context).events.

ProphetXEventHandlers (React / React Native)

All fields are optional. Pass only the events you care about.

HandlerPayloadDescription
onReady—The route's first screen rendered.
onSuccess{ transactionId: string, amount?: number }A flow succeeded.
onError{ code: string, message: string }An embed error, or SESSION_REFRESH_FAILED from the SDK.
onCancel—The modal closed.
onKycSuccess{ identityUuid?: string }Document verification passed (identityUuid is always absent).
onKycFailed{ reason: string, retryable?: boolean }Document verification failed; always final.
onKycPending—Document verification still under review.
onOneClickSuccess{ identityUuid: string }1-Click Signup: the user shared their identity.
onOneClickFailed{ reason: string, retryable?: boolean }1-Click Signup failed.
onOneClickDeclined—1-Click Signup: the user declined to share.
onGeofenceBlocked{ stateCode: string, reason: string }Location blocked when the flow opened.

Note: useEvents receives payload data as objects (e.g. { transactionId, amount }), while flow hook callbacks receive them as positional arguments (e.g. (transactionId, amount)). For successAction, open and close, subscribe on the emitter (see EventEmitter).

Flutter event types

The Flutter SDK uses a sealed ProphetXEvent hierarchy. Subscribe to a single subtype with events.on<T>(handler) or to the full union with events.stream.listen(...).

Event subtypeFieldsDescription
ReadyEvent—The route's first screen rendered.
SuccessEventtransactionId: String, amount: num?A flow succeeded.
SuccessActionEvent—The user pressed the success screen's button.
ErrorEventcode: String, message: StringAn error occurred.
CancelEvent—The modal closed.
KycSuccessEventidentityUuid: StringDocument verification passed.
KycFailedEventreason: StringDocument verification failed; always final.
KycPendingEvent—Document verification still under review.
OneClickSuccessEventidentityUuid: String1-Click Signup: the user shared their identity.
OneClickFailedEventreason: String1-Click Signup failed.
OneClickDeclinedEvent—1-Click Signup: the user declined to share.
GeofenceBlockedEventstateCode: String, reason: StringLocation blocked when the flow opened.
SessionExpiredEvent—The session token expired mid-flow.
SessionRefreshedEventtoken: StringA new session token was obtained after expiry.
FlowOpenEventflow: StringA flow opened. flow is the route path: "deposit", "withdraw", "onboarding", "verified" (from kyc), "id-upload", "one-click-signup", or "tandc".
FlowCloseEventflow: StringA flow closed. Same values.

ProphetXEmbed

Low-level modal component for React. Use it when you need direct control over the embed — for example to show the /tandc route — or to run a flow without ProphetXProvider. Most integrations should use the hooks above instead. React Native has its own low-level components; see React Native low-level components.

import { useRef } from "react";
import { ProphetXEmbed, MODAL_WIDTHS, type ProphetXEmbedHandle } from "@prophetx/sdk-react";

function CustomEmbed({ token }: { token: string }) {
  const ref = useRef<ProphetXEmbedHandle>(null);

  return (
    <ProphetXEmbed
      ref={ref}
      open={true}
      onOpenChange={(open) => console.log("Open state:", open)}
      src="https://embed.prophetx.co/deposit"
      token={token}
      title="Deposit"
      width={MODAL_WIDTHS.deposit}
      theme={{ primaryColor: "#e91e63" }}
      onSuccess={(transactionId, amount) => console.log("Success:", transactionId, amount)}
      onError={(code, message) => console.error("Error:", code, message)}
      onCancel={() => console.log("Closed")}
      onReady={() => console.log("Ready")}
      onSessionExpired={async () => fetchToken()}
    />
  );
}

Props

PropTypeRequiredDescription
openbooleanYesControls whether the modal is visible.
onOpenChange(open: boolean) => voidYesCalled when the open state should change (e.g. the user closes the modal).
srcstringYesFull URL of the embed route to load, e.g. https://embed.prophetx.co/deposit.
tokenstringNoPartner session JWT. Leave it out only for 1-Click Signup, which uses a session key instead.
titlestringNoAccessible title for the modal.
widthnumberNoModal width in pixels. Defaults to 480. Pass MODAL_WIDTHS[route] — 1-Click Signup needs 396.
themeEmbedThemeNoTheme overrides. Re-sent to an open modal only when primaryColor or backgroundColor changes.
localestringNoBCP 47 locale tag ("en", "es"). Sent via PROPHETX_LOCALE. Defaults to "en".
onSuccess(transactionId: string, amount?: number) => voidNoThe flow succeeded. The modal stays open on the success screen.
onSuccessAction() => voidNoThe user pressed the success screen's button; the modal then closes and onCancel doesn't fire. Only sent when src includes successAction=1.
onError(code: string, message: string) => voidNoAn error occurred. message is for logs.
onCancel() => voidNoThe modal closed.
onReady() => voidNoThe route's first screen rendered.
onGeofenceBlocked(stateCode: string, reason: string) => voidNoLocation blocked when the flow opened. Both arguments are currently 'unknown'.
onKycSuccess(identityUuid?: string) => voidNoDocument verification passed (identityUuid is always absent).
onKycFailed(reason: string, retryable?: boolean) => voidNoDocument verification failed; always final.
onKycPending() => voidNoDocument verification still under review.
onOneClickSuccess(identityUuid: string) => voidNo1-Click Signup: the user shared their identity.
onOneClickFailed(reason: string, retryable?: boolean) => voidNo1-Click Signup failed.
onOneClickDeclined() => voidNo1-Click Signup: the user declined to share.
onSessionExpired() => Promise<string | null>NoReturn a fresh JWT within 10 seconds, or null to stop.
emitterEventEmitterNoAdvanced: an event emitter to publish events on (the provider passes its own).
devtoolsDevToolsNoAdvanced: a devtools logger.

MODAL_WIDTHS (per-route widths) and DEFAULT_MODAL_WIDTH (480) are exported from @prophetx/sdk-react for sizing the modal the way the provider does.

ProphetXEmbedHandle (ref)

Access the imperative handle via useRef<ProphetXEmbedHandle>:

MethodTypeDescription
sendMessage(message: { type: string; payload?: unknown }) => voidSend a raw postMessage to the iframe.
reload() => voidReload the iframe.

React Native low-level components

@prophetx/sdk-react-native exports the pieces ProphetXProvider is built from:

ExportWhat it is
ProphetXWebViewThe embed in a WebView, with no modal around it. Props: embedUrl and route (an EmbedRoute: "deposit", "withdraw", "id-upload", "one-click-signup", "tandc", …) are required, plus token (or sessionKey and environment for 1-Click), theme, locale, the flow options (appLink, initialAmount, successButtonLabel, redirectUrl) and every flow callback.
ProphetXWebViewHandleIts ref: sendMessage(message), reload(), goBack().
ProphetXModalProphetXWebView inside the SDK's native modal. Adds visible, onRequestClose, and optional animationType ("none", "slide", "fade") and presentationStyle ("fullScreen", "pageSheet", "formSheet", "overFullScreen").
PoweredByProphetXThe "Powered by ProphetX" mark, for your own chrome. Also exported by @prophetx/sdk-react.

Flutter has the same pieces: ProphetXWebView (with ProphetXWebViewState), ProphetXModal and PoweredByProphetX.

JavaScript SDK instance

The object returned by createProphetX().

Method / PropertyTypeDescription
openDeposit(opts)(OpenOptions) => voidOpen the deposit flow.
openWithdraw(opts)(OpenOptions) => voidOpen the withdraw flow.
openOneClickSignup(opts)(OneClickOpenOptions) => voidOpen the 1-Click Signup flow (new users). opts is required — needs sessionKey/environment.
openKyc(opts) / openIdUpload(opts)(KycOpenOptions) => voidOpen the document verification flow (existing users). Same flow, two names.
openOnboarding(opts)(KycOpenOptions) => voidOpens the onboarding route, which is permanently unavailable: it shows a notice, sends onReady, then onCancel on Close. Don't use it.
close()() => voidClose any open flow.
destroy()() => voidTear down the SDK — removes DOM elements, clears listeners, destroys auth manager. The instance is unusable afterwards.
updateTheme(theme)(EmbedTheme) => voidSend a new theme to the open flow. Does nothing when no flow is open, and isn't kept for the next flow.
updateLocale(locale)(locale: string) => voidSend a new locale ("en", "es") to the open flow. Does nothing when no flow is open.
on(event, handler)See EventEmitterSubscribe to an event. Returns an unsubscribe function.
off(event, handler)See EventEmitterUnsubscribe from an event.
authAuthManager | nullAuth manager instance. null if auth was not provided.
walletWalletClient | nullWallet client instance. null unless both auth and an environment are configured.

Every open* call throws "No token provided" when you pass no token and haven't configured auth.

OpenOptions (JavaScript SDK)

Used by openDeposit and openWithdraw.

OptionTypeDescription
tokenstringSession JWT. Required unless using the auth module.
themeEmbedThemeTheme for this flow.
localestringBCP 47 locale tag ("en", "es"). Defaults to "en".
initialAmountnumberPre-fills the amount field.
successButtonLabelstringText for the success screen's button (at most 40 characters, not translated).
onSuccessAction() => voidThe user pressed the success screen's button; the modal then closes.
onSuccess(transactionId: string, amount?: number) => voidThe deposit or withdrawal was accepted. The modal stays open.
onError(code: string, message: string) => voidAn error occurred. message is for logs.
onCancel() => voidThe modal closed.
onReady() => voidThe first screen rendered.
onGeofenceBlocked(stateCode: string, reason: string) => voidLocation blocked when the flow opened.
onSessionExpired() => Promise<string | null>Return a fresh JWT within 10 seconds, or null to stop.

KycOpenOptions (JavaScript SDK)

Used by openKyc, openIdUpload and openOnboarding.

OptionTypeDescription
tokenstringSession JWT. Required unless using the auth module.
themeEmbedThemeTheme for this flow.
localestringBCP 47 locale tag ("en", "es"). Defaults to "en".
redirectUrlstringWhere IDComply sends the user when they finish. Only same-origin URLs and custom app schemes are used.
onKycSuccess(identityUuid?: string) => voidDocument verified (or already verified). identityUuid is always absent.
onKycFailed(reason: string, retryable?: boolean) => voidThe user can't verify through this flow. Always final.
onKycPending() => voidReview still in progress.
onError(code: string, message: string) => voidAn error occurred.
onCancel() => voidThe modal closed.
onReady() => voidThe flow mounted.
onGeofenceBlocked(stateCode: string, reason: string) => voidLocation blocked when the flow opened.
onSessionExpired() => Promise<string | null>Return a fresh JWT within 10 seconds, or null to stop.

The type also accepts onOneClickSuccess, onOneClickFailed and onOneClickDeclined, which only fire on 1-Click Signup.

OneClickOpenOptions (JavaScript SDK)

Used by openOneClickSignup. It is KycOpenOptions without token, redirectUrl and onSessionExpired, plus:

OptionTypeDescription
sessionKeystring (required)Single-use key from POST /private/v1/one-click/sessions.
environment'sandbox' | 'production' (required)Must match the key's environment.

Use onOneClickSuccess, onOneClickFailed and onOneClickDeclined for the outcome — see OpenOneClickSignupOptions.

Events

The SDK has three event layers. Most integrations only use callback events (passed to open()). Use the EventEmitter for global analytics or logging. Use the postMessage protocol only if building a custom integration without the SDK.

Callback events

Passed as options to open() on each flow hook. See the individual hook sections above for the full list per flow.

Summary of all callback events across flows:

CallbackAvailable onPayload
onSuccessDeposit, withdraw (and /tandc)(transactionId: string, amount?: number) — never sent by document verification or 1-Click Signup
onSuccessActionDeposit, withdraw—
onErrorAll flows(code: string, message: string)
onCancelAll flows—
onReadyAll flows—
onGeofenceBlockedAll flows (never fires on 1-Click Signup)(stateCode: string, reason: string) — both currently 'unknown'
onOneClickSuccessuseOneClickSignup(identityUuid: string)
onOneClickDeclineduseOneClickSignup—
onOneClickFaileduseOneClickSignup(reason: string, retryable?: boolean)
onKycSuccessuseKyc, useIdUpload(identityUuid?: string) — always absent
onKycFaileduseKyc, useIdUpload(reason: string, retryable?: boolean) — retryable always false
onKycPendinguseKyc, useIdUpload—

EventEmitter

A typed pub/sub system available in all four SDKs. In React/React Native, use useEvents (or the emitter's events below); in JavaScript, use sdk.on() / sdk.off(); in Flutter, use ProphetX.of(context).events.

Event namePayload typeDescription
ready—The route's first screen rendered.
success{ transactionId: string; amount?: number }A flow succeeded.
successAction—The user pressed the deposit/withdraw success button. The modal closes after it.
error{ code: string; message: string }An embed error, or SESSION_REFRESH_FAILED when your onSessionExpired handler throws.
cancel—The modal closed.
kycSuccess{ identityUuid?: string }Document verification passed (identityUuid is always absent).
kycFailed{ reason: string; retryable?: boolean }Document verification failed; always final.
kycPending—Document verification still under review.
oneClickSuccess{ identityUuid: string }1-Click Signup: the user shared their identity.
oneClickFailed{ reason: string; retryable?: boolean }1-Click Signup failed.
oneClickDeclined—1-Click Signup: the user declined to share.
geofenceBlocked{ stateCode: string; reason: string }Location blocked when the flow opened.
resize{ height: number }Embed content height changed.
sessionExpired—The session token expired mid-flow.
sessionRefreshed{ token: string }A new session token was obtained after expiry.
open{ flow: string }A flow opened. flow is the route path: "deposit", "withdraw", "onboarding", "verified" (opened by useKyc/openKyc), "id-upload", or "one-click-signup".
close{ flow: string }A flow closed. Same values.

EventEmitter API:

// Subscribe — returns an unsubscribe function
const unsub = sdk.on("success", ({ transactionId, amount }) => { ... });

// Unsubscribe by reference
sdk.off("success", handler);

// Unsubscribe via return value
unsub();

postMessage protocol

Raw messages exchanged between the host page and the ProphetX iframe via window.postMessage. The SDK handles these automatically — use this reference only if you are building a custom integration without the SDK.

Outbound messages (iframe to host)

These messages are sent by the ProphetX embed to your page. Full detail is in the postMessage Protocol.

Message typePayloadDescription
PROPHETX_EMBED_LOADED—The iframe mounted. Always first; reply with PROPHETX_SESSION. Sent to '*'.
PROPHETX_READY—The route's first screen rendered.
PROPHETX_SUCCESS{ transactionId: string; amount?: number }A flow succeeded. The embed stays on its success screen.
PROPHETX_SUCCESS_ACTION—The user pressed the success button (only when the URL has successAction=1). Close the iframe.
PROPHETX_ERROR{ code: string; message: string }An error occurred. message is for logs.
PROPHETX_CANCEL—The user closed the flow. Remove the iframe.
PROPHETX_RESIZE{ height: number; width?: number }Content size changed. width is sent by 1-Click Signup only.
PROPHETX_GEOFENCE_BLOCKED{ stateCode: string; reason: string }Location blocked when the flow opened. Both values are currently "unknown". Never sent by 1-Click Signup.
PROPHETX_KYC_SUCCESS{ identityUuid?: string }Document verification passed. identityUuid is always absent. Final.
PROPHETX_KYC_FAILED{ reason: string; retryable?: boolean }Document verification failed. retryable is always false.
PROPHETX_KYC_PENDING{}Document submitted, review not yet resolved.
PROPHETX_ONE_CLICK_SUCCESS{ identityUuid: string }1-Click Signup: the user shared their identity. KYC hasn't run yet — redeem via POST /private/v1/users/one-click to start it.
PROPHETX_ONE_CLICK_FAILED{ reason: string; retryable?: boolean }1-Click Signup: terminal failure. retryable is true only when a fresh session key would help.
PROPHETX_ONE_CLICK_DECLINED{}1-Click Signup: the user chose not to share. Not an error.
PROPHETX_SESSION_EXPIRED—An API call in the open flow returned 401. Reply with PROPHETX_SESSION_REFRESH within 10 seconds.
PROPHETX_HEADER_UPDATE{ title: string; showBack: boolean }Defined, but the embed doesn't send it.

Inbound messages (host to iframe)

Send these messages to the ProphetX iframe:

Message typePayloadDescription
PROPHETX_SESSION{ token: string }Provide the session JWT. Only the first one is accepted.
PROPHETX_SESSION_REFRESH{ token: string }Provide a refreshed JWT after PROPHETX_SESSION_EXPIRED. Ignored at any other time.
PROPHETX_THEMEEmbedThemeSet or replace the embed's theme.
PROPHETX_LOCALE{ locale: string }Set the language: "en" or "es" (others fall back to "en").
PROPHETX_BACK—Cancel the current flow. Deposit, withdraw and Terms reply with PROPHETX_CANCEL; other routes ignore it.
PROPHETX_CLOSE—Accepted, but has no effect today. Remove the iframe to close.

Example — listening without the SDK:

window.addEventListener("message", (event) => {
  // Validate origin and source
  if (event.origin !== "https://embed.prophetx.co") return;
  if (event.source !== iframe.contentWindow) return;

  const { type, payload } = event.data;

  switch (type) {
    case "PROPHETX_READY":
      console.log("Embed ready");
      break;
    case "PROPHETX_SUCCESS":
      console.log("Transaction:", payload.transactionId, payload.amount);
      break;
    case "PROPHETX_ERROR":
      console.error("Error:", payload.code, payload.message);
      break;
    case "PROPHETX_CANCEL":
    case "PROPHETX_SUCCESS_ACTION":
      iframe.remove(); // the flow is over
      break;
    case "PROPHETX_SESSION_EXPIRED":
      // Fetch a new token and send it back within 10 seconds
      fetchToken().then((token) => {
        iframe.contentWindow.postMessage(
          { type: "PROPHETX_SESSION_REFRESH", payload: { token } },
          "https://embed.prophetx.co"
        );
      });
      break;
  }
});

EmbedTheme

Theme overrides applied to the embed UI. Pass via the theme prop on ProphetXProvider (React/React Native), as part of OpenOptions (JavaScript SDK), or dynamically via sdk.updateTheme().

type EmbedTheme = {
  primaryColor?: string;
  backgroundColor?: string;
  colorOverrides?: Partial<ColorOverrides>;
  spacingOverrides?: Partial<SpacingOverrides>;
  radiusOverrides?: Partial<RadiusOverrides>;
  fontSizeOverrides?: Partial<FontSizeOverrides>;
};

Top-level fields

FieldTypeDescription
primaryColorstringPrimary brand color. Applied to primary, primaryHover, cta, and ctaHover — but only when colorOverrides is empty. Once colorOverrides has any keys, primaryColor is ignored.
backgroundColorstringReact Native and Flutter only: the background of the native modal around the embed. The web embed ignores it.

There is no mode field. The embed always starts from the ProphetX dark palette; for a light look, send a full light palette in colorOverrides (the Theming Guide has one to copy).

colorOverrides

Fine-grained color tokens. All fields are optional CSS color strings.

TokenDescription
primaryPrimary brand color
primaryHoverHover state for primary elements
primaryForegroundText/icon color on primary backgrounds
secondarySecondary color
secondaryHoverHover state for secondary elements
backgroundInput fields and inset panels
surfaceEmbed background and cards
surfaceElevatedElevated surface (modals, dropdowns)
textDefault text color
textMutedDe-emphasized text
textSubtleLeast prominent text (placeholders, hints)
borderDefault border color
borderSubtleSubtle border (dividers, separators)
errorError text/icon color
errorBackgroundError background (alerts, badges)
successSuccess text/icon color
successBackgroundSuccess background
warningWarning text/icon color
warningBackgroundWarning background
ctaCall-to-action button color
ctaHoverCTA hover state
ctaForegroundText on CTA buttons
filledFilled/solid button color
filledHoverFilled button hover state
filledForegroundText on filled buttons
dangerDestructive action color
dangerHoverDestructive action hover state
dangerForegroundText on destructive action buttons

spacingOverrides

TokenDescription
xsExtra-small spacing
smSmall spacing
mdMedium spacing
lgLarge spacing
xlExtra-large spacing

radiusOverrides

TokenDescription
smSmall border radius
mdMedium border radius
lgLarge border radius
fullFully rounded (pill shape)

fontSizeOverrides

TokenDescription
xsExtra-small font size
smSmall font size
mdMedium (base) font size
lgLarge font size
xlExtra-large font size

DevToolsLogEntry

Entries emitted by the devtools system. Receive them via DevToolsConfig.onEvent.

FieldTypeDescription
timestampnumberUnix timestamp (ms).
category"auth" | "message" | "api" | "lifecycle" | "event"Log category.
level"error" | "warn" | "info" | "debug"Severity level.
messagestringHuman-readable log message.
dataRecord<string, unknown> | undefinedOptional structured data.

Type exports

All types are exported from the SDK package you're using. Import them alongside components and hooks. The lists below are exactly what each package exports.



Did this page help you?