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 becomeChangeNotifierflow controllers onProphetX.of(context), callbacks fire on DartFunctiontypes, and the event bus is a DartStream.
useOnboarding/openOnboardingis 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.onGeofenceBlockedis 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:
| Name | Embed URL | API Base URL |
|---|---|---|
"production" | https://embed.prophetx.co | https://isv-api.prophetx.co |
"staging" | https://isv-embed-fe-embed.vercel.app | https://isv-api.staging.prophetx.dev |
"sandbox" | https://isv-embed-fe-embed-sandbox.vercel.app | https://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-mintedtokeninstead (see Embedded UI).
| Field | Type | Required | Description |
|---|---|---|---|
apiBaseUrl | string | Yes | API base URL for authentication requests. |
refreshBufferSeconds | number | No | Auto-refresh the token this many seconds before expiry. Default: 30. |
onAuthStateChanged | (state: AuthState) => void | No | Called whenever auth state changes. |
getCredentials | () => LoginCredentials | Promise<LoginCredentials> | No | Returns credentials on demand for auto-refresh. Avoids storing plaintext credentials in memory. |
storage | StorageAdapter | No | Custom storage adapter. Defaults to browser localStorage. |
http | HttpAdapter | No | Custom HTTP adapter. Defaults to fetch. |
random | RandomAdapter | No | Custom 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
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Enable or disable devtools. |
logLevel | "none" | "error" | "warn" | "info" | "debug" | No | Log level threshold. |
redactPII | boolean | No | When true, masks tokens, passwords, and emails in log output. |
onEvent | (entry: DevToolsLogEntry) => void | No | Custom 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
| Surface | Field | Type | Description |
|---|---|---|---|
| React / React Native | open | (options?: OpenDepositOptions) => void | Opens the deposit modal. |
| React / React Native | close | () => void | Closes the deposit modal programmatically. |
| React / React Native | isOpen | boolean | Whether the deposit modal is currently open. |
| Flutter | open | ([OpenDepositOptions?]) => void | Opens the deposit modal. |
| Flutter | close | () => void | Closes the deposit modal programmatically. |
| Flutter | isOpen | bool | Whether the deposit modal is currently open. Notifies via ChangeNotifier. |
OpenDepositOptions
| Option | Type | Description |
|---|---|---|
onSuccess | (transactionId: string, amount?: number) => void | Fires when the deposit is accepted. The modal stays open on the success screen. Store transactionId on your backend. |
onError | (code: string, message: string) => void | Fires on an error. message is for logs. See Error Codes. |
onCancel | () => void | Fires when the modal closes — the user dismissed it, or tapped Close on the success or error screen. |
onReady | () => void | Fires when the first screen has rendered (after payment methods load). |
onGeofenceBlocked | (stateCode: string, reason: string) => void | Fires when the user's location blocks the flow as it opens. Both arguments are currently 'unknown'. |
initialAmount | number | Pre-fills the amount field. The user can still change it. Values that aren't a finite positive number are ignored. |
successButtonLabel | string | Text 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 | () => void | Fires when the user presses the success screen's button; then the modal closes. onCancel doesn't fire for that path. |
appLink | string | React 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
OpenOptionsalso acceptstoken,theme,locale, andonSessionExpiredper call, because it has no provider. It doesn't takeappLink.
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
| Surface | Field | Type | Description |
|---|---|---|---|
| React / React Native | open | (options?: OpenWithdrawOptions) => void | Opens the withdraw modal. |
| React / React Native | close | () => void | Closes the withdraw modal programmatically. |
| React / React Native | isOpen | boolean | Whether the withdraw modal is currently open. |
| Flutter | open | ([OpenWithdrawOptions?]) => void | Opens the withdraw modal. |
| Flutter | close | () => void | Closes the withdraw modal programmatically. |
| Flutter | isOpen | bool | Whether the withdraw modal is currently open. Notifies via ChangeNotifier. |
OpenWithdrawOptions
| Option | Type | Description |
|---|---|---|
onSuccess | (transactionId: string, amount?: number) => void | Fires when the withdrawal is accepted. The modal stays open on the success screen. Store transactionId on your backend. |
onError | (code: string, message: string) => void | Fires on an error. message is for logs. See Error Codes. |
onCancel | () => void | Fires when the modal closes — the user dismissed it, or tapped Close on the success or error screen. |
onReady | () => void | Fires when the first screen has rendered (after payment methods load). |
onGeofenceBlocked | (stateCode: string, reason: string) => void | Fires when the user's location blocks the flow as it opens. Both arguments are currently 'unknown'. |
initialAmount | number | Pre-fills the amount field. The user can still change it. Values that aren't a finite positive number are ignored. |
successButtonLabel | string | Text 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 | () => void | Fires when the user presses the success screen's button; then the modal closes. onCancel doesn't fire for that path. |
appLink | string | React 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
Replaces the old "Onboarding flow."
useOnboarding/openOnboardingopened 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: notoken(it runs before a user exists), a backend-mintedsessionKeyinstead, andonOneClick*callbacks rather thanonKyc*. 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
| Surface | Field | Type | Description |
|---|---|---|---|
| React / React Native | open | (options: OpenOneClickSignupOptions) => void | Opens the modal. Unlike other flows, options are required — there's no opening this one without a sessionKey. |
| React / React Native | close | () => void | Closes the modal programmatically. |
| React / React Native | isOpen | boolean | Whether the modal is currently open. |
| Flutter | open | (OpenOneClickSignupOptions) => void | Opens the modal. Options are required here too. |
| Flutter | close | () => void | Closes the modal programmatically. |
| Flutter | isOpen | bool | Whether the modal is currently open. Notifies via ChangeNotifier. |
OpenOneClickSignupOptions
| Option | Type | Description |
|---|---|---|
sessionKey | string (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) => void | Always present — unlike document verification's KYC success, 1-Click always yields an identity. |
onOneClickDeclined | () => void | The user chose not to share. Not an error — fall back to manual signup. |
onOneClickFailed | (reason: string, retryable?: boolean) => void | Terminal. 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 | () => void | Fires 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) => void | Fires on any error. See Error Codes. |
onReady | () => void | Fires 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
There is no
useTerms/openTermshook. 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'stermsgate on your backend and show this route first when it isn't complete.
Messages this route sends
| Message | When | Payload |
|---|---|---|
PROPHETX_READY | Once the terms document has loaded, or failed to load | — |
PROPHETX_SUCCESS | The user accepted. Also sent immediately, with no screen, when they had already accepted the current version | { transactionId: "tandc", amount: 0 } |
PROPHETX_CANCEL | The user tapped Close on the success page (the terms screen itself has no back or cancel control), or you sent PROPHETX_BACK | — |
PROPHETX_ERROR | Session or origin problems only: SESSION_EXPIRED, SESSION_INVALID, ORIGIN_UNAUTHORIZED, UNCAUGHT_ERROR | { code, message } |
PROPHETX_GEOFENCE_BLOCKED | Location check fails | { stateCode, reason } (both "unknown") |
PROPHETX_RESIZE | Content 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
- Document list. The documents come from
GET /embed/v1/termsverbatim, with document typesPRIVACY_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. - 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.
- 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
This is not a phone/OTP flow. A previous version of this page described
useKycas 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) —useKycnever opened it.useKycopens 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
| Surface | Field | Type | Description |
|---|---|---|---|
| React / React Native | open | (options?: OpenIdUploadOptions) => void | Opens the modal. |
| React / React Native | close | () => void | Closes the modal programmatically. |
| React / React Native | isOpen | boolean | Whether the modal is currently open. |
| Flutter | open | ([OpenIdUploadOptions?]) => void | Opens the modal. |
| Flutter | close | () => void | Closes the modal programmatically. |
| Flutter | isOpen | bool | Whether 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.)
| Option | Type | Description |
|---|---|---|
redirectUrl | string — useIdUpload only, not on useKyc | Absolute 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) => void | Not emitted by this flow (no transaction) — present only for parity with the shared callbacks union. |
onKycSuccess | (identityUuid?: string) => void | Fires 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) => void | Fires 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 | () => void | Fires when the document was submitted but review hasn't resolved yet. |
onError | (code: string, message: string) => void | Fires on any error. See Error Codes. |
onCancel | () => void | Fires when the user closes the modal. |
onReady | () => void | Fires when the flow has mounted. |
onGeofenceBlocked | (stateCode: string, reason: string) => void | See the geofence note at the top of this page. |
What users see
Once you call open():
- 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_retryablefrom the API; the embed disambiguates by checking status first, so you just receive the resolved outcome. - 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. - 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.
- 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)
| Field | Type | Description |
|---|---|---|
balance | WalletBalance | null | Current balance, or null if not yet fetched. |
loading | boolean | Whether a fetch is in progress. |
error | ProphetXApiError | null | Last error, or null. |
refetch | () => Promise<void> | Call to re-fetch the balance. Not automatic — call it on mount and after deposits/withdrawals. |
WalletBalance
| Field | Type | Description |
|---|---|---|
totalBalance | number | The user's available balance. |
currency | string | Currency code (e.g. "USD"). |
JavaScript SDK
The vanilla SDK exposes a wallet property on the SDK instance:
| Method | Type | Description |
|---|---|---|
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.
| Field | Type | Description |
|---|---|---|
balance | WalletBalance? | Current balance, or null if not yet fetched. |
loading | bool | Whether a fetch is in progress. |
error | Object? | Last error, or null. |
refetch | Future<WalletBalance?> Function() | Re-fetches the balance. Call on mount and after deposits/withdrawals. |
Auth
isv-api doesn't serve the
/api/v1/auth/loginendpoint this module calls, sologin()can't succeed against the ProphetX API today. Use a backend-mintedtokeninstead. 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)
| Field | Type | Description |
|---|---|---|
state | AuthState | Current authentication state. See AuthState. |
login | (credentials: LoginCredentials) => Promise<LoginResult> | Authenticate with email and password. |
logout | () => void | Clear the token and reset state. |
token | string | null | Current JWT, or null if unauthenticated. |
isAuthenticated | boolean | Convenience boolean — true when state.status === "authenticated". |
AuthState
| Status | Fields | Description |
|---|---|---|
"unauthenticated" | — | No active session. |
"authenticating" | — | Login in progress. |
"authenticated" | token: string, expiresAt: number | Active session with a valid JWT. |
"expired" | lastToken: string | Session expired. Contains the last token for reference. |
"error" | error: ProphetXAuthError | Authentication failed. |
LoginCredentials
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User's email address. |
password | string | Yes | User's password. |
deviceId | string | No | Optional device identifier. |
LoginResult
| Field | Type | Description |
|---|---|---|
token | string | Signed JWT. |
expiresAt | number | Unix timestamp in seconds (the JWT exp claim) when the token expires. Multiply by 1000 for a JavaScript Date. |
ProphetXAuthError
| Field | Type | Description |
|---|---|---|
type | "AUTH_ERROR" | Always "AUTH_ERROR". |
code | "INVALID_CREDENTIALS" | "NETWORK_ERROR" | "SERVER_ERROR" | "TIMEOUT" | Error category. |
message | string | Human-readable error message. |
status | number | undefined | HTTP status code, if applicable. |
JavaScript SDK
The vanilla SDK exposes an auth property on the SDK instance:
| Method | Type | Description |
|---|---|---|
sdk.auth.login(credentials) | (LoginCredentials) => Promise<LoginResult> | Authenticate. |
sdk.auth.logout() | () => void | Clear the session. |
sdk.auth.getToken() | () => string | null | Get the current JWT. |
sdk.auth.getState() | () => AuthState | Get the current auth state. |
sdk.auth.onStateChange(cb) | (cb: (state: AuthState) => void) => () => void | Subscribe to state changes. Returns an unsubscribe function. |
sdk.auth.handleSessionExpired() | () => Promise<string | null> | Re-authenticates using the getCredentials callback from AuthConfig. |
sdk.auth.destroy() | () => void | Tear down the auth manager and clear timers. |
sdk.authisnullifAuthConfigwas not passed tocreateProphetX.
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.
| Member | Type | Description |
|---|---|---|
login | Future<LoginResult> Function(LoginCredentials) | Authenticate with email + password. Throws ProphetXAuthError. |
logout | void Function() | Clear the session. |
token | String? | Current JWT, or null when not in the Authenticated state. |
isAuthenticated | bool | true when state is Authenticated. |
state | AuthState | Sealed hierarchy. See enum below. |
handleSessionExpired | Future<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.
| Handler | Payload | Description |
|---|---|---|
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:
useEventsreceives payload data as objects (e.g.{ transactionId, amount }), while flow hook callbacks receive them as positional arguments (e.g.(transactionId, amount)). ForsuccessAction,openandclose, 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 subtype | Fields | Description |
|---|---|---|
ReadyEvent | — | The route's first screen rendered. |
SuccessEvent | transactionId: String, amount: num? | A flow succeeded. |
SuccessActionEvent | — | The user pressed the success screen's button. |
ErrorEvent | code: String, message: String | An error occurred. |
CancelEvent | — | The modal closed. |
KycSuccessEvent | identityUuid: String | Document verification passed. |
KycFailedEvent | reason: String | Document verification failed; always final. |
KycPendingEvent | — | Document verification still under review. |
OneClickSuccessEvent | identityUuid: String | 1-Click Signup: the user shared their identity. |
OneClickFailedEvent | reason: String | 1-Click Signup failed. |
OneClickDeclinedEvent | — | 1-Click Signup: the user declined to share. |
GeofenceBlockedEvent | stateCode: String, reason: String | Location blocked when the flow opened. |
SessionExpiredEvent | — | The session token expired mid-flow. |
SessionRefreshedEvent | token: String | A new session token was obtained after expiry. |
FlowOpenEvent | flow: String | A flow opened. flow is the route path: "deposit", "withdraw", "onboarding", "verified" (from kyc), "id-upload", "one-click-signup", or "tandc". |
FlowCloseEvent | flow: String | A 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
| Prop | Type | Required | Description |
|---|---|---|---|
open | boolean | Yes | Controls whether the modal is visible. |
onOpenChange | (open: boolean) => void | Yes | Called when the open state should change (e.g. the user closes the modal). |
src | string | Yes | Full URL of the embed route to load, e.g. https://embed.prophetx.co/deposit. |
token | string | No | Partner session JWT. Leave it out only for 1-Click Signup, which uses a session key instead. |
title | string | No | Accessible title for the modal. |
width | number | No | Modal width in pixels. Defaults to 480. Pass MODAL_WIDTHS[route] — 1-Click Signup needs 396. |
theme | EmbedTheme | No | Theme overrides. Re-sent to an open modal only when primaryColor or backgroundColor changes. |
locale | string | No | BCP 47 locale tag ("en", "es"). Sent via PROPHETX_LOCALE. Defaults to "en". |
onSuccess | (transactionId: string, amount?: number) => void | No | The flow succeeded. The modal stays open on the success screen. |
onSuccessAction | () => void | No | The 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) => void | No | An error occurred. message is for logs. |
onCancel | () => void | No | The modal closed. |
onReady | () => void | No | The route's first screen rendered. |
onGeofenceBlocked | (stateCode: string, reason: string) => void | No | Location blocked when the flow opened. Both arguments are currently 'unknown'. |
onKycSuccess | (identityUuid?: string) => void | No | Document verification passed (identityUuid is always absent). |
onKycFailed | (reason: string, retryable?: boolean) => void | No | Document verification failed; always final. |
onKycPending | () => void | No | Document verification still under review. |
onOneClickSuccess | (identityUuid: string) => void | No | 1-Click Signup: the user shared their identity. |
onOneClickFailed | (reason: string, retryable?: boolean) => void | No | 1-Click Signup failed. |
onOneClickDeclined | () => void | No | 1-Click Signup: the user declined to share. |
onSessionExpired | () => Promise<string | null> | No | Return a fresh JWT within 10 seconds, or null to stop. |
emitter | EventEmitter | No | Advanced: an event emitter to publish events on (the provider passes its own). |
devtools | DevTools | No | Advanced: 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>:
| Method | Type | Description |
|---|---|---|
sendMessage | (message: { type: string; payload?: unknown }) => void | Send a raw postMessage to the iframe. |
reload | () => void | Reload the iframe. |
React Native low-level components
@prophetx/sdk-react-native exports the pieces ProphetXProvider is built from:
| Export | What it is |
|---|---|
ProphetXWebView | The 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. |
ProphetXWebViewHandle | Its ref: sendMessage(message), reload(), goBack(). |
ProphetXModal | ProphetXWebView inside the SDK's native modal. Adds visible, onRequestClose, and optional animationType ("none", "slide", "fade") and presentationStyle ("fullScreen", "pageSheet", "formSheet", "overFullScreen"). |
PoweredByProphetX | The "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 / Property | Type | Description |
|---|---|---|
openDeposit(opts) | (OpenOptions) => void | Open the deposit flow. |
openWithdraw(opts) | (OpenOptions) => void | Open the withdraw flow. |
openOneClickSignup(opts) | (OneClickOpenOptions) => void | Open the 1-Click Signup flow (new users). opts is required — needs sessionKey/environment. |
openKyc(opts) / openIdUpload(opts) | (KycOpenOptions) => void | Open the document verification flow (existing users). Same flow, two names. |
openOnboarding(opts) | (KycOpenOptions) => void | Opens the onboarding route, which is permanently unavailable: it shows a notice, sends onReady, then onCancel on Close. Don't use it. |
close() | () => void | Close any open flow. |
destroy() | () => void | Tear down the SDK — removes DOM elements, clears listeners, destroys auth manager. The instance is unusable afterwards. |
updateTheme(theme) | (EmbedTheme) => void | Send 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) => void | Send a new locale ("en", "es") to the open flow. Does nothing when no flow is open. |
on(event, handler) | See EventEmitter | Subscribe to an event. Returns an unsubscribe function. |
off(event, handler) | See EventEmitter | Unsubscribe from an event. |
auth | AuthManager | null | Auth manager instance. null if auth was not provided. |
wallet | WalletClient | null | Wallet 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.
| Option | Type | Description |
|---|---|---|
token | string | Session JWT. Required unless using the auth module. |
theme | EmbedTheme | Theme for this flow. |
locale | string | BCP 47 locale tag ("en", "es"). Defaults to "en". |
initialAmount | number | Pre-fills the amount field. |
successButtonLabel | string | Text for the success screen's button (at most 40 characters, not translated). |
onSuccessAction | () => void | The user pressed the success screen's button; the modal then closes. |
onSuccess | (transactionId: string, amount?: number) => void | The deposit or withdrawal was accepted. The modal stays open. |
onError | (code: string, message: string) => void | An error occurred. message is for logs. |
onCancel | () => void | The modal closed. |
onReady | () => void | The first screen rendered. |
onGeofenceBlocked | (stateCode: string, reason: string) => void | Location 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.
| Option | Type | Description |
|---|---|---|
token | string | Session JWT. Required unless using the auth module. |
theme | EmbedTheme | Theme for this flow. |
locale | string | BCP 47 locale tag ("en", "es"). Defaults to "en". |
redirectUrl | string | Where IDComply sends the user when they finish. Only same-origin URLs and custom app schemes are used. |
onKycSuccess | (identityUuid?: string) => void | Document verified (or already verified). identityUuid is always absent. |
onKycFailed | (reason: string, retryable?: boolean) => void | The user can't verify through this flow. Always final. |
onKycPending | () => void | Review still in progress. |
onError | (code: string, message: string) => void | An error occurred. |
onCancel | () => void | The modal closed. |
onReady | () => void | The flow mounted. |
onGeofenceBlocked | (stateCode: string, reason: string) => void | Location 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:
| Option | Type | Description |
|---|---|---|
sessionKey | string (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:
| Callback | Available on | Payload |
|---|---|---|
onSuccess | Deposit, withdraw (and /tandc) | (transactionId: string, amount?: number) — never sent by document verification or 1-Click Signup |
onSuccessAction | Deposit, withdraw | — |
onError | All flows | (code: string, message: string) |
onCancel | All flows | — |
onReady | All flows | — |
onGeofenceBlocked | All flows (never fires on 1-Click Signup) | (stateCode: string, reason: string) — both currently 'unknown' |
onOneClickSuccess | useOneClickSignup | (identityUuid: string) |
onOneClickDeclined | useOneClickSignup | — |
onOneClickFailed | useOneClickSignup | (reason: string, retryable?: boolean) |
onKycSuccess | useKyc, useIdUpload | (identityUuid?: string) — always absent |
onKycFailed | useKyc, useIdUpload | (reason: string, retryable?: boolean) — retryable always false |
onKycPending | useKyc, 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 name | Payload type | Description |
|---|---|---|
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 type | Payload | Description |
|---|---|---|
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 type | Payload | Description |
|---|---|---|
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_THEME | EmbedTheme | Set 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
| Field | Type | Description |
|---|---|---|
primaryColor | string | Primary brand color. Applied to primary, primaryHover, cta, and ctaHover — but only when colorOverrides is empty. Once colorOverrides has any keys, primaryColor is ignored. |
backgroundColor | string | React 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.
| Token | Description |
|---|---|
primary | Primary brand color |
primaryHover | Hover state for primary elements |
primaryForeground | Text/icon color on primary backgrounds |
secondary | Secondary color |
secondaryHover | Hover state for secondary elements |
background | Input fields and inset panels |
surface | Embed background and cards |
surfaceElevated | Elevated surface (modals, dropdowns) |
text | Default text color |
textMuted | De-emphasized text |
textSubtle | Least prominent text (placeholders, hints) |
border | Default border color |
borderSubtle | Subtle border (dividers, separators) |
error | Error text/icon color |
errorBackground | Error background (alerts, badges) |
success | Success text/icon color |
successBackground | Success background |
warning | Warning text/icon color |
warningBackground | Warning background |
cta | Call-to-action button color |
ctaHover | CTA hover state |
ctaForeground | Text on CTA buttons |
filled | Filled/solid button color |
filledHover | Filled button hover state |
filledForeground | Text on filled buttons |
danger | Destructive action color |
dangerHover | Destructive action hover state |
dangerForeground | Text on destructive action buttons |
spacingOverrides
| Token | Description |
|---|---|
xs | Extra-small spacing |
sm | Small spacing |
md | Medium spacing |
lg | Large spacing |
xl | Extra-large spacing |
radiusOverrides
| Token | Description |
|---|---|
sm | Small border radius |
md | Medium border radius |
lg | Large border radius |
full | Fully rounded (pill shape) |
fontSizeOverrides
| Token | Description |
|---|---|
xs | Extra-small font size |
sm | Small font size |
md | Medium (base) font size |
lg | Large font size |
xl | Extra-large font size |
DevToolsLogEntry
Entries emitted by the devtools system. Receive them via DevToolsConfig.onEvent.
| Field | Type | Description |
|---|---|---|
timestamp | number | Unix timestamp (ms). |
category | "auth" | "message" | "api" | "lifecycle" | "event" | Log category. |
level | "error" | "warn" | "info" | "debug" | Severity level. |
message | string | Human-readable log message. |
data | Record<string, unknown> | undefined | Optional 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.
Updated 11 days ago
